Doxygen documentation for: highgui, video, imgcodecs and videoio

modules/highgui/include/opencv2/highgui.hpp

@@ -47,11 +47,92 @@
 #include "opencv2/imgcodecs.hpp"
 #include "opencv2/videoio.hpp"
 
+/**
+@defgroup highgui High-level GUI
+
+While OpenCV was designed for use in full-scale applications and can be used within functionally
+rich UI frameworks (such as Qt\*, WinForms\*, or Cocoa\*) or without any UI at all, sometimes there
+it is required to try functionality quickly and visualize the results. This is what the HighGUI
+module has been designed for.
+
+It provides easy interface to:
+
+-   Create and manipulate windows that can display images and "remember" their content (no need to
+    handle repaint events from OS).
+-   Add trackbars to the windows, handle simple mouse events as well as keyboard commands.
+
+@{
+    @defgroup highgui_opengl OpenGL support
+    @defgroup highgui_qt Qt New Functions
+
+    ![image](pics/qtgui.png)
+
+    This figure explains new functionality implemented with Qt\* GUI. The new GUI provides a statusbar,
+    a toolbar, and a control panel. The control panel can have trackbars and buttonbars attached to it.
+    If you cannot see the control panel, press Ctrl+P or right-click any Qt window and select **Display
+    properties window**.
+
+    -   To attach a trackbar, the window name parameter must be NULL.
+
+    -   To attach a buttonbar, a button must be created. If the last bar attached to the control panel
+        is a buttonbar, the new button is added to the right of the last button. If the last bar
+        attached to the control panel is a trackbar, or the control panel is empty, a new buttonbar is
+        created. Then, a new button is attached to it.
+
+    See below the example used to generate the figure: :
+    @code
+        int main(int argc, char *argv[])
+            int value = 50;
+            int value2 = 0;
+
+            cvNamedWindow("main1",CV_WINDOW_NORMAL);
+            cvNamedWindow("main2",CV_WINDOW_AUTOSIZE | CV_GUI_NORMAL);
+
+            cvCreateTrackbar( "track1", "main1", &value, 255,  NULL);//OK tested
+            char* nameb1 = "button1";
+            char* nameb2 = "button2";
+            cvCreateButton(nameb1,callbackButton,nameb1,CV_CHECKBOX,1);
+
+            cvCreateButton(nameb2,callbackButton,nameb2,CV_CHECKBOX,0);
+            cvCreateTrackbar( "track2", NULL, &value2, 255, NULL);
+            cvCreateButton("button5",callbackButton1,NULL,CV_RADIOBOX,0);
+            cvCreateButton("button6",callbackButton2,NULL,CV_RADIOBOX,1);
+
+            cvSetMouseCallback( "main2",on_mouse,NULL );
+
+            IplImage* img1 = cvLoadImage("files/flower.jpg");
+            IplImage* img2 = cvCreateImage(cvGetSize(img1),8,3);
+            CvCapture* video = cvCaptureFromFile("files/hockey.avi");
+            IplImage* img3 = cvCreateImage(cvGetSize(cvQueryFrame(video)),8,3);
+
+            while(cvWaitKey(33) != 27)
+            {
+                cvAddS(img1,cvScalarAll(value),img2);
+                cvAddS(cvQueryFrame(video),cvScalarAll(value2),img3);
+                cvShowImage("main1",img2);
+                cvShowImage("main2",img3);
+            }
+
+            cvDestroyAllWindows();
+            cvReleaseImage(&img1);
+            cvReleaseImage(&img2);
+            cvReleaseImage(&img3);
+            cvReleaseCapture(&video);
+            return 0;
+        }
+    @endcode
+
+    @defgroup highgui_c C API
+@}
+*/
 
 ///////////////////////// graphical user interface //////////////////////////
 namespace cv
 {
 
+//! @addtogroup highgui
+//! @{
+
 // Flags for namedWindow
 enum { WINDOW_NORMAL     = 0x00000000, // the user can resize the window (no constraint) / also use to switch a fullscreen window to a normal size
        WINDOW_AUTOSIZE   = 0x00000001, // the user cannot resize the window, the size is constrainted by the image displayed
@@ -117,54 +198,334 @@ typedef void (*TrackbarCallback)(int pos, void* userdata);
 typedef void (*OpenGlDrawCallback)(void* userdata);
 typedef void (*ButtonCallback)(int state, void* userdata);
 
+/** @brief Creates a window.
+
+@param winname Name of the window in the window caption that may be used as a window identifier.
+@param flags Flags of the window. The supported flags are:
+> -   **WINDOW\_NORMAL** If this is set, the user can resize the window (no constraint).
+> -   **WINDOW\_AUTOSIZE** If this is set, the window size is automatically adjusted to fit the
+>     displayed image (see imshow ), and you cannot change the window size manually.
+> -   **WINDOW\_OPENGL** If this is set, the window will be created with OpenGL support.
+
+The function namedWindow creates a window that can be used as a placeholder for images and
+trackbars. Created windows are referred to by their names.
+
+If a window with the same name already exists, the function does nothing.
+
+You can call destroyWindow or destroyAllWindows to close the window and de-allocate any associated
+memory usage. For a simple program, you do not really have to call these functions because all the
+resources and windows of the application are closed automatically by the operating system upon exit.
 
+@note
+
+Qt backend supports additional flags:
+ -   **CV\_WINDOW\_NORMAL or CV\_WINDOW\_AUTOSIZE:** CV\_WINDOW\_NORMAL enables you to resize the
+     window, whereas CV\_WINDOW\_AUTOSIZE adjusts automatically the window size to fit the
+     displayed image (see imshow ), and you cannot change the window size manually.
+ -   **CV\_WINDOW\_FREERATIO or CV\_WINDOW\_KEEPRATIO:** CV\_WINDOW\_FREERATIO adjusts the image
+     with no respect to its ratio, whereas CV\_WINDOW\_KEEPRATIO keeps the image ratio.
+ -   **CV\_GUI\_NORMAL or CV\_GUI\_EXPANDED:** CV\_GUI\_NORMAL is the old way to draw the window
+     without statusbar and toolbar, whereas CV\_GUI\_EXPANDED is a new enhanced GUI.
+By default, flags == CV\_WINDOW\_AUTOSIZE | CV\_WINDOW\_KEEPRATIO | CV\_GUI\_EXPANDED
+ */
 CV_EXPORTS_W void namedWindow(const String& winname, int flags = WINDOW_AUTOSIZE);
 
+/** @brief Destroys a window.
+
+@param winname Name of the window to be destroyed.
+
+The function destroyWindow destroys the window with the given name.
+ */
 CV_EXPORTS_W void destroyWindow(const String& winname);
 
+/** @brief Destroys all of the HighGUI windows.
+
+The function destroyAllWindows destroys all of the opened HighGUI windows.
+ */
 CV_EXPORTS_W void destroyAllWindows();
 
 CV_EXPORTS_W int startWindowThread();
 
+/** @brief Waits for a pressed key.
+
+@param delay Delay in milliseconds. 0 is the special value that means "forever".
+
+The function waitKey waits for a key event infinitely (when \f$\texttt{delay}\leq 0\f$ ) or for delay
+milliseconds, when it is positive. Since the OS has a minimum time between switching threads, the
+function will not wait exactly delay ms, it will wait at least delay ms, depending on what else is
+running on your computer at that time. It returns the code of the pressed key or -1 if no key was
+pressed before the specified time had elapsed.
+
+@note
+
+This function is the only method in HighGUI that can fetch and handle events, so it needs to be
+called periodically for normal event processing unless HighGUI is used within an environment that
+takes care of event processing.
+
+@note
+
+The function only works if there is at least one HighGUI window created and the window is active.
+If there are several HighGUI windows, any of them can be active.
+ */
 CV_EXPORTS_W int waitKey(int delay = 0);
 
+/** @brief Displays an image in the specified window.
+
+@param winname Name of the window.
+@param mat Image to be shown.
+
+The function imshow displays an image in the specified window. If the window was created with the
+CV\_WINDOW\_AUTOSIZE flag, the image is shown with its original size. Otherwise, the image is scaled
+to fit the window. The function may scale the image, depending on its depth:
+
+-   If the image is 8-bit unsigned, it is displayed as is.
+-   If the image is 16-bit unsigned or 32-bit integer, the pixels are divided by 256. That is, the
+    value range [0,255\*256] is mapped to [0,255].
+-   If the image is 32-bit floating-point, the pixel values are multiplied by 255. That is, the
+    value range [0,1] is mapped to [0,255].
+
+If window was created with OpenGL support, imshow also support ogl::Buffer , ogl::Texture2D and
+cuda::GpuMat as input.
+
+@note This function should be followed by waitKey function which displays the image for specified
+milliseconds. Otherwise, it won't display the image. For example, waitKey(0) will display the window
+infinitely until any keypress (it is suitable for image display). waitKey(25) will display a frame
+for 25 ms, after which display will be automatically closed. (If you put it in a loop to read
+videos, it will display the video frame-by-frame)
+
+@note
+
+[Windows Backend Only] Pressing Ctrl+C will copy the image to the clipboard.
+
+ */
 CV_EXPORTS_W void imshow(const String& winname, InputArray mat);
 
+/** @brief Resizes window to the specified size
+
+@param winname Window name
+@param width The new window width
+@param height The new window height
+
+@note
+
+-   The specified window size is for the image area. Toolbars are not counted.
+-   Only windows created without CV\_WINDOW\_AUTOSIZE flag can be resized.
+ */
 CV_EXPORTS_W void resizeWindow(const String& winname, int width, int height);
 
+/** @brief Moves window to the specified position
+
+@param winname Window name
+@param x The new x-coordinate of the window
+@param y The new y-coordinate of the window
+ */
 CV_EXPORTS_W void moveWindow(const String& winname, int x, int y);
 
+/** @brief Changes parameters of a window dynamically.
+
+@param winname Name of the window.
+@param prop_id Window property to edit. The following operation flags are available:
+ -   **CV\_WND\_PROP\_FULLSCREEN** Change if the window is fullscreen ( CV\_WINDOW\_NORMAL or
+     CV\_WINDOW\_FULLSCREEN ).
+ -   **CV\_WND\_PROP\_AUTOSIZE** Change if the window is resizable (CV\_WINDOW\_NORMAL or
+     CV\_WINDOW\_AUTOSIZE ).
+ -   **CV\_WND\_PROP\_ASPECTRATIO** Change if the aspect ratio of the image is preserved (
+     CV\_WINDOW\_FREERATIO or CV\_WINDOW\_KEEPRATIO ).
+@param prop_value New value of the window property. The following operation flags are available:
+ -   **CV\_WINDOW\_NORMAL** Change the window to normal size or make the window resizable.
+ -   **CV\_WINDOW\_AUTOSIZE** Constrain the size by the displayed image. The window is not
+     resizable.
+ -   **CV\_WINDOW\_FULLSCREEN** Change the window to fullscreen.
+ -   **CV\_WINDOW\_FREERATIO** Make the window resizable without any ratio constraints.
+ -   **CV\_WINDOW\_KEEPRATIO** Make the window resizable, but preserve the proportions of the
+     displayed image.
+
+The function setWindowProperty enables changing properties of a window.
+ */
 CV_EXPORTS_W void setWindowProperty(const String& winname, int prop_id, double prop_value);
 
+/** @brief Updates window title
+*/
 CV_EXPORTS_W void setWindowTitle(const String& winname, const String& title);
 
+/** @brief Provides parameters of a window.
+
+@param winname Name of the window.
+@param prop_id Window property to retrieve. The following operation flags are available:
+ -   **CV\_WND\_PROP\_FULLSCREEN** Change if the window is fullscreen ( CV\_WINDOW\_NORMAL or
+     CV\_WINDOW\_FULLSCREEN ).
+ -   **CV\_WND\_PROP\_AUTOSIZE** Change if the window is resizable (CV\_WINDOW\_NORMAL or
+     CV\_WINDOW\_AUTOSIZE ).
+ -   **CV\_WND\_PROP\_ASPECTRATIO** Change if the aspect ratio of the image is preserved
+     (CV\_WINDOW\_FREERATIO or CV\_WINDOW\_KEEPRATIO ).
+
+See setWindowProperty to know the meaning of the returned values.
+
+The function getWindowProperty returns properties of a window.
+ */
 CV_EXPORTS_W double getWindowProperty(const String& winname, int prop_id);
 
-//! assigns callback for mouse events
+/** @brief Sets mouse handler for the specified window
+
+@param winname Window name
+@param onMouse Mouse callback. See OpenCV samples, such as
+<https://github.com/Itseez/opencv/tree/master/samples/cpp/ffilldemo.cpp>, on how to specify and
+use the callback.
+@param userdata The optional parameter passed to the callback.
+ */
 CV_EXPORTS void setMouseCallback(const String& winname, MouseCallback onMouse, void* userdata = 0);
 
+/** @brief Gets the mouse-wheel motion delta, when handling mouse-wheel events EVENT\_MOUSEWHEEL and
+EVENT\_MOUSEHWHEEL.
+
+@param flags The mouse callback flags parameter.
+
+For regular mice with a scroll-wheel, delta will be a multiple of 120. The value 120 corresponds to
+a one notch rotation of the wheel or the threshold for action to be taken and one such action should
+occur for each delta. Some high-precision mice with higher-resolution freely-rotating wheels may
+generate smaller values.
+
+For EVENT\_MOUSEWHEEL positive and negative values mean forward and backward scrolling,
+respectively. For EVENT\_MOUSEHWHEEL, where available, positive and negative values mean right and
+left scrolling, respectively.
+
+With the C API, the macro CV\_GET\_WHEEL\_DELTA(flags) can be used alternatively.
+
+@note
+
+Mouse-wheel events are currently supported only on Windows.
+ */
 CV_EXPORTS int getMouseWheelDelta(int flags);
 
+/** @brief Creates a trackbar and attaches it to the specified window.
+
+@param trackbarname Name of the created trackbar.
+@param winname Name of the window that will be used as a parent of the created trackbar.
+@param value Optional pointer to an integer variable whose value reflects the position of the
+slider. Upon creation, the slider position is defined by this variable.
+@param count Maximal position of the slider. The minimal position is always 0.
+@param onChange Pointer to the function to be called every time the slider changes position. This
+function should be prototyped as void Foo(int,void\*); , where the first parameter is the trackbar
+position and the second parameter is the user data (see the next parameter). If the callback is
+the NULL pointer, no callbacks are called, but only value is updated.
+@param userdata User data that is passed as is to the callback. It can be used to handle trackbar
+events without using global variables.
+
+The function createTrackbar creates a trackbar (a slider or range control) with the specified name
+and range, assigns a variable value to be a position synchronized with the trackbar and specifies
+the callback function onChange to be called on the trackbar position change. The created trackbar is
+displayed in the specified window winname.
+
+@note
+
+**[Qt Backend Only]** winname can be empty (or NULL) if the trackbar should be attached to the
+control panel.
+
+Clicking the label of each trackbar enables editing the trackbar values manually.
+
+@note
+
+-   An example of using the trackbar functionality can be found at
+    opencv\_source\_code/samples/cpp/connected\_components.cpp
+ */
 CV_EXPORTS int createTrackbar(const String& trackbarname, const String& winname,
                               int* value, int count,
                               TrackbarCallback onChange = 0,
                               void* userdata = 0);
 
+/** @brief Returns the trackbar position.
+
+@param trackbarname Name of the trackbar.
+@param winname Name of the window that is the parent of the trackbar.
+
+The function returns the current position of the specified trackbar.
+
+@note
+
+**[Qt Backend Only]** winname can be empty (or NULL) if the trackbar is attached to the control
+panel.
+
+ */
 CV_EXPORTS_W int getTrackbarPos(const String& trackbarname, const String& winname);
 
+/** @brief Sets the trackbar position.
+
+@param trackbarname Name of the trackbar.
+@param winname Name of the window that is the parent of trackbar.
+@param pos New position.
+
+The function sets the position of the specified trackbar in the specified window.
+
+@note
+
+**[Qt Backend Only]** winname can be empty (or NULL) if the trackbar is attached to the control
+panel.
+ */
 CV_EXPORTS_W void setTrackbarPos(const String& trackbarname, const String& winname, int pos);
 
+//! @addtogroup highgui_opengl OpenGL support
+//! @{
 
-// OpenGL support
 CV_EXPORTS void imshow(const String& winname, const ogl::Texture2D& tex);
 
+/** @brief Sets a callback function to be called to draw on top of displayed image.
+
+@param winname Name of the window.
+@param onOpenGlDraw Pointer to the function to be called every frame. This function should be
+prototyped as void Foo(void\*) .
+@param userdata Pointer passed to the callback function. *(Optional)*
+
+The function setOpenGlDrawCallback can be used to draw 3D data on the window. See the example of
+callback function below: :
+@code
+    void on_opengl(void* param)
+    {
+        glLoadIdentity();
+
+        glTranslated(0.0, 0.0, -1.0);
+
+        glRotatef( 55, 1, 0, 0 );
+        glRotatef( 45, 0, 1, 0 );
+        glRotatef( 0, 0, 0, 1 );
+
+        static const int coords[6][4][3] = {
+            { { +1, -1, -1 }, { -1, -1, -1 }, { -1, +1, -1 }, { +1, +1, -1 } },
+            { { +1, +1, -1 }, { -1, +1, -1 }, { -1, +1, +1 }, { +1, +1, +1 } },
+            { { +1, -1, +1 }, { +1, -1, -1 }, { +1, +1, -1 }, { +1, +1, +1 } },
+            { { -1, -1, -1 }, { -1, -1, +1 }, { -1, +1, +1 }, { -1, +1, -1 } },
+            { { +1, -1, +1 }, { -1, -1, +1 }, { -1, -1, -1 }, { +1, -1, -1 } },
+            { { -1, -1, +1 }, { +1, -1, +1 }, { +1, +1, +1 }, { -1, +1, +1 } }
+        };
+
+        for (int i = 0; i < 6; ++i) {
+                    glColor3ub( i*20, 100+i*10, i*42 );
+                    glBegin(GL_QUADS);
+                    for (int j = 0; j < 4; ++j) {
+                            glVertex3d(0.2 * coords[i][j][0], 0.2 * coords[i][j][1], 0.2 * coords[i][j][2]);
+                    }
+                    glEnd();
+        }
+    }
+@endcode
+ */
 CV_EXPORTS void setOpenGlDrawCallback(const String& winname, OpenGlDrawCallback onOpenGlDraw, void* userdata = 0);
 
+/** @brief Sets the specified window as current OpenGL context.
+
+@param winname Window name
+ */
 CV_EXPORTS void setOpenGlContext(const String& winname);
 
+/** @brief Force window to redraw its context and call draw callback ( setOpenGlDrawCallback ).
+
+@param winname Window name
+ */
 CV_EXPORTS void updateWindow(const String& winname);
 
+//! @} highgui_opengl
 
+//! @addtogroup highgui_qt
+//! @{
 // Only for Qt
 
 struct QtFont
@@ -182,27 +543,138 @@ struct QtFont
     int         line_type; // Qt: PointSize
 };
 
+/** @brief Creates the font to draw a text on an image.
+
+@param nameFont Name of the font. The name should match the name of a system font (such as
+*Times*). If the font is not found, a default one is used.
+@param pointSize Size of the font. If not specified, equal zero or negative, the point size of the
+font is set to a system-dependent default value. Generally, this is 12 points.
+@param color Color of the font in BGRA where A = 255 is fully transparent. Use the macro CV \_ RGB
+for simplicity.
+@param weight Font weight. The following operation flags are available:
+ -   **CV\_FONT\_LIGHT** Weight of 25
+ -   **CV\_FONT\_NORMAL** Weight of 50
+ -   **CV\_FONT\_DEMIBOLD** Weight of 63
+ -   **CV\_FONT\_BOLD** Weight of 75
+ -   **CV\_FONT\_BLACK** Weight of 87
+
+ You can also specify a positive integer for better control.
+@param style Font style. The following operation flags are available:
+ -   **CV\_STYLE\_NORMAL** Normal font
+ -   **CV\_STYLE\_ITALIC** Italic font
+ -   **CV\_STYLE\_OBLIQUE** Oblique font
+@param spacing Spacing between characters. It can be negative or positive.
+
+The function fontQt creates a CvFont object. This CvFont is not compatible with putText .
+
+A basic usage of this function is the following: :
+@code
+    CvFont font = fontQt(''Times'');
+    addText( img1, ``Hello World !'', Point(50,50), font);
+@endcode
+ */
 CV_EXPORTS QtFont fontQt(const String& nameFont, int pointSize = -1,
                          Scalar color = Scalar::all(0), int weight = QT_FONT_NORMAL,
                          int style = QT_STYLE_NORMAL, int spacing = 0);
 
+/** @brief Creates the font to draw a text on an image.
+
+@param img 8-bit 3-channel image where the text should be drawn.
+@param text Text to write on an image.
+@param org Point(x,y) where the text should start on an image.
+@param font Font to use to draw a text.
+
+The function addText draws *text* on an image *img* using a specific font *font* (see example fontQt
+)
+ */
 CV_EXPORTS void addText( const Mat& img, const String& text, Point org, const QtFont& font);
 
+/** @brief Displays a text on a window image as an overlay for a specified duration.
+
+@param winname Name of the window.
+@param text Overlay text to write on a window image.
+@param delayms The period (in milliseconds), during which the overlay text is displayed. If this
+function is called before the previous overlay text timed out, the timer is restarted and the text
+is updated. If this value is zero, the text never disappears.
+
+The function displayOverlay displays useful information/tips on top of the window for a certain
+amount of time *delayms*. The function does not modify the image, displayed in the window, that is,
+after the specified delay the original content of the window is restored.
+ */
 CV_EXPORTS void displayOverlay(const String& winname, const String& text, int delayms = 0);
 
+/** @brief Displays a text on the window statusbar during the specified period of time.
+
+@param winname Name of the window.
+@param text Text to write on the window statusbar.
+@param delayms Duration (in milliseconds) to display the text. If this function is called before
+the previous text timed out, the timer is restarted and the text is updated. If this value is
+zero, the text never disappears.
+
+The function displayOverlay displays useful information/tips on top of the window for a certain
+amount of time *delayms* . This information is displayed on the window statusbar (the window must be
+created with the CV\_GUI\_EXPANDED flags).
+ */
 CV_EXPORTS void displayStatusBar(const String& winname, const String& text, int delayms = 0);
 
+/** @brief Saves parameters of the specified window.
+
+@param windowName Name of the window.
+
+The function saveWindowParameters saves size, location, flags, trackbars value, zoom and panning
+location of the window window\_name .
+ */
 CV_EXPORTS void saveWindowParameters(const String& windowName);
 
+/** @brief Loads parameters of the specified window.
+
+@param windowName Name of the window.
+
+The function loadWindowParameters loads size, location, flags, trackbars value, zoom and panning
+location of the window window\_name .
+ */
 CV_EXPORTS void loadWindowParameters(const String& windowName);
 
 CV_EXPORTS  int startLoop(int (*pt2Func)(int argc, char *argv[]), int argc, char* argv[]);
 
 CV_EXPORTS  void stopLoop();
 
+/** @brief Attaches a button to the control panel.
+
+@param  bar_name
+   Name of the button.
+@param on_change Pointer to the function to be called every time the button changes its state.
+This function should be prototyped as void Foo(int state,\*void); . *state* is the current state
+of the button. It could be -1 for a push button, 0 or 1 for a check/radio box button.
+@param userdata Pointer passed to the callback function.
+@param type Optional type of the button.
+ -   **CV\_PUSH\_BUTTON** Push button
+ -   **CV\_CHECKBOX** Checkbox button
+ -   **CV\_RADIOBOX** Radiobox button. The radiobox on the same buttonbar (same line) are
+     exclusive, that is only one can be selected at a time.
+@param initial_button_state Default state of the button. Use for checkbox and radiobox. Its
+value could be 0 or 1. *(Optional)*
+
+The function createButton attaches a button to the control panel. Each button is added to a
+buttonbar to the right of the last button. A new buttonbar is created if nothing was attached to the
+control panel before, or if the last element attached to the control panel was a trackbar.
+
+See below various examples of the createButton function call: :
+@code
+    createButton(NULL,callbackButton);//create a push button "button 0", that will call callbackButton.
+    createButton("button2",callbackButton,NULL,CV_CHECKBOX,0);
+    createButton("button3",callbackButton,&value);
+    createButton("button5",callbackButton1,NULL,CV_RADIOBOX);
+    createButton("button6",callbackButton2,NULL,CV_PUSH_BUTTON,1);
+@endcode
+*/
 CV_EXPORTS int createButton( const String& bar_name, ButtonCallback on_change,
                              void* userdata = 0, int type = QT_PUSH_BUTTON,
                              bool initial_button_state = false);
 
+//! @} highgui_qt
+
+//! @} highgui
+
 } // cv
 #endif

