improve the doc for the viz module.

cmake/OpenCVDetectVTK.cmake

@@ -19,7 +19,7 @@ if(NOT VTK_FOUND)
   return()
 endif()
 
-# Don't support ealier VTKs
+# Don't support earlier VTKs
 if(${VTK_VERSION} VERSION_LESS "5.8.0")
   message(STATUS "VTK support is disabled. VTK ver. 5.8.0 is minimum required, but found VTK ver. ${VTK_VERSION}")
   return()

modules/calib3d/src/homography_decomp.cpp

@@ -2,7 +2,7 @@
  //
  // This is a homography decomposition implementation contributed to OpenCV
  // by Samson Yilma. It implements the homography decomposition algorithm
- // descriped in the research report:
+ // described in the research report:
  // Malis, E and Vargas, M, "Deeper understanding of the homography decomposition
  // for vision-based control", Research Report 6303, INRIA (2007)
  //
@@ -84,6 +84,16 @@ protected:
     }
 
 private:
+    /**
+     * Normalize the homograhpy \f$H\f$.
+     *
+     * @param H Homography matrix.
+     * @param K Intrinsic parameter matrix.
+     * @return It returns
+     * \f[
+     *   K^{-1} * H * K
+     * \f]
+     */
     cv::Matx33d normalize(const cv::Matx33d& H, const cv::Matx33d& K);
     void removeScale();
     cv::Matx33d _Hnorm;

modules/viz/include/opencv2/viz.hpp

@@ -64,7 +64,7 @@ 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.
+simple ones such as lines to complex ones 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.

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

@@ -58,12 +58,13 @@ namespace cv
 //! @addtogroup viz
 //! @{
 
-        /** @brief This class a represents BGR color.
+        /** @brief This class represents color in BGR order.
         */
         class Color : public Scalar
         {
         public:
             Color();
+            //! The three channels will have the same value equal to gray.
             Color(double gray);
             Color(double blue, double green, double red);
 
@@ -125,13 +126,16 @@ namespace cv
                 LOAD_OBJ = 2
             };
 
-            Mat cloud, colors, normals;
+            Mat cloud; //!< point coordinates of type CV_32FC3 or CV_64FC3 with only 1 row
+            Mat colors; //!< point color of type CV_8UC3 or CV_8UC4 with only 1 row
+            Mat normals; //!< point normals of type CV_32FC3, CV_32FC4, CV_64FC3 or CV_64FC4 with only 1 row
 
             //! Raw integer list of the form: (n,id1,id2,...,idn, n,id1,id2,...,idn, ...)
-            //! where n is the number of points in the poligon, and id is a zero-offset index into an associated cloud.
-            Mat polygons;
+            //! where n is the number of points in the polygon, and id is a zero-offset index into an associated cloud.
+            Mat polygons; //!< CV_32SC1 with only 1 row
 
-            Mat texture, tcoords;
+            Mat texture;
+            Mat tcoords; //!< CV_32FC2 or CV_64FC2 with only 1 row
 
             /** @brief Loads a mesh from a ply or a obj file.
 
@@ -165,20 +169,39 @@ namespace cv
             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);
+            Camera(const Vec2d &fov, const Size &window_size);
+
             /** @overload
-            @param K Intrinsic matrix of the camera.
+            @param K Intrinsic matrix of the camera with the following form
+            \f[
+              \begin{bmatrix}
+              f_x &   0 & c_x\\
+                0 & f_y & c_y\\
+                0 &   0 &   1\\
+              \end{bmatrix}
+            \f]
             @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);
+            Camera(const Matx33d &K, const Size &window_size);
+
             /** @overload
-            @param proj Projection matrix of the camera.
+            @param proj Projection matrix of the camera with the following form
+            \f[
+              \begin{bmatrix}
+              \frac{2n}{r-l} &        0       & \frac{r+l}{r-l}  & 0\\
+                    0        & \frac{2n}{t-b} & \frac{t+b}{t-b}  & 0\\
+                    0        &        0       & -\frac{f+n}{f-n} & -\frac{2fn}{f-n}\\
+                    0        &        0       & -1               & 0\\
+              \end{bmatrix}
+            \f]
+
             @param window_size Size of the window. This together with projection matrix determines
             the field of view.
             */
