Class cv::VideoCapture#

Class for video capturing from video files, image sequences or cameras. View details

#include <opencv2/videoio.hpp>

Collaboration diagram for cv::VideoCapture:

cv::VideoCapture Node1 cv::VideoCapture   + VideoCapture() + VideoCapture() + VideoCapture() + VideoCapture() + VideoCapture() + VideoCapture() + ~VideoCapture() + get() + getBackendName() + getExceptionMode() and 14 more... + waitAny() Node2 Ptr< IVideoCapture >     Node2->Node1 #icap Node3 bool     Node3->Node1 #throwOnFail

cv::VideoCapture Node1 cv::VideoCapture   + VideoCapture() + VideoCapture() + VideoCapture() + VideoCapture() + VideoCapture() + VideoCapture() + ~VideoCapture() + get() + getBackendName() + getExceptionMode() and 14 more... + waitAny() Node2 Ptr< IVideoCapture >     Node2->Node1 #icap Node3 bool     Node3->Node1 #throwOnFail

Friends#

Return

Name

Description

class

internal::VideoCapturePrivateAccessor

Detailed Description#

Class for video capturing from video files, image sequences or cameras.

The class provides C++ API for capturing video from cameras or for reading video files and image sequences.

Here is how the class can be used: 

#include <opencv2/core.hpp>
#include <opencv2/videoio.hpp>
#include <opencv2/highgui.hpp>
#include <iostream>
#include <stdio.h>

using namespace cv;
using namespace std;

int main(int, char**)
{
    Mat frame;
    //--- INITIALIZE VIDEOCAPTURE
    VideoCapture cap;
    // open the default camera using default API
    // cap.open(0);
    // OR advance usage: select any API backend
    int deviceID = 0;             // 0 = open default camera
    int apiID = cv::CAP_ANY;      // 0 = autodetect default API
    // open selected camera using selected API
    cap.open(deviceID, apiID);
    // check if we succeeded
    if (!cap.isOpened()) {
        cerr << "ERROR! Unable to open camera\n";
        return -1;
    }

    //--- GRAB AND WRITE LOOP
    cout << "Start grabbing" << endl
        << "Press any key to terminate" << endl;
    for (;;)
    {
        // wait for a new frame from camera and store it into 'frame'
        cap.read(frame);
        // check if we succeeded
        if (frame.empty()) {
            cerr << "ERROR! blank frame grabbed\n";
            break;
        }
        // show live and wait for a key with timeout long enough to show images
        imshow("Live", frame);
        if (waitKey(5) >= 0)
            break;
    }
    // the camera will be deinitialized automatically in VideoCapture destructor
    return 0;
}

Note

  • (C++) A basic sample on using the VideoCapture interface can be found at OPENCV_SOURCE_CODE/samples/cpp/videocapture_combined.cpp

  • (Python) A basic sample on using the VideoCapture interface can be found at OPENCV_SOURCE_CODE/samples/python/video.py

  • (Python) A multi threaded video processing sample can be found at OPENCV_SOURCE_CODE/samples/python/video_threaded.py

  • (Python) VideoCapture sample showcasing some features of the Video4Linux2 backend OPENCV_SOURCE_CODE/samples/python/video_v4l2.py

Examples
samples/facedetect.cpp, samples/hog_tapi.cpp, samples/peopledetect.cpp, samples/cpp/lkdemo.cpp, samples/cpp/tutorial_code/videoio/video-write/video-write.cpp, samples/cpp/videowriter.cpp, samples/dnn/classification.cpp, samples/dnn/object_detection.cpp, samples/dnn/segmentation.cpp, and samples/python/snippets/laplace.py.

Constructor & Destructor Documentation#

VideoCapture()#

cv::VideoCapture::VideoCapture()

Python:

cv.VideoCapture() -> <VideoCapture object>

cv.VideoCapture(filename[, apiPreference]) -> <VideoCapture object>

cv.VideoCapture(filename, apiPreference, params) -> <VideoCapture object>

cv.VideoCapture(index[, apiPreference]) -> <VideoCapture object>

cv.VideoCapture(index, apiPreference, params) -> <VideoCapture object>

cv.VideoCapture(source, apiPreference, params) -> <VideoCapture object>

Default constructor.

VideoCapture()#

cv::VideoCapture::VideoCapture(
const Ptr< IStreamReader > & source,
int apiPreference,
const std::vector< int > & params )

Python:

cv.VideoCapture() -> <VideoCapture object>

cv.VideoCapture(filename[, apiPreference]) -> <VideoCapture object>

cv.VideoCapture(filename, apiPreference, params) -> <VideoCapture object>

