generic-library/opencv
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

OpenCV reference manual (C++ part only for now) is now produced directly from RST, not from TeX.

Browse Source
This commit is contained in:
Vadim Pisarevsky
2011-02-22 20:43:26 +00:00
parent 32a2fde8ac
commit 371aa08006
65 changed files with 41233 additions and 98 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
modules/highgui/doc/highgui.rst Normal file
View File

@@ -0,0 +1,3 @@
****************************
High-level GUI and Media I/O
****************************

39
modules/highgui/doc/highgui__high-level_gui_and_media_i_o.rst Normal file
View File

@@ -0,0 +1,39 @@
*************************************
highgui. High-level GUI and Media I/O
*************************************
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 is a need to try some 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 commmands
*
read and write images to/from disk or memory.
*
read video from camera or file and write video to a file.
.. toctree::
:maxdepth: 2
highgui_user_interface
highgui_reading_and_writing_images_and_video
highgui_qt_new_functions

607
modules/highgui/doc/qt_new_functions.rst Normal file
View File

@@ -0,0 +1,607 @@
Qt new functions
================
.. highlight:: cpp
.. image:: ../../pics/Qt_GUI.png
This figure explains the new functionalities implemented with Qt GUI. As we can see, the new GUI provides a statusbar, a toolbar, and a control panel. The control panel can have trackbars and buttonbars attached to it.
*
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 on 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.
::
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;
}
..
.. index:: setWindowProperty
cv::setWindowProperty
---------------------
`id=0.202216555435 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/highgui/setWindowProperty>`__
.. cfunction:: void setWindowProperty(const string\& name, int prop_id, double prop_value)
Change the parameters of the window dynamically.
:param name: Name of the window.
:param prop_id: Window's property to edit. The operation flags:
* **CV_WND_PROP_FULLSCREEN** Change if the window is fullscreen ( ``CV_WINDOW_NORMAL`` or ``CV_WINDOW_FULLSCREEN`` ).
* **CV_WND_PROP_AUTOSIZE** Change if the user can resize the window (texttt {CV\_WINDOW\_NORMAL} or ``CV_WINDOW_AUTOSIZE`` ).
* **CV_WND_PROP_ASPECTRATIO** Change if the image's aspect ratio is preserved (texttt {CV\_WINDOW\_FREERATIO} or ``CV_WINDOW_KEEPRATIO`` ).
:param prop_value: New value of the Window's property. The operation flags:
* **CV_WINDOW_NORMAL** Change the window in normal size, or allows the user to resize the window.
* **CV_WINDOW_AUTOSIZE** The user cannot resize the window, the size is constrainted by the image displayed.
* **CV_WINDOW_FULLSCREEN** Change the window to fullscreen.
* **CV_WINDOW_FREERATIO** The image expends as much as it can (no ratio constraint)
* **CV_WINDOW_KEEPRATIO** The ration image is respected.
The function
`` setWindowProperty``
allows to change the window's properties.
.. index:: getWindowProperty
cv::getWindowProperty
---------------------
`id=0.467280795493 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/highgui/getWindowProperty>`__
.. cfunction:: void getWindowProperty(const char* name, int prop_id)
Get the parameters of the window.
:param name: Name of the window.
:param prop_id: Window's property to retrive. The operation flags:
* **CV_WND_PROP_FULLSCREEN** Change if the window is fullscreen ( ``CV_WINDOW_NORMAL`` or ``CV_WINDOW_FULLSCREEN`` ).
* **CV_WND_PROP_AUTOSIZE** Change if the user can resize the window (texttt {CV\_WINDOW\_NORMAL} or ``CV_WINDOW_AUTOSIZE`` ).
* **CV_WND_PROP_ASPECTRATIO** Change if the image's aspect ratio is preserved (texttt {CV\_WINDOW\_FREERATIO} or ``CV_WINDOW_KEEPRATIO`` ).
See
:ref:`setWindowProperty`
to know the meaning of the returned values.
The function
`` getWindowProperty``
return window's properties.
.. index:: fontQt
cv::fontQt
----------
`id=0.680350496921 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/highgui/fontQt>`__
.. cfunction:: 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)
Create the font to be used to draw 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 will be 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 weight: The operation flags:
* **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 more control.
:param style: The operation flags:
* **CV_STYLE_NORMAL** Font is normal
* **CV_STYLE_ITALIC** Font is in italic
* **CV_STYLE_OBLIQUE** Font is oblique
:param spacing: Spacing between characters. 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:
::
CvFont font = fontQt(''Times'');
addText( img1, ``Hello World !'', Point(50,50), font);
..
.. index:: addText
cv::addText
-----------
`id=0.0425492674947 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/highgui/addText>`__
.. cfunction:: void addText(const Mat\& img, const string\& text, Point location, CvFont *font)
Create the font to be used to draw text on an image
:param img: Image where the text should be drawn
:param text: Text to write on the image
:param location: Point(x,y) where the text should start on the image
:param font: Font to use to draw the text
The function
``addText``
draw
*text*
on the image
*img*
using a specific font
*font*
(see example
:ref:`fontQt`
)
.. index:: displayOverlay
cv::displayOverlay
------------------
`id=0.969508597197 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/highgui/displayOverlay>`__
.. cfunction:: void displayOverlay(const string\& name, const string\& text, int delay)
Display text on the window's image as an overlay for delay milliseconds. This is not editing the image's data. The text is display on the top of the image.
:param name: Name of the window
:param text: Overlay text to write on the window's image
:param delay: Delay to display the overlay text. If this function is called before the previous overlay text time out, the timer is restarted and the text updated. . If this value is zero, the text never disapers.
The function
``displayOverlay``
aims at displaying useful information/tips on the window for a certain amount of time
*delay*
. This information is display on the top of the window.
.. index:: displayStatusBar
cv::displayStatusBar
--------------------
`id=0.132014751496 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/highgui/displayStatusBar>`__
.. cfunction:: void displayStatusBar(const string\& name, const string\& text, int delayms)
Display text on the window's statusbar as for delay milliseconds.
:param name: Name of the window
:param text: Text to write on the window's statusbar
:param delay: Delay to display the text. If this function is called before the previous text time out, the timer is restarted and the text updated. If this value is zero, the text never disapers.
The function
``displayOverlay``
aims at displaying useful information/tips on the window for a certain amount of time
*delay*
. This information is displayed on the window's statubar (the window must be created with
``CV_GUI_EXPANDED``
flags).
.. index:: createOpenGLCallback
cv::createOpenGLCallback
------------------------
`id=0.0486773148219 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/highgui/createOpenGLCallback>`__
*_*
.. cfunction:: 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)
Create a callback function called to draw OpenGL on top the the image display by windowname.
:param window_name: Name of the window
:param callbackOpenGL:
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)*
:param angle: Specifies the field of view angle, in degrees, in the y direction.. *(Optional - Default 45 degree)*
:param zmin: Specifies the distance from the viewer to the near clipping plane (always positive). *(Optional - Default 0.01)*
:param zmax: Specifies the distance from the viewer to the far clipping plane (always positive). *(Optional - Default 1000)*
The function
``createOpenGLCallback``
can be used to draw 3D data on the window. An example of callback could be:
::
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();
}
}
..
.. index:: saveWindowParameters
cv::saveWindowParameters
------------------------
`id=0.189887022151 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/highgui/saveWindowParameters>`__
*_*
.. cfunction:: void saveWindowParameters(const string\& name)
Save parameters of the window windowname.
: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
cv::loadWindowParameters
------------------------
`id=0.922344403304 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/highgui/loadWindowParameters>`__
*_*
.. cfunction:: void loadWindowParameters(const string\& name)
Load parameters of the window windowname.
:param name: Name of the window
The function
``loadWindowParameters``
load size, location, flags, trackbars' value, zoom and panning location of the window
*window_name*
.. index:: createButton
cv::createButton
----------------
`id=0.367650849719 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/highgui/createButton>`__
*_*
.. cfunction:: 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)
Create a callback function called to draw OpenGL on top the the image display by windowname.
:param button_name: Name of the button *( if NULL, the name will be "button <number of boutton>")*
:param on_change:
Pointer to the function to be called every time the button changed 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. *(Optional)*
The
``button_type``
parameter can be :
*(Optional -- Will be a push button by default.)
* **CV_PUSH_BUTTON** The button will be a push button.
* **CV_CHECKBOX** The button will be a checkbox button.
* **CV_RADIOBOX** The button will be a radiobox button. The radiobox on the same buttonbar (same line) are exclusive; one on can be select at the time.
*

624
modules/highgui/doc/reading_and_writing_images_and_video.rst Normal file
View File

@@ -0,0 +1,624 @@
Reading and Writing Images and Video
====================================
.. highlight:: cpp
.. index:: imdecode
cv::imdecode
------------
`id=0.524391584247 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/highgui/imdecode>`__
.. cfunction:: Mat imdecode( const Mat\& buf, int flags )
Reads an image from a buffer in memory.
:param buf: The input array of vector of bytes
:param flags: The same flags as in :ref:`imread`
The function reads image from the specified buffer in memory.
If the buffer is too short or contains invalid data, the empty matrix will be returned.
See
:ref:`imread`
for the list of supported formats and the flags description.
.. index:: imencode
cv::imencode
------------
`id=0.960190095821 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/highgui/imencode>`__
.. cfunction:: bool imencode( const string\& ext, const Mat\& img, vector<uchar>\& buf, const vector<int>\& params=vector<int>())
Encode an image into a memory buffer.
:param ext: The file extension that defines the output format
:param img: The image to be written
:param buf: The output buffer; resized to fit the compressed image
:param params: The format-specific parameters; see :ref:`imwrite`
The function compresses the image and stores it in the memory buffer, which is resized to fit the result.
See
:ref:`imwrite`
for the list of supported formats and the flags description.
.. index:: imread
cv::imread
----------
`id=0.16110153292 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/highgui/imread>`__
.. cfunction:: Mat imread( const string\& filename, int flags=1 )
Loads an image from a file.
:param filename: Name of file to be loaded.
:param flags: Specifies color type of the loaded image:
* **>0** the loaded image is forced to be a 3-channel color image
* **=0** the loaded image is forced to be grayscale
* **<0** the loaded image will be loaded as-is (note that in the current implementation the alpha channel, if any, is stripped from the output image, e.g. 4-channel RGBA image will be loaded as RGB if :math:`flags\ge0` ).
The function
``imread``
loads an image from the specified file and returns it. If the image can not be read (because of missing file, improper permissions, unsupported or invalid format), the function returns empty matrix (
``Mat::data==NULL``
).Currently, the following file formats are supported:
*
Windows bitmaps -
``*.bmp, *.dib``
(always supported)
*
JPEG files -
``*.jpeg, *.jpg, *.jpe``
(see
**Note2**
)
*
JPEG 2000 files -
``*.jp2``
(see
**Note2**
)
*
Portable Network Graphics -
``*.png``
(see
**Note2**
)
*
Portable image format -
``*.pbm, *.pgm, *.ppm``
(always supported)
*
Sun rasters -
``*.sr, *.ras``
(always supported)
*
TIFF files -
``*.tiff, *.tif``
(see
**Note2**
)
**Note1**
: The function determines type of the image by the content, not by the file extension.
**Note2**
: On Windows and MacOSX the shipped with OpenCV image codecs (libjpeg, libpng, libtiff and libjasper) are used by default; so OpenCV can always read JPEGs, PNGs and TIFFs. On MacOSX there is also the option to use native MacOSX image readers. But beware that currently these native image loaders give images with somewhat different pixel values, because of the embedded into MacOSX color management.
On Linux, BSD flavors and other Unix-like open-source operating systems OpenCV looks for the supplied with OS image codecs. Please, install the relevant packages (do not forget the development files, e.g. "libjpeg-dev" etc. in Debian and Ubuntu) in order to get the codec support, or turn on
``OPENCV_BUILD_3RDPARTY_LIBS``
flag in CMake.
.. index:: imwrite
cv::imwrite
-----------
`id=0.00846497387051 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/highgui/imwrite>`__
.. cfunction:: bool imwrite( const string\& filename, const Mat\& img, const vector<int>\& params=vector<int>())
Saves an image to a specified file.
:param filename: Name of the file.
:param img: The image to be saved.
:param params: The format-specific save parameters, encoded as pairs ``paramId_1, paramValue_1, paramId_2, paramValue_2, ...`` . The following parameters are currently supported:
* In the case of JPEG it can be a quality ( ``CV_IMWRITE_JPEG_QUALITY`` ), from 0 to 100 (the higher is the better), 95 by default.
* In the case of PNG it can be the compression level ( ``CV_IMWRITE_PNG_COMPRESSION`` ), from 0 to 9 (the higher value means smaller size and longer compression time), 3 by default.
* In the case of PPM, PGM or PBM it can a binary format flag ( ``CV_IMWRITE_PXM_BINARY`` ), 0 or 1, 1 by default.
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 the 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:
VideoCapture
------------
`id=0.267295181599 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/highgui/VideoCapture>`__
.. ctype:: VideoCapture
Class for video capturing from video files or cameras
::
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"
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, CV_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;
}
..
.. index:: VideoCapture::VideoCapture
cv::VideoCapture::VideoCapture
------------------------------
`id=0.788880569149 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/highgui/VideoCapture%3A%3AVideoCapture>`__
.. cfunction:: VideoCapture::VideoCapture()
.. cfunction:: VideoCapture::VideoCapture(const string\& filename)
.. cfunction:: VideoCapture::VideoCapture(int device)
:param filename: TOWRITE
:param device: TOWRITE
VideoCapture constructors.
.. index:: VideoCapture::get
cv::VideoCapture::get
---------------------
`id=0.977076859044 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/highgui/VideoCapture%3A%3Aget>`__
.. cfunction:: double VideoCapture::get(int property_id)
:param property_id: Property identifier. Can be one of the following:
* **CV_CAP_PROP_POS_MSEC** Film current position 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** The format of the Mat objects returned by retrieve()
* **CV_CAP_PROP_MODE** A 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** TOWRITE (note: only supported by DC1394 v 2.x backend currently)
Note that when querying a property which is unsupported by the backend used by the VideoCapture class, the value 0 is returned.
.. index:: VideoCapture::set
cv::VideoCapture::set
---------------------
`id=0.845027627213 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/highgui/VideoCapture%3A%3Aset>`__
.. cfunction:: bool VideoCapture::set(int property_id, double value)
:param property_id: Property identifier. Can be one of the following:
* **CV_CAP_PROP_POS_MSEC** Film current position 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** The format of the Mat objects returned by retrieve()
* **CV_CAP_PROP_MODE** A 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** TOWRITE (note: only supported by DC1394 v 2.x backend currently)
:param value: value of the property.
Sets a property in the VideoCapture backend.
.. index:: VideoWriter
.. _VideoWriter:
VideoWriter
-----------
`id=0.234127975013 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/highgui/VideoWriter>`__
.. ctype:: VideoWriter
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);
// returns true if the writer has been initialized successfully
virtual bool isOpened() const;
// writes the next video frame to the stream
virtual VideoWriter& operator << (const Mat& image);
protected:
...
};
..

