opencv/modules/viz/doc/viz3d.rst

Viz
===

.. highlight:: cpp

This section describes 3D visualization window as well as classes and methods
that are used to interact with it.

3D visualization window (see :ocv:class:`Viz3d`) is used to display widgets (see :ocv:class:`Widget`), and it provides
several methods to interact with scene and widgets.

viz::makeTransformToGlobal
--------------------------
Takes coordinate frame data and builds transform to global coordinate frame.

.. ocv:function:: Affine3f viz::makeTransformToGlobal(const Vec3f& axis_x, const Vec3f& axis_y, const Vec3f& axis_z, const Vec3f& origin = Vec3f::all(0))

    :param axis_x: X axis vector in global coordinate frame.
    :param axis_y: Y axis vector in global coordinate frame.
    :param axis_z: Z axis vector in global coordinate frame.
    :param origin: Origin of the coordinate frame in global coordinate frame.

This function returns affine transform that describes transformation between global coordinate frame and a given coordinate frame.

viz::makeCameraPose
-------------------
Constructs camera pose from position, focal_point and up_vector (see gluLookAt() for more infromation).

.. ocv:function:: Affine3f makeCameraPose(const Vec3f& position, const Vec3f& focal_point, const Vec3f& y_dir)

    :param position: Position of the camera in global coordinate frame.
    :param focal_point: Focal point of the camera in global coordinate frame.
    :param y_dir: Up vector of the camera in global coordinate frame.

This function returns pose of the camera in global coordinate frame.

viz::get
--------
Retrieves a window by its name.

.. ocv:function:: Viz3d get(const String &window_name)

    :param window_name: Name of the window that is to be retrieved.

This function returns a :ocv:class:`Viz3d` object with the given name.

.. note:: If the window with that name already exists, that window is returned. Otherwise, new window is created with the given name, and it is returned.

.. note:: Window names are automatically prefixed by "Viz - " if it is not done by the user.

          .. code-block:: cpp

                /// window and window_2 are the same windows.
                viz::Viz3d window   = viz::get("myWindow");
                viz::Viz3d window_2 = viz::get("Viz - myWindow");

viz::isNan
----------
Checks **float/double** value for nan.

    .. ocv:function:: bool isNan(float x)

    .. ocv:function:: bool isNan(double x)

        :param x: return true if nan.

Checks **vector** for nan.

    .. ocv:function:: bool isNan(const Vec<_Tp, cn>& v)

        :param v: return true if **any** of the elements of the vector is *nan*.

Checks **point** for nan

    .. ocv:function:: bool isNan(const Point3_<_Tp>& p)

        :param p: return true if **any** of the elements of the point is *nan*.

viz::VizAccessor
----------------
.. ocv:class:: VizAccessor

A singleton class that provides access by name infrastructure for 3D visualization windows. ::

    class CV_EXPORTS VizAccessor
    {
    public:
        static VizAccessor & getInstance();
        static void release();

        Viz3d get(const String &window_name);

        //! window names automatically have Viz - prefix even though not provided by the users
        static void generateWindowName(const String &window_name, String &output);

    private:
        /* hidden */
    };

viz::VizAccessor::getInstance
-----------------------------
Returns the single instance of VizAccessor.

.. ocv:function:: static VizAccessor & getInstance()

viz::VizAccessor::release
-------------------------
Deletes the single instance of VizAccessor.

.. ocv:function:: static void release()

viz::VizAccessor::get
---------------------
Retrieves a window by its name.

.. ocv:function:: Viz3d get(const String &window_name)

    :param window_name: Name of the window that is to be retrieved.

This function returns a :ocv:class:`Viz3d` object with the given name.

.. note:: If the window with that name already exists, that window is returned. Otherwise, new window is created with the given name, and it is returned.

.. note:: Window names are automatically prefixed by "Viz - " if it is not done by the user.

          .. code-block:: cpp

                /// window and window_2 are the same windows.
                viz::Viz3d window   = viz::get("myWindow");
                viz::Viz3d window_2 = viz::get("Viz - myWindow");

viz::VizAccessor::generateWindowName
------------------------------------
Generates a window name by prefixing "Viz - " if it has not already been prefixed.

.. ocv:function:: static void generateWindowName(const String &window_name, String &output)

    :param window_name: Window name
    :param output: Prefixed window name

viz::Viz3d
----------
.. ocv:class:: Viz3d

