Skip to content

O
opencv
Commit 397bf7f2 authored by Maksim Shabunin's avatar Maksim Shabunin
Browse files
Options

Doxygen documentation: viz

parent 9d89f8d3
Expand all Hide whitespace changes
Inline Side-by-side
Showing with 376 additions and 10 deletions
modules/viz/include/opencv2/viz.hpp
View file @ 397bf7f2
......@@ -51,4 +51,34 @@
#include <opencv2/viz/viz3d.hpp>
#include <opencv2/viz/vizcore.hpp>
/**
@defgroup viz 3D Visualizer
This section describes 3D visualization window as well as classes and methods that are used to
interact with it.
3D visualization window (see Viz3d) is used to display widgets (see Widget), and it provides several
methods to interact with scene and widgets.
@{
@defgroup viz_widget Widget
In this section, the widget framework is explained. Widgets represent 2D or 3D objects, varying from
simple ones such as lines to complex one such as point clouds and meshes.
Widgets are **implicitly shared**. Therefore, one can add a widget to the scene, and modify the
widget without re-adding the widget.
@code
// Create a cloud widget
viz::WCloud cw(cloud, viz::Color::red());
// Display it in a window
myWindow.showWidget("CloudWidget1", cw);
// Modify it, and it will be modified in the window.
cw.setColor(viz::Color::yellow());
@endcode
@}
*/
#endif /* __OPENCV_VIZ_HPP__ */
modules/viz/include/opencv2/viz/types.hpp
View file @ 397bf7f2
......@@ -54,6 +54,12 @@ namespace cv
{
namespace viz
{
//! @addtogroup viz
//! @{
/** @brief This class a represents BGR color.
*/
class Color : public Scalar
{
public:
......@@ -108,6 +114,8 @@ namespace cv
static Color not_set();
};
/** @brief This class wraps mesh attributes, and it can load a mesh from a ply file. :
*/
class CV_EXPORTS Mesh
{
public:
......@@ -119,16 +127,49 @@ namespace cv
Mat texture, tcoords;
//! Loads mesh from a given ply file (no texture load support for now)
/** @brief Loads a mesh from a ply file.
@param file File name (for now only PLY is supported)
*/
static Mesh load(const String& file);
};
/** @brief This class wraps intrinsic parameters of a camera.
It provides several constructors that can extract the intrinsic parameters from field of
view, intrinsic matrix and projection matrix. :
*/
class CV_EXPORTS Camera
{
public:
/** @brief Constructs a Camera.
@param fx Horizontal focal length.
@param fy Vertical focal length.
@param cx x coordinate of the principal point.
@param cy y coordinate of the principal point.
@param window_size Size of the window. This together with focal length and principal
point determines the field of view.
*/
Camera(double fx, double fy, double cx, double cy, const Size &window_size);
/** @overload
@param fov Field of view (horizontal, vertical)
@param window\_size Size of the window. Principal point is at the center of the window
by default.
*/
explicit Camera(const Vec2d &fov, const Size &window_size);
/** @overload
@param K Intrinsic matrix of the camera.
@param window\_size Size of the window. This together with intrinsic matrix determines
the field of view.
*/
explicit Camera(const Matx33d &K, const Size &window_size);
/** @overload
@param proj Projection matrix of the camera.
@param window\_size Size of the window. This together with projection matrix determines
the field of view.
*/
explicit Camera(const Matx44d &proj, const Size &window_size);
const Vec2d & getClip() const { return clip_; }
......@@ -143,8 +184,17 @@ namespace cv
const Vec2d& getPrincipalPoint() const { return principal_point_; }
const Vec2d& getFocalLength() const { return focal_; }
/** @brief Computes projection matrix using intrinsic parameters of the camera.
@param proj Output projection matrix.
*/
void computeProjectionMatrix(Matx44d &proj) const;
/** @brief Creates a Kinect Camera.
@param window\_size Size of the window. This together with intrinsic matrix of a Kinect Camera
determines the field of view.
*/
static Camera KinectCamera(const Size &window_size);
private:
......@@ -157,12 +207,21 @@ namespace cv
Vec2d focal_;
};
/** @brief This class represents a keyboard event.
*/
class CV_EXPORTS KeyboardEvent
{
public:
enum { NONE = 0, ALT = 1, CTRL = 2, SHIFT = 4 };
enum Action { KEY_UP = 0, KEY_DOWN = 1 };
/** @brief Constructs a KeyboardEvent.
@param action Signals if key is pressed or released.
@param symbol Name of the key.
@param code Code of the key.
@param modifiers Signals if alt, ctrl or shift are pressed or their combination.
*/
KeyboardEvent(Action action, const String& symbol, unsigned char code, int modifiers);
Action action;
......@@ -171,12 +230,23 @@ namespace cv
int modifiers;
};
/** @brief This class represents a mouse event.
*/
class CV_EXPORTS MouseEvent
{
public:
enum Type { MouseMove = 1, MouseButtonPress, MouseButtonRelease, MouseScrollDown, MouseScrollUp, MouseDblClick } ;
enum MouseButton { NoButton = 0, LeftButton, MiddleButton, RightButton, VScroll } ;
/** @brief Constructs a MouseEvent.
@param type Type of the event. This can be **MouseMove**, **MouseButtonPress**,
**MouseButtonRelease**, **MouseScrollDown**, **MouseScrollUp**, **MouseDblClick**.
@param button Mouse button. This can be **NoButton**, **LeftButton**, **MiddleButton**,
**RightButton**, **VScroll**.
@param pointer Position of the event.
@param modifiers Signals if alt, ctrl or shift are pressed or their combination.
*/
MouseEvent(const Type& type, const MouseButton& button, const Point& pointer, int modifiers);
Type type;
......@@ -184,6 +254,9 @@ namespace cv
Point pointer;
int modifiers;
};
//! @} viz
} /* namespace viz */
} /* namespace cv */
......
modules/viz/include/opencv2/viz/viz3d.hpp
View file @ 397bf7f2
......@@ -58,6 +58,12 @@ namespace cv
{
namespace viz
{
//! @addtogroup viz
//! @{
/** @brief The Viz3d class represents a 3D visualizer window. This class is implicitly shared. :
*/
class CV_EXPORTS Viz3d
{
public:
......@@ -65,54 +71,240 @@ namespace cv
typedef void (*KeyboardCallback)(const KeyboardEvent&, void*);
typedef void (*MouseCallback)(const MouseEvent&, void*);
/** @brief The constructors.
@param window\_name Name of the window.
*/
Viz3d(const String& window_name = String());
Viz3d(const Viz3d&);
Viz3d& operator=(const Viz3d&);
~Viz3d();
/** @brief Shows a widget in the window.
@param id A unique id for the widget. @param widget The widget to be displayed in the window.
@param pose Pose of the widget.
*/
void showWidget(const String &id, const Widget &widget, const Affine3d &pose = Affine3d::Identity());
/** @brief Removes a widget from the window.
@param id The id of the widget that will be removed.
*/
void removeWidget(const String &id);
/** @brief Retrieves a widget from the window.
A widget is implicitly shared; that is, if the returned widget is modified, the changes
will be immediately visible in the window.
@param id The id of the widget that will be returned.
*/
Widget getWidget(const String &id) const;
/** @brief Removes all widgets from the window.
*/
void removeAllWidgets();
/** @brief Removed all widgets and displays image scaled to whole window area.
@param image Image to be displayed.
@param window_size Size of Viz3d window. Default value means no change.
*/
void showImage(InputArray image, const Size& window_size = Size(-1, -1));
/** @brief Sets pose of a widget in the window.
@param id The id of the widget whose pose will be set. @param pose The new pose of the widget.
*/
void setWidgetPose(const String &id, const Affine3d &pose);
/** @brief Updates pose of a widget in the window by pre-multiplying its current pose.
@param id The id of the widget whose pose will be updated. @param pose The pose that the current
pose of the widget will be pre-multiplied by.
*/
void updateWidgetPose(const String &id, const Affine3d &pose);
/** @brief Returns the current pose of a widget in the window.
@param id The id of the widget whose pose will be returned.
*/
Affine3d getWidgetPose(const String &id) const;
/** @brief Sets the intrinsic parameters of the viewer using Camera.
@param camera Camera object wrapping intrinsinc parameters.
*/
void setCamera(const Camera &camera);
/** @brief Returns a camera object that contains intrinsic parameters of the current viewer.
*/
Camera getCamera() const;
/** @brief Returns the current pose of the viewer.
*/
Affine3d getViewerPose();
/** @brief Sets pose of the viewer.
@param pose The new pose of the viewer.
*/
void setViewerPose(const Affine3d &pose);
/** @brief Resets camera viewpoint to a 3D widget in the scene.
@param id Id of a 3D widget.
*/
void resetCameraViewpoint(const String &id);
/** @brief Resets camera.
*/
void resetCamera();
/** @brief Transforms a point in world coordinate system to window coordinate system.
@param pt Point in world coordinate system.
@param window\_coord Output point in window coordinate system.
*/
void convertToWindowCoordinates(const Point3d &pt, Point3d &window_coord);
/** @brief Transforms a point in window coordinate system to a 3D ray in world coordinate system.
@param window\_coord Point in window coordinate system. @param origin Output origin of the ray.
@param direction Output direction of the ray.
*/
void converTo3DRay(const Point3d &window_coord, Point3d &origin, Vec3d &direction);
/** @brief Returns the current size of the window.
*/
Size getWindowSize() const;
/** @brief Sets the size of the window.
@param window\_size New size of the window.
*/
void setWindowSize(const Size &window_size);
/** @brief Returns the name of the window which has been set in the constructor.
*/
String getWindowName() const;
/** @brief Saves screenshot of the current scene.
@param file Name of the file.
*/
void saveScreenshot(const String &file);
/** @brief Sets the position of the window in the screen.
@param window_position coordinates of the window
*/
void setWindowPosition(const Point& window_position);
/** @brief Sets or unsets full-screen rendering mode.
@param mode If true, window will use full-screen mode.
*/
void setFullScreen(bool mode = true);
/** @brief Sets background color.
*/
void setBackgroundColor(const Color& color = Color::black(), const Color& color2 = Color::not_set());
void setBackgroundTexture(InputArray image = noArray());
void setBackgroundMeshLab();
/** @brief The window renders and starts the event loop.
*/
void spin();
/** @brief Starts the event loop for a given time.
@param time Amount of time in milliseconds for the event loop to keep running.
@param force_redraw If true, window renders.
*/
void spinOnce(int time = 1, bool force_redraw = false);
/** @brief Returns whether the event loop has been stopped.
*/
bool wasStopped() const;
void close();
/** @brief Sets keyboard handler.
@param callback Keyboard callback (void (\*KeyboardCallbackFunction(const
KeyboardEvent&, void\*)).
@param cookie The optional parameter passed to the callback.
*/
void registerKeyboardCallback(KeyboardCallback callback, void* cookie = 0);
/** @brief Sets mouse handler.
@param callback Mouse callback (void (\*MouseCallback)(const MouseEvent&, void\*)).
@param cookie The optional parameter passed to the callback.
*/
void registerMouseCallback(MouseCallback callback, void* cookie = 0);
/** @brief Sets rendering property of a widget.
@param id Id of the widget.
@param property Property that will be modified.
@param value The new value of the property.
**Rendering property** can be one of the following:
- **POINT\_SIZE**
- **OPACITY**
- **LINE\_WIDTH**
- **FONT\_SIZE**
-
**REPRESENTATION**: Expected values are
- **REPRESENTATION\_POINTS**
- **REPRESENTATION\_WIREFRAME**
- **REPRESENTATION\_SURFACE**
-
**IMMEDIATE\_RENDERING**:
- Turn on immediate rendering by setting the value to 1.
- Turn off immediate rendering by setting the value to 0.
-
**SHADING**: Expected values are
- **SHADING\_FLAT**
- **SHADING\_GOURAUD**
- **SHADING\_PHONG**
*/
void setRenderingProperty(const String &id, int property, double value);
/** @brief Returns rendering property of a widget.
@param id Id of the widget.
@param property Property.
**Rendering property** can be one of the following:
- **POINT\_SIZE**
- **OPACITY**
- **LINE\_WIDTH**
- **FONT\_SIZE**
-
**REPRESENTATION**: Expected values are
- **REPRESENTATION\_POINTS**
- **REPRESENTATION\_WIREFRAME**
- **REPRESENTATION\_SURFACE**
-
**IMMEDIATE\_RENDERING**:
- Turn on immediate rendering by setting the value to 1.
- Turn off immediate rendering by setting the value to 0.
-
**SHADING**: Expected values are
- **SHADING\_FLAT**
- **SHADING\_GOURAUD**
- **SHADING\_PHONG**
*/
double getRenderingProperty(const String &id, int property);
/** @brief Sets geometry representation of the widgets to surface, wireframe or points.
@param representation Geometry representation which can be one of the following:
- **REPRESENTATION\_POINTS**
- **REPRESENTATION\_WIREFRAME**
- **REPRESENTATION\_SURFACE**
*/
void setRepresentation(int representation);
void setGlobalWarnings(bool enabled = false);
......@@ -127,6 +319,8 @@ namespace cv
friend class VizStorage;
};
//! @}
} /* namespace viz */
} /* namespace cv */
......
modules/viz/include/opencv2/viz/vizcore.hpp
View file @ 397bf7f2
......@@ -54,13 +54,48 @@ namespace cv
{
namespace viz
{
//! takes coordiante frame data and builds transfrom to global coordinate frame
//! @addtogroup viz
//! @{
/** @brief Takes coordinate frame data and builds transform to global coordinate frame.
@param axis\_x X axis vector in global coordinate frame. @param axis\_y Y axis vector in global
coordinate frame. @param axis\_z Z axis vector in global coordinate frame. @param origin Origin of
the coordinate frame in global coordinate frame.
This function returns affine transform that describes transformation between global coordinate frame
and a given coordinate frame.
*/
CV_EXPORTS Affine3d makeTransformToGlobal(const Vec3d& axis_x, const Vec3d& axis_y, const Vec3d& axis_z, const Vec3d& origin = Vec3d::all(0));
//! constructs camera pose from position, focal_point and up_vector (see gluLookAt() for more infromation)
/** @brief Constructs camera pose from position, focal\_point and up\_vector (see gluLookAt() for more
infromation).
@param position Position of the camera in global coordinate frame. @param focal\_point Focal point
of the camera in global coordinate frame. @param y\_dir Up vector of the camera in global
coordinate frame.
This function returns pose of the camera in global coordinate frame.
*/
CV_EXPORTS Affine3d makeCameraPose(const Vec3d& position, const Vec3d& focal_point, const Vec3d& y_dir);
//! retrieves a window by its name. If no window with such name, then it creates new.
/** @brief Retrieves a window by its name.
@param window\_name Name of the window that is to be retrieved.
This function returns a Viz3d object with the given name.
@note If the window with that name already exists, that window is returned. Otherwise, new window is
created with the given name, and it is returned.
@note Window names are automatically prefixed by "Viz - " if it is not done by the user.
@code
/// window and window_2 are the same windows.
viz::Viz3d window = viz::getWindowByName("myWindow");
viz::Viz3d window_2 = viz::getWindowByName("Viz - myWindow");
@endcode
*/
CV_EXPORTS Viz3d getWindowByName(const String &window_name);
//! Unregisters all Viz windows from internal database. After it 'getWindowByName()' will create new windows instead getting existing from the database.
......@@ -69,25 +104,37 @@ namespace cv
//! Displays image in specified window
CV_EXPORTS Viz3d imshow(const String& window_name, InputArray image, const Size& window_size = Size(-1, -1));
//! checks float value for Nan
/** @brief Checks **float/double** value for nan.
@param x return true if nan.
*/
inline bool isNan(float x)
{
unsigned int *u = reinterpret_cast<unsigned int *>(&x);
return ((u[0] & 0x7f800000) == 0x7f800000) && (u[0] & 0x007fffff);
}
//! checks double value for Nan
/** @brief Checks **float/double** value for nan.
@param x return true if nan.
*/
inline bool isNan(double x)
{
unsigned int *u = reinterpret_cast<unsigned int *>(&x);
return (u[1] & 0x7ff00000) == 0x7ff00000 && (u[0] != 0 || (u[1] & 0x000fffff) != 0);
}
//! checks vectors for Nans
/** @brief Checks **float/double** value for nan.
@param v return true if **any** of the elements of the vector is *nan*.
*/
template<typename _Tp, int cn> inline bool isNan(const Vec<_Tp, cn>& v)
{ return isNan(v.val[0]) || isNan(v.val[1]) || isNan(v.val[2]); }
//! checks point for Nans
/** @brief Checks **float/double** value for nan.
@param p return true if **any** of the elements of the point is *nan*.
*/
template<typename _Tp> inline bool isNan(const Point3_<_Tp>& p)
{ return isNan(p.x) || isNan(p.y) || isNan(p.z); }
......@@ -121,6 +168,8 @@ namespace cv
CV_EXPORTS void computeNormals(const Mesh& mesh, OutputArray normals);
//! @}
} /* namespace viz */
} /* namespace cv */
......
modules/viz/include/opencv2/viz/widget_accessor.hpp
View file @ 397bf7f2
......@@ -54,15 +54,35 @@ namespace cv
{
namespace viz
{
//! @addtogroup viz_widget
//! @{
class Widget;
//The class is only that depends on VTK in its interface.
//It is indended for those users who want to develop own widgets system using VTK library API.
/** @brief This class is for users who want to develop their own widgets using VTK library API. :
*/
struct CV_EXPORTS WidgetAccessor
{
/** @brief Returns vtkProp of a given widget.
@param widget Widget whose vtkProp is to be returned.
@note vtkProp has to be down cast appropriately to be modified.
@code
vtkActor * actor = vtkActor::SafeDownCast(viz::WidgetAccessor::getProp(widget));
@endcode
*/
static vtkSmartPointer<vtkProp> getProp(const Widget &widget);
/** @brief Sets vtkProp of a given widget.
@param widget Widget whose vtkProp is to be set. @param prop A vtkProp.
*/
static void setProp(Widget &widget, vtkSmartPointer<vtkProp> prop);
};
//! @}
}
}
......
modules/viz/include/opencv2/viz/widgets.hpp
View file @ 397bf7f2
This diff is collapsed.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment