potok/opencv
1
0
Fork 0
mirror of https://github.com/opencv/opencv.git synced 2026-07-31 08:13:04 +04:00
Code Packages Releases Wiki Activity

propagated some more fixes from 2.3 branch to the trunk

Browse Source
This commit is contained in:
Vadim Pisarevsky
2011-06-29 22:06:42 +00:00
parent dacd265424
commit b204e73d9a
54 changed files with 9120 additions and 3049 deletions
Download Patch File Download Diff File Expand all files Collapse all files
modules/highgui/doc/qt_new_functions.rst
+61 -60
View File
@@ -4,7 +4,7 @@ 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 can't see the control panel then press Ctrl+P or right-click on any Qt-window and select "Display properties window".
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.
@@ -14,7 +14,7 @@ This figure explains new functionality implemented with Qt* GUI. The new GUI pro
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.
The following code is an example used to generate the figure. ::
See below the example used to generate the figure: ::
int main(int argc, char *argv[])
int value = 50;
@@ -56,103 +56,104 @@ The following code is an example used to generate the figure. ::
return 0;
}
.. index:: setWindowProperty
.. _setWindowProperty:
setWindowProperty
---------------------
Changes parameters of a window dynamically.
.. ocv:function:: void setWindowProperty(const string& name, int prop_id, double prop_value)
Changes parameters of a window dynamically.
.. ocv:pyfunction:: cv2.setWindowProperty(winname, prop_id, prop_value) -> None
.. ocv:cfunction:: void cvSetWindowProperty(const char* name, int propId, double propValue)
:param name: 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_FULLSCREEN** Change if the window is fullscreen ( ``CV_WINDOW_NORMAL`` or ``CV_WINDOW_FULLSCREEN`` ).
* **CV_WND_PROP_AUTOSIZE** Change if the window is resizable (texttt {CV\_WINDOW\_NORMAL} or ``CV_WINDOW_AUTOSIZE`` ).
* **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 (texttt {CV\_WINDOW\_FREERATIO} or ``CV_WINDOW_KEEPRATIO`` ).
* **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_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_AUTOSIZE** Constrain the size by the displayed image. The window is not resizable.
* **CV_WINDOW_FULLSCREEN** Change the window to fullscreen.
* **CV_WINDOW_FULLSCREEN** Change the window to fullscreen.
* **CV_WINDOW_FREERATIO** Make the window resizable without any ratio constraints.
* **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.
* **CV_WINDOW_KEEPRATIO** Make the window resizable, but preserve the proportions of the displayed image.
The function ``setWindowProperty`` enables changing properties of a window.
.. index:: getWindowProperty
getWindowProperty
---------------------
Provides parameters of a window.
.. ocv:function:: void getWindowProperty(const string& name, int prop_id)
Provides parameters of a window.
.. ocv:pyfunction:: cv2.getWindowProperty(winname, prop_id) -> retval
.. ocv:cfunction:: void cvGetWindowProperty(const char* name, int propId)
:param name: Name of the window.
:param prop_id: Window property to retrive. 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_FULLSCREEN** Change if the window is fullscreen ( ``CV_WINDOW_NORMAL`` or ``CV_WINDOW_FULLSCREEN`` ).
* **CV_WND_PROP_AUTOSIZE** Change if the window is resizable (texttt {CV\_WINDOW\_NORMAL} or ``CV_WINDOW_AUTOSIZE`` ).
* **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 (texttt {CV\_WINDOW\_FREERATIO} or ``CV_WINDOW_KEEPRATIO`` ).
* **CV_WND_PROP_ASPECTRATIO** Change if the aspect ratio of the image is preserved (``CV_WINDOW_FREERATIO`` or ``CV_WINDOW_KEEPRATIO`` ).
See
:ref:`setWindowProperty` to know the meaning of the returned values.
:ocv:func:`setWindowProperty` to know the meaning of the returned values.
The function ``getWindowProperty`` returns properties of a window.
.. index:: fontQt
.. _fontQt:
fontQt
----------
Creates the font to draw a text on an image.
.. ocv:function:: CvFont fontQt(const string& nameFont, int pointSize = -1, Scalar color = Scalar::all(0), int weight = CV_FONT_NORMAL, int style = CV_STYLE_NORMAL, int spacing = 0)
Creates the font to draw a text on an image.
.. ocv:cfunction:: CvFont cvFontQt(const char* nameFont, int pointSize=-1, CvScalar color=cvScalarAll(0), int weight=CV_FONT_NORMAL, int style=CV_STYLE_NORMAL, int spacing=0)
: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 -- A = 255 is fully transparent. Use the macro ``CV _ RGB`` for simplicity.
: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_LIGHT** Weight of 25
* **CV_FONT_NORMAL** Weight of 50
* **CV_FONT_NORMAL** Weight of 50
* **CV_FONT_DEMIBOLD** Weight of 63
* **CV_FONT_DEMIBOLD** Weight of 63
* **CV_FONT_BOLD** Weight of 75
* **CV_FONT_BOLD** Weight of 75
* **CV_FONT_BLACK** Weight of 87
* **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_NORMAL** Normal font
* **CV_STYLE_ITALIC** Italic font
* **CV_STYLE_ITALIC** Italic font
* **CV_STYLE_OBLIQUE** Oblique font
* **CV_STYLE_OBLIQUE** Oblique font
:param spacing: Spacing between characters. It can be negative or positive.
@@ -163,13 +164,14 @@ A basic usage of this function is the following: ::
CvFont font = fontQt(''Times'');
addText( img1, ``Hello World !'', Point(50,50), font);
.. index:: addText
addText
-----------
Creates the font to draw a text on an image.
.. ocv:function:: void addText(const Mat& img, const string& text, Point location, CvFont *font)
Creates the font to draw a text on an image.
.. ocv:cfunction:: void cvAddText(const CvArr* img, const char* text, CvPoint location, CvFont *font)
:param img: 8-bit 3-channel image where the text should be drawn.
@@ -185,16 +187,17 @@ on an image
*img*
using a specific font
*font*
(see example
:ref:`fontQt` )
(see example :ocv:func:`fontQt` )
.. index:: displayOverlay
displayOverlay
------------------
Displays a text on a window image as an overlay for a specified duration.
.. ocv:function:: void displayOverlay(const string& name, const string& text, int delay)
Displays a text on a window image as an overlay for a specified duration.
.. ocv:cfunction:: void cvDisplayOverlay(const char* name, const char* text, int delay)
:param name: Name of the window.
@@ -204,13 +207,14 @@ displayOverlay
The function ``displayOverlay`` displays useful information/tips on top of the window for a certain amount of time *delay*. 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.
.. index:: displayStatusBar
displayStatusBar
--------------------
Displays a text on the window statusbar during the specified period of time.
.. ocv:function:: void displayStatusBar(const string& name, const string& text, int delay)
Displays a text on the window statusbar during the specified period of time.
.. ocv:cfunction:: void cvDisplayStatusBar(const char* name, const char* text, int delayms)
:param name: Name of the window.
@@ -222,14 +226,13 @@ The function ``displayOverlay`` displays useful information/tips on top of the w
*delay*
. This information is displayed on the window statubar (the window must be created with the ``CV_GUI_EXPANDED`` flags).
.. index:: createOpenGLCallback
createOpenGLCallback
------------------------
Creates a callback function called to draw OpenGL on top the the image display by ``windowname``.
.. ocv:function:: void createOpenGLCallback( const string& window_name, OpenGLCallback callbackOpenGL, void* userdata CV_DEFAULT(NULL), double angle CV_DEFAULT(-1), double zmin CV_DEFAULT(-1), double zmax CV_DEFAULT(-1)
Creates a callback function called to draw OpenGL on top the the image display by ``windowname``.
.. ocv:cfunction:: void cvCreateOpenGLCallback( const char* windowName, CvOpenGLCallback callbackOpenGL, void* userdata=NULL, double angle=-1, double zmin=-1, double zmax=-1
:param window_name: Name of the window.
@@ -237,13 +240,13 @@ createOpenGLCallback
:param userdata: Pointer passed to the callback function. *(Optional)*
:param angle: Parameter specifying the field of view angle, in degrees, in the y direction. Default value is 45 degrees. *(Optional)*
:param angle: Parameter specifying the field of a view angle, in degrees, in the y direction. Default value is 45 degrees. *(Optional)*
:param zmin: Parameter specifying the distance from the viewer to the near clipping plane (always positive). Default value is 0.01. *(Optional)*
:param zmax: Parameter specifying the distance from the viewer to the far clipping plane (always positive). Default value is 1000. *(Optional)*
The function ``createOpenGLCallback`` can be used to draw 3D data on the window. An example of callback could be: ::
The function ``createOpenGLCallback`` can be used to draw 3D data on the window. See the example of callback use below: ::
void on_opengl(void* param)
{
@@ -274,42 +277,40 @@ The function ``createOpenGLCallback`` can be used to draw 3D data on the window.
}
}
.. index:: saveWindowParameters
saveWindowParameters
------------------------
Saves parameters of the specified window.
.. ocv:function:: void saveWindowParameters(const string& name)
Saves parameters of the window ``windowname`` .
.. ocv:cfunction:: void cvSaveWindowParameters(const char* name)
:param name: Name of the window.
The function ``saveWindowParameters`` saves size, location, flags, trackbars value, zoom and panning location of the window
``window_name`` .
.. index:: loadWindowParameters
loadWindowParameters
------------------------
Loads parameters of the specified window.
.. ocv:function:: void loadWindowParameters(const string& name)
Loads parameters of the window ``windowname`` .
.. ocv:cfunction:: void cvLoadWindowParameters(const char* name)
:param name: Name of the window.
The function ``loadWindowParameters`` loads size, location, flags, trackbars value, zoom and panning location of the window
``window_name`` .
.. index:: createButton
createButton
----------------
Attaches a button to the control panel.
.. ocv:function:: createButton( const string& button_name CV_DEFAULT(NULL),ButtonCallback on_change CV_DEFAULT(NULL), void* userdata CV_DEFAULT(NULL), int button_type CV_DEFAULT(CV_PUSH_BUTTON), int initial_button_state CV_DEFAULT(0))
Attaches a button to the control panel.
.. ocv:cfunction:: cvCreateButton( const char* buttonName=NULL, CvButtonCallback onChange=NULL, void* userdata=NULL, int buttonType=CV_PUSH_BUTTON, int initialButtonState=0
:param button_name: Name of the button.
@@ -317,20 +318,20 @@ createButton
:param userdata: Pointer passed to the callback function.
:param button_type: The optional type of the button.
:param button_type: Optional type of the button.
* **CV_PUSH_BUTTON** Push button
* **CV_PUSH_BUTTON** Push button
* **CV_CHECKBOX** Checkbox 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.
* **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.
Here are various examples of the ``createButton`` function call: ::
See below various examples of the ``createButton`` function call: ::
createButton(NULL,callbackButton);//create a push button "button 0", that will call callbackButton.
createButton("button2",callbackButton,NULL,CV_CHECKBOX,0);
modules/highgui/doc/reading_and_writing_images_and_video.rst
+250 -145
View File
@@ -3,35 +3,31 @@ Reading and Writing Images and Video
.. highlight:: cpp
.. index:: imdecode
.. _imdecode:
imdecode
------------
Reads an image from a buffer in memory.
.. ocv:function:: Mat imdecode( InputArray buf, int flags )
Reads an image from a buffer in memory.
.. ocv:pyfunction:: cv2.imdecode(buf, flags) -> retval
:param buf: Input array of vector of bytes.
:param flags: The same flags as in :ref:`imread` .
:param flags: The same flags as in :ocv:func:`imread` .
The function reads an image from the specified buffer in memory.
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 is returned.
See
:ref:`imread` for the list of supported formats and flags description.
.. index:: imencode
.. _imencode:
:ocv:func:`imread` for the list of supported formats and flags description.
imencode
------------
Encodes an image into a memory buffer.
.. ocv:function:: bool imencode( const string& ext, InputArray img, vector<uchar>& buf, const vector<int>& params=vector<int>())
Encode an image into a memory buffer.
.. ocv:pyfunction:: cv2.imencode(ext, img, buf[, params]) -> retval
:param ext: File extension that defines the output format.
@@ -39,31 +35,37 @@ imencode
:param buf: Output buffer resized to fit the compressed image.
:param params: Format-specific parameters. See :ref:`imwrite` .
:param params: Format-specific parameters. See :ocv:func:`imwrite` .
The function compresses the image and stores it in the memory buffer that is resized to fit the result.
See
:ref:`imwrite` for the list of supported formats and flags description.
.. index:: imread
.. _imread:
:ocv:func:`imwrite` for the list of supported formats and flags description.
imread
----------
Loads an image from a file.
.. ocv:function:: Mat imread( const string& filename, int flags=1 )
Loads an image from a file.
.. ocv:pyfunction:: cv2.imread(filename[, flags]) -> retval
.. ocv:cfunction:: IplImage* cvLoadImage( const char* filename, int flags=CV_LOAD_IMAGE_COLOR )
.. ocv:cfunction:: CvMat* cvLoadImageM( const char* filename, int flags=CV_LOAD_IMAGE_COLOR )
.. ocv:pyoldfunction:: cv.LoadImage(filename, flags=CV_LOAD_IMAGE_COLOR)->None
.. ocv:pyoldfunction:: cv.LoadImageM(filename, flags=CV_LOAD_IMAGE_COLOR)->None
:param filename: Name of file to be loaded.
:param flags: Flags specifying the color type of a loaded image:
* **>0** a 3-channel color image
* **>0** Return a 3-channel color image
* **=0** a grayscale image
* **=0** Return a grayscale image
* **<0** The image is loaded as is. Note that in the current implementation the alpha channel, if any, is stripped from the output image. For example, a 4-channel RGBA image is loaded as RGB if :math:`flags\ge0` .
* **<0** Return the loaded image as is. Note that in the current implementation the alpha channel, if any, is stripped from the output image. For example, a 4-channel RGBA image is loaded as RGB if :math:`flags\ge0` .
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:
@@ -81,27 +83,29 @@ The function ``imread`` loads an image from the specified file and returns it. I
* TIFF files - ``*.tiff, *.tif`` (see the *Notes* section)
**Notes**:
.. note::
* The function determines the type of an image by the content, not by the file extension.
* 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 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.
.. index:: imwrite
.. _imwrite:
* 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.
imwrite
-----------
.. ocv:function:: bool imwrite( const string& filename, InputArray img, const vector<int>& params=vector<int>())
Saves an image to a specified file.
Saves an image to a specified file.
.. ocv:function:: bool imwrite( const string& filename, InputArray image, const vector<int>& params=vector<int>())
.. ocv:pyfunction:: cv2.imwrite(filename, image[, params]) -> retval
.. ocv:cfunction:: int cvSaveImage( const char* filename, const CvArr* image )
.. ocv:pyoldfunction:: cv.SaveImage(filename, image)-> None
:param filename: Name of the file.
:param img: Image to be saved.
:param image: 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:
@@ -112,70 +116,18 @@ imwrite
* 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
:ref:`imread` for the list of extensions). Only 8-bit (or 16-bit 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
:ref:`Mat::convertTo` , and
:ref:`cvtColor` to convert it before saving. Or, use the universal XML I/O functions to save the image to XML or YAML format.
.. index:: VideoCapture
.. _VideoCapture:
:ocv:func:`imread` for the list of extensions). Only 8-bit (or 16-bit 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
:ocv:func:`Mat::convertTo` , and
:ocv:func:`cvtColor` to convert it before saving. Or, use the universal XML I/O functions to save the image to XML or YAML format.
VideoCapture
------------
.. c:type:: VideoCapture
.. ocv:class:: VideoCapture
Class for video capturing from video files or cameras ::
Class for video capturing from video files or cameras.
The class provides C++ API for capturing video from cameras or for reading video files. Here is how the class can be used: ::
class VideoCapture
{
public:
// the default constructor
VideoCapture();
// the constructor that opens video file
VideoCapture(const string& filename);
// the constructor that starts streaming from the camera
VideoCapture(int device);
// the destructor
virtual ~VideoCapture();
// opens the specified video file
virtual bool open(const string& filename);
// starts streaming from the specified camera by its id
virtual bool open(int device);
// returns true if the file was open successfully or if the camera
// has been initialized succesfully
virtual bool isOpened() const;
// closes the camera stream or the video file
// (automatically called by the destructor)
virtual void release();
// grab the next frame or a set of frames from a multi-head camera;
// returns false if there are no more frames
virtual bool grab();
// reads the frame from the specified video stream
// (non-zero channel is only valid for multi-head camera live streams)
virtual bool retrieve(Mat& image, int channel=0);
// equivalent to grab() + retrieve(image, 0);
virtual VideoCapture& operator >> (Mat& image);
// sets the specified property propId to the specified value
virtual bool set(int propId, double value);
// retrieves value of the specified property
virtual double get(int propId);
protected:
...
};
The class provides C++ video capturing API. Here is how the class can be used: ::
#include "cv.h"
#include "highgui.h"
#include "opencv2/opencv.hpp"
using namespace cv;
@@ -202,35 +154,146 @@ The class provides C++ video capturing API. Here is how the class can be used: :
}
.. index:: VideoCapture::VideoCapture
.. note:: In C API the black-box structure ``CvCapture`` is used instead of ``VideoCapture``.
.. _VideoCapture::VideoCapture:
VideoCapture::VideoCapture
------------------------------
VideoCapture constructors.
.. ocv:function:: VideoCapture::VideoCapture()
.. ocv:function:: VideoCapture::VideoCapture(const string& filename)
.. ocv:function:: VideoCapture::VideoCapture(int device)
VideoCapture constructors.
.. ocv:pyfunction:: cv2.VideoCapture() -> <VideoCapture object>
.. ocv:pyfunction:: cv2.VideoCapture(filename) -> <VideoCapture object>
.. ocv:pyfunction:: cv2.VideoCapture(device) -> <VideoCapture object>
.. ocv:cfunction:: CvCapture* cvCaptureFromCAM( int device )
.. ocv:pyoldfunction:: cv.CaptureFromCAM(device) -> CvCapture
.. ocv:cfunction:: CvCapture* cvCaptureFromFile( const char* filename )
.. ocv:pyoldfunction:: cv.CaptureFromFile(filename) -> CvCapture
:param filename: name of the opened video file
:param device: id of the opened video capturing device (i.e. a camera index). If there is a single camera connected, just pass 0.
.. 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.
VideoCapture::open
---------------------
Open video file or a capturing device for video capturing
.. ocv:function:: bool VideoCapture::open(const string& filename)
.. ocv:function:: bool VideoCapture::open(int device)
.. ocv:pyfunction:: cv2.VideoCapture.open(filename) -> successFlag
.. ocv:pyfunction:: cv2.VideoCapture.open(device) -> successFlag
:param filename: name of the opened video file
:param device: id of the opened video capturing device (i.e. a camera index).
.. index:: VideoCapture::get
The methods first call :ocv:cfunc:`VideoCapture::release` to close the already opened file or camera.
VideoCapture::isOpened
----------------------
Returns true if video capturing has been initialized already.
.. ocv:function:: bool VideoCapture::isOpened()
.. ocv:pyfunction:: cv2.VideoCapture.isOpened() -> flag
If the previous call to ``VideoCapture`` constructor or ``VideoCapture::open`` succeeded, the method returns true.
VideoCapture::release
---------------------
Closes video file or capturing device.
.. ocv:function:: void VideoCapture::release()
.. ocv:pyfunction:: cv2.VideoCapture.release()
.. ocv:cfunction: void cvReleaseCapture(CvCapture** capture)
The methods are automatically called by subsequent :ocv:func:`VideoCapture::open` and by ``VideoCapture`` destructor.
The C function also deallocates memory and clears ``*capture`` pointer.
VideoCapture::grab
---------------------
Grabs the next frame from video file or capturing device.
.. ocv:function:: bool VideoCapture::grab()
.. ocv:pyfunction:: cv2.VideoCapture.grab() -> successFlag
.. ocv:cfunction: int cvGrabFrame(CvCapture* capture)
.. ocv:pyoldfunction:: cv.GrabFrame(capture) -> int
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 :ocv:func:`VideoCapture::retrieve` one or more times with different values of the ``channel`` parameter. See https://code.ros.org/svn/opencv/trunk/opencv/samples/cpp/kinect_maps.cpp
VideoCapture::retrieve
----------------------
Decodes and returns the grabbed video frame.
.. ocv:function:: bool VideoCapture::retrieve(Mat& image, int channel=0)
.. ocv:pyfunction:: cv2.VideoCapture.retrieve([image[, channel]]) -> successFlag, image
.. ocv:cfunction: IplImage* cvRetrieveFrame(CvCapture* capture)
.. ocv:pyoldfunction:: cv.RetrieveFrame(capture) -> iplimage
The methods/functions decode and retruen 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 :ocv:cfunc:`cvCloneImage` and then do whatever you want with the copy.
VideoCapture::read
----------------------
Grabs, decodes and returns the next video frame.
.. ocv:function:: VideoCapture& VideoCapture::operator >> (Mat& image)
.. ocv:function:: bool VideoCapture::read(Mat& image)
.. ocv:pyfunction:: cv2.VideoCapture.read([image]) -> successFlag, image
.. ocv:cfunction: IplImage* cvQueryFrame(CvCapture* capture)
.. ocv:pyoldfunction:: cv.QueryFrame(capture) -> iplimage
The methods/functions combine :ocv:func:`VideoCapture::grab` and :ocv:func:`VideoCapture::retrieve` in one call. This is the most convenient method for reading video files or capturing data from decode and retruen 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 :ocv:cfunc:`cvCloneImage` and then do whatever you want with the copy.
.. _VideoCapture::get:
VideoCapture::get
---------------------
.. ocv:function:: double VideoCapture::get(int property_id)
Returns the specified ``VideoCapture`` property
:param property_id: Property identifier. It can be one of the following:
.. ocv:function:: double VideoCapture::get(int propId)
* **CV_CAP_PROP_POS_MSEC** Film current position in milliseconds or video capture timestamp.
.. ocv:pyfunction:: cv2.VideoCapture.get(propId) -> retval
.. ocv:cfunction:: double cvGetCaptureProperty( CvCapture* capture, int propId )
.. ocv:pyoldfunction:: cv.GetCaptureProperty(capture, propId)->double
: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.
@@ -264,26 +327,27 @@ VideoCapture::get
* **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_WHITE_BALANCE** Currently not supported
* **CV_CAP_PROP_RECTIFICATION** TOWRITE (note: only supported by DC1394 v 2.x backend currently)
* **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.
.. index:: VideoCapture::set
.. _VideoCapture::set:
VideoCapture::set
---------------------
.. ocv:function:: bool VideoCapture::set(int property_id, double value)
Sets a property in the ``VideoCapture``.
Sets a property in the VideoCapture backend.
.. ocv:function:: bool VideoCapture::set(int propertyId, double value)
:param property_id: Property identifier. It can be one of the following:
.. ocv:pyfunction:: cv2.VideoCapture.set(propId, value) -> retval
* **CV_CAP_PROP_POS_MSEC** Film current position in milliseconds or video capture timestamp.
.. ocv:cfunction:: int cvSetCaptureProperty( CvCapture* capture, int propId, double value )
.. ocv:pyoldfunction:: cv.SetCaptureProperty(capture, propId, value)->None
: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.
@@ -319,53 +383,94 @@ VideoCapture::set
* **CV_CAP_PROP_WHITE_BALANCE** Currently unsupported
* **CV_CAP_PROP_RECTIFICATION** TOWRITE (note: only supported by DC1394 v 2.x backend currently)
* **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.
.. index:: VideoWriter
.. _VideoWriter:
VideoWriter
-----------
.. c:type:: VideoWriter
.. ocv:class:: VideoWriter
Video writer class ::
Video writer class.
class VideoWriter
{
public:
// default constructor
VideoWriter();
// constructor that calls open
VideoWriter(const string& filename, int fourcc,
double fps, Size frameSize, bool isColor=true);
// the destructor
virtual ~VideoWriter();
// opens the file and initializes the video writer.
// filename - the output file name.
// fourcc - the codec
// fps - the number of frames per second
// frameSize - the video frame size
// isColor - specifies whether the video stream is color or grayscale
virtual bool open(const string& filename, int fourcc,
double fps, Size frameSize, bool isColor=true);
VideoWriter::VideoWriter
------------------------
VideoWriter constructors
// returns true if the writer has been initialized successfully
virtual bool isOpened() const;
.. ocv:function:: VideoWriter::VideoWriter()
.. ocv:function:: VideoWriter::VideoWriter(const string& filename, int fourcc, double fps, Size frameSize, bool isColor=true)
// writes the next video frame to the stream
virtual VideoWriter& operator << (const Mat& image);
.. ocv:pyfunction:: cv2.VideoWriter([filename, fourcc, fps, frameSize[, isColor]]) -> <VideoWriter object>
protected:
...
};
.. ocv:cfunction:: CvVideoWriter* cvCreateVideoWriter( const char* filename, int fourcc, double fps, CvSize frameSize, int isColor=1 )
.. ocv:pyoldfunction:: cv.CreateVideoWriter(filename, fourcc, fps, frameSize, isColor) -> CvVideoWriter
For more detailed description see http://opencv.willowgarage.com/wiki/documentation/cpp/highgui/VideoWriter
..
.. ocv:pyfunction:: cv2.VideoWriter.isOpened() -> retval
.. ocv:pyfunction:: cv2.VideoWriter.open(filename, fourcc, fps, frameSize[, isColor]) -> retval
.. ocv:pyfunction:: cv2.VideoWriter.write(image) -> None
:param filename: Name of the output video file.
:param fourcc: 4-character code of codec used to compress the frames. For example, ``CV_FOURCC('P','I','M,'1')`` is a MPEG-1 codec, ``CV_FOURCC('M','J','P','G')`` is a motion-jpeg codec etc.
: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).
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.
ReleaseVideoWriter
------------------
Releases the AVI writer.
.. ocv:cfunction:: void cvReleaseVideoWriter( CvVideoWriter** writer )
The function should be called after you finished using ``CvVideoWriter`` opened with :ocv:cfunc:`CreateVideoWriter`.
VideoWriter::open
-----------------
Initializes or reinitializes video writer.
.. ocv:function: bool VideoWriter::open(const string& filename, int fourcc, double fps, Size frameSize, bool isColor=true)
.. ocv:pyfunction:: cv2.VideoWriter.open(filename, fourcc, fps, frameSize[, isColor]) -> retval
The method opens video writer. Parameters are the same as in the constructor :ocv:func:`VideoWriter::VideoWriter`.
VideoWriter::isOpened
---------------------
Returns true if video writer has been successfully initialized.
.. ocv:function: bool VideoWriter::isOpened()
.. ocv:pyfunction:: cv2.VideoWriter.isOpened() -> retval
VideoWriter::write
------------------
Writes the next video frame
.. ocv:function:: VideoWriter& VideoWriter::operator << (const Mat& image)
.. ocv:function:: void VideoWriter::write(const Mat& image)
.. ocv:pyfunction:: cv2.VideoWriter.write(image) -> None
.. ocv:cfunction:: int cvWriteFrame( CvVideoWriter* writer, const IplImage* image )
.. ocv:pyoldfunction:: cv.WriteFrame(writer, image)->int
:param writer: Video writer structure (OpenCV 1.x API)
: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.
modules/highgui/doc/user_interface.rst
+119 -86
View File
@@ -3,15 +3,14 @@ User Interface
.. highlight:: cpp
.. index:: createTrackbar
.. _createTrackbar:
createTrackbar
------------------
Creates a trackbar and attaches it to the specified window.
.. ocv:function:: int createTrackbar( const string& trackbarname, const string& winname, int* value, int count, TrackbarCallback onChange=0, void* userdata=0)
Creates a trackbar and attaches it to the specified window.
.. ocv:cfunction:: int cvCreateTrackbar( const char* trackbarName, const char* windowName, int* value, int count, CvTrackbarCallback onChange )
.. ocv:pyoldfunction:: cv.CreateTrackbar(trackbarName, windowName, value, count, onChange) -> None
:param trackbarname: Name of the created trackbar.
@@ -25,29 +24,24 @@ createTrackbar
: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.k.a. slider or range control) with the specified name and range, assigns a variable ``value`` to be syncronized with the trackbar position and specifies the callback function ``onChange`` to be called on the trackbar position change. The created trackbar is displayed on top of the given window.
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 syncronized 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.
**[Qt Backend Only]**
Qt-specific details:
* **winname** Name of the window that will be used as a parent for created trackbar. It can be NULL if the trackbar should be attached to the control panel.
The created trackbar is displayed at the bottom of the given window if
*winname*
is correctly provided, or displayed on the control panel if
*winname*
is NULL.
Clicking the label of each trackbar enables editing the trackbar values manually for a more accurate control of it.
.. index:: getTrackbarPos
Clicking the label of each trackbar enables editing the trackbar values manually.
getTrackbarPos
------------------
Returns the trackbar position.
.. ocv:function:: int getTrackbarPos( const string& trackbarname, const string& winname )
Returns the trackbar position.
.. ocv:pyfunction:: cv2.getTrackbarPos(trackbarname, winname) -> retval
.. ocv:cfunction:: int cvGetTrackbarPos( const char* trackbarName, const char* windowName )
.. ocv:pyoldfunction:: cv.GetTrackbarPos(trackbarName, windowName)-> None
:param trackbarname: Name of the trackbar.
@@ -55,21 +49,20 @@ getTrackbarPos
The function returns the current position of the specified trackbar.
.. note::
**[Qt Backend Only]**
Qt-specific details:
* **winname** Name of the window that is the parent of the trackbar. It can be NULL if the trackbar is attached to the control panel.
.. index:: imshow
.. _imshow:
**[Qt Backend Only]** ``winname`` can be empty (or NULL) if the trackbar is attached to the control panel.
imshow
----------
Displays an image in the specified window.
.. ocv:function:: void imshow( const string& winname, InputArray image )
Displays an image in the specified window.
.. ocv:pyfunction:: cv2.imshow(winname, image) -> None
.. ocv:cfunction:: void cvShowImage( const char* winname, const CvArr* image )
.. ocv:pyoldfunction:: cv.ShowImage(winname, image)-> None
:param winname: Name of the window.
@@ -77,95 +70,135 @@ imshow
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 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 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 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].
.. index:: namedWindow
.. _namedWindow:
namedWindow
---------------
Creates a window.
.. ocv:function:: void namedWindow( const string& winname, int flags )
Creates a window.
.. ocv:pyfunction:: cv2.namedWindow(winname[, flags]) -> None
.. ocv:cfunction:: int cvNamedWindow( const char* name, int flags )
.. ocv:pyoldfunction:: cv.NamedWindow(name, flags=CV_WINDOW_AUTOSIZE)-> None
:param name: Name of the window in the window caption that may be used as a window identifier.
:param flags: Flags of the window. Currently the only supported flag is ``CV_WINDOW_AUTOSIZE`` . If this is set, the window size is automatically adjusted to fit the displayed image (see :ref:`imshow` ), and you cannot change the window size manually.
:param flags: Flags of the window. Currently the only supported flag is ``CV_WINDOW_AUTOSIZE`` . If this is set, the window size is automatically adjusted to fit the displayed image (see :ocv:func:`imshow` ), and you cannot change the window size manually.
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 :cpp:func:`destroyWindow` or :cpp:func:`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.
You can call :ocv:func:`destroyWindow` or :ocv:func:`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 Only]**
Qt-specific details:
Qt backend supports additional flags:
* **flags** Flags of the window. Currently the supported flags are:
* **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 :ocv:func:`imshow` ), and you cannot change the window size manually.
* **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 :ref:`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_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.
* **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``
This parameter is optional. The default flags set for a new window are ``CV_WINDOW_AUTOSIZE`` , ``CV_WINDOW_KEEPRATIO`` , and ``CV_GUI_EXPANDED`` .
However, if you want to modify the flags, you can combine them using the OR operator, that is:
::
namedWindow( "myWindow", CV_WINDOW_NORMAL | CV_GUI_NORMAL );
..
.. index:: destroyWindow
.. _destroyWindow:
destroyWindow
-------------
.. ocv:function:: void destroyWindow( const string &winname )
Destroys a window.
Destroys a window.
.. ocv:function:: void destroyWindow( const string &winname )
.. ocv:pyfunction:: cv2.destroyWindow(winname) -> None
.. ocv:cfunction:: void cvDestroyWindow( const char* name )
.. ocv:pyoldfunction:: cv.DestroyWindow(name)-> None
:param winname: Name of the window to be destroyed.
The function ``destroyWindow`` destroys the window with the given name.
.. index:: destroyAllWindows
.. _destroyAllWindows:
destroyAllWindows
-----------------
Destroys all of the HighGUI windows.
.. ocv:function:: void destroyAllWindows()
Destroys all of the HighGUI windows.
.. ocv:pyfunction:: cv2.destroyAllWindows() -> None
.. ocv:cfunction:: void cvDestroyAllWindows()
.. ocv:pyoldfunction:: cv.DestroyAllWindows()-> None
The function ``destroyAllWindows`` destroys all of the opened HighGUI windows.
.. index:: setTrackbarPos
MoveWindow
----------
Moves window to the specified position
.. ocv:cfunction:: void cvMoveWindow( const char* name, int x, int y )
.. ocv:pyoldfunction:: cv.MoveWindow(name, x, y)-> None
:param name: Window name
:param x: The new x-coordinate of the window
:param y: The new y-coordinate of the window
ResizeWindow
----------
Resizes window to the specified size
.. ocv:cfunction:: void cvResizeWindow( const char* name, int width, int height )
.. ocv:pyoldfunction:: cv.ResizeWindow(name, width, height)-> None
:param name: 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.
SetMouseCallback
----------------
Sets mouse handler for the specified window
.. ocv:cfunction:: void cvSetMouseCallback( const char* name, CvMouseCallback onMouse, void* param=NULL )
.. ocv:pyoldfunction:: cv.SetMouseCallback(name, onMouse, param) -> None
:param name: Window name
:param onMouse: Mouse callback. See OpenCV samples, such as https://code.ros.org/svn/opencv/trunk/opencv/samples/cpp/ffilldemo.cpp, on how to specify and use the callback.
:param param: The optional parameter passed to the callback.
.. _setTrackbarPos:
setTrackbarPos
------------------
Sets the trackbar position.
.. ocv:function:: void setTrackbarPos( const string& trackbarname, const string& winname, int pos )
Sets the trackbar position.
.. ocv:pyfunction:: cv2.setTrackbarPos(trackbarname, winname, pos) -> None
.. ocv:cfunction:: void cvSetTrackbarPos( const char* trackbarName, const char* windowName, int pos )
.. ocv:pyoldfunction:: cv.SetTrackbarPos(trackbarName, windowName, pos)-> None
:param trackbarname: Name of the trackbar.
@@ -175,30 +208,30 @@ setTrackbarPos
The function sets the position of the specified trackbar in the specified window.
**[Qt Backend Only]**
Qt-specific details:
* **winname** Name of the window that is the parent of the trackbar. It can be NULL if the trackbar is attached to the control panel.
.. index:: waitKey
.. _waitKey:
.. note::
**[Qt Backend Only]** ``winname`` can be empty (or NULL) if the trackbar is attached to the control panel.
waitKey
-----------
Waits for a pressed key.
.. ocv:function:: int waitKey(int delay=0)
Waits for a pressed key.
.. ocv:pyfunction:: cv2.waitKey([, delay]) -> retval
.. ocv:cfunction:: int cvWaitKey( int delay=0 )
.. ocv:pyoldfunction:: cv.WaitKey(delay=0)-> int
:param delay: Delay in milliseconds. 0 is the special value that means "forever".
The function ``waitKey`` waits for a key event infinitely (when
:math:`\texttt{delay}\leq 0` ) 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.
**Notes:**
.. 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.
* 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.
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.