cavapa_gui::OpenCVCapture Class Reference

The OpenCV capturing class. More...

#include <opencvcapture.h>

Inheritance diagram for cavapa_gui::OpenCVCapture:

Public Member Functions
	DISALLOW_COPY_AND_ASSIGN (OpenCVCapture)
	Copy and assign of the class is not allowed.
double	getBarrelCorrection () override
	Retrieves the barrel correction applied to the source. More...
FrameCapture	getBuffered () override
	Retrieves the currently buffered frame. More...
std::string	getDescription () const override
	Retrieves the description of the device. More...
int	getDeviceID () const override
	Returns the ID number the device was initialized with. More...
double	getFramerate () const override
	Retrieves the capture device framerate. More...
int	getMissedFrames () const override
	Retrieves the logged frame misses. More...
FrameCapture	getNext (bool skip, bool *error) override
	Retrieves the next frame. More...
std::string	getPath () const override
	Retrieves the path given during the initialization. More...
double	getProperty (int propId)
	Gets the OpenCV specific source properties. More...
cv::Size	getResolution () const override
	Retrieves the capture device resolution. More...
int	getRetrievedFrames () const override
	Retrieves the total logged frames. More...
INTERFACE_TYPE	getType () const overridefinal
	Retrieves the type of the device. More...
bool	hasNew () override
	Checks whether the device has a new image to be retrieved or not. More...
bool	isOpen () const override
	Checks whether the source has been initialized or not. More...
bool	open (int index)
	Opens OpenCV VideoCapture for the hardware device. More...
bool	open (const std::string &path) override
	Opens the video file or the stream. More...
void	release ()
	Forces the release of the worker thread. More...
void	resetStats () override
	Resets the statistical counters. More...
void	setBarrelCorrection (double amount) override
	Sets the amount of the barrel correction to be applied. More...
bool	setProperty (int propId, double value)
	Sets OpenCV specific source properties. More...
bool	setResolution (const cv::Size &new_size) override
	Sets the capturing device resolution. More...
Public Member Functions inherited from cavapa_gui::CaptureInterface
	DISALLOW_COPY_AND_ASSIGN (CaptureInterface)
	Copy and assign of the class is not allowed.

Additional Inherited Members
Public Types inherited from cavapa_gui::CaptureInterface
enum	INTERFACE_TYPE { HTTP, OPENCV }
	Used to define the type of source interface.

Detailed Description

The OpenCV capturing class.

The class provides OpenCV-powered VideoCapture. It can be used for hardware cameras, network streams or video files. The class multithreads the actual retrievals and offers some buffering for possible frame misses and device lag time. The class does not handle HTTP image sources as current version of OpenCV (2.4.9) is unable to retrieve them multiple times.

OpenCV allows limited access to resolution and framerate changing on most device sources. Unfortunately, it seriously lacks any kind of error catching method. Special statistical values are used to catch missed frames and other problems.

As an extension of the CaptureInterface class, the class is initialized with open() that opens the connection to the actual capturing device. Once connection has been established, images can be retrieved with getNext(). Some OpenCV devices also support the change of image size and framerate.

Author

Petri Partanen

Member Function Documentation

double cavapa_gui::OpenCVCapture::getBarrelCorrection ( )

overridevirtual

Retrieves the barrel correction applied to the source.

Returns

The amount of the barrel correction.

Implements cavapa_gui::CaptureInterface.

FrameCapture cavapa_gui::OpenCVCapture::getBuffered ( )

overridevirtual

Retrieves the currently buffered frame.

Returns

The buffered frame.

Remarks

This does not signal for a new image fetch from the device.

Implements cavapa_gui::CaptureInterface.

string cavapa_gui::OpenCVCapture::getDescription ( ) const

overridevirtual

Retrieves the description of the device.

Returns

For the devices initialized with HW index, this will be the name of the HW device. For other devices this is the path given during initialization.

Implements cavapa_gui::CaptureInterface.

int cavapa_gui::OpenCVCapture::getDeviceID ( ) const

inlineoverridevirtual

Returns the ID number the device was initialized with.

Returns

The device ID used in the initialization or UNKNOWN_DEVICE if not specified.

Implements cavapa_gui::CaptureInterface.

double cavapa_gui::OpenCVCapture::getFramerate ( ) const

inlineoverridevirtual

Retrieves the capture device framerate.

Returns

The current framerate.

Implements cavapa_gui::CaptureInterface.

int cavapa_gui::OpenCVCapture::getMissedFrames ( ) const

inlineoverridevirtual

Retrieves the logged frame misses.

A frame miss occurs everytime when getNext() is called and the previous retrieval was still ongoing.

Returns

The count of the missed frames.

Implements cavapa_gui::CaptureInterface.

FrameCapture cavapa_gui::OpenCVCapture::getNext ( bool  skip, bool *  error  )

overridevirtual

Retrieves the next frame.