@@ -198,11 +221,23 @@ namespace cv
 
             /** @brief Computes projection matrix using intrinsic parameters of the camera.
 
-            @param proj Output projection matrix.
+
+            @param proj Output projection matrix with the following form
+            \f[
+              \begin{bmatrix}
+              \frac{2n}{r-l} &        0       & \frac{r+l}{r-l}  & 0\\
+                    0        & \frac{2n}{t-b} & \frac{t+b}{t-b}  & 0\\
+                    0        &        0       & -\frac{f+n}{f-n} & -\frac{2fn}{f-n}\\
+                    0        &        0       & -1               & 0\\
+              \end{bmatrix}
+            \f]
              */
             void computeProjectionMatrix(Matx44d &proj) const;
 
-            /** @brief Creates a Kinect Camera.
+            /** @brief Creates a Kinect Camera with
+              - fx = fy = 525
+              - cx = 320
+              - cy = 240
 
             @param window_size Size of the window. This together with intrinsic matrix of a Kinect Camera
             determines the field of view.
@@ -212,10 +247,33 @@ namespace cv
         private:
             void init(double fx, double fy, double cx, double cy, const Size &window_size);
 
+            /** The near plane and the far plane.
+             *  - clip_[0]: the near plane; default value is 0.01
+             *  - clip_[1]: the far plane; default value is 1000.01
+             */
             Vec2d clip_;
+
+            /**
+             * Field of view.
+             *  - fov_[0]: horizontal(x-axis) field of view in radians
+             *  - fov_[1]: vertical(y-axis) field of view in radians
+             */
             Vec2d fov_;
+
+            /** Window size.*/
             Size window_size_;
+
+            /**
+             * Principal point.
+             *  - principal_point_[0]: cx
+             *  - principal_point_[1]: cy
+             */
             Vec2d principal_point_;
+            /**
+             * Focal length.
+             *  - focal_[0]: fx
+             *  - focal_[1]: fy
+             */
             Vec2d focal_;
         };
 

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

@@ -62,7 +62,7 @@ namespace cv
 //! @addtogroup viz
 //! @{
 
