diff --git a/modules/highgui/include/opencv2/highgui.hpp b/modules/highgui/include/opencv2/highgui.hpp index 0247cc38a..ddd4be15d 100644 --- a/modules/highgui/include/opencv2/highgui.hpp +++ b/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 +, 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 diff --git a/modules/highgui/include/opencv2/highgui/highgui_c.h b/modules/highgui/include/opencv2/highgui/highgui_c.h index 13849e254..a8780ade0 100644 --- a/modules/highgui/include/opencv2/highgui/highgui_c.h +++ b/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 diff --git a/modules/imgcodecs/include/opencv2/imgcodecs.hpp b/modules/imgcodecs/include/opencv2/imgcodecs.hpp index fd5c08a93..680eb2be9 100644 --- a/modules/imgcodecs/include/opencv2/imgcodecs.hpp +++ b/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 + #include + #include + + 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(i, j); + rgba[0] = UCHAR_MAX; + rgba[1] = saturate_cast((float (mat.cols - j)) / ((float)mat.cols) * UCHAR_MAX); + rgba[2] = saturate_cast((float (mat.rows - i)) / ((float)mat.rows) * UCHAR_MAX); + rgba[3] = saturate_cast(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 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& params = std::vector()); +/** @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& buf, const std::vector& params = std::vector()); +//! @} imgcodecs + } // cv #endif //__OPENCV_IMGCODECS_HPP__ diff --git a/modules/imgcodecs/include/opencv2/imgcodecs/imgcodecs_c.h b/modules/imgcodecs/include/opencv2/imgcodecs/imgcodecs_c.h index ccd29a7c1..ad793cc94 100644 --- a/modules/imgcodecs/include/opencv2/imgcodecs/imgcodecs_c.h +++ b/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 } diff --git a/modules/imgcodecs/include/opencv2/imgcodecs/ios.h b/modules/imgcodecs/include/opencv2/imgcodecs/ios.h index 8ec135605..fbd6371e5 100644 --- a/modules/imgcodecs/include/opencv2/imgcodecs/ios.h +++ b/modules/imgcodecs/include/opencv2/imgcodecs/ios.h @@ -47,6 +47,11 @@ #import #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); + +//! @} diff --git a/modules/video/include/opencv2/video.hpp b/modules/video/include/opencv2/video.hpp index 70c17e67d..6d20a26cc 100644 --- a/modules/video/include/opencv2/video.hpp +++ b/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" diff --git a/modules/video/include/opencv2/video/background_segm.hpp b/modules/video/include/opencv2/video/background_segm.hpp index 789f9db96..dbeccbdc8 100644 --- a/modules/video/include/opencv2/video/background_segm.hpp +++ b/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 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 createBackgroundSubtractorKNN(int history=500, double dist2Threshold=400.0, bool detectShadows=true); +//! @} video_motion + } // cv #endif diff --git a/modules/video/include/opencv2/video/tracking.hpp b/modules/video/include/opencv2/video/tracking.hpp index a9fdaa272..9d449c3dd 100644 --- a/modules/video/include/opencv2/video/tracking.hpp +++ b/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 , +@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 createOptFlow_DualTVL1(); +//! @} video_track + } // cv #endif diff --git a/modules/video/include/opencv2/video/tracking_c.h b/modules/video/include/opencv2/video/tracking_c.h index e05a0b3ad..b35535287 100644 --- a/modules/video/include/opencv2/video/tracking_c.h +++ b/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" diff --git a/modules/videoio/include/opencv2/videoio.hpp b/modules/videoio/include/opencv2/videoio.hpp index b0a371af3..9c089c4a6 100644 --- a/modules/videoio/include/opencv2/videoio.hpp +++ b/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\ 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 + + */ 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 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::operator ()(CvCapture* obj) const; template<> CV_EXPORTS void DefaultDeleter::operator ()(CvVideoWriter* obj) const; +//! @} videoio + } // cv #endif //__OPENCV_VIDEOIO_HPP__ diff --git a/modules/videoio/include/opencv2/videoio/cap_ios.h b/modules/videoio/include/opencv2/videoio/cap_ios.h index 4d270aba9..440450428 100644 --- a/modules/videoio/include/opencv2/videoio/cap_ios.h +++ b/modules/videoio/include/opencv2/videoio/cap_ios.h @@ -32,6 +32,9 @@ #import #include "opencv2/core.hpp" +//! @addtogroup videoio_ios +//! @{ + /////////////////////////////////////// CvAbstractCamera ///////////////////////////////////// @class CvAbstractCamera; @@ -167,3 +170,6 @@ - (void)takePicture; @end + +//! @} videoio_ios + diff --git a/modules/videoio/include/opencv2/videoio/videoio_c.h b/modules/videoio/include/opencv2/videoio/videoio_c.h index 13805c0a4..d993ab312 100644 --- a/modules/videoio/include/opencv2/videoio/videoio_c.h +++ b/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 }