VideoCapture

Objective-C

@interface VideoCapture : NSObject

Swift

class VideoCapture : NSObject

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: samples/cpp/videocapture_basic.cpp

Note

In REF: videoio_c “C API” the black-box structure CvCapture is used instead of %VideoCapture. @note

(C++) A basic sample on using the %VideoCapture interface can be found at OPENCV_SOURCE_CODE/samples/cpp/videocapture_starter.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

Member of Videoio

Methods


                    
                    
                    -initWithFilename:apiPreference:

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

Declaration

Objective-C

- (nonnull instancetype)initWithFilename:(nonnull NSString *)filename
                           apiPreference:(int)apiPreference;

Swift

init(filename: String, apiPreference: Int32)

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.

See

cv::VideoCaptureAPIs


                    
                    
                    -initWithFilename:

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

Declaration

Objective-C

- (nonnull instancetype)initWithFilename:(nonnull NSString *)filename;

Swift

init(filename: String)

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. implementation if multiple are available: e.g. cv::CAP_FFMPEG or cv::CAP_IMAGES or cv::CAP_DSHOW.

See

cv::VideoCaptureAPIs


                    
                    
                    -initWithIndex:apiPreference:

  Opens a camera for video capturing

Declaration

Objective-C

- (nonnull instancetype)initWithIndex:(int)index
                        apiPreference:(int)apiPreference;

Swift

init(index: Int32, apiPreference: Int32)

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. See `cv::VideoCaptureAPIs`


                    
                    
                    -initWithIndex:

  Opens a camera for video capturing

Declaration

Objective-C

- (nonnull instancetype)initWithIndex:(int)index;

Swift

init(index: Int32)

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) implementation if multiple are available: e.g. cv::CAP_DSHOW or cv::CAP_MSMF or cv::CAP_V4L.

See

cv::VideoCaptureAPIs

-init
Default constructor - note: In REF: videoio_c “C API”, when you finished working with video, release CvCapture structure with cvReleaseCapture(), or use Ptr<CvCapture> that calls cvReleaseCapture() automatically in the destructor.
Declaration
Objective-C

- (nonnull instancetype)init;
Swift

init()


                    
                    
                    -getBackendName

Returns used backend API name

  - note: Stream should be opened.

Declaration

Objective-C

- (nonnull NSString *)getBackendName;

Swift

func getBackendName() -> String


                    
                    
                    -getExceptionMode

Declaration

Objective-C

- (BOOL)getExceptionMode NS_SWIFT_NAME(getExceptionMode());

Swift

func getExceptionMode() -> Bool


                    
                    
                    -grab

Grabs the next frame from video file or capturing device.

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

 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.

 REF: tutorial_kinect_openni

Declaration

Objective-C

- (BOOL)grab;

Swift

func grab() -> Bool


                    
                    
                    -isOpened

Returns true if video capturing has been initialized already.

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

Declaration

Objective-C

- (BOOL)isOpened;

Swift

func isOpened() -> Bool


                    
                    
                    -open:apiPreference:

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

 Parameters are same as the constructor VideoCapture(const String& filename, int apiPreference = CAP_ANY)
 - returns: `true` if the file has been successfully opened

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

Declaration

Objective-C

- (BOOL)open:(nonnull NSString *)filename apiPreference:(int)apiPreference;

Swift

func open(filename: String, apiPreference: Int32) -> Bool


                    
                    
                    -open:

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

 Parameters are same as the constructor VideoCapture(const String& filename, int apiPreference = CAP_ANY)
 - returns: `true` if the file has been successfully opened

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

Declaration

Objective-C

- (BOOL)open:(nonnull NSString *)filename;

Swift

func open(filename: String) -> Bool


                    
                    
                    -openWithIndex:apiPreference:

Opens a camera for video capturing

 Parameters are same as the constructor VideoCapture(int index, int apiPreference = CAP_ANY)
 - returns: `true` if the camera has been successfully opened.

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

Declaration

Objective-C

- (BOOL)openWithIndex:(int)index apiPreference:(int)apiPreference;

Swift

func open(index: Int32, apiPreference: Int32) -> Bool


                    
                    
                    -openWithIndex:

Opens a camera for video capturing

 Parameters are same as the constructor VideoCapture(int index, int apiPreference = CAP_ANY)
 - returns: `true` if the camera has been successfully opened.

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

Declaration

Objective-C

- (BOOL)openWithIndex:(int)index;

Swift

func open(index: Int32) -> Bool


                    
                    
                    -read:

Grabs, decodes and returns the next video frame.

 - returns: `false` if no frames has been grabbed

 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()).

 - note: In REF: videoio_c "C API", 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
 cvCloneImage and then do whatever you want with the copy.

Declaration

Objective-C

- (BOOL)read:(nonnull Mat *)image;

Swift

func read(image: Mat) -> Bool


                    
                    
                    -retrieve:flag:

Decodes and returns the grabbed video frame.

Declaration

Objective-C

- (BOOL)retrieve:(nonnull Mat *)image flag:(int)flag;

Swift

func retrieve(image: Mat, flag: Int32) -> Bool

Parameters


                                flag

it could be a frame index or a driver specific flag

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

read()

Note

In REF: videoio_c “C API”, 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 cvCloneImage and then do whatever you want with the copy.

Return Value

false if no frames has been grabbed


                    
                    
                    -retrieve:

Decodes and returns the grabbed video frame.

 - returns: `false` if no frames has been grabbed

 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: `read()`

 - note: In REF: videoio_c "C API", 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
 cvCloneImage and then do whatever you want with the copy.

Declaration

Objective-C

- (BOOL)retrieve:(nonnull Mat *)image;

Swift

func retrieve(image: Mat) -> Bool


                    
                    
                    -set:value:

Sets a property in the VideoCapture.

Declaration

Objective-C

- (BOOL)set:(int)propId value:(double)value;

Swift

func set(propId: Int32, value: Double) -> Bool

Parameters

`propId`	Property identifier from cv::VideoCaptureProperties (eg. cv::CAP_PROP_POS_MSEC, cv::CAP_PROP_POS_FRAMES, …) or one from REF: videoio_flags_others
`value`	Value of the property. 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()

Return Value

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


                    
                    
                    -get:

Returns the specified VideoCapture property

Declaration

Objective-C

- (double)get:(int)propId;

Swift

func get(propId: Int32) -> Double

Parameters


                                propId

Property identifier from cv::VideoCaptureProperties (eg. cv::CAP_PROP_POS_MSEC, cv::CAP_PROP_POS_FRAMES, …) or one from REF: videoio_flags_others

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

Return Value

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

-setExceptionMode:
Switches exceptions mode

methods raise exceptions if not successful instead of returning an error code
Declaration
Objective-C

- (void)setExceptionMode:(BOOL)enable;
Swift

func setExceptionMode(enable: Bool)