Table of Contents

Class VideoCapture

Namespace
Emgu.CV
Assembly
Emgu.CV.dll

Capture images from either camera or video file.

public class VideoCapture : UnmanagedObject, IDisposable
Inheritance
VideoCapture
Implements
Inherited Members

Remarks

VideoCapture class is NOT implemented in Open CV for Android, iOS or UWP platforms

Constructors

VideoCapture(int, API, params Tuple<CapProp, int>[])

Create a capture using the specific camera

public VideoCapture(int camIndex = 0, VideoCapture.API captureApi = API.Any, params Tuple<CapProp, int>[] captureProperties)

Parameters

camIndex int

The index of the camera to create capture from, starting from 0

captureApi VideoCapture.API

The preferred Capture API backends to use. Can be used to enforce a specific reader implementation if multiple are available.

captureProperties Tuple<CapProp, int>[]

Optional capture properties. e.g. new Tuple<CvEnum.CapProp>(CvEnum.CapProp.HwAcceleration, (int) VideoAccelerationType.Any)

VideoCapture(string, API, params Tuple<CapProp, int>[])

Create a capture from file or a video stream

public VideoCapture(string fileName, VideoCapture.API captureApi = API.Any, params Tuple<CapProp, int>[] captureProperties)

Parameters

fileName string

The name of a file, or an url pointed to a stream.

captureApi VideoCapture.API

The preferred Capture API backends to use. Can be used to enforce a specific reader implementation if multiple are available.

captureProperties Tuple<CapProp, int>[]

Optional capture properties. e.g. new Tuple<CvEnum.CapProp>(CvEnum.CapProp.HwAcceleration, (int) VideoAccelerationType.Any)

Properties

BackendName

The name of the backend used by this VideoCapture

public string BackendName { get; }

Property Value

string

CaptureSource

Get the type of the capture module

public VideoCapture.CaptureModuleType CaptureSource { get; }

Property Value

VideoCapture.CaptureModuleType

ExceptionMode

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

public bool ExceptionMode { get; set; }

Property Value

bool

FlipHorizontal

Get or Set if the captured image should be flipped horizontally

public bool FlipHorizontal { get; set; }

Property Value

bool

FlipType

Get and set the flip type. If null, no flipping will be done.

public FlipType? FlipType { get; set; }

Property Value

FlipType?

FlipVertical

Get or Set if the captured image should be flipped vertically

public bool FlipVertical { get; set; }

Property Value

bool

Height

The height of this capture

public int Height { get; }

Property Value

int

IsOpened

True if the camera is opened

public bool IsOpened { get; }

Property Value

bool

Width

The width of this capture

public int Width { get; }

Property Value

int

Methods

DisposeObject()

Release the resource for this capture

protected override void DisposeObject()

Get(CapProp)

Obtain the capture property

public double Get(CapProp index)

Parameters

index CapProp

The index for the property

Returns

double

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.

Remarks

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

Grab()

Grab a frame

public virtual bool Grab()

Returns

bool

True on success

Pause()

Pause the grab process if it is running.

public void Pause()

QueryFrame()

Capture a Bgr image frame

public virtual Mat QueryFrame()

Returns

Mat

A Bgr image frame. If no more frames are available, null will be returned.

QuerySmallFrame()

Capture a Bgr image frame that is half width and half height. Mainly used by WCF when sending image to remote locations in a bandwidth conservative scenario

public virtual Mat QuerySmallFrame()

Returns

Mat

A Bgr image frame that is half width and half height

Remarks

Internally, this is a cvQueryFrame operation follow by a cvPyrDown

Read(IOutputArray)

First call Grab() function follows by Retrieve()

public bool Read(IOutputArray m)

Parameters

m IOutputArray

The output array where the image will be read into.

Returns

bool

False if no frames has been grabbed

Read(Mat)

Same to cv::VideoCapture >gt; cv::Mat function

public bool Read(Mat mat)

Parameters

mat Mat

The Mat to be written to. If no more frame is available, the resulting Mat will be empty.

Returns

bool

False if no frames has been grabbed

Read(UMat)

Same to cv::VideoCapture >gt; cv::UMat function

public bool Read(UMat umat)

Parameters

umat UMat

The UMat to be written to. If no more frame is available, the resulting UMat will be empty.

Returns

bool

False if no frames has been grabbed

Release()

The method is automatically called by subsequent VideoCapture.Open and by VideoCapture destructor.

public void Release()

Retrieve(IOutputArray, int)

Decodes and returns the grabbed video frame.

public virtual bool Retrieve(IOutputArray image, int flag = 0)

Parameters

image IOutputArray

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

flag int

It could be a frame index or a driver specific flag

Returns

bool

False if no frames has been grabbed

Set(CapProp, double)

Sets the specified property of video capture

public bool Set(CapProp property, double value)

Parameters

property CapProp

Property identifier

value double

Value of the property

Returns

bool

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

Remarks

Even if it returns true this doesn't ensure that the property value has been accepted by the capture device.

Start(ExceptionHandler)

Start the grab process in a separate thread. Once started, use the ImageGrabbed event handler and RetrieveGrayFrame/RetrieveBgrFrame to obtain the images.

public void Start(ExceptionHandler eh = null)

Parameters

eh ExceptionHandler

An exception handler. If provided, it will be used to handle exception in the capture thread.

Stop()

Stop the grabbing thread

public void Stop()

WaitAny(VectorOfVideoCapture, VectorOfInt, int)

Wait for ready frames from VideoCapture.

public static bool WaitAny(VectorOfVideoCapture streams, VectorOfInt readyIndex, int timeoutNs = 0)

Parameters

streams VectorOfVideoCapture

input video streams

readyIndex VectorOfInt

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

timeoutNs int

number of nanoseconds (0 - infinite)

Returns

bool

true if streamReady is not empty

Remarks

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.

Events

ImageGrabbed

The event to be called when an image is grabbed

public event EventHandler ImageGrabbed

Event Type

EventHandler