1
\section{HighGUI. Image, Video I/O and simple UI functions}
3
While OpenCV was designed for use in full-scale
4
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.
6
It provides easy interface to:
8
\item create and manipulate windows that can display images and "remember" their content (no need to handle repaint events from OS)
9
\item add trackbars to the windows, handle simple mouse events as well as keyboard commmands
10
\item read and write images to/from disk or memory.
11
\item read video from camera or file and write video to a file.
14
\subsection{The Reference}
16
\cvfunc{createTrackbar}\label{createTrackbar}
19
int createTrackbar( const string& trackbarname, const string& winname,
20
int* value, int count,
21
TrackbarCallback onChange CV_DEFAULT(0),
22
void* userdata CV_DEFAULT(0));
25
\cvarg{trackbarname}{Name of the created trackbar.}
26
\cvarg{winname}{Name of the window which will be used as a parent of the created trackbar.}
27
\cvarg{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.}
28
\cvarg{count}{The maximal position of the slider. The minimal position is always 0.}
29
\cvarg{onChange}{Pointer to the function to be called every time the slider changes position. This function should be prototyped as \texttt{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 \texttt{value} is updated}
30
\cvarg{userdata}{The user data that is passed as-is to the callback; it can be used to handle trackbar events without using global variables}
33
The function \texttt{createTrackbar} creates a trackbar (a.k.a. slider or range control) with the specified name and range, assigns a variable \texttt{value} to be syncronized with trackbar position and specifies a callback function \texttt{onChange} to be called on the trackbar position change. The created trackbar is displayed on the top of the given window.
36
\cvfunc{getTrackbarPos}\label{getTrackbarPos}
37
Returns the trackbar position.
40
int getTrackbarPos( const string& trackbarname, const string& winname );
43
\cvarg{trackbarname}{Name of the trackbar.}
44
\cvarg{winname}{Name of the window which is the parent of the trackbar.}
47
The function returns the current position of the specified trackbar.
49
\cvfunc{imdecode}\label{imdecode}
52
Mat imdecode( const Mat& buf, int flags );
55
\cvarg{buf}{The input array of vector of bytes}
56
\cvarg{flags}{The same flags as in \cross{imread}}
59
The function reads image from the specified buffer in memory.
60
If the buffer is too short or contains invalid data, the empty matrix will be returned.
62
See \cross{imread} for the list of supported formats and the flags description.
64
\cvfunc{imencode}\label{imencode}
67
bool imencode( const string& ext, const Mat& img,
69
const vector<int>& params=vector<int>());
72
\cvarg{ext}{The file extension that defines the output format}
73
\cvarg{img}{The image to be written}
74
\cvarg{buf}{The output buffer; resized to fit the compressed image}
75
\cvarg{params}{The format-specific parameters; see \cross{imwrite}}
78
The function compresses the image and stores it in the memory buffer, which is resized to fit the result.
79
See \cross{imwrite} for the list of supported formats and the flags description.
82
\cvfunc{imread}\label{imread}
83
Loads an image from a file.
86
Mat imread( const string& filename, int flags=1 );
88
#define CV_LOAD_IMAGE_COLOR 1
89
#define CV_LOAD_IMAGE_GRAYSCALE 0
90
#define CV_LOAD_IMAGE_UNCHANGED -1
94
\cvarg{filename}{Name of file to be loaded.}
95
\cvarg{flags}{Specifies color type of the loaded image: if $>$0, the loaded image is forced to be a 3-channel color image; if 0, the loaded image is forced to be grayscale; if $<$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).}
98
The function \texttt{imread} loads an image from the specified file and returns it. Currently, the following file formats are supported:
100
\item Windows bitmaps - \texttt{*.bmp, *.dib} (always supported)
101
\item JPEG files - \texttt{*.jpeg, *.jpg, *.jpe} (see \textbf{Note2})
102
\item JPEG 2000 files - \texttt{*.jp2} (see \textbf{Note2})
103
\item Portable Network Graphics - \texttt{*.png} (see \textbf{Note2})
104
\item Portable image format - \texttt{*.pbm, *.pgm, *.ppm} (always supported)
105
\item Sun rasters - \texttt{*.sr, *.ras} (always supported)
106
\item TIFF files - \texttt{*.tiff, *.tif} (see \textbf{Note2})
109
\textbf{Note1}: The function determines type of the image by the content, not by the file extension.
111
\textbf{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.
113
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 \texttt{OPENCV\_BUILD\_3RDPARTY\_LIBS} flag in CMake.
115
\cvfunc{imshow}\label{imshow}
116
Displays the image in the specified window
119
void imshow( const string& winname, const Mat& image );
122
\cvarg{winname}{Name of the window.}
123
\cvarg{image}{Image to be shown.}
126
The function \texttt{imshow} displays the image in the specified window. If the window was created with the \texttt{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:
128
\item If the image is 8-bit unsigned, it is displayed as is.
129
\item 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].
130
\item 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].
133
\cvfunc{imwrite}\label{imwrite}
134
Saves an image to a specified file.
137
bool imwrite( const string& filename, const Mat& img,
138
const vector<int>& params=vector<int>());
139
#define CV_IMWRITE_JPEG_QUALITY 1
140
#define CV_IMWRITE_PNG_COMPRESSION 16
141
#define CV_IMWRITE_PXM_BINARY 32
144
\cvarg{filename}{Name of the file.}
145
\cvarg{img}{The image to be saved.}
146
\cvarg{params}{The format-specific save parameters, encoded as pairs \texttt{paramId\_1, paramValue\_1, paramId\_2, paramValue\_2, ...}. The following parameters are currently supported:
148
\item In the case of JPEG it can be a quality (\texttt{CV\_IMWRITE\_JPEG\_QUALITY}), from 0 to 100 (the higher is the better), 95 by default.
149
\item In the case of PNG it can be the compression level (\texttt{CV\_IMWRITE\_PNG\_COMPRESSION}), from 0 to 9 (the higher value means smaller size and longer compression time), 3 by default.
150
\item In the case of PPM, PGM or PBM it can a binary format flag (\texttt{CV\_IMWRITE\_PXM\_BINARY}), 0 or 1, 1 by default.
155
The function \texttt{imwrite} saves the image to the specified file. The image format is chosen based on the \texttt{filename} extension, see \cross{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 \cross{Mat::convertTo}, and \cross{cvtColor} to convert it before saving, or use the universal XML I/O functions to save the image to XML or YAML format.
157
\cvfunc{namedWindow}\label{namedWindow}
161
void namedWindow( const string& winname, int flags );
164
\cvarg{name}{Name of the window in the window caption that may be used as a window identifier.}
165
\cvarg{flags}{Flags of the window. Currently the only supported flag is \texttt{CV\_WINDOW\_AUTOSIZE}. If this is set, the window size is automatically adjusted to fit the displayed image (see \cross{imshow}), and the user can not change the window size manually.}
168
The function \texttt{namedWindow} creates a window which can be used as a placeholder for images and trackbars. Created windows are referred to by their names.
170
If a window with the same name already exists, the function does nothing.
172
\cvfunc{setTrackbarPos}\label{setTrackbarPos}
173
Sets the trackbar position.
176
void setTrackbarPos( const string& trackbarname, const string& winname, int pos );
179
\cvarg{trackbarname}{Name of the trackbar.}
180
\cvarg{winname}{Name of the window which is the parent of trackbar.}
181
\cvarg{pos}{The new position.}
184
The function sets the position of the specified trackbar in the specified window.
187
\cvfunc{VideoCapture}\label{VideoCapture}
188
Class for video capturing from video files or cameras
194
// the default constructor
196
// the constructor that opens video file
197
VideoCapture(const string& filename);
198
// the constructor that starts streaming from the camera
199
VideoCapture(int device);
202
virtual ~VideoCapture();
204
// opens the specified video file
205
virtual bool open(const string& filename);
207
// starts streaming from the specified camera by its id
208
virtual bool open(int device);
210
// returns true if the file was open successfully or if the camera
211
// has been initialized succesfully
212
virtual bool isOpened() const;
214
// closes the camera stream or the video file
215
// (automatically called by the destructor)
216
virtual void release();
218
// grab the next frame or a set of frames from a multi-head camera;
219
// returns false if there are no more frames
221
// reads the frame from the specified video stream
222
// (non-zero channel is only valid for multi-head camera live streams)
223
virtual bool retrieve(Mat& image, int channel=0);
224
// equivalent to grab() + retrieve(image, 0);
225
virtual VideoCapture& operator >> (Mat& image);
227
// sets the specified property propId to the specified value
228
virtual bool set(int propId, double value);
229
// retrieves value of the specified property
230
virtual double get(int propId);
237
See \hyperref[AutomaticMemoryManagement2]{the CXCORE introduction} for the sample code.
239
\cvfunc{VideoWriter}\label{VideoWriter}
246
// default constructor
248
// constructor that calls open
249
VideoWriter(const string& filename, int fourcc,
250
double fps, Size frameSize, bool isColor=true);
253
virtual ~VideoWriter();
255
// opens the file and initializes the video writer.
256
// filename - the output file name.
257
// fourcc - the codec
258
// fps - the number of frames per second
259
// frameSize - the video frame size
260
// isColor - specifies whether the video stream is color or grayscale
261
virtual bool open(const string& filename, int fourcc,
262
double fps, Size frameSize, bool isColor=true);
264
// returns true if the writer has been initialized successfully
265
virtual bool isOpened() const;
267
// writes the next video frame to the stream
268
virtual VideoWriter& operator << (const Mat& image);
275
\cvfunc{waitKey}\label{waitKey}
276
Waits for a pressed key.
279
int waitKey(int delay=0);
282
\cvarg{delay}{Delay in milliseconds. 0 is the special value that means "forever"}
285
The function \texttt{waitKey} waits for key event infinitely (when $\texttt{delay}\leq 0$) or for \texttt{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.
287
\textbf{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.
added
removed
doc/HighGui-cpp.tex
