From: Maksim Shabunin Date: Thu, 20 Nov 2014 15:02:44 +0000 (+0300) Subject: Doxygen documentation: viz X-Git-Tag: accepted/tizen/6.0/unified/20201030.111113~2796^2~14 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=397bf7f2b78eb9c4e614c584e080dc9603ce3ec1;p=platform%2Fupstream%2Fopencv.git Doxygen documentation: viz --- diff --git a/modules/viz/include/opencv2/viz.hpp b/modules/viz/include/opencv2/viz.hpp index 6fa6249..3f8353e 100644 --- a/modules/viz/include/opencv2/viz.hpp +++ b/modules/viz/include/opencv2/viz.hpp @@ -51,4 +51,34 @@ #include #include +/** + @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__ */ diff --git a/modules/viz/include/opencv2/viz/types.hpp b/modules/viz/include/opencv2/viz/types.hpp index 169a674..de2d69c 100644 --- a/modules/viz/include/opencv2/viz/types.hpp +++ b/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 */ diff --git a/modules/viz/include/opencv2/viz/viz3d.hpp b/modules/viz/include/opencv2/viz/viz3d.hpp index 9917213..e0ab86f 100644 --- a/modules/viz/include/opencv2/viz/viz3d.hpp +++ b/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 */ diff --git a/modules/viz/include/opencv2/viz/vizcore.hpp b/modules/viz/include/opencv2/viz/vizcore.hpp index 0fde95b..764f9a4 100644 --- a/modules/viz/include/opencv2/viz/vizcore.hpp +++ b/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(&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(&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 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 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 */ diff --git a/modules/viz/include/opencv2/viz/widget_accessor.hpp b/modules/viz/include/opencv2/viz/widget_accessor.hpp index 29352a2..ccc5b28 100644 --- a/modules/viz/include/opencv2/viz/widget_accessor.hpp +++ b/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 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 prop); }; + +//! @} + } } diff --git a/modules/viz/include/opencv2/viz/widgets.hpp b/modules/viz/include/opencv2/viz/widgets.hpp index 611db54..188a01b 100644 --- a/modules/viz/include/opencv2/viz/widgets.hpp +++ b/modules/viz/include/opencv2/viz/widgets.hpp @@ -52,6 +52,10 @@ namespace cv { namespace viz { + +//! @addtogroup viz_widget +//! @{ + ///////////////////////////////////////////////////////////////////////////// /// Widget rendering properties enum RenderingProperties @@ -80,7 +84,9 @@ namespace cv }; ///////////////////////////////////////////////////////////////////////////// - /// The base class for all widgets + + /** @brief Base class of all widgets. Widget is implicitly shared. : + */ class CV_EXPORTS Widget { public: @@ -89,14 +95,75 @@ namespace cv Widget& operator=(const Widget& other); ~Widget(); - //! Create a widget directly from ply file + /** @brief Creates a widget from ply file. + + @param file\_name Ply file name. + */ static Widget fromPlyFile(const String &file_name); - //! Rendering properties of this particular widget + /** @brief Sets rendering property 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(int property, double value); + /** @brief Returns rendering property 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(int property) const; - //! Casting between widgets + /** @brief Casts a widget to another. + + @code + // Create a sphere widget + viz::WSphere sw(Point3f(0.0f,0.0f,0.0f), 0.5f); + // Cast sphere widget to cloud widget + viz::WCloud cw = sw.cast(); + @endcode + + @note 3D Widgets can only be cast to 3D Widgets. 2D Widgets can only be cast to 2D Widgets. + */ template _W cast(); private: class Impl; @@ -105,161 +172,356 @@ namespace cv }; ///////////////////////////////////////////////////////////////////////////// - /// The base class for all 3D widgets + + /** @brief Base class of all 3D widgets. + */ class CV_EXPORTS Widget3D : public Widget { public: Widget3D() {} - //! widget position manipulation, i.e. place where it is rendered + /** @brief Sets pose of the widget. + + @param pose The new pose of the widget. + */ void setPose(const Affine3d &pose); + /** @brief Updates pose of the widget by pre-multiplying its current pose. + + @param pose The pose that the current pose of the widget will be pre-multiplied by. + */ void updatePose(const Affine3d &pose); + /** @brief Returns the current pose of the widget. + */ Affine3d getPose() const; - //! update internal widget data, i.e. points, normals, etc. + /** @brief Transforms internal widget data (i.e. points, normals) using the given transform. + + @param transform Specified transformation to apply. + */ void applyTransform(const Affine3d &transform); + /** @brief Sets the color of the widget. + + @param color color of type Color + */ void setColor(const Color &color); }; ///////////////////////////////////////////////////////////////////////////// - /// The base class for all 2D widgets + + /** @brief Base class of all 2D widgets. + */ class CV_EXPORTS Widget2D : public Widget { public: Widget2D() {} + /** @brief Sets the color of the widget. + + @param color color of type Color + */ void setColor(const Color &color); }; ///////////////////////////////////////////////////////////////////////////// /// Simple widgets + /** @brief This 3D Widget defines a finite line. + */ class CV_EXPORTS WLine : public Widget3D { public: + /** @brief Constructs a WLine. + + @param pt1 Start point of the line. + @param pt2 End point of the line. + @param color Color of the line. + */ WLine(const Point3d &pt1, const Point3d &pt2, const Color &color = Color::white()); }; + /** @brief This 3D Widget defines a finite plane. + */ class CV_EXPORTS WPlane : public Widget3D { public: - //! created default plane with center point at origin and normal oriented along z-axis + /** @brief Constructs a default plane with center point at origin and normal oriented along z-axis. + + @param size Size of the plane + @param color Color of the plane. + */ WPlane(const Size2d& size = Size2d(1.0, 1.0), const Color &color = Color::white()); - //! repositioned plane + /** @brief Constructs a repositioned plane + + @param center Center of the plane + @param normal Plane normal orientation + @param new\_yaxis Up-vector. New orientation of plane y-axis. + @param size + @param color Color of the plane. + */ WPlane(const Point3d& center, const Vec3d& normal, const Vec3d& new_yaxis, const Size2d& size = Size2d(1.0, 1.0), const Color &color = Color::white()); }; + /** @brief This 3D Widget defines a sphere. : + */ class CV_EXPORTS WSphere : public Widget3D { public: + /** @brief Constructs a WSphere. + + @param center Center of the sphere. + @param radius Radius of the sphere. + @param sphere\_resolution Resolution of the sphere. + @param color Color of the sphere. + */ WSphere(const cv::Point3d ¢er, double radius, int sphere_resolution = 10, const Color &color = Color::white()); }; + /** @brief This 3D Widget defines an arrow. + */ class CV_EXPORTS WArrow : public Widget3D { public: + /** @brief Constructs an WArrow. + + @param pt1 Start point of the arrow. + @param pt2 End point of the arrow. + @param thickness Thickness of the arrow. Thickness of arrow head is also adjusted + accordingly. + @param color Color of the arrow. + + Arrow head is located at the end point of the arrow. + */ WArrow(const Point3d& pt1, const Point3d& pt2, double thickness = 0.03, const Color &color = Color::white()); }; + /** @brief This 3D Widget defines a circle. + */ class CV_EXPORTS WCircle : public Widget3D { public: - //! creates default planar circle centred at origin with plane normal along z-axis + /** @brief Constructs default planar circle centred at origin with plane normal along z-axis + + @param radius Radius of the circle. + @param thickness Thickness of the circle. + @param color Color of the circle. + */ WCircle(double radius, double thickness = 0.01, const Color &color = Color::white()); - //! creates repositioned circle + /** @brief Constructs repositioned planar circle. + + @param radius Radius of the circle. + @param center Center of the circle. + @param normal Normal of the plane in which the circle lies. + @param thickness Thickness of the circle. + @param color Color of the circle. + */ WCircle(double radius, const Point3d& center, const Vec3d& normal, double thickness = 0.01, const Color &color = Color::white()); }; + /** @brief This 3D Widget defines a cone. : + */ class CV_EXPORTS WCone : public Widget3D { public: - //! create default cone, oriented along x-axis with center of its base located at origin + /** @brief Constructs default cone oriented along x-axis with center of its base located at origin + + @param length Length of the cone. + @param radius Radius of the cone. + @param resolution Resolution of the cone. + @param color Color of the cone. + */ WCone(double length, double radius, int resolution = 6.0, const Color &color = Color::white()); - //! creates repositioned cone + /** @brief Constructs repositioned planar cone. + + @param radius Radius of the cone. + @param center Center of the cone base. + @param tip Tip of the cone. + @param resolution Resolution of the cone. + @param color Color of the cone. + + */ WCone(double radius, const Point3d& center, const Point3d& tip, int resolution = 6.0, const Color &color = Color::white()); }; + /** @brief This 3D Widget defines a cylinder. : + */ class CV_EXPORTS WCylinder : public Widget3D { public: + /** @brief Constructs a WCylinder. + + @param axis\_point1 A point1 on the axis of the cylinder. + @param axis\_point2 A point2 on the axis of the cylinder. + @param radius Radius of the cylinder. + @param numsides Resolution of the cylinder. + @param color Color of the cylinder. + */ WCylinder(const Point3d& axis_point1, const Point3d& axis_point2, double radius, int numsides = 30, const Color &color = Color::white()); }; + /** @brief This 3D Widget defines a cube. + */ class CV_EXPORTS WCube : public Widget3D { public: + /** @brief Constructs a WCube. + + @param min_point Specifies minimum point of the bounding box. + @param max_point Specifies maximum point of the bounding box. + @param wire\_frame If true, cube is represented as wireframe. + @param color Color of the cube. + + ![Cube Widget](images/cube_widget.png) + */ WCube(const Point3d& min_point = Vec3d::all(-0.5), const Point3d& max_point = Vec3d::all(0.5), bool wire_frame = true, const Color &color = Color::white()); }; + /** @brief This 3D Widget defines a poly line. : + */ class CV_EXPORTS WPolyLine : public Widget3D { public: WPolyLine(InputArray points, InputArray colors); + /** @brief Constructs a WPolyLine. + + @param points Point set. + @param color Color of the poly line. + */ WPolyLine(InputArray points, const Color &color = Color::white()); }; ///////////////////////////////////////////////////////////////////////////// /// Text and image widgets + /** @brief This 2D Widget represents text overlay. + */ class CV_EXPORTS WText : public Widget2D { public: + /** @brief Constructs a WText. + + @param text Text content of the widget. + @param pos Position of the text. + @param font\_size Font size. + @param color Color of the text. + */ WText(const String &text, const Point &pos, int font_size = 20, const Color &color = Color::white()); + /** @brief Sets the text content of the widget. + + @param text Text content of the widget. + */ void setText(const String &text); + /** @brief Returns the current text content of the widget. + */ String getText() const; }; + /** @brief This 3D Widget represents 3D text. The text always faces the camera. + */ class CV_EXPORTS WText3D : public Widget3D { public: - //! creates text label in 3D. If face_camera = false, text plane normal is oriented along z-axis. Use widget pose to orient it properly + /** @brief Constructs a WText3D. + + @param text Text content of the widget. + @param position Position of the text. + @param text\_scale Size of the text. + @param face\_camera If true, text always faces the camera. + @param color Color of the text. + */ WText3D(const String &text, const Point3d &position, double text_scale = 1., bool face_camera = true, const Color &color = Color::white()); + /** @brief Sets the text content of the widget. + + @param text Text content of the widget. + + */ void setText(const String &text); + /** @brief Returns the current text content of the widget. + */ String getText() const; }; + /** @brief This 2D Widget represents an image overlay. : + */ class CV_EXPORTS WImageOverlay : public Widget2D { public: + /** @brief Constructs an WImageOverlay. + + @param image BGR or Gray-Scale image. + @param rect Image is scaled and positioned based on rect. + */ WImageOverlay(InputArray image, const Rect &rect); + /** @brief Sets the image content of the widget. + + @param image BGR or Gray-Scale image. + */ void setImage(InputArray image); }; + /** @brief This 3D Widget represents an image in 3D space. : + */ class CV_EXPORTS WImage3D : public Widget3D { public: - //! Creates 3D image in a plane centered at the origin with normal orientaion along z-axis, - //! image x- and y-axes are oriented along x- and y-axes of 3d world + /** @brief Constructs an WImage3D. + + @param image BGR or Gray-Scale image. + @param size Size of the image. + */ WImage3D(InputArray image, const Size2d &size); - //! Creates 3D image at a given position, pointing in the direction of the normal, and having the up_vector orientation + /** @brief Constructs an WImage3D. + + @param image BGR or Gray-Scale image. + @param size Size of the image. + @param center Position of the image. + @param normal Normal of the plane that represents the image. + @param up\_vector Determines orientation of the image. + */ WImage3D(InputArray image, const Size2d &size, const Vec3d ¢er, const Vec3d &normal, const Vec3d &up_vector); + /** @brief Sets the image content of the widget. + + @param image BGR or Gray-Scale image. + */ void setImage(InputArray image); }; ///////////////////////////////////////////////////////////////////////////// /// Compond widgets + /** @brief This 3D Widget represents a coordinate system. : + */ class CV_EXPORTS WCoordinateSystem : public Widget3D { public: + /** @brief Constructs a WCoordinateSystem. + + @param scale Determines the size of the axes. + */ WCoordinateSystem(double scale = 1.0); }; + /** @brief This 3D Widget defines a grid. : + */ class CV_EXPORTS WGrid : public Widget3D { public: - //! Creates grid at the origin and normal oriented along z-axis + /** @brief Constructs a WGrid. + + @param cells Number of cell columns and rows, respectively. + @param cells\_spacing Size of each cell, respectively. + @param color Color of the grid. + */ WGrid(const Vec2i &cells = Vec2i::all(10), const Vec2d &cells_spacing = Vec2d::all(1.0), const Color &color = Color::white()); //! Creates repositioned grid @@ -267,47 +529,134 @@ namespace cv const Vec2i &cells = Vec2i::all(10), const Vec2d &cells_spacing = Vec2d::all(1.0), const Color &color = Color::white()); }; + /** @brief This 3D Widget represents camera position in a scene by its axes or viewing frustum. : + */ class CV_EXPORTS WCameraPosition : public Widget3D { public: - //! Creates camera coordinate frame (axes) at the origin + /** @brief Creates camera coordinate frame at the origin. + + ![Camera coordinate frame](images/cpw1.png) + */ WCameraPosition(double scale = 1.0); - //! Creates frustum based on the intrinsic marix K at the origin + /** @brief Display the viewing frustum + @param K Intrinsic matrix of the camera. + @param scale Scale of the frustum. + @param color Color of the frustum. + + Creates viewing frustum of the camera based on its intrinsic matrix K. + + ![Camera viewing frustum](images/cpw2.png) + */ WCameraPosition(const Matx33d &K, double scale = 1.0, const Color &color = Color::white()); - //! Creates frustum based on the field of view at the origin + /** @brief Display the viewing frustum + @param fov Field of view of the camera (horizontal, vertical). + @param scale Scale of the frustum. + @param color Color of the frustum. + + Creates viewing frustum of the camera based on its field of view fov. + + ![Camera viewing frustum](images/cpw2.png) + */ WCameraPosition(const Vec2d &fov, double scale = 1.0, const Color &color = Color::white()); - //! Creates frustum and display given image at the far plane + /** @brief Display image on the far plane of the viewing frustum + + @param K Intrinsic matrix of the camera. + @param image BGR or Gray-Scale image that is going to be displayed on the far plane of the frustum. + @param scale Scale of the frustum and image. + @param color Color of the frustum. + + Creates viewing frustum of the camera based on its intrinsic matrix K, and displays image on + the far end plane. + + ![Camera viewing frustum with image](images/cpw3.png) + */ WCameraPosition(const Matx33d &K, InputArray image, double scale = 1.0, const Color &color = Color::white()); - //! Creates frustum and display given image at the far plane + /** @brief Display image on the far plane of the viewing frustum + + @param fov Field of view of the camera (horizontal, vertical). + @param image BGR or Gray-Scale image that is going to be displayed on the far plane of the frustum. + @param scale Scale of the frustum and image. + @param color Color of the frustum. + + Creates viewing frustum of the camera based on its intrinsic matrix K, and displays image on + the far end plane. + + ![Camera viewing frustum with image](images/cpw3.png) + */ WCameraPosition(const Vec2d &fov, InputArray image, double scale = 1.0, const Color &color = Color::white()); }; ///////////////////////////////////////////////////////////////////////////// /// Trajectories + /** @brief This 3D Widget represents a trajectory. : + */ class CV_EXPORTS WTrajectory : public Widget3D { public: enum {FRAMES = 1, PATH = 2, BOTH = FRAMES + PATH }; - //! Takes vector> and displays trajectory of the given path either by coordinate frames or polyline + /** @brief Constructs a WTrajectory. + + @param path List of poses on a trajectory. Takes std::vector\\> with T == [float | double] + @param display\_mode Display mode. This can be PATH, FRAMES, and BOTH. + @param scale Scale of the frames. Polyline is not affected. + @param color Color of the polyline that represents path. + + Frames are not affected. + Displays trajectory of the given path as follows: + - PATH : Displays a poly line that represents the path. + - FRAMES : Displays coordinate frames at each pose. + - PATH & FRAMES : Displays both poly line and coordinate frames. + */ WTrajectory(InputArray path, int display_mode = WTrajectory::PATH, double scale = 1.0, const Color &color = Color::white()); }; + /** @brief This 3D Widget represents a trajectory. : + */ class CV_EXPORTS WTrajectoryFrustums : public Widget3D { public: - //! Takes vector> and displays trajectory of the given path by frustums + /** @brief Constructs a WTrajectoryFrustums. + + @param path List of poses on a trajectory. Takes std::vector\\> with T == [float | double] + @param K Intrinsic matrix of the camera. + @param scale Scale of the frustums. + @param color Color of the frustums. + + Displays frustums at each pose of the trajectory. + */ WTrajectoryFrustums(InputArray path, const Matx33d &K, double scale = 1., const Color &color = Color::white()); - //! Takes vector> and displays trajectory of the given path by frustums + /** @brief Constructs a WTrajectoryFrustums. + + @param path List of poses on a trajectory. Takes std::vector\\> with T == [float | double] + @param fov Field of view of the camera (horizontal, vertical). + @param scale Scale of the frustums. + @param color Color of the frustums. + + Displays frustums at each pose of the trajectory. + */ WTrajectoryFrustums(InputArray path, const Vec2d &fov, double scale = 1., const Color &color = Color::white()); }; + /** @brief This 3D Widget represents a trajectory using spheres and lines + + where spheres represent the positions of the camera, and lines represent the direction from + previous position to the current. : + */ class CV_EXPORTS WTrajectorySpheres: public Widget3D { public: - //! Takes vector> and displays trajectory of the given path + /** @brief Constructs a WTrajectorySpheres. + + @param path List of poses on a trajectory. Takes std::vector\\> with T == [float | double] + @param line\_length Max length of the lines which point to previous position + @param radius Radius of the spheres. + @param from Color for first sphere. + @param to Color for last sphere. Intermediate spheres will have interpolated color. + */ WTrajectorySpheres(InputArray path, double line_length = 0.05, double radius = 0.007, const Color &from = Color::red(), const Color &to = Color::white()); }; @@ -315,19 +664,47 @@ namespace cv ///////////////////////////////////////////////////////////////////////////// /// Clouds + /** @brief This 3D Widget defines a point cloud. : + + @note In case there are four channels in the cloud, fourth channel is ignored. + */ class CV_EXPORTS WCloud: public Widget3D { public: - //! Each point in cloud is mapped to a color in colors + /** @brief Constructs a WCloud. + + @param cloud Set of points which can be of type: CV\_32FC3, CV\_32FC4, CV\_64FC3, CV\_64FC4. + @param colors Set of colors. It has to be of the same size with cloud. + + Points in the cloud belong to mask when they are set to (NaN, NaN, NaN). + */ WCloud(InputArray cloud, InputArray colors); - //! All points in cloud have the same color + /** @brief Constructs a WCloud. + @param cloud Set of points which can be of type: CV\_32FC3, CV\_32FC4, CV\_64FC3, CV\_64FC4. + @param color A single Color for the whole cloud. + + Points in the cloud belong to mask when they are set to (NaN, NaN, NaN). + */ WCloud(InputArray cloud, const Color &color = Color::white()); - //! Each point in cloud is mapped to a color in colors, normals are used for shading + /** @brief Constructs a WCloud. + @param cloud Set of points which can be of type: CV\_32FC3, CV\_32FC4, CV\_64FC3, CV\_64FC4. + @param colors Set of colors. It has to be of the same size with cloud. + @param normals Normals for each point in cloud. Size and type should match with the cloud parameter. + + Points in the cloud belong to mask when they are set to (NaN, NaN, NaN). + */ WCloud(InputArray cloud, InputArray colors, InputArray normals); - //! All points in cloud have the same color, normals are used for shading + /** @brief Constructs a WCloud. + @param cloud Set of points which can be of type: CV\_32FC3, CV\_32FC4, CV\_64FC3, CV\_64FC4. + @param color A single Color for the whole cloud. + @param normals Normals for each point in cloud. + + Size and type should match with the cloud parameter. + Points in the cloud belong to mask when they are set to (NaN, NaN, NaN). + */ WCloud(InputArray cloud, const Color &color, InputArray normals); }; @@ -344,25 +721,61 @@ namespace cv WPaintedCloud(InputArray cloud, const Point3d& p1, const Point3d& p2, const Color& c1, const Color c2); }; + /** @brief This 3D Widget defines a collection of clouds. : + @note In case there are four channels in the cloud, fourth channel is ignored. + */ class CV_EXPORTS WCloudCollection : public Widget3D { public: WCloudCollection(); - //! Each point in cloud is mapped to a color in colors + /** @brief Adds a cloud to the collection. + + @param cloud Point set which can be of type: CV\_32FC3, CV\_32FC4, CV\_64FC3, CV\_64FC4. + @param colors Set of colors. It has to be of the same size with cloud. + @param pose Pose of the cloud. Points in the cloud belong to mask when they are set to (NaN, NaN, NaN). + */ void addCloud(InputArray cloud, InputArray colors, const Affine3d &pose = Affine3d::Identity()); - //! All points in cloud have the same color + /** @brief Adds a cloud to the collection. + + @param cloud Point set which can be of type: CV\_32FC3, CV\_32FC4, CV\_64FC3, CV\_64FC4. + @param color A single Color for the whole cloud. + @param pose Pose of the cloud. Points in the cloud belong to mask when they are set to (NaN, NaN, NaN). + */ void addCloud(InputArray cloud, const Color &color = Color::white(), const Affine3d &pose = Affine3d::Identity()); - //! Repacks internal structure to single cloud + /** @brief Finalizes cloud data by repacking to single cloud. + + Useful for large cloud collections to reduce memory usage + */ void finalize(); }; + /** @brief This 3D Widget represents normals of a point cloud. : + */ class CV_EXPORTS WCloudNormals : public Widget3D { public: + /** @brief Constructs a WCloudNormals. + + @param cloud Point set which can be of type: CV\_32FC3, CV\_32FC4, CV\_64FC3, CV\_64FC4. + @param normals A set of normals that has to be of same type with cloud. + @param level Display only every level th normal. + @param scale Scale of the arrows that represent normals. + @param color Color of the arrows that represent normals. + + @note In case there are four channels in the cloud, fourth channel is ignored. + */ WCloudNormals(InputArray cloud, InputArray normals, int level = 64, double scale = 0.1, const Color &color = Color::white()); }; + /** @brief Constructs a WMesh. + + @param mesh Mesh object that will be displayed. + @param cloud Points of the mesh object. + @param polygons Points of the mesh object. + @param colors Point colors. + @param normals Point normals. + */ class CV_EXPORTS WMesh : public Widget3D { public: @@ -370,6 +783,13 @@ namespace cv WMesh(InputArray cloud, InputArray polygons, InputArray colors = noArray(), InputArray normals = noArray()); }; + /** @brief This class allows to merge several widgets to single one. + + It has quite limited functionality and can't merge widgets with different attributes. For + instance, if widgetA has color array and widgetB has only global color defined, then result + of merge won't have color at all. The class is suitable for merging large amount of similar + widgets. : + */ class CV_EXPORTS WWidgetMerger : public Widget3D { public: @@ -413,6 +833,8 @@ namespace cv template<> CV_EXPORTS WMesh Widget::cast(); template<> CV_EXPORTS WWidgetMerger Widget::cast(); +//! @} + } /* namespace viz */ } /* namespace cv */