modules/highgui/include/opencv2/highgui/highgui_c.h

@@ -51,6 +51,10 @@
 extern "C" {
 #endif /* __cplusplus */
 
+/** @addtogroup highgui_c
+  @{
+  */
+
 /****************************************************************************************\
 *                                  Basic GUI functions                                   *
 \****************************************************************************************/
@@ -237,6 +241,8 @@ CVAPI(void) cvSetPostprocessFuncWin32_(const void* callback);
 
 #endif
 
+/** @} highgui_c */
+
 #ifdef __cplusplus
 }
 #endif

modules/imgcodecs/include/opencv2/imgcodecs.hpp

@@ -45,10 +45,21 @@
 
 #include "opencv2/core.hpp"
 
+/**
+  @defgroup imgcodecs Image file reading and writing
+  @{
+    @defgroup imgcodecs_c C API
+    @defgroup imgcodecs_ios iOS glue
+  @}
+*/
+
 //////////////////////////////// image codec ////////////////////////////////
 namespace cv
 {
 
+//! @addtogroup imgcodecs
+//! @{
+
 enum { IMREAD_UNCHANGED  = -1, // 8bit, color or not
        IMREAD_GRAYSCALE  = 0,  // 8bit, gray
        IMREAD_COLOR      = 1,  // ?, color
@@ -77,19 +88,166 @@ enum { IMWRITE_PNG_STRATEGY_DEFAULT      = 0,
        IMWRITE_PNG_STRATEGY_FIXED        = 4
      };
 
+/** @brief Loads an image from a file.
+
+@param filename Name of file to be loaded.
+@param flags Flags specifying the color type of a loaded image:
+-   CV\_LOAD\_IMAGE\_ANYDEPTH - If set, return 16-bit/32-bit image when the input has the
+    corresponding depth, otherwise convert it to 8-bit.
+-   CV\_LOAD\_IMAGE\_COLOR - If set, always convert image to the color one
+-   CV\_LOAD\_IMAGE\_GRAYSCALE - If set, always convert image to the grayscale one
+-   **\>0** Return a 3-channel color image.
+
+@note In the current implementation the alpha channel, if any, is stripped from the output image.
+Use negative value if you need the alpha channel.
+
+-   **=0** Return a grayscale image.
+-   **\<0** Return the loaded image as is (with alpha channel).
+
+The function imread loads an image from the specified file and returns it. If the image cannot be
+read (because of missing file, improper permissions, unsupported or invalid format), the function
+returns an empty matrix ( Mat::data==NULL ). Currently, the following file formats are supported:
+
+-   Windows bitmaps - \*.bmp, \*.dib (always supported)
+-   JPEG files - \*.jpeg, \*.jpg, \*.jpe (see the *Notes* section)
+-   JPEG 2000 files - \*.jp2 (see the *Notes* section)
+-   Portable Network Graphics - \*.png (see the *Notes* section)
+-   WebP - \*.webp (see the *Notes* section)
+-   Portable image format - \*.pbm, \*.pgm, \*.ppm (always supported)
+-   Sun rasters - \*.sr, \*.ras (always supported)
+-   TIFF files - \*.tiff, \*.tif (see the *Notes* section)
+
+@note
+
+-   The function determines the type of an image by the content, not by the file extension.
+-   On Microsoft Windows\* OS and MacOSX\*, the codecs shipped with an OpenCV image (libjpeg,
+    libpng, libtiff, and libjasper) are used by default. So, OpenCV can always read JPEGs, PNGs,
+    and TIFFs. On MacOSX, there is also an option to use native MacOSX image readers. But beware
+    that currently these native image loaders give images with different pixel values because of
+    the color management embedded into MacOSX.
+-   On Linux\*, BSD flavors and other Unix-like open-source operating systems, OpenCV looks for
+    codecs supplied with an OS image. Install the relevant packages (do not forget the development
+    files, for example, "libjpeg-dev", in Debian\* and Ubuntu\*) to get the codec support or turn
+    on the OPENCV\_BUILD\_3RDPARTY\_LIBS flag in CMake.
+
+@note In the case of color images, the decoded images will have the channels stored in B G R order.
+ */
 CV_EXPORTS_W Mat imread( const String& filename, int flags = IMREAD_COLOR );
 
+/** @brief Saves an image to a specified file.
+
+@param filename Name of the file.
+@param img Image to be saved.
+@param params Format-specific save parameters encoded as pairs
+paramId\_1, paramValue\_1, paramId\_2, paramValue\_2, ... . The following parameters are currently
+supported:
+-   For JPEG, it can be a quality ( CV\_IMWRITE\_JPEG\_QUALITY ) from 0 to 100 (the higher is
+    the better). Default value is 95.
+-   For WEBP, it can be a quality ( CV\_IMWRITE\_WEBP\_QUALITY ) from 1 to 100 (the higher is
+    the better). By default (without any parameter) and for quality above 100 the lossless
+    compression is used.
+-   For PNG, it can be the compression level ( CV\_IMWRITE\_PNG\_COMPRESSION ) from 0 to 9. A
+    higher value means a smaller size and longer compression time. Default value is 3.
+-   For PPM, PGM, or PBM, it can be a binary format flag ( CV\_IMWRITE\_PXM\_BINARY ), 0 or 1.
+    Default value is 1.
+
+The function imwrite saves the image to the specified file. The image format is chosen based on the
+filename extension (see imread for the list of extensions). Only 8-bit (or 16-bit unsigned (CV\_16U)
+in case of PNG, JPEG 2000, and TIFF) single-channel or 3-channel (with 'BGR' channel order) images
+can be saved using this function. If the format, depth or channel order is different, use
+Mat::convertTo , and cvtColor to convert it before saving. Or, use the universal FileStorage I/O
+functions to save the image to XML or YAML format.
+
+It is possible to store PNG images with an alpha channel using this function. To do this, create
+8-bit (or 16-bit) 4-channel image BGRA, where the alpha channel goes last. Fully transparent pixels
+should have alpha set to 0, fully opaque pixels should have alpha set to 255/65535. The sample below
+shows how to create such a BGRA image and store to PNG file. It also demonstrates how to set custom
+compression parameters :
+@code
+    #include <vector>
+    #include <stdio.h>
+    #include <opencv2/opencv.hpp>
+
+    using namespace cv;
+    using namespace std;
+
+    void createAlphaMat(Mat &mat)
+    {
+        for (int i = 0; i < mat.rows; ++i) {
+            for (int j = 0; j < mat.cols; ++j) {
+                Vec4b& rgba = mat.at<Vec4b>(i, j);
+                rgba[0] = UCHAR_MAX;
+                rgba[1] = saturate_cast<uchar>((float (mat.cols - j)) / ((float)mat.cols) * UCHAR_MAX);
+                rgba[2] = saturate_cast<uchar>((float (mat.rows - i)) / ((float)mat.rows) * UCHAR_MAX);
+                rgba[3] = saturate_cast<uchar>(0.5 * (rgba[1] + rgba[2]));
+            }
+        }
+    }
+
+    int main(int argv, char **argc)
+    {
+        // Create mat with alpha channel
+        Mat mat(480, 640, CV_8UC4);
+        createAlphaMat(mat);
+
+        vector<int> compression_params;
+        compression_params.push_back(CV_IMWRITE_PNG_COMPRESSION);
+        compression_params.push_back(9);
+
+        try {
+            imwrite("alpha.png", mat, compression_params);
+        }
+        catch (runtime_error& ex) {
+            fprintf(stderr, "Exception converting image to PNG format: %s\n", ex.what());
+            return 1;
+        }
+
+        fprintf(stdout, "Saved PNG file with alpha data.\n");
+        return 0;
+    }
+@endcode
+ */
 CV_EXPORTS_W bool imwrite( const String& filename, InputArray img,
               const std::vector<int>& params = std::vector<int>());
 
+/** @overload */
 CV_EXPORTS_W Mat imdecode( InputArray buf, int flags );
 
+/** @brief Reads an image from a buffer in memory.
+
+@param buf Input array or vector of bytes.
+@param flags The same flags as in imread .
+@param dst The optional output placeholder for the decoded matrix. It can save the image
+reallocations when the function is called repeatedly for images of the same size.
+
+The function reads an image from the specified buffer in the memory. If the buffer is too short or
+contains invalid data, the empty matrix/image is returned.
+
+See imread for the list of supported formats and flags description.
+
+@note In the case of color images, the decoded images will have the channels stored in B G R order.
+ */
 CV_EXPORTS Mat imdecode( InputArray buf, int flags, Mat* dst);
 
+/** @brief Encodes an image into a memory buffer.
+
+@param ext File extension that defines the output format.
+@param img Image to be written.
+@param buf Output buffer resized to fit the compressed image.
+@param params Format-specific parameters. See imwrite .
+
+The function compresses the image and stores it in the memory buffer that is resized to fit the
+result. See imwrite for the list of supported formats and flags description.
+
+@note cvEncodeImage returns single-row matrix of type CV\_8UC1 that contains encoded image as array
+of bytes.
+ */
 CV_EXPORTS_W bool imencode( const String& ext, InputArray img,
                             CV_OUT std::vector<uchar>& buf,
                             const std::vector<int>& params = std::vector<int>());
 
+//! @} imgcodecs
+
 } // cv
 
 #endif //__OPENCV_IMGCODECS_HPP__

modules/imgcodecs/include/opencv2/imgcodecs/imgcodecs_c.h

@@ -48,6 +48,10 @@
 extern "C" {
 #endif /* __cplusplus */
 
+/** @addtogroup imgcodecs_c
+  @{
+  */
+
 enum
 {
 /* 8bit, color or not */
@@ -124,6 +128,7 @@ CVAPI(int) cvHaveImageWriter(const char* filename);
 #define cvvSaveImage cvSaveImage
 #define cvvConvertImage cvConvertImage
 
+/** @} imgcodecs_c */
 
 #ifdef __cplusplus
 }

modules/imgcodecs/include/opencv2/imgcodecs/ios.h

@@ -47,6 +47,11 @@
 #import <ImageIO/ImageIO.h>
 #include "opencv2/core/core.hpp"
 
+//! @addtogroup imgcodecs_ios
+//! @{
+
 UIImage* MatToUIImage(const cv::Mat& image);
 void UIImageToMat(const UIImage* image,
                          cv::Mat& m, bool alphaExist = false);
+
+//! @}

modules/video/include/opencv2/video.hpp

@@ -44,6 +44,15 @@
 #ifndef __OPENCV_VIDEO_HPP__
 #define __OPENCV_VIDEO_HPP__
 
+/**
+  @defgroup video Video Analysis
+  @{
+    @defgroup video_motion Motion Analysis
+    @defgroup video_track Object Tracking
+    @defgroup video_c C API
+  @}
+*/
+
 #include "opencv2/video/tracking.hpp"
 #include "opencv2/video/background_segm.hpp"
 

modules/video/include/opencv2/video/background_segm.hpp

@@ -49,49 +49,102 @@
 namespace cv
 {
 
-/*!
- The Base Class for Background/Foreground Segmentation
+//! @addtogroup video_motion
+//! @{
 
- The class is only used to define the common interface for
- the whole family of background/foreground segmentation algorithms.
-*/
+/** @brief Base class for background/foreground segmentation. :
+
+The class is only used to define the common interface for the whole family of background/foreground
+segmentation algorithms.
+ */
 class CV_EXPORTS_W BackgroundSubtractor : public Algorithm
 {
 public:
-    //! the update operator that takes the next video frame and returns the current foreground mask as 8-bit binary image.
+    /** @brief Computes a foreground mask.
+
+    @param image Next video frame.
+    @param fgmask The output foreground mask as an 8-bit binary image.
+    @param learningRate The value between 0 and 1 that indicates how fast the background model is
+    learnt. Negative parameter value makes the algorithm to use some automatically chosen learning
+    rate. 0 means that the background model is not updated at all, 1 means that the background model
+    is completely reinitialized from the last frame.
+     */
     CV_WRAP virtual void apply(InputArray image, OutputArray fgmask, double learningRate=-1) = 0;
 
-    //! computes a background image
+    /** @brief Computes a background image.
+
+    @param backgroundImage The output background image.
+
+    @note Sometimes the background image can be very blurry, as it contain the average background
+    statistics.
+     */
     CV_WRAP virtual void getBackgroundImage(OutputArray backgroundImage) const = 0;
 };
 
 
-/*!
- The class implements the following algorithm:
- "Improved adaptive Gausian mixture model for background subtraction"
- Z.Zivkovic
- International Conference Pattern Recognition, UK, August, 2004.
- http://www.zoranz.net/Publications/zivkovic2004ICPR.pdf
+/** @brief Gaussian Mixture-based Background/Foreground Segmentation Algorithm.
+
+The class implements the Gaussian mixture model background subtraction described in @cite Zivkovic2004
+and @cite Zivkovic2006 .
  */
 class CV_EXPORTS_W BackgroundSubtractorMOG2 : public BackgroundSubtractor
 {
 public:
+    /** @brief Returns the number of last frames that affect the background model
+    */
     CV_WRAP virtual int getHistory() const = 0;
+    /** @brief Sets the number of last frames that affect the background model
+    */
     CV_WRAP virtual void setHistory(int history) = 0;
 
+    /** @brief Returns the number of gaussian components in the background model
+    */
     CV_WRAP virtual int getNMixtures() const = 0;
+    /** @brief Sets the number of gaussian components in the background model.
+
+    The model needs to be reinitalized to reserve memory.
+    */
     CV_WRAP virtual void setNMixtures(int nmixtures) = 0;//needs reinitialization!
 
+    /** @brief Returns the "background ratio" parameter of the algorithm
+
+    If a foreground pixel keeps semi-constant value for about backgroundRatio\*history frames, it's
+    considered background and added to the model as a center of a new component. It corresponds to TB
+    parameter in the paper.
+     */
     CV_WRAP virtual double getBackgroundRatio() const = 0;
+    /** @brief Sets the "background ratio" parameter of the algorithm
+    */
     CV_WRAP virtual void setBackgroundRatio(double ratio) = 0;
 
+    /** @brief Returns the variance threshold for the pixel-model match
+
+    The main threshold on the squared Mahalanobis distance to decide if the sample is well described by
+    the background model or not. Related to Cthr from the paper.
+     */
     CV_WRAP virtual double getVarThreshold() const = 0;
+    /** @brief Sets the variance threshold for the pixel-model match
+    */
     CV_WRAP virtual void setVarThreshold(double varThreshold) = 0;
 
+    /** @brief Returns the variance threshold for the pixel-model match used for new mixture component generation
+
+    Threshold for the squared Mahalanobis distance that helps decide when a sample is close to the
+    existing components (corresponds to Tg in the paper). If a pixel is not close to any component, it
+    is considered foreground or added as a new component. 3 sigma =\> Tg=3\*3=9 is default. A smaller Tg
+    value generates more components. A higher Tg value may result in a small number of components but
+    they can grow too large.
+     */
     CV_WRAP virtual double getVarThresholdGen() const = 0;
+    /** @brief Sets the variance threshold for the pixel-model match used for new mixture component generation
+    */
     CV_WRAP virtual void setVarThresholdGen(double varThresholdGen) = 0;
 
+    /** @brief Returns the initial variance of each gaussian component
+    */
     CV_WRAP virtual double getVarInit() const = 0;
+    /** @brief Sets the initial variance of each gaussian component
+    */
     CV_WRAP virtual void setVarInit(double varInit) = 0;
 
     CV_WRAP virtual double getVarMin() const = 0;
@@ -100,62 +153,154 @@ public:
     CV_WRAP virtual double getVarMax() const = 0;
     CV_WRAP virtual void setVarMax(double varMax) = 0;
 
+    /** @brief Returns the complexity reduction threshold
+
+    This parameter defines the number of samples needed to accept to prove the component exists. CT=0.05
+    is a default value for all the samples. By setting CT=0 you get an algorithm very similar to the
+    standard Stauffer&Grimson algorithm.
+     */
     CV_WRAP virtual double getComplexityReductionThreshold() const = 0;
+    /** @brief Sets the complexity reduction threshold
+    */
     CV_WRAP virtual void setComplexityReductionThreshold(double ct) = 0;
 
+    /** @brief Returns the shadow detection flag
+
+    If true, the algorithm detects shadows and marks them. See createBackgroundSubtractorMOG2 for
+    details.
+     */
     CV_WRAP virtual bool getDetectShadows() const = 0;
+    /** @brief Enables or disables shadow detection
+    */
     CV_WRAP virtual void setDetectShadows(bool detectShadows) = 0;
 
+    /** @brief Returns the shadow value
+
+    Shadow value is the value used to mark shadows in the foreground mask. Default value is 127. Value 0
+    in the mask always means background, 255 means foreground.
+     */
     CV_WRAP virtual int getShadowValue() const = 0;
+    /** @brief Sets the shadow value
+    */
     CV_WRAP virtual void setShadowValue(int value) = 0;
 
+    /** @brief Returns the shadow threshold
+
+    A shadow is detected if pixel is a darker version of the background. The shadow threshold (Tau in
+    the paper) is a threshold defining how much darker the shadow can be. Tau= 0.5 means that if a pixel
+    is more than twice darker then it is not shadow. See Prati, Mikic, Trivedi and Cucchiarra,
+    *Detecting Moving Shadows...*, IEEE PAMI,2003.
+     */
     CV_WRAP virtual double getShadowThreshold() const = 0;
+    /** @brief Sets the shadow threshold
+    */
     CV_WRAP virtual void setShadowThreshold(double threshold) = 0;
 };
 
+/** @brief Creates MOG2 Background Subtractor
+
+@param history Length of the history.
+@param varThreshold Threshold on the squared Mahalanobis distance between the pixel and the model
+to decide whether a pixel is well described by the background model. This parameter does not
+affect the background update.
+@param detectShadows If true, the algorithm will detect shadows and mark them. It decreases the
+speed a bit, so if you do not need this feature, set the parameter to false.
+ */
 CV_EXPORTS_W Ptr<BackgroundSubtractorMOG2>
     createBackgroundSubtractorMOG2(int history=500, double varThreshold=16,
                                    bool detectShadows=true);
 
-/*!
- The class implements the K nearest neigbours algorithm from:
- "Efficient Adaptive Density Estimation per Image Pixel for the Task of Background Subtraction"
- Z.Zivkovic, F. van der Heijden
- Pattern Recognition Letters, vol. 27, no. 7, pages 773-780, 2006
- http://www.zoranz.net/Publications/zivkovicPRL2006.pdf
-
- Fast for small foreground object. Results on the benchmark data is at http://www.changedetection.net.
-*/
+/** @brief K-nearest neigbours - based Background/Foreground Segmentation Algorithm.
 
+The class implements the K-nearest neigbours background subtraction described in @cite Zivkovic2006 .
+Very efficient if number of foreground pixels is low.
+ */
 class CV_EXPORTS_W BackgroundSubtractorKNN : public BackgroundSubtractor
 {
 public:
+    /** @brief Returns the number of last frames that affect the background model
+    */
     CV_WRAP virtual int getHistory() const = 0;
+    /** @brief Sets the number of last frames that affect the background model
+    */
     CV_WRAP virtual void setHistory(int history) = 0;
 
+    /** @brief Returns the number of data samples in the background model
+    */
     CV_WRAP virtual int getNSamples() const = 0;
+    /** @brief Sets the number of data samples in the background model.
+
+    The model needs to be reinitalized to reserve memory.
+    */
     CV_WRAP virtual void setNSamples(int _nN) = 0;//needs reinitialization!
 
+    /** @brief Returns the threshold on the squared distance between the pixel and the sample
+
+    The threshold on the squared distance between the pixel and the sample to decide whether a pixel is
+    close to a data sample.
+     */
     CV_WRAP virtual double getDist2Threshold() const = 0;
+    /** @brief Sets the threshold on the squared distance
+    */
     CV_WRAP virtual void setDist2Threshold(double _dist2Threshold) = 0;
 
+    /** @brief Returns the number of neighbours, the k in the kNN.
+
+    K is the number of samples that need to be within dist2Threshold in order to decide that that
+    pixel is matching the kNN background model.
+     */
     CV_WRAP virtual int getkNNSamples() const = 0;
+    /** @brief Sets the k in the kNN. How many nearest neigbours need to match.
+    */
     CV_WRAP virtual void setkNNSamples(int _nkNN) = 0;
 
+    /** @brief Returns the shadow detection flag
+
+    If true, the algorithm detects shadows and marks them. See createBackgroundSubtractorKNN for
+    details.
+     */
     CV_WRAP virtual bool getDetectShadows() const = 0;
+    /** @brief Enables or disables shadow detection
+    */
     CV_WRAP virtual void setDetectShadows(bool detectShadows) = 0;
 
+    /** @brief Returns the shadow value
+
+    Shadow value is the value used to mark shadows in the foreground mask. Default value is 127. Value 0
+    in the mask always means background, 255 means foreground.
+     */
     CV_WRAP virtual int getShadowValue() const = 0;
+    /** @brief Sets the shadow value
+    */
     CV_WRAP virtual void setShadowValue(int value) = 0;
 
+    /** @brief Returns the shadow threshold
+
+    A shadow is detected if pixel is a darker version of the background. The shadow threshold (Tau in
+    the paper) is a threshold defining how much darker the shadow can be. Tau= 0.5 means that if a pixel
+    is more than twice darker then it is not shadow. See Prati, Mikic, Trivedi and Cucchiarra,
+    *Detecting Moving Shadows...*, IEEE PAMI,2003.
+     */
     CV_WRAP virtual double getShadowThreshold() const = 0;
+    /** @brief Sets the shadow threshold
+     */
     CV_WRAP virtual void setShadowThreshold(double threshold) = 0;
 };
 
+/** @brief Creates KNN Background Subtractor
+
+@param history Length of the history.
+@param dist2Threshold Threshold on the squared distance between the pixel and the sample to decide
+whether a pixel is close to that sample. This parameter does not affect the background update.
+@param detectShadows If true, the algorithm will detect shadows and mark them. It decreases the
+speed a bit, so if you do not need this feature, set the parameter to false.
+ */
 CV_EXPORTS_W Ptr<BackgroundSubtractorKNN>
     createBackgroundSubtractorKNN(int history=500, double dist2Threshold=400.0,
                                    bool detectShadows=true);
 
+//! @} video_motion
+
 } // cv
 
 #endif

modules/video/include/opencv2/video/tracking.hpp

@@ -50,26 +50,126 @@
 namespace cv
 {
 
+//! @addtogroup video_track
+//! @{
+
 enum { OPTFLOW_USE_INITIAL_FLOW     = 4,
        OPTFLOW_LK_GET_MIN_EIGENVALS = 8,
        OPTFLOW_FARNEBACK_GAUSSIAN   = 256
      };
 
-//! updates the object tracking window using CAMSHIFT algorithm
+/** @brief Finds an object center, size, and orientation.
+
+@param probImage Back projection of the object histogram. See calcBackProject.
+@param window Initial search window.
+@param criteria Stop criteria for the underlying meanShift.
+returns
+(in old interfaces) Number of iterations CAMSHIFT took to converge
+The function implements the CAMSHIFT object tracking algorithm @cite Bradski98. First, it finds an
+object center using meanShift and then adjusts the window size and finds the optimal rotation. The
+function returns the rotated rectangle structure that includes the object position, size, and
+orientation. The next position of the search window can be obtained with RotatedRect::boundingRect()
+
+See the OpenCV sample camshiftdemo.c that tracks colored objects.
+
+@note
+-   (Python) A sample explaining the camshift tracking algorithm can be found at
+    opencv\_source\_code/samples/python2/camshift.py
+ */
 CV_EXPORTS_W RotatedRect CamShift( InputArray probImage, CV_IN_OUT Rect& window,
                                    TermCriteria criteria );
 
-//! updates the object tracking window using meanshift algorithm
+/** @brief Finds an object on a back projection image.
+
+@param probImage Back projection of the object histogram. See calcBackProject for details.
+@param window Initial search window.
+@param criteria Stop criteria for the iterative search algorithm.
+returns
+:   Number of iterations CAMSHIFT took to converge.
+The function implements the iterative object search algorithm. It takes the input back projection of
+an object and the initial position. The mass center in window of the back projection image is
+computed and the search window center shifts to the mass center. The procedure is repeated until the
+specified number of iterations criteria.maxCount is done or until the window center shifts by less
+than criteria.epsilon. The algorithm is used inside CamShift and, unlike CamShift , the search
+window size or orientation do not change during the search. You can simply pass the output of
+calcBackProject to this function. But better results can be obtained if you pre-filter the back
+projection and remove the noise. For example, you can do this by retrieving connected components
+with findContours , throwing away contours with small area ( contourArea ), and rendering the
+remaining contours with drawContours.
+
+@note
+-   A mean-shift tracking sample can be found at opencv\_source\_code/samples/cpp/camshiftdemo.cpp
+ */
 CV_EXPORTS_W int meanShift( InputArray probImage, CV_IN_OUT Rect& window, TermCriteria criteria );
 
-//! constructs a pyramid which can be used as input for calcOpticalFlowPyrLK
+/** @brief Constructs the image pyramid which can be passed to calcOpticalFlowPyrLK.
+
+@param img 8-bit input image.
+@param pyramid output pyramid.
+@param winSize window size of optical flow algorithm. Must be not less than winSize argument of
+calcOpticalFlowPyrLK. It is needed to calculate required padding for pyramid levels.
+@param maxLevel 0-based maximal pyramid level number.
+@param withDerivatives set to precompute gradients for the every pyramid level. If pyramid is
+constructed without the gradients then calcOpticalFlowPyrLK will calculate them internally.
+@param pyrBorder the border mode for pyramid layers.
+@param derivBorder the border mode for gradients.
+@param tryReuseInputImage put ROI of input image into the pyramid if possible. You can pass false
+to force data copying.
+@return number of levels in constructed pyramid. Can be less than maxLevel.
+ */
 CV_EXPORTS_W int buildOpticalFlowPyramid( InputArray img, OutputArrayOfArrays pyramid,
                                           Size winSize, int maxLevel, bool withDerivatives = true,
                                           int pyrBorder = BORDER_REFLECT_101,
                                           int derivBorder = BORDER_CONSTANT,
                                           bool tryReuseInputImage = true );
 
-//! computes sparse optical flow using multi-scale Lucas-Kanade algorithm
+/** @brief Calculates an optical flow for a sparse feature set using the iterative Lucas-Kanade method with
+pyramids.
+
+@param prevImg first 8-bit input image or pyramid constructed by buildOpticalFlowPyramid.
+@param nextImg second input image or pyramid of the same size and the same type as prevImg.
+@param prevPts vector of 2D points for which the flow needs to be found; point coordinates must be
+single-precision floating-point numbers.
+@param nextPts output vector of 2D points (with single-precision floating-point coordinates)
+containing the calculated new positions of input features in the second image; when
+OPTFLOW\_USE\_INITIAL\_FLOW flag is passed, the vector must have the same size as in the input.
+@param status output status vector (of unsigned chars); each element of the vector is set to 1 if
+the flow for the corresponding features has been found, otherwise, it is set to 0.
+@param err output vector of errors; each element of the vector is set to an error for the
+corresponding feature, type of the error measure can be set in flags parameter; if the flow wasn't
+found then the error is not defined (use the status parameter to find such cases).
+@param winSize size of the search window at each pyramid level.
+@param maxLevel 0-based maximal pyramid level number; if set to 0, pyramids are not used (single
+level), if set to 1, two levels are used, and so on; if pyramids are passed to input then
+algorithm will use as many levels as pyramids have but no more than maxLevel.
+@param criteria parameter, specifying the termination criteria of the iterative search algorithm
+(after the specified maximum number of iterations criteria.maxCount or when the search window
+moves by less than criteria.epsilon.
+@param flags operation flags:
+ -   **OPTFLOW\_USE\_INITIAL\_FLOW** uses initial estimations, stored in nextPts; if the flag is
+     not set, then prevPts is copied to nextPts and is considered the initial estimate.
+ -   **OPTFLOW\_LK\_GET\_MIN\_EIGENVALS** use minimum eigen values as an error measure (see
+     minEigThreshold description); if the flag is not set, then L1 distance between patches
+     around the original and a moved point, divided by number of pixels in a window, is used as a
+     error measure.
+@param minEigThreshold the algorithm calculates the minimum eigen value of a 2x2 normal matrix of
+optical flow equations (this matrix is called a spatial gradient matrix in @cite Bouguet00), divided
+by number of pixels in a window; if this value is less than minEigThreshold, then a corresponding
+feature is filtered out and its flow is not processed, so it allows to remove bad points and get a
+performance boost.
+
+The function implements a sparse iterative version of the Lucas-Kanade optical flow in pyramids. See
+@cite Bouguet00. The function is parallelized with the TBB library.
+
+@note
+
+-   An example using the Lucas-Kanade optical flow algorithm can be found at
+    opencv\_source\_code/samples/cpp/lkdemo.cpp
+-   (Python) An example using the Lucas-Kanade optical flow algorithm can be found at
+    opencv\_source\_code/samples/python2/lk\_track.py
+-   (Python) An example using the Lucas-Kanade tracker for homography matching can be found at
+    opencv\_source\_code/samples/python2/lk\_homography.py
+ */
 CV_EXPORTS_W void calcOpticalFlowPyrLK( InputArray prevImg, InputArray nextImg,
                                         InputArray prevPts, InputOutputArray nextPts,
                                         OutputArray status, OutputArray err,
@@ -77,14 +177,76 @@ CV_EXPORTS_W void calcOpticalFlowPyrLK( InputArray prevImg, InputArray nextImg,
                                         TermCriteria criteria = TermCriteria(TermCriteria::COUNT+TermCriteria::EPS, 30, 0.01),
                                         int flags = 0, double minEigThreshold = 1e-4 );
 
-//! computes dense optical flow using Farneback algorithm
+/** @brief Computes a dense optical flow using the Gunnar Farneback's algorithm.
+
+@param prev first 8-bit single-channel input image.
+@param next second input image of the same size and the same type as prev.
+@param flow computed flow image that has the same size as prev and type CV\_32FC2.
+@param pyr\_scale parameter, specifying the image scale (\<1) to build pyramids for each image;
+pyr\_scale=0.5 means a classical pyramid, where each next layer is twice smaller than the previous
+one.
+@param levels number of pyramid layers including the initial image; levels=1 means that no extra
+layers are created and only the original images are used.
+@param winsize averaging window size; larger values increase the algorithm robustness to image
+noise and give more chances for fast motion detection, but yield more blurred motion field.
+@param iterations number of iterations the algorithm does at each pyramid level.
+@param poly\_n size of the pixel neighborhood used to find polynomial expansion in each pixel;
+larger values mean that the image will be approximated with smoother surfaces, yielding more
+robust algorithm and more blurred motion field, typically poly\_n =5 or 7.
+@param poly\_sigma standard deviation of the Gaussian that is used to smooth derivatives used as a
+basis for the polynomial expansion; for poly\_n=5, you can set poly\_sigma=1.1, for poly\_n=7, a
+good value would be poly\_sigma=1.5.
+@param flags operation flags that can be a combination of the following:
+ -   **OPTFLOW\_USE\_INITIAL\_FLOW** uses the input flow as an initial flow approximation.
+ -   **OPTFLOW\_FARNEBACK\_GAUSSIAN** uses the Gaussian \f$\texttt{winsize}\times\texttt{winsize}\f$
+     filter instead of a box filter of the same size for optical flow estimation; usually, this
+     option gives z more accurate flow than with a box filter, at the cost of lower speed;
+     normally, winsize for a Gaussian window should be set to a larger value to achieve the same
+     level of robustness.
+
+The function finds an optical flow for each prev pixel using the @cite Farneback2003 algorithm so that
+
+\f[\texttt{prev} (y,x)  \sim \texttt{next} ( y + \texttt{flow} (y,x)[1],  x + \texttt{flow} (y,x)[0])\f]
+
+@note
+
+-   An example using the optical flow algorithm described by Gunnar Farneback can be found at
+    opencv\_source\_code/samples/cpp/fback.cpp
+-   (Python) An example using the optical flow algorithm described by Gunnar Farneback can be
+    found at opencv\_source\_code/samples/python2/opt\_flow.py
+ */
 CV_EXPORTS_W void calcOpticalFlowFarneback( InputArray prev, InputArray next, InputOutputArray flow,
                                             double pyr_scale, int levels, int winsize,
                                             int iterations, int poly_n, double poly_sigma,
                                             int flags );
 
-//! estimates the best-fit Euqcidean, similarity, affine or perspective transformation
-// that maps one 2D point set to another or one image to another.
+/** @brief Computes an optimal affine transformation between two 2D point sets.
+
+@param src First input 2D point set stored in std::vector or Mat, or an image stored in Mat.
+@param dst Second input 2D point set of the same size and the same type as A, or another image.
+@param fullAffine If true, the function finds an optimal affine transformation with no additional
+restrictions (6 degrees of freedom). Otherwise, the class of transformations to choose from is
+limited to combinations of translation, rotation, and uniform scaling (5 degrees of freedom).
+
+The function finds an optimal affine transform *[A|b]* (a 2 x 3 floating-point matrix) that
+approximates best the affine transformation between:
+
+*   Two point sets
+*   Two raster images. In this case, the function first finds some features in the src image and
+    finds the corresponding features in dst image. After that, the problem is reduced to the first
+    case.
+In case of point sets, the problem is formulated as follows: you need to find a 2x2 matrix *A* and
+2x1 vector *b* so that:
+
+\f[[A^*|b^*] = arg  \min _{[A|b]}  \sum _i  \| \texttt{dst}[i] - A { \texttt{src}[i]}^T - b  \| ^2\f]
+where src[i] and dst[i] are the i-th points in src and dst, respectively
+\f$[A|b]\f$ can be either arbitrary (when fullAffine=true ) or have a form of
+\f[\begin{bmatrix} a_{11} & a_{12} & b_1  \\ -a_{12} & a_{11} & b_2  \end{bmatrix}\f]
+when fullAffine=false.
+
+@sa
+getAffineTransform, getPerspectiveTransform, findHomography
+ */
 CV_EXPORTS_W Mat estimateRigidTransform( InputArray src, InputArray dst, bool fullAffine );
 
 
@@ -96,37 +258,106 @@ enum
     MOTION_HOMOGRAPHY  = 3
 };
 
-//! estimates the best-fit Translation, Euclidean, Affine or Perspective Transformation
-// with respect to Enhanced Correlation Coefficient criterion that maps one image to
-// another (area-based alignment)
-//
-// see reference:
-// Evangelidis, G. E., Psarakis, E.Z., Parametric Image Alignment using
-// Enhanced Correlation Coefficient Maximization, PAMI, 30(8), 2008
+/** @brief Finds the geometric transform (warp) between two images in terms of the ECC criterion @cite EP08.
+
+@param templateImage single-channel template image; CV\_8U or CV\_32F array.
+@param inputImage single-channel input image which should be warped with the final warpMatrix in
+order to provide an image similar to templateImage, same type as temlateImage.
+@param warpMatrix floating-point \f$2\times 3\f$ or \f$3\times 3\f$ mapping matrix (warp).
+@param motionType parameter, specifying the type of motion:
+ -   **MOTION\_TRANSLATION** sets a translational motion model; warpMatrix is \f$2\times 3\f$ with
+     the first \f$2\times 2\f$ part being the unity matrix and the rest two parameters being
+     estimated.
+ -   **MOTION\_EUCLIDEAN** sets a Euclidean (rigid) transformation as motion model; three
+     parameters are estimated; warpMatrix is \f$2\times 3\f$.
+ -   **MOTION\_AFFINE** sets an affine motion model (DEFAULT); six parameters are estimated;
+     warpMatrix is \f$2\times 3\f$.
+ -   **MOTION\_HOMOGRAPHY** sets a homography as a motion model; eight parameters are
+     estimated;\`warpMatrix\` is \f$3\times 3\f$.
+@param criteria parameter, specifying the termination criteria of the ECC algorithm;
+criteria.epsilon defines the threshold of the increment in the correlation coefficient between two
+iterations (a negative criteria.epsilon makes criteria.maxcount the only termination criterion).
+Default values are shown in the declaration above.
+
+The function estimates the optimum transformation (warpMatrix) with respect to ECC criterion
+(@cite EP08), that is
+
+\f[\texttt{warpMatrix} = \texttt{warpMatrix} = \arg\max_{W} \texttt{ECC}(\texttt{templateImage}(x,y),\texttt{inputImage}(x',y'))\f]
+
+where
+
+\f[\begin{bmatrix} x' \\ y' \end{bmatrix} = W \cdot \begin{bmatrix} x \\ y \\ 1 \end{bmatrix}\f]
+
+(the equation holds with homogeneous coordinates for homography). It returns the final enhanced
+correlation coefficient, that is the correlation coefficient between the template image and the
+final warped input image. When a \f$3\times 3\f$ matrix is given with motionType =0, 1 or 2, the third
+row is ignored.
+
+Unlike findHomography and estimateRigidTransform, the function findTransformECC implements an
+area-based alignment that builds on intensity similarities. In essence, the function updates the
+initial transformation that roughly aligns the images. If this information is missing, the identity
+warp (unity matrix) should be given as input. Note that if images undergo strong
+displacements/rotations, an initial transformation that roughly aligns the images is necessary
+(e.g., a simple euclidean/similarity transform that allows for the images showing the same image
+content approximately). Use inverse warping in the second image to take an image close to the first
+one, i.e. use the flag WARP\_INVERSE\_MAP with warpAffine or warpPerspective. See also the OpenCV
+sample image\_alignment.cpp that demonstrates the use of the function. Note that the function throws
+an exception if algorithm does not converges.
+
+@sa
+estimateRigidTransform, findHomography
+ */
 CV_EXPORTS_W double findTransformECC( InputArray templateImage, InputArray inputImage,
                                       InputOutputArray warpMatrix, int motionType = MOTION_AFFINE,
                                       TermCriteria criteria = TermCriteria(TermCriteria::COUNT+TermCriteria::EPS, 50, 0.001));
 
-/*!
- Kalman filter.
+/** @brief Kalman filter class.
 
- The class implements standard Kalman filter http://en.wikipedia.org/wiki/Kalman_filter.
- However, you can modify KalmanFilter::transitionMatrix, KalmanFilter::controlMatrix and
- KalmanFilter::measurementMatrix to get the extended Kalman filter functionality.
-*/
+The class implements a standard Kalman filter <http://en.wikipedia.org/wiki/Kalman_filter>,
+@cite Welch95. However, you can modify transitionMatrix, controlMatrix, and measurementMatrix to get
+an extended Kalman filter functionality. See the OpenCV sample kalman.cpp.
+
+@note
+
+-   An example using the standard Kalman filter can be found at
+    opencv\_source\_code/samples/cpp/kalman.cpp
+ */
 class CV_EXPORTS_W KalmanFilter
 {
 public:
-    //! the default constructor
+    /** @brief The constructors.
+
+    @note In C API when CvKalman\* kalmanFilter structure is not needed anymore, it should be released
+    with cvReleaseKalman(&kalmanFilter)
+     */
     CV_WRAP KalmanFilter();
-    //! the full constructor taking the dimensionality of the state, of the measurement and of the control vector
+    /** @overload
+    @param dynamParams Dimensionality of the state.
+    @param measureParams Dimensionality of the measurement.
+    @param controlParams Dimensionality of the control vector.
+    @param type Type of the created matrices that should be CV\_32F or CV\_64F.
+    */
     CV_WRAP KalmanFilter( int dynamParams, int measureParams, int controlParams = 0, int type = CV_32F );
-    //! re-initializes Kalman filter. The previous content is destroyed.
+
+    /** @brief Re-initializes Kalman filter. The previous content is destroyed.
+
+    @param dynamParams Dimensionalityensionality of the state.
+    @param measureParams Dimensionality of the measurement.
+    @param controlParams Dimensionality of the control vector.
+    @param type Type of the created matrices that should be CV\_32F or CV\_64F.
+     */
     void init( int dynamParams, int measureParams, int controlParams = 0, int type = CV_32F );
 
-    //! computes predicted state
+    /** @brief Computes a predicted state.
+
+    @param control The optional input control
+     */
     CV_WRAP const Mat& predict( const Mat& control = Mat() );
-    //! updates the predicted state from the measurement
+
+    /** @brief Updates the predicted state from the measurement.
+
+    @param measurement The measured system parameters
+     */
     CV_WRAP const Mat& correct( const Mat& measurement );
 
     CV_PROP_RW Mat statePre;           //!< predicted state (x'(k)): x(k)=A*x(k-1)+B*u(k)
@@ -149,21 +380,69 @@ public:
 };
 
 
+/** @brief "Dual TV L1" Optical Flow Algorithm.
 
+The class implements the "Dual TV L1" optical flow algorithm described in @cite Zach2007 and
+@cite Javier2012.
+Here are important members of the class that control the algorithm, which you can set after
+constructing the class instance:
+
+-   member double tau
+    Time step of the numerical scheme.
+
+-   member double lambda
+    Weight parameter for the data term, attachment parameter. This is the most relevant
+    parameter, which determines the smoothness of the output. The smaller this parameter is,
+    the smoother the solutions we obtain. It depends on the range of motions of the images, so
+    its value should be adapted to each image sequence.
+
+-   member double theta
+    Weight parameter for (u - v)\^2, tightness parameter. It serves as a link between the
+    attachment and the regularization terms. In theory, it should have a small value in order
+    to maintain both parts in correspondence. The method is stable for a large range of values
+    of this parameter.
+
+-   member int nscales
+    Number of scales used to create the pyramid of images.
+
+-   member int warps
+    Number of warpings per scale. Represents the number of times that I1(x+u0) and grad(
+    I1(x+u0) ) are computed per scale. This is a parameter that assures the stability of the
+    method. It also affects the running time, so it is a compromise between speed and
+    accuracy.
+
+-   member double epsilon
+    Stopping criterion threshold used in the numerical scheme, which is a trade-off between
+    precision and running time. A small value will yield more accurate solutions at the
+    expense of a slower convergence.
+
+-   member int iterations
+    Stopping criterion iterations number used in the numerical scheme.
+
+C. Zach, T. Pock and H. Bischof, "A Duality Based Approach for Realtime TV-L1 Optical Flow".
+Javier Sanchez, Enric Meinhardt-Llopis and Gabriele Facciolo. "TV-L1 Optical Flow Estimation".
+*/
 class CV_EXPORTS_W DenseOpticalFlow : public Algorithm
 {
 public:
+    /** @brief Calculates an optical flow.
+
+    @param I0 first 8-bit single-channel input image.
+    @param I1 second input image of the same size and the same type as prev.
+    @param flow computed flow image that has the same size as prev and type CV\_32FC2.
+     */
     CV_WRAP virtual void calc( InputArray I0, InputArray I1, InputOutputArray flow ) = 0;
+    /** @brief Releases all inner buffers.
+    */
     CV_WRAP virtual void collectGarbage() = 0;
 };
 
-// Implementation of the Zach, Pock and Bischof Dual TV-L1 Optical Flow method
-//
-// see reference:
-//   [1] C. Zach, T. Pock and H. Bischof, "A Duality Based Approach for Realtime TV-L1 Optical Flow".
-//   [2] Javier Sanchez, Enric Meinhardt-Llopis and Gabriele Facciolo. "TV-L1 Optical Flow Estimation".
+/** @brief Creates instance of cv::DenseOpticalFlow
+*/
 CV_EXPORTS_W Ptr<DenseOpticalFlow> createOptFlow_DualTVL1();
 
+//! @} video_track
+
 } // cv
 
 #endif

modules/video/include/opencv2/video/tracking_c.h

@@ -50,6 +50,10 @@
 extern "C" {
 #endif
 
+/** @addtogroup video_c
+  @{
+*/
+
 /****************************************************************************************\
 *                                  Motion Analysis                                       *
 \****************************************************************************************/
@@ -218,6 +222,7 @@ CVAPI(const CvMat*)  cvKalmanCorrect( CvKalman* kalman, const CvMat* measurement
 #define cvKalmanUpdateByTime  cvKalmanPredict
 #define cvKalmanUpdateByMeasurement cvKalmanCorrect
 
+/** @} video_c */
 
 #ifdef __cplusplus
 } // extern "C"

modules/videoio/include/opencv2/videoio.hpp

@@ -45,6 +45,13 @@
 
 #include "opencv2/core.hpp"
 
+/**
+  @defgroup videoio Media I/O
+  @{
+    @defgroup videoio_c C API
+    @defgroup videoio_ios iOS glue
+  @}
+*/
 
 ////////////////////////////////// video io /////////////////////////////////
 
@@ -54,6 +61,9 @@ typedef struct CvVideoWriter CvVideoWriter;
 namespace cv
 {
 
+//! @addtogroup videoio
+//! @{
+
 // Camera API
 enum { CAP_ANY          = 0,     // autodetect
        CAP_VFW          = 200,   // platform native
@@ -345,26 +355,209 @@ enum { CAP_INTELPERC_DEPTH_MAP              = 0, // Each pixel is a 16-bit integ
 
 
 class IVideoCapture;
+
+/** @brief Class for video capturing from video files, image sequences or cameras. The class provides C++ API
+for capturing video from cameras or for reading video files and image sequences. Here is how the
+class can be used: :
+@code
+    #include "opencv2/opencv.hpp"
+
+    using namespace cv;
+
+    int main(int, char**)
+    {
+        VideoCapture cap(0); // open the default camera
+        if(!cap.isOpened())  // check if we succeeded
+            return -1;
+
+        Mat edges;
+        namedWindow("edges",1);
+        for(;;)
+        {
+            Mat frame;
+            cap >> frame; // get a new frame from camera
+            cvtColor(frame, edges, COLOR_BGR2GRAY);
+            GaussianBlur(edges, edges, Size(7,7), 1.5, 1.5);
+            Canny(edges, edges, 0, 30, 3);
+            imshow("edges", edges);
+            if(waitKey(30) >= 0) break;
+        }
+        // the camera will be deinitialized automatically in VideoCapture destructor
+        return 0;
+    }
+@endcode
+@note In C API the black-box structure CvCapture is used instead of VideoCapture.
+
+@note
+-   A basic sample on using the VideoCapture interface can be found at
+    opencv\_source\_code/samples/cpp/starter\_video.cpp
+-   Another basic video processing sample can be found at
+    opencv\_source\_code/samples/cpp/video\_dmtx.cpp
+-   (Python) A basic sample on using the VideoCapture interface can be found at
+    opencv\_source\_code/samples/python2/video.py
+-   (Python) Another basic video processing sample can be found at
+    opencv\_source\_code/samples/python2/video\_dmtx.py
+-   (Python) A multi threaded video processing sample can be found at
+    opencv\_source\_code/samples/python2/video\_threaded.py
+ */
 class CV_EXPORTS_W VideoCapture
 {
 public:
+    /** @brief
+    @note In C API, when you finished working with video, release CvCapture structure with
+    cvReleaseCapture(), or use Ptr\<CvCapture\> that calls cvReleaseCapture() automatically in the
+    destructor.
+     */
     CV_WRAP VideoCapture();
+
+    /** @overload
+    @param filename name of the opened video file (eg. video.avi) or image sequence (eg.
+    img\_%02d.jpg, which will read samples like img\_00.jpg, img\_01.jpg, img\_02.jpg, ...)
+    */
     CV_WRAP VideoCapture(const String& filename);
+
+    /** @overload
+    @param device id of the opened video capturing device (i.e. a camera index). If there is a single
+    camera connected, just pass 0.
+    */
     CV_WRAP VideoCapture(int device);
 
     virtual ~VideoCapture();
+
+    /** @brief Open video file or a capturing device for video capturing
+
+    @param filename name of the opened video file (eg. video.avi) or image sequence (eg.
+    img\_%02d.jpg, which will read samples like img\_00.jpg, img\_01.jpg, img\_02.jpg, ...)
+
+    The methods first call VideoCapture::release to close the already opened file or camera.
+     */
     CV_WRAP virtual bool open(const String& filename);
+
+    /** @overload
+    @param device id of the opened video capturing device (i.e. a camera index).
+    */
     CV_WRAP virtual bool open(int device);
+
+    /** @brief Returns true if video capturing has been initialized already.
+
+    If the previous call to VideoCapture constructor or VideoCapture::open succeeded, the method returns
+    true.
+     */
     CV_WRAP virtual bool isOpened() const;
+
+    /** @brief Closes video file or capturing device.
+
+    The methods are automatically called by subsequent VideoCapture::open and by VideoCapture
+    destructor.
+
+    The C function also deallocates memory and clears \*capture pointer.
+     */
     CV_WRAP virtual void release();
 
+    /** @brief Grabs the next frame from video file or capturing device.
+
+    The methods/functions grab the next frame from video file or camera and return true (non-zero) in
+    the case of success.
+
+    The primary use of the function is in multi-camera environments, especially when the cameras do not
+    have hardware synchronization. That is, you call VideoCapture::grab() for each camera and after that
+    call the slower method VideoCapture::retrieve() to decode and get frame from each camera. This way
+    the overhead on demosaicing or motion jpeg decompression etc. is eliminated and the retrieved frames
+    from different cameras will be closer in time.
+
+    Also, when a connected camera is multi-head (for example, a stereo camera or a Kinect device), the
+    correct way of retrieving data from it is to call VideoCapture::grab first and then call
+    VideoCapture::retrieve one or more times with different values of the channel parameter. See
+    <https://github.com/Itseez/opencv/tree/master/samples/cpp/openni_capture.cpp>
+     */
     CV_WRAP virtual bool grab();
+
+    /** @brief Decodes and returns the grabbed video frame.
+
+    The methods/functions decode and return the just grabbed frame. If no frames has been grabbed
+    (camera has been disconnected, or there are no more frames in video file), the methods return false
+    and the functions return NULL pointer.
+
+    @note OpenCV 1.x functions cvRetrieveFrame and cv.RetrieveFrame return image stored inside the video
+    capturing structure. It is not allowed to modify or release the image! You can copy the frame using
+    :ocvcvCloneImage and then do whatever you want with the copy.
+     */
     CV_WRAP virtual bool retrieve(OutputArray image, int flag = 0);
     virtual VideoCapture& operator >> (CV_OUT Mat& image);
     virtual VideoCapture& operator >> (CV_OUT UMat& image);
+
+    /** @brief Grabs, decodes and returns the next video frame.
+
+    The methods/functions combine VideoCapture::grab and VideoCapture::retrieve in one call. This is the
+    most convenient method for reading video files or capturing data from decode and return the just
+    grabbed frame. If no frames has been grabbed (camera has been disconnected, or there are no more
+    frames in video file), the methods return false and the functions return NULL pointer.
+
+    @note OpenCV 1.x functions cvRetrieveFrame and cv.RetrieveFrame return image stored inside the video
+    capturing structure. It is not allowed to modify or release the image! You can copy the frame using
+    :ocvcvCloneImage and then do whatever you want with the copy.
+     */
     CV_WRAP virtual bool read(OutputArray image);
 
+    /** @brief Sets a property in the VideoCapture.
+
+    @param propId Property identifier. It can be one of the following:
+     -   **CV\_CAP\_PROP\_POS\_MSEC** Current position of the video file in milliseconds.
+     -   **CV\_CAP\_PROP\_POS\_FRAMES** 0-based index of the frame to be decoded/captured next.
+     -   **CV\_CAP\_PROP\_POS\_AVI\_RATIO** Relative position of the video file: 0 - start of the
+         film, 1 - end of the film.
+     -   **CV\_CAP\_PROP\_FRAME\_WIDTH** Width of the frames in the video stream.
+     -   **CV\_CAP\_PROP\_FRAME\_HEIGHT** Height of the frames in the video stream.
+     -   **CV\_CAP\_PROP\_FPS** Frame rate.
+     -   **CV\_CAP\_PROP\_FOURCC** 4-character code of codec.
+     -   **CV\_CAP\_PROP\_FRAME\_COUNT** Number of frames in the video file.
+     -   **CV\_CAP\_PROP\_FORMAT** Format of the Mat objects returned by retrieve() .
+     -   **CV\_CAP\_PROP\_MODE** Backend-specific value indicating the current capture mode.
+     -   **CV\_CAP\_PROP\_BRIGHTNESS** Brightness of the image (only for cameras).
+     -   **CV\_CAP\_PROP\_CONTRAST** Contrast of the image (only for cameras).
+     -   **CV\_CAP\_PROP\_SATURATION** Saturation of the image (only for cameras).
+     -   **CV\_CAP\_PROP\_HUE** Hue of the image (only for cameras).
+     -   **CV\_CAP\_PROP\_GAIN** Gain of the image (only for cameras).
+     -   **CV\_CAP\_PROP\_EXPOSURE** Exposure (only for cameras).
+     -   **CV\_CAP\_PROP\_CONVERT\_RGB** Boolean flags indicating whether images should be converted
+         to RGB.
+     -   **CV\_CAP\_PROP\_WHITE\_BALANCE** Currently unsupported
+     -   **CV\_CAP\_PROP\_RECTIFICATION** Rectification flag for stereo cameras (note: only supported
+         by DC1394 v 2.x backend currently)
+    @param value Value of the property.
+     */
     CV_WRAP virtual bool set(int propId, double value);
+
+    /** @brief Returns the specified VideoCapture property
+
+    @param propId Property identifier. It can be one of the following:
+     -   **CV\_CAP\_PROP\_POS\_MSEC** Current position of the video file in milliseconds or video
+         capture timestamp.
+     -   **CV\_CAP\_PROP\_POS\_FRAMES** 0-based index of the frame to be decoded/captured next.
+     -   **CV\_CAP\_PROP\_POS\_AVI\_RATIO** Relative position of the video file: 0 - start of the
+         film, 1 - end of the film.
+     -   **CV\_CAP\_PROP\_FRAME\_WIDTH** Width of the frames in the video stream.
+     -   **CV\_CAP\_PROP\_FRAME\_HEIGHT** Height of the frames in the video stream.
+     -   **CV\_CAP\_PROP\_FPS** Frame rate.
+     -   **CV\_CAP\_PROP\_FOURCC** 4-character code of codec.
+     -   **CV\_CAP\_PROP\_FRAME\_COUNT** Number of frames in the video file.
+     -   **CV\_CAP\_PROP\_FORMAT** Format of the Mat objects returned by retrieve() .
+     -   **CV\_CAP\_PROP\_MODE** Backend-specific value indicating the current capture mode.
+     -   **CV\_CAP\_PROP\_BRIGHTNESS** Brightness of the image (only for cameras).
+     -   **CV\_CAP\_PROP\_CONTRAST** Contrast of the image (only for cameras).
+     -   **CV\_CAP\_PROP\_SATURATION** Saturation of the image (only for cameras).
+     -   **CV\_CAP\_PROP\_HUE** Hue of the image (only for cameras).
+     -   **CV\_CAP\_PROP\_GAIN** Gain of the image (only for cameras).
+     -   **CV\_CAP\_PROP\_EXPOSURE** Exposure (only for cameras).
+     -   **CV\_CAP\_PROP\_CONVERT\_RGB** Boolean flags indicating whether images should be converted
+         to RGB.
+     -   **CV\_CAP\_PROP\_WHITE\_BALANCE** Currently not supported
+     -   **CV\_CAP\_PROP\_RECTIFICATION** Rectification flag for stereo cameras (note: only supported
+         by DC1394 v 2.x backend currently)
+
+    **Note**: When querying a property that is not supported by the backend used by the VideoCapture
+    class, value 0 is returned.
+     */
     CV_WRAP virtual double get(int propId);
 
 protected:
@@ -374,21 +567,63 @@ private:
     static Ptr<IVideoCapture> createCameraCapture(int index);
 };
 
+/** @brief Video writer class.
+ */
 class CV_EXPORTS_W VideoWriter
 {
 public:
+    /** @brief VideoWriter constructors
+
+    The constructors/functions initialize video writers. On Linux FFMPEG is used to write videos; on
+    Windows FFMPEG or VFW is used; on MacOSX QTKit is used.
+     */
     CV_WRAP VideoWriter();
+
+    /** @overload
+    @param filename Name of the output video file.
+    @param fourcc 4-character code of codec used to compress the frames. For example,
+    VideoWriter::fourcc('P','I','M','1') is a MPEG-1 codec, VideoWriter::fourcc('M','J','P','G') is a
+    motion-jpeg codec etc. List of codes can be obtained at [Video Codecs by
+    FOURCC](http://www.fourcc.org/codecs.php) page.
+    @param fps Framerate of the created video stream.
+    @param frameSize Size of the video frames.
+    @param isColor If it is not zero, the encoder will expect and encode color frames, otherwise it
+    will work with grayscale frames (the flag is currently supported on Windows only).
+    */
     CV_WRAP VideoWriter(const String& filename, int fourcc, double fps,
                 Size frameSize, bool isColor = true);
 
     virtual ~VideoWriter();
+
+    /** @brief Initializes or reinitializes video writer.
+
+    The method opens video writer. Parameters are the same as in the constructor
+    VideoWriter::VideoWriter.
+
+     */
     CV_WRAP virtual bool open(const String& filename, int fourcc, double fps,
                       Size frameSize, bool isColor = true);
+
+    /** @brief Returns true if video writer has been successfully initialized.
+    */
     CV_WRAP virtual bool isOpened() const;
     CV_WRAP virtual void release();
     virtual VideoWriter& operator << (const Mat& image);
+
+    /** @brief Writes the next video frame
+
+    @param image The written frame
+
+    The functions/methods write the specified image to video file. It must have the same size as has
+    been specified when opening the video writer.
+     */
     CV_WRAP virtual void write(const Mat& image);
 
+    /** @brief Concatenates 4 chars to a fourcc code
+
+    This static method constructs the fourcc code of the codec to be used in the constructor
+    VideoWriter::VideoWriter or VideoWriter::open.
+     */
     CV_WRAP static int fourcc(char c1, char c2, char c3, char c4);
 
 protected:
@@ -398,6 +633,8 @@ protected:
 template<> CV_EXPORTS void DefaultDeleter<CvCapture>::operator ()(CvCapture* obj) const;
 template<> CV_EXPORTS void DefaultDeleter<CvVideoWriter>::operator ()(CvVideoWriter* obj) const;
 
+//! @} videoio
+
 } // cv
 
 #endif //__OPENCV_VIDEOIO_HPP__

modules/videoio/include/opencv2/videoio/cap_ios.h

@@ -32,6 +32,9 @@
 #import <ImageIO/ImageIO.h>
 #include "opencv2/core.hpp"
 
+//! @addtogroup videoio_ios
+//! @{
+
 /////////////////////////////////////// CvAbstractCamera /////////////////////////////////////
 
 @class CvAbstractCamera;
@@ -167,3 +170,6 @@
 - (void)takePicture;
 
 @end
+
+//! @} videoio_ios
+

modules/videoio/include/opencv2/videoio/videoio_c.h

@@ -48,6 +48,10 @@
 extern "C" {
 #endif /* __cplusplus */
 
+/**
+  @addtogroup videoio_c
+  @{
+*/
 
 /****************************************************************************************\
 *                         Working with Video Files and Cameras                           *
@@ -416,6 +420,7 @@ CVAPI(void) cvReleaseVideoWriter( CvVideoWriter** writer );
 #define cvCreateAVIWriter cvCreateVideoWriter
 #define cvWriteToAVI cvWriteFrame
 
+/** @} videoio_c */
 
 #ifdef __cplusplus
 }