315
modules/highgui/doc/user_interface.rst Normal file
View File

@@ -0,0 +1,315 @@
User Interface
==============
.. highlight:: cpp
.. index:: createTrackbar
cv::createTrackbar
------------------
`id=0.122963695249 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/highgui/createTrackbar>`__
.. cfunction:: int createTrackbar( const string\& trackbarname, const string\& winname, int* value, int count, TrackbarCallback onChange CV_DEFAULT(0), void* userdata CV_DEFAULT(0))
Creates a trackbar and attaches it to the specified window
:param trackbarname: Name of the created trackbar.
:param winname: Name of the window which will be used as a parent of the created trackbar.
:param value: The optional pointer to an integer variable, whose value will reflect the position of the slider. Upon creation, the slider position is defined by this variable.
:param count: The 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 NULL pointer, then no callbacks is called, but only ``value`` is updated
:param userdata: The 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 trackbar position and specifies a callback function
``onChange``
to be called on the trackbar position change. The created trackbar is displayed on the top of the given window.
\
\
**[Qt Backend Only]**
qt-specific details:
* **winname** Name of the window which will be used as a parent for created trackbar. 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.
By clicking on the label of each trackbar, it is possible to edit the trackbar's value manually for a more accurate control of it.
.. index:: getTrackbarPos
cv::getTrackbarPos
------------------
`id=0.51821188779 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/highgui/getTrackbarPos>`__
.. cfunction:: int getTrackbarPos( const string\& trackbarname, const string\& winname )
Returns the trackbar position.
:param trackbarname: Name of the trackbar.
:param winname: Name of the window which is the parent of the trackbar.
The function returns the current position of the specified trackbar.
\
\
**[Qt Backend Only]**
qt-specific details:
* **winname** Name of the window which is the parent of the trackbar. Can be NULL if the trackbar is attached to the control panel.
.. index:: imshow
cv::imshow
----------
`id=0.765508098436 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/highgui/imshow>`__
.. cfunction:: void imshow( const string\& winname, const Mat\& image )
Displays the image in the specified window
:param winname: Name of the window.
:param image: Image to be shown.
The function
``imshow``
displays the image in the specified window. If the window was created with the
``CV_WINDOW_AUTOSIZE``
flag then the image is shown with its original size, otherwise the image is scaled to fit in 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].
.. index:: namedWindow
cv::namedWindow
---------------
`id=0.618574996458 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/highgui/namedWindow>`__
.. cfunction:: void namedWindow( const string\& winname, int flags )
Creates a window.
: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 the user can not change the window size manually.
The function
``namedWindow``
creates a window which 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.
\
\
**[Qt Backend Only]**
qt-specific details:
* **flags** Flags of the window. Currently the supported flags are:
* **CV_WINDOW_NORMAL or CV_WINDOW_AUTOSIZE:** ``CV_WINDOW_NORMAL`` let the user resize the window, whereas ``CV_WINDOW_AUTOSIZE`` adjusts automatically the window's size to fit the displayed image (see :ref:`ShowImage` ), and the user can not change the window size manually.
* **CV_WINDOW_FREERATIO or CV_WINDOW_KEEPRATIO:** ``CV_WINDOW_FREERATIO`` adjust the image without respect the its ration, whereas ``CV_WINDOW_KEEPRATIO`` keep the image's 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 the new enhance GUI.
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 OR operator, ie:
::
namedWindow( ``myWindow'', ``CV_WINDOW_NORMAL`` textbar ``CV_GUI_NORMAL`` );
..
.. index:: setTrackbarPos
cv::setTrackbarPos
------------------
`id=0.247665233354 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/highgui/setTrackbarPos>`__
.. cfunction:: void setTrackbarPos( const string\& trackbarname, const string\& winname, int pos )
Sets the trackbar position.
:param trackbarname: Name of the trackbar.
:param winname: Name of the window which is the parent of trackbar.
:param pos: The new position.
The function sets the position of the specified trackbar in the specified window.
\
\
**[Qt Backend Only]**
qt-specific details:
* **winname** Name of the window which is the parent of trackbar. Can be NULL if the trackbar is attached to the control panel.
.. index:: waitKey
cv::waitKey
-----------
`id=0.777845991089 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/highgui/waitKey>`__
.. cfunction:: int waitKey(int delay=0)
Waits for a pressed key.
:param delay: Delay in milliseconds. 0 is the special value that means "forever"
The function
``waitKey``
waits for key event infinitely (when
:math:`\texttt{delay}\leq 0`
) or for
``delay``
milliseconds, when it's positive. 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 some environment that takes care of event processing.
**Note 2:**
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.