cv.VideoCapture(index[, apiPreference]) -> <VideoCapture object>

cv.VideoCapture(index, apiPreference, params) -> <VideoCapture object>

cv.VideoCapture(source, apiPreference, params) -> <VideoCapture object>

Opens a video using data stream.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

The params parameter allows to specify extra parameters encoded as pairs (paramId_1, paramValue_1, paramId_2, paramValue_2, ...). See cv::VideoCaptureProperties

VideoCapture()#

cv::VideoCapture::VideoCapture(
const String & filename,
int apiPreference,
const std::vector< int > & params )

Python:

cv.VideoCapture() -> <VideoCapture object>

cv.VideoCapture(filename[, apiPreference]) -> <VideoCapture object>

cv.VideoCapture(filename, apiPreference, params) -> <VideoCapture object>

cv.VideoCapture(index[, apiPreference]) -> <VideoCapture object>

cv.VideoCapture(index, apiPreference, params) -> <VideoCapture object>

cv.VideoCapture(source, apiPreference, params) -> <VideoCapture object>

Opens a video file or a capturing device or an IP video stream for video capturing with API Preference and parameters.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

The params parameter allows to specify extra parameters encoded as pairs (paramId_1, paramValue_1, paramId_2, paramValue_2, ...). See cv::VideoCaptureProperties

VideoCapture()#

cv::VideoCapture::VideoCapture(
const String & filename,
int apiPreference = CAP_ANY )

Python:

cv.VideoCapture() -> <VideoCapture object>

cv.VideoCapture(filename[, apiPreference]) -> <VideoCapture object>

cv.VideoCapture(filename, apiPreference, params) -> <VideoCapture object>

cv.VideoCapture(index[, apiPreference]) -> <VideoCapture object>

cv.VideoCapture(index, apiPreference, params) -> <VideoCapture object>

cv.VideoCapture(source, apiPreference, params) -> <VideoCapture object>

Opens a video file or a capturing device or an IP video stream for video capturing with API Preference.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

See also

cv::VideoCaptureAPIs

