comments on widgets where constructors might be confusing

modules/viz/include/opencv2/viz.hpp

@@ -65,9 +65,10 @@ namespace cv
         //! takes coordiante frame data and builds transfrom to global coordinate frame
         CV_EXPORTS Affine3f makeTransformToGlobal(const Vec3f& axis_x, const Vec3f& axis_y, const Vec3f& axis_z, const Vec3f& origin = Vec3f::all(0));
 
-        //! constructs camera pose from position, focal_point and up_vector (see gluLookAt() for more infromation
+        //! constructs camera pose from position, focal_point and up_vector (see gluLookAt() for more infromation)
         CV_EXPORTS Affine3f makeCameraPose(const Vec3f& position, const Vec3f& focal_point, const Vec3f& y_dir);
 
+        //! retrieves a window by its name
         CV_EXPORTS Viz3d get(const String &window_name);
 
         //! checks float value for Nan
@@ -92,6 +93,7 @@ namespace cv
         template<typename _Tp> inline bool isNan(const Point3_<_Tp>& p)
         { return isNan(p.x) || isNan(p.y) || isNan(p.z); }
         
+        //! helper class that provides access by name infrastructure
         class CV_EXPORTS VizAccessor
         {
         public:
@@ -102,6 +104,7 @@ namespace cv
             void add(Viz3d window);
             void remove(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:
@@ -112,8 +115,8 @@ namespace cv
             static bool is_instantiated_;
             static VizMap viz_map_;
         };
-    }
-}
+    } /* namespace viz */
+} /* namespace cv */
 
 
 #endif /* __OPENCV_VIZ_HPP__ */

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

@@ -39,6 +39,7 @@ namespace cv
             Mat cloud, colors;
             Mat polygons;
 
+            //! Loads mesh from a given ply file
             static cv::viz::Mesh3d loadMesh(const String& file);
             
         private:
@@ -52,14 +53,8 @@ namespace cv
             static const unsigned int Ctrl  = 2;
             static const unsigned int Shift = 4;
 
-            /** \brief Constructor
-              * \param[in] action    true for key was pressed, false for released
-              * \param[in] key_sym   the key-name that caused the action
-              * \param[in] key       the key code that caused the action
-              * \param[in] alt       whether the alt key was pressed at the time where this event was triggered
-              * \param[in] ctrl      whether the ctrl was pressed at the time where this event was triggered
-              * \param[in] shift     whether the shift was pressed at the time where this event was triggered
-              */
+            //! 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;

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

@@ -18,11 +18,14 @@ namespace cv
             Widget& operator=(const Widget& other);
             ~Widget();
             
+            //! Create a widget directly from ply file
             static Widget fromPlyFile(const String &file_name);
             
+            //! Rendering properties of this particular widget
             void setRenderingProperty(int property, double value);
             double getRenderingProperty(int property) const;
 
+            //! Casting between widgets
             template<typename _W> _W cast();
         private:
             class Impl;
@@ -120,7 +123,9 @@ namespace cv
         class CV_EXPORTS GridWidget : public Widget3D
         {
         public:
+            //! Creates grid at the origin
             GridWidget(const Vec2i &dimensions, const Vec2d &spacing, const Color &color = Color::white());
+            //! Creates grid based on the plane equation
             GridWidget(const Vec4f &coeffs, const Vec2i &dimensions, const Vec2d &spacing, const Color &color = Color::white());
             
         private:
@@ -157,7 +162,9 @@ namespace cv
         class CV_EXPORTS Image3DWidget : public Widget3D
         {
         public:
+            //! Creates 3D image at the origin
             Image3DWidget(const Mat &image, const Size &size);
+            //! Creates 3D image at a given position, pointing in the direction of the normal, and having the up_vector orientation
             Image3DWidget(const Vec3f &position, const Vec3f &normal, const Vec3f &up_vector, const Mat &image, const Size &size);
             
             void setImage(const Mat &image);
@@ -166,11 +173,14 @@ namespace cv
         class CV_EXPORTS CameraPositionWidget : public Widget3D
         {
         public:
+            //! Creates camera coordinate frame (axes) at the origin
             CameraPositionWidget(double scale = 1.0);
+            //! Creates frustum based on the intrinsic marix K at the origin
             CameraPositionWidget(const Matx33f &K, double scale = 1.0, const Color &color = Color::white());
+            //! Creates frustum based on the field of view at the origin
             CameraPositionWidget(const Vec2f &fov, double scale = 1.0, const Color &color = Color::white());
+            //! Creates frustum and display given image at the far plane
             CameraPositionWidget(const Matx33f &K, const Mat &img, double scale = 1.0, const Color &color = Color::white());
-            
         };
         
         class CV_EXPORTS TrajectoryWidget : public Widget3D
@@ -178,9 +188,12 @@ namespace cv
         public:
             enum {DISPLAY_FRAMES = 1, DISPLAY_PATH = 2};
             
+            //! Displays trajectory of the given path either by coordinate frames or polyline
             TrajectoryWidget(const std::vector<Affine3f> &path, int display_mode = TrajectoryWidget::DISPLAY_PATH, const Color &color = Color::white(), double scale = 1.0);
-            TrajectoryWidget(const std::vector<Affine3f> &path, const Matx33f &K, double scale = 1.0, const Color &color = Color::white()); // Camera frustums
-            TrajectoryWidget(const std::vector<Affine3f> &path, const Vec2f &fov, double scale = 1.0, const Color &color = Color::white()); // Camera frustums
+            //! Displays trajectory of the given path by frustums
+            TrajectoryWidget(const std::vector<Affine3f> &path, const Matx33f &K, double scale = 1.0, const Color &color = Color::white());
+            //! Displays trajectory of the given path by frustums
+            TrajectoryWidget(const std::vector<Affine3f> &path, const Vec2f &fov, double scale = 1.0, const Color &color = Color::white());
             
         private:
             struct ApplyPath;
@@ -196,7 +209,9 @@ namespace cv
         class CV_EXPORTS CloudWidget : public Widget3D
         {
         public:
+            //! Each point in cloud is mapped to a color in colors
             CloudWidget(InputArray cloud, InputArray colors);
+            //! All points in cloud have the same color
             CloudWidget(InputArray cloud, const Color &color = Color::white());
 
         private:
@@ -208,7 +223,9 @@ namespace cv
         public:
             CloudCollectionWidget();
             
+            //! Each point in cloud is mapped to a color in colors
             void addCloud(InputArray cloud, InputArray colors, const Affine3f &pose = Affine3f::Identity());
+            //! All points in cloud have the same color
             void addCloud(InputArray cloud, const Color &color = Color::white(), const Affine3f &pose = Affine3f::Identity());
             
         private: