Doxygen documentation: viz

modules/viz/include/opencv2/viz.hpp

@@ -51,4 +51,34 @@
 #include <opencv2/viz/viz3d.hpp>
 #include <opencv2/viz/vizcore.hpp>
 
+/**
+  @defgroup viz 3D Visualizer
+
+This section describes 3D visualization window as well as classes and methods that are used to
+interact with it.
+
+3D visualization window (see Viz3d) is used to display widgets (see Widget), and it provides several
+methods to interact with scene and widgets.
+
+  @{
+    @defgroup viz_widget Widget
+
+In this section, the widget framework is explained. Widgets represent 2D or 3D objects, varying from
+simple ones such as lines to complex one such as point clouds and meshes.
+
+Widgets are **implicitly shared**. Therefore, one can add a widget to the scene, and modify the
+widget without re-adding the widget.
+
+@code
+// Create a cloud widget
+viz::WCloud cw(cloud, viz::Color::red());
+// Display it in a window
+myWindow.showWidget("CloudWidget1", cw);
+// Modify it, and it will be modified in the window.
+cw.setColor(viz::Color::yellow());
+@endcode
+
+  @}
+*/
+
 #endif /* __OPENCV_VIZ_HPP__ */

modules/viz/include/opencv2/viz/types.hpp

@@ -54,6 +54,12 @@ namespace cv
 {
     namespace viz
     {
+
+//! @addtogroup viz
+//! @{
+
+        /** @brief This class a represents BGR color.
+        */
         class Color : public Scalar
         {
         public:
@@ -108,6 +114,8 @@ namespace cv
             static Color not_set();
         };
 
+        /** @brief This class wraps mesh attributes, and it can load a mesh from a ply file. :
+        */
         class CV_EXPORTS Mesh
         {
         public:
@@ -119,16 +127,49 @@ namespace cv
 
             Mat texture, tcoords;
 
-            //! Loads mesh from a given ply file (no texture load support for now)
+            /** @brief Loads a mesh from a ply file.
+
+            @param file File name (for now only PLY is supported)
+             */
             static Mesh load(const String& file);
         };
 
+        /** @brief 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:
+
+            /** @brief Constructs a Camera.
+
+            @param fx Horizontal focal length.
+            @param fy Vertical focal length.
+            @param cx x coordinate of the principal point.
+            @param cy 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.
+             */
             Camera(double fx, double fy, double cx, double cy, const Size &window_size);
+            /** @overload
+            @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.
+            */
             explicit Camera(const Vec2d &fov, const Size &window_size);
+            /** @overload
+            @param K Intrinsic matrix of the camera.
+            @param window\_size Size of the window. This together with intrinsic matrix determines
+            the field of view.
+            */
             explicit Camera(const Matx33d &K, const Size &window_size);
+            /** @overload
+            @param proj Projection matrix of the camera.
+            @param window\_size Size of the window. This together with projection matrix determines
+            the field of view.
+            */
             explicit Camera(const Matx44d &proj, const Size &window_size);
 
             const Vec2d & getClip() const { return clip_; }
@@ -143,8 +184,17 @@ namespace cv
             const Vec2d& getPrincipalPoint() const { return principal_point_; }
             const Vec2d& getFocalLength() const { return focal_; }
 
+            /** @brief Computes projection matrix using intrinsic parameters of the camera.
+
+            @param proj Output projection matrix.
+             */
             void computeProjectionMatrix(Matx44d &proj) const;
 
+            /** @brief Creates a Kinect Camera.
+
+            @param window\_size Size of the window. This together with intrinsic matrix of a Kinect Camera
+            determines the field of view.
+             */
             static Camera KinectCamera(const Size &window_size);
 
         private:
@@ -157,12 +207,21 @@ namespace cv
             Vec2d focal_;
         };
 
+        /** @brief This class represents a keyboard event.
+        */
         class CV_EXPORTS KeyboardEvent
         {
         public:
             enum { NONE = 0, ALT = 1, CTRL = 2, SHIFT = 4 };
             enum Action { KEY_UP = 0, KEY_DOWN = 1 };
 
+            /** @brief Constructs a KeyboardEvent.
+
+            @param action Signals if key is pressed or released.
+            @param symbol Name of the key.
+            @param code Code of the key.
+            @param modifiers Signals if alt, ctrl or shift are pressed or their combination.
+             */
             KeyboardEvent(Action action, const String& symbol, unsigned char code, int modifiers);
 
             Action action;
@@ -171,12 +230,23 @@ namespace cv
             int modifiers;
         };
 
+        /** @brief 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 } ;
 
+            /** @brief Constructs a MouseEvent.
+
+            @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 pointer Position of the event.
+            @param modifiers Signals if alt, ctrl or shift are pressed or their combination.
+             */
             MouseEvent(const Type& type, const MouseButton& button, const Point& pointer, int modifiers);
 
             Type type;
@@ -184,6 +254,9 @@ namespace cv
             Point pointer;
             int modifiers;
         };
+
+//! @} viz
+
     } /* namespace viz */
 } /* namespace cv */
 

modules/viz/include/opencv2/viz/viz3d.hpp

@@ -58,6 +58,12 @@ namespace cv
 {
     namespace viz
     {
+
+//! @addtogroup viz
+//! @{
+
+        /** @brief The Viz3d class represents a 3D visualizer window. This class is implicitly shared. :
+        */
         class CV_EXPORTS Viz3d
         {
         public:
@@ -65,54 +71,240 @@ namespace cv
             typedef void (*KeyboardCallback)(const KeyboardEvent&, void*);
             typedef void (*MouseCallback)(const MouseEvent&, void*);
 
+            /** @brief The constructors.
+
+            @param window\_name Name of the window.
+             */
             Viz3d(const String& window_name = String());
             Viz3d(const Viz3d&);
             Viz3d& operator=(const Viz3d&);
             ~Viz3d();
 
+            /** @brief Shows a widget in the window.
+
+            @param id A unique id for the widget. @param widget The widget to be displayed in the window.
+            @param pose Pose of the widget.
+             */
             void showWidget(const String &id, const Widget &widget, const Affine3d &pose = Affine3d::Identity());
+
+            /** @brief Removes a widget from the window.
+
+            @param id The id of the widget that will be removed.
+             */
             void removeWidget(const String &id);
+
+            /** @brief 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.
+
+            @param id The id of the widget that will be returned.
+             */
             Widget getWidget(const String &id) const;
+
+            /** @brief Removes all widgets from the window.
+            */
             void removeAllWidgets();
 
+            /** @brief Removed all widgets and displays image scaled to whole window area.
+
+            @param image Image to be displayed.
+            @param window_size Size of Viz3d window. Default value means no change.
+             */
             void showImage(InputArray image, const Size& window_size = Size(-1, -1));
 
+            /** @brief Sets pose of a widget in the window.
+
+            @param id The id of the widget whose pose will be set. @param pose The new pose of the widget.
+             */
             void setWidgetPose(const String &id, const Affine3d &pose);
+
+            /** @brief Updates pose of a widget in the window by pre-multiplying its current 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.
+             */
             void updateWidgetPose(const String &id, const Affine3d &pose);
+
+            /** @brief Returns the current pose of a widget in the window.
+
+            @param id The id of the widget whose pose will be returned.
+             */
             Affine3d getWidgetPose(const String &id) const;
 
+            /** @brief Sets the intrinsic parameters of the viewer using Camera.
+
+            @param camera Camera object wrapping intrinsinc parameters.
+             */
             void setCamera(const Camera &camera);
+
+            /** @brief Returns a camera object that contains intrinsic parameters of the current viewer.
+            */
             Camera getCamera() const;
+
+            /** @brief Returns the current pose of the viewer.
+            */
             Affine3d getViewerPose();
+
+            /** @brief Sets pose of the viewer.
+
+            @param pose The new pose of the viewer.
+             */
             void setViewerPose(const Affine3d &pose);
 
+            /** @brief Resets camera viewpoint to a 3D widget in the scene.
+
+            @param id Id of a 3D widget.
+             */
             void resetCameraViewpoint(const String &id);
+
+            /** @brief Resets camera.
+            */
             void resetCamera();
 
+            /** @brief Transforms a point in world coordinate system to window coordinate system.
+
+            @param pt Point in world coordinate system.
+            @param window\_coord Output point in window coordinate system.
+             */
             void convertToWindowCoordinates(const Point3d &pt, Point3d &window_coord);
+
+            /** @brief Transforms a point in window coordinate system to a 3D ray in world coordinate system.
+
+            @param window\_coord Point in window coordinate system. @param origin Output origin of the ray.
+            @param direction Output direction of the ray.
+             */
             void converTo3DRay(const Point3d &window_coord, Point3d &origin, Vec3d &direction);
 
+            /** @brief Returns the current size of the window.
+            */
             Size getWindowSize() const;
+            /** @brief Sets the size of the window.
+
+            @param window\_size New size of the window.
+             */
             void setWindowSize(const Size &window_size);
+
+            /** @brief Returns the name of the window which has been set in the constructor.
+             */
             String getWindowName() const;
+
+            /** @brief Saves screenshot of the current scene.
+
+            @param file Name of the file.
+             */
             void saveScreenshot(const String &file);
+
+            /** @brief Sets the position of the window in the screen.
+
+            @param window_position coordinates of the window
+             */
             void setWindowPosition(const Point& window_position);
+
+            /** @brief Sets or unsets full-screen rendering mode.
+
+            @param mode If true, window will use full-screen mode.
+             */
             void setFullScreen(bool mode = true);
+
+            /** @brief Sets background color.
+            */
             void setBackgroundColor(const Color& color = Color::black(), const Color& color2 = Color::not_set());
             void setBackgroundTexture(InputArray image = noArray());
             void setBackgroundMeshLab();
 
+            /** @brief The window renders and starts the event loop.
+            */
             void spin();
+
+            /** @brief Starts the event loop for a given time.
+
+            @param time Amount of time in milliseconds for the event loop to keep running.
+            @param force_redraw If true, window renders.
+             */
             void spinOnce(int time = 1, bool force_redraw = false);
+
+            /** @brief Returns whether the event loop has been stopped.
+            */
             bool wasStopped() const;
             void close();
 
+            /** @brief Sets keyboard handler.
+
+            @param callback Keyboard callback (void (\*KeyboardCallbackFunction(const
+            KeyboardEvent&, void\*)).
+            @param cookie The optional parameter passed to the callback.
+             */
             void registerKeyboardCallback(KeyboardCallback callback, void* cookie = 0);
+
+            /** @brief Sets mouse handler.
+
+            @param callback Mouse callback (void (\*MouseCallback)(const MouseEvent&, void\*)).
+            @param cookie The optional parameter passed to the callback.
+             */
             void registerMouseCallback(MouseCallback callback, void* cookie = 0);
 
+            /** @brief Sets rendering property of a widget.
+
+            @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**
+             */
             void setRenderingProperty(const String &id, int property, double value);
+            /** @brief Returns rendering property of a widget.
+
+            @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**
+             */
             double getRenderingProperty(const String &id, int property);
 
+            /** @brief Sets geometry representation of the widgets to surface, wireframe or points.
+
+            @param representation Geometry representation which can be one of the following:
+            -   **REPRESENTATION\_POINTS**
+            -   **REPRESENTATION\_WIREFRAME**
+            -   **REPRESENTATION\_SURFACE**
+             */
             void setRepresentation(int representation);
 
             void setGlobalWarnings(bool enabled = false);
@@ -127,6 +319,8 @@ namespace cv
             friend class VizStorage;
         };
 
+//! @}
+
     } /* namespace viz */
 } /* namespace cv */
 

