ds::help::SourceHandler Class Reference

Helper class to handle different types of video input sources, like webcams, IP cameras or video files. More...

Public Types
enum	Status : unsigned char {   Status::OK, Status::NOT_INITIALIZED, Status::NOT_READY, Status::FAILURE,   Status::STREAM_RECONNECTING, Status::VIDEO_ENDED }
	The status of the last frame retrieved from ds::help::SourceHandler::getNextFrame() More...

Public Member Functions
	SourceHandler (int webcamIndex=0, const cv::Size &resolution={ 0, 0 })
	ds::help::SourceHandler constructor to handle a USB camera. More...
	SourceHandler (const std::string &videoFilePath, bool loopVideo, bool processAllFrames)
	ds::help::SourceHandler constructor to handle a video file. More...
	SourceHandler (const std::string &videoStreamUrl)
	ds::help::SourceHandler constructor to handle an IP camera stream. More...
void	useUsbCamera (int webcamIndex=0, const cv::Size &resolution={ 0, 0 })
	Release the previous source and handle a USB camera. More...
void	useVideoFile (const std::string &videoFilePath, bool loopVideo, bool processAllFrames)
	Release the previous source and handle a video file. More...
void	useVideoStream (const std::string &videoStreamUrl)
	Release the previous source and handle an IP camera stream. More...
void	start ()
	Starts the internal playback of the video source. More...
void	stop ()
	Stops the internal playback of the video source.
void	pause ()
	Pauses the internal playback of the video source.
void	unpause ()
	Unpauses the internal playback of the video source.
bool	isUsbCamera () const
	Returns true if a USB camera is being handled.
bool	isVideoFile () const
	Returns true if a video file is being handled.
bool	isVideoStream () const
	Returns true if a video stream is being handled.
cv::Size	getSourceResolution () const
	Returns the resolution of the video source.
int	getSourceFps () const
	Returns the frame rate of the video source.
std::tuple< cv::Mat, unsigned int, Status >	getNextFrame ()
	Returns the last frame retrieved from the video source. More...

Detailed Description

Helper class to handle different types of video input sources, like webcams, IP cameras or video files.

OpenCV offers the cv::VideoCapture interface to handle video input. However the cv::VideoCapture interface does not offer a way to handle circumstances related to the specific source type: eg. retrieving frames from a video file at the same speed the video is encoded, or reconnecting to an IP camera if the connection dropped.

The ds::help::SourceHandler features:

• skipping video frames in order to respect the fps the video file was encoded with. This allows for a processing duration equal to the video duration, by discarding video frames that are not processed in time.
• looping a video file from the beginning.
• real-time frame retrieval from IP cameras or RTSP streams in general. Also in this case, the ds::help::SourceHandler class discards frames that are not processed in time.
• reconnecting to a video stream after the connection is lost
• pausing/unpausing playback

Sample Usage:

ds::help::SourceHandler         sourceHandler( 0, cv::Size( 640, 480 ) );
cv::Mat                         frame;
int                             frameNumber;
ds::help::SourceHandler::Status status;
 
// Start SourceHandler engine
sourceHandler.start();
 
while( true )
{
  // Get next frame and status
  std::tie( frame, frameNumber, status ) = sourceHandler.getNextFrame();
 
  // Check the frame status
  if( status == ds::help::SourceHandler::Status::FAILURE )
    break;
  else if( ( status == ds::help::SourceHandler::Status::NOT_INITIALIZED ) ||
           ( status == ds::help::SourceHandler::Status::NOT_READY ) )
    continue;
 
  // Process frame
}
 
// Stop SourceHandler engine
sourceHandler.stop();

Member Enumeration Documentation

Status

enum ds::help::SourceHandler::Status : unsigned char

strong

The status of the last frame retrieved from ds::help::SourceHandler::getNextFrame()

Enumerator
OK	The frame has successfully been retrieved by the ds::help::SourceHandler::getNextFrame() call.
NOT_INITIALIZED	The source has not started yet, or ds::help::SourceHandler::start() was not called. The frame is empty.
NOT_READY	The frame was not retrieved from the source yet. The frame is empty.
FAILURE	There was an error retrieving the frame the source, eg. the usb camera was disconnected. The frame is empty.
STREAM_RECONNECTING	The connection to the video stream was lost. The source handler is trying to reconnect. The frame is empty.
VIDEO_ENDED	Video file has ended. The frame is empty.

Constructor & Destructor Documentation

SourceHandler() [1/3]

ds::help::SourceHandler::SourceHandler	(	int	webcamIndex = 0,
		const cv::Size &	resolution = { 0, 0 }
	)

ds::help::SourceHandler constructor to handle a USB camera.

Parameters

webcamIndex	Usb camera index assigned by the OS. 0 is usually the first USB camera found by the system.
resolution	The resolution that the camera device should be open with. The resolution must be supported by the device.

Example usage:

// Open the default camera with the default resolution
ds::help::SourceHandler sourceHandler();
// Open the second camera available in the system with 640x480 resolution
ds::help::SourceHandler sourceHandler( 1, cv::Size( 640, 480 ) );