-        /** @brief The Viz3d class represents a 3D visualizer window. This class is implicitly shared. :
+        /** @brief The Viz3d class represents a 3D visualizer window. This class is implicitly shared.
         */
         class CV_EXPORTS Viz3d
         {
@@ -134,7 +134,7 @@ namespace cv
 
             /** @brief Sets the intrinsic parameters of the viewer using Camera.
 
-            @param camera Camera object wrapping intrinsinc parameters.
+            @param camera Camera object wrapping intrinsic parameters.
              */
             void setCamera(const Camera &camera);
 
@@ -186,6 +186,7 @@ namespace cv
             void setWindowSize(const Size &window_size);
 
             /** @brief Returns the name of the window which has been set in the constructor.
+             *  `Viz - ` is prepended to the name if necessary.
              */
             String getWindowName() const;
 
@@ -274,22 +275,22 @@ namespace cv
             @param property Property that will be modified.
             @param value The new value of the property.
 
-            **Rendering property** can be one of the following:
+            Rendering property can be one of the following:
             -   **POINT_SIZE**
             -   **OPACITY**
             -   **LINE_WIDTH**
             -   **FONT_SIZE**
-            -
-            **REPRESENTATION**: Expected values are
+
+            REPRESENTATION: Expected values are
             -   **REPRESENTATION_POINTS**
             -   **REPRESENTATION_WIREFRAME**
             -   **REPRESENTATION_SURFACE**
-            -
-            **IMMEDIATE_RENDERING**:
+
+            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: Expected values are
             -   **SHADING_FLAT**
             -   **SHADING_GOURAUD**
             -   **SHADING_PHONG**
@@ -300,22 +301,22 @@ namespace cv
             @param id Id of the widget.
             @param property Property.
 
-            **Rendering property** can be one of the following:
+            Rendering property can be one of the following:
             -   **POINT_SIZE**
             -   **OPACITY**
             -   **LINE_WIDTH**
             -   **FONT_SIZE**
-            -
-            **REPRESENTATION**: Expected values are
+
+            REPRESENTATION: Expected values are
             -   **REPRESENTATION_POINTS**
             -   **REPRESENTATION_WIREFRAME**
             -   **REPRESENTATION_SURFACE**
-            -
-            **IMMEDIATE_RENDERING**:
+
+            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: Expected values are
             -   **SHADING_FLAT**
             -   **SHADING_GOURAUD**
             -   **SHADING_PHONG**

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

@@ -60,21 +60,24 @@ namespace cv
 
         /** @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.
+        @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
+        @return An affine transform that describes transformation between global coordinate frame
         and a given coordinate frame.
+        The returned transforms can transform a point in the given coordinate frame to the global
+        coordinate frame.
          */
         CV_EXPORTS Affine3d makeTransformToGlobal(const Vec3d& axis_x, const Vec3d& axis_y, const Vec3d& axis_z, const Vec3d& origin = Vec3d::all(0));
 
         /** @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.
+        @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.
          */
@@ -98,7 +101,7 @@ namespace cv
          */
         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.
+        //! Unregisters all Viz windows from internal database. After it 'getWindowByName()' will create new windows instead of getting existing from the database.
         CV_EXPORTS void unregisterAllWindows();
 
         //! Displays image in specified window
@@ -142,7 +145,23 @@ namespace cv
         ///////////////////////////////////////////////////////////////////////////////////////////////
         /// Read/write clouds. Supported formats: ply, xyz, obj and stl (readonly)
 
+        /**
+         * @param file Filename with extension. Supported formats: PLY, XYZ and OBJ.
+         * @param cloud  Supported depths: CV_32F and CV_64F. Supported channels: 3 and 4.
+         * @param colors Used by PLY format only. Supported depth: CV_8U. Supported channels: 1, 3 and 4.
+         * @param normals Used by PLY and OBJ format only. Supported depths: CV_32F and CV_64F.
+         *                Supported channels: 3 and 4.
+         * @param binary Used only for PLY format.
+         */
         CV_EXPORTS void writeCloud(const String& file, InputArray cloud, InputArray colors = noArray(), InputArray normals = noArray(), bool binary = false);
+
+        /**
+         * @param file Filename with extension. Supported formats: PLY, XYZ, OBJ and STL.
+         * @param colors Used by PLY and STL formats only.
+         * @param normals Used by PLY, OBJ and STL formats only.
+         * @return A mat containing the point coordinates with depth CV_32F or CV_64F and number of
+         *         channels 3 or 4 with only 1 row.
+         */
         CV_EXPORTS Mat  readCloud (const String& file, OutputArray colors = noArray(), OutputArray normals = noArray());
 
         ///////////////////////////////////////////////////////////////////////////////////////////////
@@ -153,19 +172,50 @@ namespace cv
         ///////////////////////////////////////////////////////////////////////////////////////////////
         /// Read/write poses and trajectories
 
+        /**
+         * @param file Filename of type supported by cv::FileStorage.
+         * @param pose Output matrix.
+         * @param tag Name of the pose in the file.
+         */
         CV_EXPORTS bool readPose(const String& file, Affine3d& pose, const String& tag = "pose");
+        /**
+         * @param file Filename.
+         * @param pose Input matrix.
+         * @param tag Name of the pose to be saved into the given file.
+         */
         CV_EXPORTS void writePose(const String& file, const Affine3d& pose, const String& tag = "pose");
 
-        //! takes vector<Affine3<T>> with T = float/dobule and writes to a sequence of files with given filename format
+        /** takes vector<Affine3<T>> with T = float/dobule and writes to a sequence of files with given filename format
+         * @param traj Trajectory containing a list of poses. It can be
+         *          - std::vector<cv::Mat>, each cv::Mat is of type CV_32F16 or CV_64FC16
+         *          - std::vector<cv::Affine3f>, std::vector<cv::Affine3d>
+         *          - cv::Mat of type CV_32FC16 OR CV_64F16
+         * @param files_format Format specifier string for constructing filenames.
+         *                     The only placeholder in the string should support `int`.
+         * @param start The initial counter for files_format.
+         * @param tag Name of the matrix in the file.
+         */
         CV_EXPORTS void writeTrajectory(InputArray traj, const String& files_format = "pose%05d.xml", int start = 0, const String& tag = "pose");
 
-        //! takes vector<Affine3<T>> with T = float/dobule and loads poses from sequence of files
+        /** takes vector<Affine3<T>> with T = float/dobule and loads poses from sequence of files
+         *
+         * @param traj Output array containing a lists of poses. It can be
+         *             - std::vector<cv::Affine3f>, std::vector<cv::Affine3d>
+         *             - cv::Mat
+         * @param files_format Format specifier string for constructing filenames.
+         *                     The only placeholder in the string should support `int`.
+         * @param start The initial counter for files_format. It must be greater than or equal to 0.
+         * @param end The final  counter for files_format.
+         * @param tag Name of the matrix in the file.
+         */
         CV_EXPORTS void readTrajectory(OutputArray traj, const String& files_format = "pose%05d.xml", int start = 0, int end = INT_MAX, const String& tag = "pose");
 
 
         ///////////////////////////////////////////////////////////////////////////////////////////////
-        /// Computing normals for mesh
-
+        /** Computing normals for mesh
+         * @param mesh Input mesh.
+         * @param normals Normals at very point in the mesh of type CV_64FC3.
+         */
         CV_EXPORTS void computeNormals(const Mesh& mesh, OutputArray normals);
 
 //! @}

modules/viz/include/opencv2/viz/widgets.hpp

@@ -87,7 +87,7 @@ namespace cv
 
         /////////////////////////////////////////////////////////////////////////////
 
-        /** @brief Base class of all widgets. Widget is implicitly shared. :
+        /** @brief Base class of all widgets. Widget is implicitly shared.
         */
         class CV_EXPORTS Widget
         {
@@ -108,22 +108,22 @@ namespace cv
             @param property Property that will be modified.
             @param value The new value of the property.
 
-            **Rendering property** can be one of the following:
+            Rendering property can be one of the following:
             -   **POINT_SIZE**
             -   **OPACITY**
             -   **LINE_WIDTH**
             -   **FONT_SIZE**
-            -
-            **REPRESENTATION**: Expected values are
+
+            REPRESENTATION: Expected values are
             -   **REPRESENTATION_POINTS**
             -   **REPRESENTATION_WIREFRAME**
             -   **REPRESENTATION_SURFACE**
-            -
-            **IMMEDIATE_RENDERING**:
+
+            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: Expected values are
             -   **SHADING_FLAT**
             -   **SHADING_GOURAUD**
             -   **SHADING_PHONG**
@@ -133,24 +133,24 @@ namespace cv
 
             @param property Property.
 
-            **Rendering property** can be one of the following:
+            Rendering property can be one of the following:
             -   **POINT_SIZE**
             -   **OPACITY**
             -   **LINE_WIDTH**
             -   **FONT_SIZE**
             -   **AMBIENT**
-            -
-            **REPRESENTATION**: Expected values are
-            :   -   **REPRESENTATION_POINTS**
+
+            REPRESENTATION: Expected values are
+            -   **REPRESENTATION_POINTS**
             -   **REPRESENTATION_WIREFRAME**
             -   **REPRESENTATION_SURFACE**
-            -
+
             **IMMEDIATE_RENDERING**:
-            :   -   Turn on immediate rendering by setting the value to 1.
+            -   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: Expected values are
+            -   **SHADING_FLAT**
             -   **SHADING_GOURAUD**
             -   **SHADING_PHONG**
              */
@@ -306,7 +306,7 @@ namespace cv
         class CV_EXPORTS WCircle : public Widget3D
         {
         public:
-            /** @brief Constructs default planar circle centred at origin with plane normal along z-axis
+            /** @brief Constructs default planar circle centered at origin with plane normal along z-axis
 
             @param radius Radius of the circle.
             @param thickness Thickness of the circle.

modules/viz/src/clouds.cpp

@@ -89,10 +89,8 @@ cv::viz::WCloud::WCloud(cv::InputArray cloud, cv::InputArray colors, cv::InputAr
     actor->SetMapper(mapper);
 
     WidgetAccessor::setProp(*this, actor);
-
 }
 
-
 template<> cv::viz::WCloud cv::viz::Widget::cast<cv::viz::WCloud>()
 {
     Widget3D widget = this->cast<Widget3D>();

modules/viz/src/vizcore.cpp

@@ -169,26 +169,26 @@ cv::viz::Viz3d cv::viz::imshow(const String& window_name, InputArray image, cons
 
 void cv::viz::writeCloud(const String& file, InputArray cloud, InputArray colors, InputArray normals, bool binary)
 {
-    CV_Assert(file.size() > 4 && "Extention is required");
-    String extention = file.substr(file.size()-4);
+    CV_Assert(file.size() > 4 && "Extension is required");
+    String extension = file.substr(file.size()-4);
 
     vtkSmartPointer<vtkCloudMatSource> source = vtkSmartPointer<vtkCloudMatSource>::New();
     source->SetColorCloudNormals(cloud, colors, normals);
 
     vtkSmartPointer<vtkWriter> writer;
-    if (extention == ".xyz")
+    if (extension == ".xyz")
     {
         writer = vtkSmartPointer<vtkXYZWriter>::New();
         vtkXYZWriter::SafeDownCast(writer)->SetFileName(file.c_str());
     }
-    else if (extention == ".ply")
+    else if (extension == ".ply")
     {
         writer = vtkSmartPointer<vtkPLYWriter>::New();
         vtkPLYWriter::SafeDownCast(writer)->SetFileName(file.c_str());
         vtkPLYWriter::SafeDownCast(writer)->SetFileType(binary ? VTK_BINARY : VTK_ASCII);
         vtkPLYWriter::SafeDownCast(writer)->SetArrayName("Colors");
     }
-    else if (extention == ".obj")
+    else if (extension == ".obj")
     {
         writer = vtkSmartPointer<vtkOBJWriter>::New();
         vtkOBJWriter::SafeDownCast(writer)->SetFileName(file.c_str());
@@ -202,27 +202,27 @@ void cv::viz::writeCloud(const String& file, InputArray cloud, InputArray colors
 
 cv::Mat cv::viz::readCloud(const String& file, OutputArray colors, OutputArray normals)
 {
-    CV_Assert(file.size() > 4 && "Extention is required");
-    String extention = file.substr(file.size()-4);
+    CV_Assert(file.size() > 4 && "Extension is required");
+    String extension = file.substr(file.size()-4);
 
     vtkSmartPointer<vtkPolyDataAlgorithm> reader;
-    if (extention == ".xyz")
+    if (extension == ".xyz")
     {
         reader = vtkSmartPointer<vtkXYZReader>::New();
         vtkXYZReader::SafeDownCast(reader)->SetFileName(file.c_str());
     }
-    else if (extention == ".ply")
+    else if (extension == ".ply")
     {
         reader = vtkSmartPointer<vtkPLYReader>::New();
         CV_Assert(vtkPLYReader::CanReadFile(file.c_str()));
         vtkPLYReader::SafeDownCast(reader)->SetFileName(file.c_str());
     }
-    else if (extention == ".obj")
+    else if (extension == ".obj")
     {
         reader = vtkSmartPointer<vtkOBJReader>::New();
         vtkOBJReader::SafeDownCast(reader)->SetFileName(file.c_str());
     }
-    else if (extention == ".stl")
+    else if (extension == ".stl")
     {
         reader = vtkSmartPointer<vtkSTLReader>::New();
         vtkSTLReader::SafeDownCast(reader)->SetFileName(file.c_str());

modules/viz/src/vtk/vtkCloudMatSink.h

@@ -73,13 +73,16 @@ namespace cv
           void WriteData();
           int FillInputPortInformation(int port, vtkInformation *info);
 
-          _OutputArray cloud, colors, normals, tcoords;
+          _OutputArray cloud; //!< point coordinates of type CV_32FC3 or CV_64FC3 with only 1 row
+          _OutputArray colors; //!< point color of type CV_8UC3 or CV_8UC4 with only 1 row
+          _OutputArray normals; //!< point normal of type CV_32FC3, CV_32FC4, CV_64FC3 or CV_64FC4 with only 1 row
+          _OutputArray tcoords; //!< texture coordinates of type CV_32FC2 or CV_64FC2 with only 1 row
 
         private:
           vtkCloudMatSink(const vtkCloudMatSink&);  // Not implemented.
           void operator=(const vtkCloudMatSink&);  // Not implemented.
         };
-    }
-}
+    } // end namespace viz
+} // end namespace cv
 
 #endif

modules/viz/src/vtk/vtkVizInteractorStyle.hpp

@@ -109,7 +109,7 @@ namespace cv
             vtkSetMacro(MotionAccelerationFactor,double)
             vtkGetMacro(MotionAccelerationFactor,double)
 
-            // Set the basic angular unit for turning : efault 1 degree
+            // Set the basic angular unit for turning : default 1 degree
             vtkSetMacro(AngleStepSize,double)
             vtkGetMacro(AngleStepSize,double)
 
@@ -163,7 +163,7 @@ namespace cv
             double        DeltaYaw;
             double        DeltaPitch;
         };
-    }
-}
+    } // end namespace viz
+} // end namespace cv
 
 #endif

modules/viz/src/widget.cpp

@@ -181,7 +181,7 @@ void cv::viz::Widget::setRenderingProperty(int property, double value)
             break;
         }
         default:
-            CV_Assert("setPointCloudRenderingProperties: Unknown property");
+            CV_Assert("setRenderingProperty: Unknown property");
     }
     actor->Modified();
 }
@@ -230,7 +230,7 @@ double cv::viz::Widget::getRenderingProperty(int property) const
             break;
         }
         default:
-            CV_Assert("getPointCloudRenderingProperties: Unknown property");
+            CV_Assert("getRenderingProperty: Unknown property");
     }
     return value;
 }