modules/viz/include/opencv2/viz/vizcore.hpp

@@ -54,13 +54,48 @@ namespace cv
 {
     namespace viz
     {
-        //! takes coordiante frame data and builds transfrom to global coordinate frame
+
+//! @addtogroup viz
+//! @{
+
+        /** @brief Takes coordinate frame data and builds transform to global coordinate frame.
+
+        @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.
+         */
         CV_EXPORTS Affine3d makeTransformToGlobal(const Vec3d& axis_x, const Vec3d& axis_y, const Vec3d& axis_z, const Vec3d& origin = Vec3d::all(0));
 
-        //! constructs camera pose from position, focal_point and up_vector (see gluLookAt() for more infromation)
+        /** @brief Constructs camera pose from position, focal\_point and up\_vector (see gluLookAt() for more
+        infromation).
+
+        @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.
+         */
         CV_EXPORTS Affine3d makeCameraPose(const Vec3d& position, const Vec3d& focal_point, const Vec3d& y_dir);
 
-        //! retrieves a window by its name. If no window with such name, then it creates new.
+        /** @brief Retrieves a window by its name.
+
+        @param window\_name Name of the window that is to be retrieved.
+
+        This function returns a 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
+            /// window and window_2 are the same windows.
+            viz::Viz3d window   = viz::getWindowByName("myWindow");
+            viz::Viz3d window_2 = viz::getWindowByName("Viz - myWindow");
+            @endcode
+         */
         CV_EXPORTS Viz3d getWindowByName(const String &window_name);
 
         //! Unregisters all Viz windows from internal database. After it 'getWindowByName()' will create new windows instead getting existing from the database.
@@ -69,25 +104,37 @@ namespace cv
         //! Displays image in specified window
         CV_EXPORTS Viz3d imshow(const String& window_name, InputArray image, const Size& window_size = Size(-1, -1));
 
-        //! checks float value for Nan
+        /** @brief Checks **float/double** value for nan.
+
+        @param x return true if nan.
+         */
         inline bool isNan(float x)
         {
             unsigned int *u = reinterpret_cast<unsigned int *>(&x);
             return ((u[0] & 0x7f800000) == 0x7f800000) && (u[0] & 0x007fffff);
         }
 
-        //! checks double value for Nan
+        /** @brief Checks **float/double** value for nan.
+
+        @param x return true if nan.
+         */
         inline bool isNan(double x)
         {
             unsigned int *u = reinterpret_cast<unsigned int *>(&x);
             return (u[1] & 0x7ff00000) == 0x7ff00000 && (u[0] != 0 || (u[1] & 0x000fffff) != 0);
         }
 
-        //! checks vectors for Nans
+        /** @brief Checks **float/double** value for nan.
+
+        @param v return true if **any** of the elements of the vector is *nan*.
+         */
         template<typename _Tp, int cn> inline bool isNan(const Vec<_Tp, cn>& v)
         { return isNan(v.val[0]) || isNan(v.val[1]) || isNan(v.val[2]); }
 
-        //! checks point for Nans
+        /** @brief Checks **float/double** value for nan.
+
+        @param p return true if **any** of the elements of the point is *nan*.
+         */
         template<typename _Tp> inline bool isNan(const Point3_<_Tp>& p)
         { return isNan(p.x) || isNan(p.y) || isNan(p.z); }
 
@@ -121,6 +168,8 @@ namespace cv
 
         CV_EXPORTS void computeNormals(const Mesh& mesh, OutputArray normals);
 
+//! @}
+
     } /* namespace viz */
 } /* namespace cv */
 

modules/viz/include/opencv2/viz/widget_accessor.hpp

@@ -54,15 +54,35 @@ namespace cv
 {
     namespace viz
     {
+
+//! @addtogroup viz_widget
+//! @{
+
         class Widget;
 
-        //The class is only that depends on VTK in its interface.
-        //It is indended for those users who want to develop own widgets system using VTK library API.
+        /** @brief This class is for users who want to develop their own widgets using VTK library API. :
+        */
         struct CV_EXPORTS WidgetAccessor
         {
+            /** @brief Returns vtkProp of a given widget.
+
+            @param widget Widget whose vtkProp is to be returned.
+
+            @note vtkProp has to be down cast appropriately to be modified.
+                @code
+                vtkActor * actor = vtkActor::SafeDownCast(viz::WidgetAccessor::getProp(widget));
+                @endcode
+             */
             static vtkSmartPointer<vtkProp> getProp(const Widget &widget);
+            /** @brief Sets vtkProp of a given widget.
+
+            @param widget Widget whose vtkProp is to be set. @param prop A vtkProp.
+             */
             static void setProp(Widget &widget, vtkSmartPointer<vtkProp> prop);
         };
+
+//! @}
+
     }
 }