The Viz3d class represents a 3D visualizer window. This class is implicitly shared.    ::

    class CV_EXPORTS Viz3d
    {
    public:
        typedef cv::Ptr<Viz3d> Ptr;
        typedef void (*KeyboardCallback)(const KeyboardEvent&, void*);
        typedef void (*MouseCallback)(const MouseEvent&, void*);

        Viz3d(const String& window_name = String());
        Viz3d(const Viz3d&);
        Viz3d& operator=(const Viz3d&);
        ~Viz3d();

        void showWidget(const String &id, const Widget &widget, const Affine3f &pose = Affine3f::Identity());
        void removeWidget(const String &id);
        Widget getWidget(const String &id) const;
        void removeAllWidgets();

        void setWidgetPose(const String &id, const Affine3f &pose);
        void updateWidgetPose(const String &id, const Affine3f &pose);
        Affine3f getWidgetPose(const String &id) const;

        void setCamera(const Camera &camera);
        Camera getCamera() const;
        Affine3f getViewerPose();
        void setViewerPose(const Affine3f &pose);

        void resetCameraViewpoint (const String &id);
        void resetCamera();

        void convertToWindowCoordinates(const Point3d &pt, Point3d &window_coord);
        void converTo3DRay(const Point3d &window_coord, Point3d &origin, Vec3d &direction);

        Size getWindowSize() const;
        void setWindowSize(const Size &window_size);
        String getWindowName() const;
        void saveScreenshot (const String &file);
        void setWindowPosition (int x, int y);
        void setFullScreen (bool mode);
        void setBackgroundColor(const Color& color = Color::black());

        void spin();
        void spinOnce(int time = 1, bool force_redraw = false);
        bool wasStopped() const;

        void registerKeyboardCallback(KeyboardCallback callback, void* cookie = 0);
        void registerMouseCallback(MouseCallback callback, void* cookie = 0);

        void setRenderingProperty(const String &id, int property, double value);
        double getRenderingProperty(const String &id, int property);

        void setDesiredUpdateRate(double rate);
        double getDesiredUpdateRate();

        void setRepresentation(int representation);
    private:
        /* hidden */
    };

viz::Viz3d::Viz3d
-----------------
The constructors.

.. ocv:function:: Viz3d::Viz3d(const String& window_name = String())

    :param window_name: Name of the window.

viz::Viz3d::showWidget
----------------------
Shows a widget in the window.

.. ocv:function:: void Viz3d::showWidget(const String &id, const Widget &widget, const Affine3f &pose = Affine3f::Identity())

    :param id: A unique id for the widget.
    :param widget: The widget to be displayed in the window.
    :param pose: Pose of the widget.

viz::Viz3d::removeWidget
------------------------
Removes a widget from the window.

.. ocv:function:: void removeWidget(const String &id)

    :param id: The id of the widget that will be removed.

viz::Viz3d::getWidget
---------------------
Retrieves a widget from the window. A widget is implicitly shared;
that is, if the returned widget is modified, the changes will be
immediately visible in the window.

.. ocv:function:: Widget getWidget(const String &id) const

    :param id: The id of the widget that will be returned.

viz::Viz3d::removeAllWidgets
----------------------------
Removes all widgets from the window.

.. ocv:function:: void removeAllWidgets()

viz::Viz3d::setWidgetPose
-------------------------
Sets pose of a widget in the window.

.. ocv:function:: void setWidgetPose(const String &id, const Affine3f &pose)

    :param id: The id of the widget whose pose will be set.
    :param pose: The new pose of the widget.

viz::Viz3d::updateWidgetPose
----------------------------
Updates pose of a widget in the window by pre-multiplying its current pose.

.. ocv:function:: void updateWidgetPose(const String &id, const Affine3f &pose)

    :param id: The id of the widget whose pose will be updated.
    :param pose: The pose that the current pose of the widget will be pre-multiplied by.

viz::Viz3d::getWidgetPose
-------------------------
Returns the current pose of a widget in the window.

.. ocv:function:: Affine3f getWidgetPose(const String &id) const

    :param id: The id of the widget whose pose will be returned.

viz::Viz3d::setCamera
---------------------
Sets the intrinsic parameters of the viewer using Camera.

.. ocv:function:: void setCamera(const Camera &camera)

    :param camera: Camera object wrapping intrinsinc parameters.

viz::Viz3d::getCamera
---------------------
Returns a camera object that contains intrinsic parameters of the current viewer.