SourceHandler() [2/3]

ds::help::SourceHandler::SourceHandler	(	const std::string &	videoFilePath,
		bool	loopVideo,
		bool	processAllFrames
	)

ds::help::SourceHandler constructor to handle a video file.

Parameters

videoFilePath	Path to the file to open.
loopVideo	If set to true, when the video reaches the end, the playback is started from the beginning.
processAllFrames	If set to true, all the video frames are returned by the ds::help::SourceHandler::getNextFrame() function. Otherwise, frames not retrieved on time will be discarded.

Video files are encoded at a specific frame rate. This is important to play a video at the same speed it was recorder. Since frames are generally retrieved sequentially from a video file, if the speed for processing frames is different than the one the video was encoded with, the playback and analysis of the video will be faster or slower that the video its self. Eg. if a 1 minute video is encoded at 30 fps, and the processing speed of the underlying hardware is 10 fps, the analysis of the video will take 3 minutes. The processing speed has an impact of the tracking accuracy. To assess the tracking accuracy of some hardware, it is advised to set the processAllFrames parameter to false. This way the ds::help::SourceHandler will discard frames that are not retrieved on time to have real-time processing. Eg. when setting processAllFrames to false, if a 1 minute video is encoded at 30 fps, and the processing speed of the underlying hardware is 10 fps, the analysis of the video will still take 1 minute.

Example usage:

// Process all frames of the video only once
ds::help::SourceHandler sourceHandler( "/path/to/video.mp4", false, true );
// Process video in realtime and loop it indefinitely
ds::help::SourceHandler sourceHandler( "/path/to/video.mp4", true, false );

SourceHandler() [3/3]

ds::help::SourceHandler::SourceHandler

(

const std::string &

videoStreamUrl

)

ds::help::SourceHandler constructor to handle an IP camera stream.

Parameters

videoStreamUrl

Url of the video stream. Supported protocols are RTSP, RTP and HTTP(S).

When handling a video stream with the cv::VideoCapture interface, the frames coming from that stream are accumulated in an internal buffer. If the processing speed is slower than the speed of frames being retrieved from the stream, the playback is not real-time and there's a risk that the buffer overflows. The ds::help::SourceHandler class internally discards frames that are not retrieved in time, such that real-time is guaranteed and the video stream buffer does not overflow.

Example usage:

// Process an RTSP stream
ds::help::SourceHandler sourceHandler( "rtsp://username@passwrod:url.com/path/to/video.mp4" );

Member Function Documentation

getNextFrame()

std::tuple< cv::Mat, unsigned int, ds::help::SourceHandler::Status > ds::help::SourceHandler::getNextFrame

(

)

Returns the last frame retrieved from the video source.

Returns

A tuple containing the frame, the frame number, and the frame status.

Example usage:

ds::help::SourceHandler         sourceHandler( 0, cv::Size( 640, 480 ) );
cv::Mat                         frame;
int                             frameNumber;
ds::help::SourceHandler::Status status;
 
// Start SourceHandler engine
sourceHandler.start();
 
// Get next frame and status
std::tie( frame, frameNumber, status ) = sourceHandler.getNextFrame();
 
// Check the frame status
if( status == ds::help::SourceHandler::Status::OK )
  processFrame( frame );

start()

void ds::help::SourceHandler::start

(

)

Starts the internal playback of the video source.

Starts the internal playback of the video source. Required to start grabbring frames with ds::help::SourceHandler::getNextFrame(). If it's not possible to open the video source an exception is thrown.

useUsbCamera()

void ds::help::SourceHandler::useUsbCamera	(	int	webcamIndex = 0,
		const cv::Size &	resolution = { 0, 0 }
	)

Release the previous source and handle a USB camera.

Parameters

webcamIndex	Usb camera index assigned by the OS. 0 is usually the first USB camera found by the system.
resolution	The resolution that the camera device should be open with. The resolution must be supported by the device.

useVideoFile()

void ds::help::SourceHandler::useVideoFile	(	const std::string &	videoFilePath,
		bool	loopVideo,
		bool	processAllFrames
	)

Release the previous source and handle a video file.

Parameters

videoFilePath	Path to the file to open.
loopVideo	If set to true, when the video reaches the end, the playback is started from the beginning.
processAllFrames	If set to true, all the video frames are returned by the ds::help::SourceHandler::getNextFrame() function. Otherwise, frames not retrieved on time will be discarded.

Refer to ds::help::SourceHandler::SourceHandler( const std::string & videoFilePath, bool loopVideo, bool processAllFrames ) for more details.

useVideoStream()

void ds::help::SourceHandler::useVideoStream

(

const std::string &

videoStreamUrl

)

Release the previous source and handle an IP camera stream.

Parameters

videoStreamUrl

Url of the video stream. Supported protocols are RTSP, RTP and HTTP(S).

Refer to ds::help::SourceHandler::SourceHandler( const std::string & videoStreamUrl ) for more details.