diff --git a/modules/calib3d/src/homography_decomp.cpp b/modules/calib3d/src/homography_decomp.cpp index 0411c4dd1e..3ee2cdbc87 100644 --- a/modules/calib3d/src/homography_decomp.cpp +++ b/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; diff --git a/modules/viz/include/opencv2/viz.hpp b/modules/viz/include/opencv2/viz.hpp index b896ef7670..fc79b8b60e 100644 --- a/modules/viz/include/opencv2/viz.hpp +++ b/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. diff --git a/modules/viz/include/opencv2/viz/types.hpp b/modules/viz/include/opencv2/viz/types.hpp index f1f0164c4c..62068ac898 100644 --- a/modules/viz/include/opencv2/viz/types.hpp +++ b/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_; }; diff --git a/modules/viz/include/opencv2/viz/viz3d.hpp b/modules/viz/include/opencv2/viz/viz3d.hpp index 86e4a3839b..226c9e90c4 100644 --- a/modules/viz/include/opencv2/viz/viz3d.hpp +++ b/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** diff --git a/modules/viz/include/opencv2/viz/vizcore.hpp b/modules/viz/include/opencv2/viz/vizcore.hpp index c32802cbee..bab7ea55c4 100644 --- a/modules/viz/include/opencv2/viz/vizcore.hpp +++ b/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> with T = float/dobule and writes to a sequence of files with given filename format + /** takes vector> 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, each cv::Mat is of type CV_32F16 or CV_64FC16 + * - std::vector, std::vector + * - 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> with T = float/dobule and loads poses from sequence of files + /** takes vector> 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, std::vector + * - 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); //! @} diff --git a/modules/viz/include/opencv2/viz/widgets.hpp b/modules/viz/include/opencv2/viz/widgets.hpp index dc05d77795..dcc1165660 100644 --- a/modules/viz/include/opencv2/viz/widgets.hpp +++ b/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. diff --git a/modules/viz/src/clouds.cpp b/modules/viz/src/clouds.cpp index ab8fd43e40..6e47f928c3 100644 --- a/modules/viz/src/clouds.cpp +++ b/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() { Widget3D widget = this->cast(); diff --git a/modules/viz/src/vizcore.cpp b/modules/viz/src/vizcore.cpp index a33a192c6c..3efc3a91c4 100644 --- a/modules/viz/src/vizcore.cpp +++ b/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 source = vtkSmartPointer::New(); source->SetColorCloudNormals(cloud, colors, normals); vtkSmartPointer writer; - if (extention == ".xyz") + if (extension == ".xyz") { writer = vtkSmartPointer::New(); vtkXYZWriter::SafeDownCast(writer)->SetFileName(file.c_str()); } - else if (extention == ".ply") + else if (extension == ".ply") { writer = vtkSmartPointer::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::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 reader; - if (extention == ".xyz") + if (extension == ".xyz") { reader = vtkSmartPointer::New(); vtkXYZReader::SafeDownCast(reader)->SetFileName(file.c_str()); } - else if (extention == ".ply") + else if (extension == ".ply") { reader = vtkSmartPointer::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::New(); vtkOBJReader::SafeDownCast(reader)->SetFileName(file.c_str()); } - else if (extention == ".stl") + else if (extension == ".stl") { reader = vtkSmartPointer::New(); vtkSTLReader::SafeDownCast(reader)->SetFileName(file.c_str()); diff --git a/modules/viz/src/vtk/vtkCloudMatSink.h b/modules/viz/src/vtk/vtkCloudMatSink.h index fc778f0c5b..997e6984a0 100644 --- a/modules/viz/src/vtk/vtkCloudMatSink.h +++ b/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 diff --git a/modules/viz/src/vtk/vtkVizInteractorStyle.hpp b/modules/viz/src/vtk/vtkVizInteractorStyle.hpp index 3588a3b6cd..c9458ae064 100644 --- a/modules/viz/src/vtk/vtkVizInteractorStyle.hpp +++ b/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 diff --git a/modules/viz/src/widget.cpp b/modules/viz/src/widget.cpp index b324a4e26c..64c5aaa305 100644 --- a/modules/viz/src/widget.cpp +++ b/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; }