Basically it returns the currently buffered frame and signals the device to grab a new image for next call to the function. If the device has not returned from previous image grab the call is recorded as a missed frame.

Parameters

skip	Specifies if the frame can be skipped. When set to true, this will force the main thread to wait for a new image from the device. This can result in a huge lag if the device is not capable of retrieving images fast enough.
error	Will receive an error message if something went wrong.

Returns

The next frame with the reference to the image! You must make a clone if you wish to alter it!

Implements cavapa_gui::CaptureInterface.

std::string cavapa_gui::OpenCVCapture::getPath ( ) const

inlineoverridevirtual

Retrieves the path given during the initialization.

Returns

The path of the device or an empty string if not found.

Implements cavapa_gui::CaptureInterface.

double cavapa_gui::OpenCVCapture::getProperty

(

int

propId

)

Gets the OpenCV specific source properties.

See OpenCV VideoCapture class for more info.

Parameters

propId

VideoCapture::get property.

Returns

The specified property or 0.0 if the source is not open.

Remarks

Accessing any of the source properties can produce lag if the source is running as we have to do mutex locking due to multithreading.

cv::Size cavapa_gui::OpenCVCapture::getResolution ( ) const

inlineoverridevirtual

Retrieves the capture device resolution.

Returns

The resolution of the device.

Implements cavapa_gui::CaptureInterface.

int cavapa_gui::OpenCVCapture::getRetrievedFrames ( ) const

inlineoverridevirtual

Retrieves the total logged frames.

Basically, this is a counter on how many times getNext() has been called.

Returns

The count of the total frames returned.

Implements cavapa_gui::CaptureInterface.

INTERFACE_TYPE cavapa_gui::OpenCVCapture::getType ( ) const

inlinefinaloverridevirtual

Retrieves the type of the device.

Returns

The interface type.

Implements cavapa_gui::CaptureInterface.

bool cavapa_gui::OpenCVCapture::hasNew ( )

overridevirtual

Checks whether the device has a new image to be retrieved or not.

This checks if the FrameTime on the buffered image differs from what was retrieved on the last get().

Returns

True if a new image available or false otherwise.

Remarks

This is protected by a mutex and should not be used when time is critical. Use it only when you know that any lag produced by this is not going to be a problem.

Implements cavapa_gui::CaptureInterface.

bool cavapa_gui::OpenCVCapture::isOpen ( ) const

inlineoverridevirtual

Checks whether the source has been initialized or not.

Returns

True if it is initialized or false otherwise.

Remarks

Because OpenCV fails to provide functionality to check for unplugged devices and other lost connections, this might not give any real indication on device's actual state. It can be however used to see if the initialization was successful.

Implements cavapa_gui::CaptureInterface.

bool cavapa_gui::OpenCVCapture::open

(

int

index

)

Opens OpenCV VideoCapture for the hardware device.

Parameters

index

The device index number.

Returns

True if the device was opened successfully or false otherwise.

bool cavapa_gui::OpenCVCapture::open ( const std::string &  path )

overridevirtual

Opens the video file or the stream.

Parameters

path	The path of the video file or the network stream.

Returns

True if it was opened successfully or false otherwise.

Implements cavapa_gui::CaptureInterface.

void cavapa_gui::OpenCVCapture::release

(

)

Forces the release of the worker thread.

This is used when multiple video files are combined as a one source of video. When the particular video file is currently not being accessed, the worker thread can be released to free up system's resources. The worker thread is again automatically started when the getNext() function is called.

Remarks

Releasing the thread can produce lag as the main thread has to wait for it to finish.

void cavapa_gui::OpenCVCapture::resetStats ( )

inlineoverridevirtual

Resets the statistical counters.

This affects the missed and total frame counters.

Implements cavapa_gui::CaptureInterface.

void cavapa_gui::OpenCVCapture::setBarrelCorrection ( double  amount )

overridevirtual

Sets the amount of the barrel correction to be applied.

Parameters

amount

The barrel effect. 0.0 means none.

Implements cavapa_gui::CaptureInterface.

bool cavapa_gui::OpenCVCapture::setProperty	(	int	propId,
		double	value
	)

Sets OpenCV specific source properties.

See OpenCV VideoCapture for more info.

Parameters

propId	VideoCapture::set property. You should NOT change resolution or framerate directly by using this.
value	The new value of the property.

Returns

Unknown, undocumented in VideoCapture::set. It will be false at least if the source is not open.

Remarks

Accessing the properties while the source is running can produce lag as we have to wait for the source to finish retrieving images first.

bool cavapa_gui::OpenCVCapture::setResolution ( const cv::Size &  new_size )

overridevirtual

Sets the capturing device resolution.

Parameters

new_size

The size to be set.

Returns

True if at least one of the dimension was set or false otherwise.

Implements cavapa_gui::CaptureInterface.

---

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

• source/opencvcapture.h
• source/opencvcapture.cpp