generic-library/opencv
1
0
Fork 0
Code Issues Pull Requests 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

395
modules/highgui/doc/reading_and_writing_images_and_video.rst
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.