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.