.. ocv:function:: Camera getCamera() const

viz::Viz3d::getViewerPose
-------------------------
Returns the current pose of the viewer.

..ocv:function:: Affine3f getViewerPose()

viz::Viz3d::setViewerPose
-------------------------
Sets pose of the viewer.

.. ocv:function:: void setViewerPose(const Affine3f &pose)

    :param pose: The new pose of the viewer.

viz::Viz3d::resetCameraViewpoint
--------------------------------
Resets camera viewpoint to a 3D widget in the scene.

.. ocv:function:: void resetCameraViewpoint (const String &id)

    :param pose: Id of a 3D widget.

viz::Viz3d::resetCamera
-----------------------
Resets camera.

.. ocv:function:: void resetCamera()

viz::Viz3d::convertToWindowCoordinates
--------------------------------------
Transforms a point in world coordinate system to window coordinate system.

.. ocv:function:: void convertToWindowCoordinates(const Point3d &pt, Point3d &window_coord)

    :param pt: Point in world coordinate system.
    :param window_coord: Output point in window coordinate system.

viz::Viz3d::converTo3DRay
-------------------------
Transforms a point in window coordinate system to a 3D ray in world coordinate system.

.. ocv:function:: void converTo3DRay(const Point3d &window_coord, Point3d &origin, Vec3d &direction)

    :param window_coord: Point in window coordinate system.
    :param origin: Output origin of the ray.
    :param direction: Output direction of the ray.

viz::Viz3d::getWindowSize
-------------------------
Returns the current size of the window.

.. ocv:function:: Size getWindowSize() const

viz::Viz3d::setWindowSize
-------------------------
Sets the size of the window.

.. ocv:function:: void setWindowSize(const Size &window_size)

    :param window_size: New size of the window.

viz::Viz3d::getWindowName
-------------------------
Returns the name of the window which has been set in the constructor.

.. ocv:function:: String getWindowName() const

viz::Viz3d::saveScreenshot
--------------------------
Saves screenshot of the current scene.

.. ocv:function:: void saveScreenshot(const String &file)

    :param file: Name of the file.

viz::Viz3d::setWindowPosition
-----------------------------
Sets the position of the window in the screen.

.. ocv:function:: void setWindowPosition(int x, int y)

    :param x: x coordinate of the window
    :param y: y coordinate of the window

viz::Viz3d::setFullScreen
-------------------------
Sets or unsets full-screen rendering mode.

.. ocv:function:: void setFullScreen(bool mode)

    :param mode: If true, window will use full-screen mode.

viz::Viz3d::setBackgroundColor
------------------------------
Sets background color.

.. ocv:function:: void setBackgroundColor(const Color& color = Color::black())

viz::Viz3d::spin
----------------
The window renders and starts the event loop.

.. ocv:function:: void spin()

viz::Viz3d::spinOnce
--------------------
Starts the event loop for a given time.

.. ocv:function:: void spinOnce(int time = 1, bool force_redraw = false)

    :param time: Amount of time in milliseconds for the event loop to keep running.
    :param force_draw: If true, window renders.

viz::Viz3d::wasStopped
----------------------
Returns whether the event loop has been stopped.

.. ocv:function:: bool wasStopped()

viz::Viz3d::registerKeyboardCallback
------------------------------------
Sets keyboard handler.

.. ocv:function:: void registerKeyboardCallback(KeyboardCallback callback, void* cookie = 0)

    :param callback: Keyboard callback ``(void (*KeyboardCallbackFunction(const KeyboardEvent&, void*))``.
    :param cookie: The optional parameter passed to the callback.

viz::Viz3d::registerMouseCallback
---------------------------------
Sets mouse handler.

.. ocv:function:: void registerMouseCallback(MouseCallback callback, void* cookie = 0)

    :param callback: Mouse callback ``(void (*MouseCallback)(const MouseEvent&, void*))``.
    :param cookie: The optional parameter passed to the callback.

viz::Viz3d::setRenderingProperty
--------------------------------
Sets rendering property of a widget.

.. ocv:function:: void setRenderingProperty(const String &id, int property, double value)

    :param id: Id of the widget.
    :param property: Property that will be modified.
    :param value: The new value of the property.

    **Rendering property** can be one of the following:

    * **POINT_SIZE**
    * **OPACITY**
    * **LINE_WIDTH**
    * **FONT_SIZE**
    * **REPRESENTATION**: Expected values are
        * **REPRESENTATION_POINTS**
        * **REPRESENTATION_WIREFRAME**
        * **REPRESENTATION_SURFACE**
    * **IMMEDIATE_RENDERING**:
        * Turn on immediate rendering by setting the value to ``1``.
        * Turn off immediate rendering by setting the value to ``0``.
    * **SHADING**: Expected values are
        * **SHADING_FLAT**
        * **SHADING_GOURAUD**
        * **SHADING_PHONG**

viz::Viz3d::getRenderingProperty
--------------------------------
Returns rendering property of a widget.

.. ocv:function:: double getRenderingProperty(const String &id, int property)

    :param id: Id of the widget.
    :param property: Property.

    **Rendering property** can be one of the following:

    * **POINT_SIZE**
    * **OPACITY**
    * **LINE_WIDTH**
    * **FONT_SIZE**
    * **REPRESENTATION**: Expected values are
        * **REPRESENTATION_POINTS**
        * **REPRESENTATION_WIREFRAME**
        * **REPRESENTATION_SURFACE**
    * **IMMEDIATE_RENDERING**:
        * Turn on immediate rendering by setting the value to ``1``.
        * Turn off immediate rendering by setting the value to ``0``.
    * **SHADING**: Expected values are
        * **SHADING_FLAT**
        * **SHADING_GOURAUD**
        * **SHADING_PHONG**

viz::Viz3d::setDesiredUpdateRate
--------------------------------
Sets desired update rate of the window.

.. ocv:function:: void setDesiredUpdateRate(double rate)

    :param rate: Desired update rate. The default is 30.

viz::Viz3d::getDesiredUpdateRate
--------------------------------
Returns desired update rate of the window.

.. ocv:function:: double getDesiredUpdateRate()

viz::Viz3d::setRepresentation
-----------------------------
Sets geometry representation of the widgets to surface, wireframe or points.

.. ocv:function:: void setRepresentation(int representation)

    :param representation: Geometry representation which can be one of the following:

        * **REPRESENTATION_POINTS**
        * **REPRESENTATION_WIREFRAME**
        * **REPRESENTATION_SURFACE**

viz::Color
----------
.. ocv:class:: Color

This class a represents BGR color. ::

    class CV_EXPORTS Color : public Scalar
    {
    public:
        Color();
        Color(double gray);
        Color(double blue, double green, double red);

        Color(const Scalar& color);

        static Color black();
        static Color blue();
        static Color green();
        static Color cyan();

        static Color red();
        static Color magenta();
        static Color yellow();
        static Color white();

        static Color gray();
    };

viz::Mesh3d
-----------
.. ocv:class:: Mesh3d

This class wraps mesh attributes, and it can load a mesh from a ``ply`` file. ::

    class CV_EXPORTS Mesh3d
    {
    public:

        Mat cloud, colors;
        Mat polygons;

        //! Loads mesh from a given ply file
        static Mesh3d loadMesh(const String& file);

    private:
        /* hidden */
    };

viz::Mesh3d::loadMesh
---------------------
Loads a mesh from a ``ply`` file.

.. ocv:function:: static Mesh3d loadMesh(const String& file)

    :param file: File name.


viz::KeyboardEvent
------------------
.. ocv:class:: KeyboardEvent

This class represents a keyboard event. ::

    class CV_EXPORTS KeyboardEvent
    {
    public:
        static const unsigned int Alt   = 1;
        static const unsigned int Ctrl  = 2;
        static const unsigned int Shift = 4;

        //! Create a keyboard event
        //! - Note that action is true if key is pressed, false if released
        KeyboardEvent (bool action, const std::string& key_sym, unsigned char key, bool alt, bool ctrl, bool shift);

        bool isAltPressed () const;
        bool isCtrlPressed () const;
        bool isShiftPressed () const;

        unsigned char getKeyCode () const;

        const String& getKeySym () const;
        bool keyDown () const;
        bool keyUp () const;

    protected:
        /* hidden */
    };

viz::KeyboardEvent::KeyboardEvent
---------------------------------
Constructs a KeyboardEvent.

.. ocv:function:: KeyboardEvent (bool action, const std::string& key_sym, unsigned char key, bool alt, bool ctrl, bool shift)

    :param action: If true, key is pressed. If false, key is released.
    :param key_sym: Name of the key.
    :param key: Code of the key.
    :param alt: If true, ``alt`` is pressed.
    :param ctrl: If true, ``ctrl`` is pressed.
    :param shift: If true, ``shift`` is pressed.

viz::MouseEvent
---------------
.. ocv:class:: MouseEvent

This class represents a mouse event. ::

    class CV_EXPORTS MouseEvent
    {
    public:
        enum Type { MouseMove = 1, MouseButtonPress, MouseButtonRelease, MouseScrollDown, MouseScrollUp, MouseDblClick } ;
        enum MouseButton { NoButton = 0, LeftButton, MiddleButton, RightButton, VScroll } ;

        MouseEvent (const Type& type, const MouseButton& button, const Point& p, bool alt, bool ctrl, bool shift);

        Type type;
        MouseButton button;
        Point pointer;
        unsigned int key_state;
    };

viz::MouseEvent::MouseEvent
---------------------------
Constructs a MouseEvent.

.. ocv:function:: MouseEvent (const Type& type, const MouseButton& button, const Point& p, bool alt, bool ctrl, bool shift)

    :param type: Type of the event. This can be **MouseMove**, **MouseButtonPress**, **MouseButtonRelease**, **MouseScrollDown**, **MouseScrollUp**, **MouseDblClick**.
    :param button: Mouse button. This can be **NoButton**, **LeftButton**, **MiddleButton**, **RightButton**, **VScroll**.
    :param p: Position of the event.
    :param alt: If true, ``alt`` is pressed.
    :param ctrl: If true, ``ctrl`` is pressed.
    :param shift: If true, ``shift`` is pressed.

viz::Camera
-----------
.. ocv:class:: Camera

This class wraps intrinsic parameters of a camera. It provides several constructors
that can extract the intrinsic parameters from ``field of view``, ``intrinsic matrix`` and
``projection matrix``. ::

    class CV_EXPORTS Camera
    {
    public:
        Camera(float f_x, float f_y, float c_x, float c_y, const Size &window_size);
        Camera(const Vec2f &fov, const Size &window_size);
        Camera(const cv::Matx33f &K, const Size &window_size);
        Camera(const cv::Matx44f &proj, const Size &window_size);

        inline const Vec2d & getClip() const { return clip_; }
        inline void setClip(const Vec2d &clip) { clip_ = clip; }

        inline const Size & getWindowSize() const { return window_size_; }
        void setWindowSize(const Size &window_size);

        inline const Vec2f & getFov() const { return fov_; }
        inline void setFov(const Vec2f & fov) { fov_ = fov; }

        inline const Vec2f & getPrincipalPoint() const { return principal_point_; }
        inline const Vec2f & getFocalLength() const { return focal_; }

        void computeProjectionMatrix(Matx44f &proj) const;

        static Camera KinectCamera(const Size &window_size);

    private:
        /* hidden */
    };

viz::Camera::Camera
-------------------
Constructs a Camera.

.. ocv:function:: Camera(float f_x, float f_y, float c_x, float c_y, const Size &window_size)

    :param f_x: Horizontal focal length.
    :param f_y: Vertical focal length.
    :param c_x: x coordinate of the principal point.
    :param c_y: y coordinate of the principal point.
    :param window_size: Size of the window. This together with focal length and principal point determines the field of view.

.. ocv:function:: Camera(const Vec2f &fov, const Size &window_size)

    :param fov: Field of view (horizontal, vertical)
    :param window_size: Size of the window.

    Principal point is at the center of the window by default.

.. ocv:function:: Camera(const cv::Matx33f &K, const Size &window_size)

    :param K: Intrinsic matrix of the camera.
    :param window_size: Size of the window. This together with intrinsic matrix determines the field of view.

.. ocv:function:: Camera(const cv::Matx44f &proj, const Size &window_size)

    :param proj: Projection matrix of the camera.
    :param window_size: Size of the window. This together with projection matrix determines the field of view.

viz::Camera::computeProjectionMatrix
------------------------------------
Computes projection matrix using intrinsic parameters of the camera.

.. ocv:function:: void computeProjectionMatrix(Matx44f &proj) const

    :param proj: Output projection matrix.

viz::Camera::KinectCamera
-------------------------
Creates a Kinect Camera.

.. ocv:function:: static Camera KinectCamera(const Size &window_size)

    :param window_size: Size of the window. This together with intrinsic matrix of a Kinect Camera determines the field of view.