Parameters

  • filename — it can be:

    • name of video file (eg. video.avi)

    • or image sequence (eg. img_%02d.jpg, which will read samples like img_00.jpg, img_01.jpg, img_02.jpg, ...)

    • or URL of video stream (eg. protocol://host:port/script_name?script_params|auth)

    • or GStreamer pipeline string in gst-launch tool format in case if GStreamer is used as backend Note that each video stream or IP camera feed has its own URL scheme. Please refer to the documentation of source stream to know the right URL.

  • apiPreference — preferred Capture API backends to use. Can be used to enforce a specific reader implementation if multiple are available: e.g. cv::CAP_FFMPEG or cv::CAP_IMAGES or cv::CAP_DSHOW.

VideoCapture()#

cv::VideoCapture::VideoCapture(
int index,
int apiPreference,
const std::vector< int > & params )

Python:

cv.VideoCapture() -> <VideoCapture object>

cv.VideoCapture(filename[, apiPreference]) -> <VideoCapture object>

cv.VideoCapture(filename, apiPreference, params) -> <VideoCapture object>

cv.VideoCapture(index[, apiPreference]) -> <VideoCapture object>

cv.VideoCapture(index, apiPreference, params) -> <VideoCapture object>

cv.VideoCapture(source, apiPreference, params) -> <VideoCapture object>

Opens a camera for video capturing with API Preference and parameters.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

The params parameter allows to specify extra parameters encoded as pairs (paramId_1, paramValue_1, paramId_2, paramValue_2, ...). See cv::VideoCaptureProperties

VideoCapture()#

cv::VideoCapture::VideoCapture(
int index,
int apiPreference = CAP_ANY )

Python:

cv.VideoCapture() -> <VideoCapture object>

cv.VideoCapture(filename[, apiPreference]) -> <VideoCapture object>

cv.VideoCapture(filename, apiPreference, params) -> <VideoCapture object>

cv.VideoCapture(index[, apiPreference]) -> <VideoCapture object>

cv.VideoCapture(index, apiPreference, params) -> <VideoCapture object>

cv.VideoCapture(source, apiPreference, params) -> <VideoCapture object>

Opens a camera for video capturing.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

See also

cv::VideoCaptureAPIs

Parameters

  • index — id of the video capturing device to open. To open default camera using default backend just pass 0. (to backward compatibility usage of camera_id + domain_offset (CAP_*) is valid when apiPreference is CAP_ANY)

  • apiPreference — preferred Capture API backends to use. Can be used to enforce a specific reader implementation if multiple are available: e.g. cv::CAP_DSHOW or cv::CAP_MSMF or cv::CAP_V4L.

~VideoCapture()#

cv::VideoCapture::~VideoCapture()

Default destructor.

The method first calls VideoCapture::release to close the already opened file or camera.

Member Function Documentation#

get()#

double cv::VideoCapture::get(int propId)

Python:

cv.VideoCapture.get(propId) -> retval

Returns the specified VideoCapture property.

Note

Reading / writing properties involves many layers. Some unexpected result might happens along this chain.

VideoCapture -> API Backend -> Operating System -> Device Driver -> Device Hardware

The returned value might be different from what really used by the device or it could be encoded using device dependent rules (eg. steps or percentage). Effective behaviour depends from device driver and API Backend

Parameters

Returns

Value for the specified property. Value cv::CAP_PROP_UNKNOWN is returned when querying a property that is not supported by the backend used by the VideoCapture instance.

getBackendName()#

String cv::VideoCapture::getBackendName()

Python:

cv.VideoCapture.getBackendName() -> retval

Returns used backend API name.

Note

Stream should be opened.

getExceptionMode()#

bool cv::VideoCapture::getExceptionMode()

Python:

cv.VideoCapture.getExceptionMode() -> retval

query if exception mode is active

grab()#

bool cv::VideoCapture::grab()

Python:

cv.VideoCapture.grab() -> retval

Grabs the next frame from video file or capturing device.

The method/function grabs the next frame from video file or camera and returns 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 VideoCapture::retrieve() one or more times with different values of the channel parameter.

tutorial_kinect_openni

Returns

true (non-zero) in the case of success.

isOpened()#

bool cv::VideoCapture::isOpened()

Python:

cv.VideoCapture.isOpened() -> retval

Returns true if video capturing has been initialized already.

If the previous call to VideoCapture constructor or VideoCapture::open() succeeded, the method returns true.

open()#

bool cv::VideoCapture::open(
const Ptr< IStreamReader > & source,
int apiPreference,
const std::vector< int > & params )

Python:

cv.VideoCapture.open(filename[, apiPreference]) -> retval

cv.VideoCapture.open(filename, apiPreference, params) -> retval

cv.VideoCapture.open(index[, apiPreference]) -> retval

cv.VideoCapture.open(index, apiPreference, params) -> retval

cv.VideoCapture.open(source, apiPreference, params) -> retval

Opens a video using data stream.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

The params parameter allows to specify extra parameters encoded as pairs (paramId_1, paramValue_1, paramId_2, paramValue_2, ...). See cv::VideoCaptureProperties

The method first calls VideoCapture::release to close the already opened file or camera.

Returns

true if the file has been successfully opened

open()#

bool cv::VideoCapture::open(
const String & filename,
int apiPreference,
const std::vector< int > & params )

Python:

cv.VideoCapture.open(filename[, apiPreference]) -> retval

cv.VideoCapture.open(filename, apiPreference, params) -> retval

cv.VideoCapture.open(index[, apiPreference]) -> retval

cv.VideoCapture.open(index, apiPreference, params) -> retval

cv.VideoCapture.open(source, apiPreference, params) -> retval

Opens a video file or a capturing device or an IP video stream for video capturing with API Preference and parameters.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

The params parameter allows to specify extra parameters encoded as pairs (paramId_1, paramValue_1, paramId_2, paramValue_2, ...). See cv::VideoCaptureProperties

The method first calls VideoCapture::release to close the already opened file or camera.

Returns

true if the file has been successfully opened

open()#

bool cv::VideoCapture::open(
const String & filename,
int apiPreference = CAP_ANY )

Python:

cv.VideoCapture.open(filename[, apiPreference]) -> retval

cv.VideoCapture.open(filename, apiPreference, params) -> retval

cv.VideoCapture.open(index[, apiPreference]) -> retval

cv.VideoCapture.open(index, apiPreference, params) -> retval

cv.VideoCapture.open(source, apiPreference, params) -> retval

Opens a video file or a capturing device or an IP video stream for video capturing.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters are same as the constructor VideoCapture(const String& filename, int apiPreference = CAP_ANY) The method first calls VideoCapture::release to close the already opened file or camera.

Returns

true if the file has been successfully opened

open()#

bool cv::VideoCapture::open(
int index,
int apiPreference,
const std::vector< int > & params )

Python:

cv.VideoCapture.open(filename[, apiPreference]) -> retval

cv.VideoCapture.open(filename, apiPreference, params) -> retval

cv.VideoCapture.open(index[, apiPreference]) -> retval

cv.VideoCapture.open(index, apiPreference, params) -> retval

cv.VideoCapture.open(source, apiPreference, params) -> retval

Opens a camera for video capturing with API Preference and parameters.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

The params parameter allows to specify extra parameters encoded as pairs (paramId_1, paramValue_1, paramId_2, paramValue_2, ...). See cv::VideoCaptureProperties

The method first calls VideoCapture::release to close the already opened file or camera.

Returns

true if the camera has been successfully opened.

open()#

bool cv::VideoCapture::open(
int index,
int apiPreference = CAP_ANY )

Python:

cv.VideoCapture.open(filename[, apiPreference]) -> retval

cv.VideoCapture.open(filename, apiPreference, params) -> retval

cv.VideoCapture.open(index[, apiPreference]) -> retval

cv.VideoCapture.open(index, apiPreference, params) -> retval

cv.VideoCapture.open(source, apiPreference, params) -> retval

Opens a camera for video capturing.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters are same as the constructor VideoCapture(int index, int apiPreference = CAP_ANY) The method first calls VideoCapture::release to close the already opened file or camera.

Returns

true if the camera has been successfully opened.

operator>>()#

VideoCapture & cv::VideoCapture::operator>>(Mat & image)

Stream operator to read the next video frame.

See also

read()

operator>>()#

VideoCapture & cv::VideoCapture::operator>>(UMat & image)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

See also

read()

read()#

bool cv::VideoCapture::read(OutputArray image)

Python:

cv.VideoCapture.read([, image]) -> retval, image

Grabs, decodes and returns the next video frame.

The method/function combines VideoCapture::grab() and VideoCapture::retrieve() in one call. This is the most convenient method for reading video files or capturing data from decode and returns the just grabbed frame. If no frames has been grabbed (camera has been disconnected, or there are no more frames in video file), the method returns false and the function returns empty image (with cv::Mat, test it with Mat::empty()).

Parameters

  • image — the video frame is returned here. If no frames has been grabbed the image will be empty.

Returns

false if no frames has been grabbed

release()#

void cv::VideoCapture::release()

Python:

cv.VideoCapture.release()

Closes video file or capturing device.

The method is automatically called by subsequent VideoCapture::open and by VideoCapture destructor.

The C function also deallocates memory and clears *capture pointer.

retrieve()#

bool cv::VideoCapture::retrieve(
OutputArray image,
int flag = 0 )

Python:

cv.VideoCapture.retrieve([, image[, flag]]) -> retval, image

Decodes and returns the grabbed video frame.

The method decodes and returns the just grabbed frame. If no frames has been grabbed (camera has been disconnected, or there are no more frames in video file), the method returns false and the function returns an empty image (with cv::Mat, test it with Mat::empty()).

See also

read()

Parameters

  • image — the video frame is returned here. If no frames has been grabbed the image will be empty.

  • flag — it could be a frame index or a driver specific flag

Returns

false if no frames has been grabbed

set()#

bool cv::VideoCapture::set(
int propId,
double value )

Python:

cv.VideoCapture.set(propId, value) -> retval

Sets a property in the VideoCapture.

Note

Even if it returns true this doesn’t ensure that the property value has been accepted by the capture device. See note in VideoCapture::get()

Parameters

Returns

true if the property is supported by backend used by the VideoCapture instance.

setExceptionMode()#

void cv::VideoCapture::setExceptionMode(bool enable)

Python:

cv.VideoCapture.setExceptionMode(enable)

Switches exceptions mode

methods raise exceptions if not successful instead of returning an error code

waitAny()#

static bool cv::VideoCapture::waitAny(
const std::vector< VideoCapture > & streams,
std::vector< int > & readyIndex,
int64 timeoutNs = 0 )

Python:

cv.VideoCapture.waitAny(streams[, timeoutNs]) -> retval, readyIndex

cv.VideoCapture_waitAny(streams[, timeoutNs]) -> retval, readyIndex

Wait for ready frames from VideoCapture.

The primary use of the function is in multi-camera environments. The method fills the ready state vector, grabs video frame, if camera is ready.

After this call use VideoCapture::retrieve() to decode and fetch frame data.

Parameters

  • streams — input video streams

  • readyIndex — stream indexes with grabbed frames (ready to use .retrieve() to fetch actual frame)

  • timeoutNs — number of nanoseconds (0 - infinite)

Returns

true if streamReady is not empty

Member Data Documentation#

icap#

Ptr< IVideoCapture > cv::VideoCapture::icap

throwOnFail#

bool cv::VideoCapture::throwOnFail

Source file#

The documentation for this class was generated from the following file: