Reading and Writing Images and Video

LoadImage

IplImage* cvLoadImage(const char* filename, int iscolor=CV_LOAD_IMAGE_COLOR)

Loads an image from a file as an IplImage.

Parameters:
  • filename – Name of file to be loaded.
  • iscolor

    Specific color type of the loaded image:

    • CV_LOAD_IMAGE_COLOR the loaded image is forced to be a 3-channel color image
    • CV_LOAD_IMAGE_GRAYSCALE the loaded image is forced to be grayscale
    • CV_LOAD_IMAGE_UNCHANGED the loaded image will be loaded as is.

The function cvLoadImage loads an image from the specified file and returns the pointer to the loaded image. Currently the following file formats are supported:

  • Windows bitmaps - BMP, DIB
  • JPEG files - JPEG, JPG, JPE
  • Portable Network Graphics - PNG
  • Portable image format - PBM, PGM, PPM
  • Sun rasters - SR, RAS
  • TIFF files - TIFF, TIF

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.

LoadImageM

CvMat* cvLoadImageM(const char* filename, int iscolor=CV_LOAD_IMAGE_COLOR)

Loads an image from a file as a CvMat.

Parameters:
  • filename – Name of file to be loaded.
  • iscolor

    Specific color type of the loaded image:

    • CV_LOAD_IMAGE_COLOR the loaded image is forced to be a 3-channel color image
    • CV_LOAD_IMAGE_GRAYSCALE the loaded image is forced to be grayscale
    • CV_LOAD_IMAGE_UNCHANGED the loaded image will be loaded as is.

The function cvLoadImageM loads an image from the specified file and returns the pointer to the loaded image. urrently the following file formats are supported:

  • Windows bitmaps - BMP, DIB
  • JPEG files - JPEG, JPG, JPE
  • Portable Network Graphics - PNG
  • Portable image format - PBM, PGM, PPM
  • Sun rasters - SR, RAS
  • TIFF files - TIFF, TIF

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.

SaveImage

int cvSaveImage(const char* filename, const CvArr* image)

Saves an image to a specified file.

Parameters:
  • filename – Name of the file.
  • image – Image to be saved.

The function cvSaveImage saves the image to the specified file. The image format is chosen based on the filename extension, see LoadImage . Only 8-bit 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 cvCvtScale and cvCvtColor to convert it before saving, or use universal cvSave to save the image to XML or YAML format.

CvCapture

CvCapture

Video capturing structure.

typedef struct CvCapture CvCapture()

The structure CvCapture does not have a public interface and is used only as a parameter for video capturing functions.

CaptureFromCAM

CvCapture* cvCaptureFromCAM(int index)

Initializes capturing a video from a camera.

Parameter:index – Index of the camera to be used. If there is only one camera or it does not matter what camera is used -1 may be passed.

The function cvCaptureFromCAM allocates and initializes the CvCapture structure for reading a video stream from the camera. Currently two camera interfaces can be used on Windows: Video for Windows (VFW) and Matrox Imaging Library (MIL); and two on Linux: V4L and FireWire (IEEE1394).

To release the structure, use ReleaseCapture .

CaptureFromFile

CvCapture* cvCaptureFromFile(const char* filename)

Initializes capturing a video from a file.

Parameter:filename – Name of the video file.

The function cvCaptureFromFile allocates and initializes the CvCapture structure for reading the video stream from the specified file. Which codecs and file formats are supported depends on the back end library. On Windows HighGui uses Video for Windows (VfW), on Linux ffmpeg is used and on Mac OS X the back end is QuickTime. See VideoCodecs for some discussion on what to expect and how to prepare your video files.

After the allocated structure is not used any more it should be released by the ReleaseCapture function.

GetCaptureProperty

double cvGetCaptureProperty(CvCapture* capture, int property_id)

Gets video capturing properties.

Parameters:
  • capture – video capturing structure.
  • 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_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)

The function cvGetCaptureProperty retrieves the specified property of the camera or video file.

GrabFrame

int cvGrabFrame(CvCapture* capture)

Grabs the frame from a camera or file.

Parameter:capture – video capturing structure.

The function cvGrabFrame grabs the frame from a camera or file. The grabbed frame is stored internally. The purpose of this function is to grab the frame quickly so that syncronization can occur if it has to read from several cameras simultaneously. The grabbed frames are not exposed because they may be stored in a compressed format (as defined by the camera/driver). To retrieve the grabbed frame, RetrieveFrame should be used.

QueryFrame

IplImage* cvQueryFrame(CvCapture* capture)

Grabs and returns a frame from a camera or file.

Parameter:capture – video capturing structure.

The function cvQueryFrame grabs a frame from a camera or video file, decompresses it and returns it. This function is just a combination of GrabFrame and RetrieveFrame , but in one call. The returned image should not be released or modified by the user. In the event of an error, the return value may be NULL.

ReleaseCapture

void cvReleaseCapture(CvCapture** capture)

Releases the CvCapture structure.

Parameter:capture – Pointer to video the capturing structure.

The function cvReleaseCapture releases the CvCapture structure allocated by CaptureFromFile or CaptureFromCAM .

RetrieveFrame

IplImage* cvRetrieveFrame(CvCapture* capture)

Gets the image grabbed with cvGrabFrame.

Parameter:capture – video capturing structure.

The function cvRetrieveFrame returns the pointer to the image grabbed with the GrabFrame function. The returned image should not be released or modified by the user. In the event of an error, the return value may be NULL.

SetCaptureProperty

int cvSetCaptureProperty(CvCapture* capture, int property_id, double value)

Sets video capturing properties.

Parameters:
  • capture – video capturing structure.
  • 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_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)
  • value – value of the property.

The function cvSetCaptureProperty sets the specified property of video capturing. Currently the function supports only video files: CV_CAP_PROP_POS_MSEC, CV_CAP_PROP_POS_FRAMES, CV_CAP_PROP_POS_AVI_RATIO .

NB This function currently does nothing when using the latest CVS download on linux with FFMPEG (the function contents are hidden if 0 is used and returned).

CreateVideoWriter

typedef struct CvVideoWriter CvVideoWriter CvVideoWriter* cvCreateVideoWriter(const char* filename, int fourcc, double fps, CvSize frame_size, int is_color=1)

Creates the video file writer.

Parameters:
  • filename – Name of the output video file.
  • 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. Under Win32 it is possible to pass -1 in order to choose compression method and additional compression parameters from dialog. Under Win32 if 0 is passed while using an avi filename it will create a video writer that creates an uncompressed avi file.
  • fps – Framerate of the created video stream.
  • frame_size – Size of the video frames.
  • is_color – 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 function cvCreateVideoWriter creates the video writer structure.

Which codecs and file formats are supported depends on the back end library. On Windows HighGui uses Video for Windows (VfW), on Linux ffmpeg is used and on Mac OS X the back end is QuickTime. See VideoCodecs for some discussion on what to expect.

ReleaseVideoWriter

void cvReleaseVideoWriter(CvVideoWriter** writer)

Releases the AVI writer.

Parameter:writer – Pointer to the video file writer structure.

The function cvReleaseVideoWriter finishes writing to the video file and releases the structure.

WriteFrame

int cvWriteFrame(CvVideoWriter* writer, const IplImage* image)

Writes a frame to a video file.

Parameters:
  • writer – Video writer structure
  • image – The written frame

The function cvWriteFrame writes/appends one frame to a video file.