QVVideoReader Class Reference

Extremely versatile class to read from multiple video devices and video/image file formats. More...

#include <QVVideoReader>

Public Types
enum	OpenOption { Default = 0x0, RealTime = 0x1, Deinterlaced = 0x2, NoLoop = 0x4 }
	Open options for a video source. Combine them using OR (\|) to form a valid QVVideoReader::OpenOptions value. More...
enum	TSourceMode { YUVMode = 0, RGBMode = 1, GrayOnlyMode = 2 }
	Possible preferred modes for video sources. More...
typedef QFlags< OpenOption >	OpenOptions
	Open options for a video source.
Public Slots
bool	close ()
	Closes the video source.
bool	seek (int pos)
	Tries to move to a given position in the video source (if possible).
Signals
void	sourceOpened ()
	Signal emitted when video source has been opened.
void	sourceClosed ()
	Signal emitted when video source has been closed.
void	newGrab ()
	Signal emitted when a new frame has been grabbed.
Public Member Functions
	QVVideoReader ()
	Constructs a QVVideoReader.
	~QVVideoReader ()
	Destroys a QVVideoReader.
bool	open (const QString &url_string, unsigned int &suggested_cols, unsigned int &suggested_rows, unsigned int &suggested_fps, OpenOptions &opts, TSourceMode &source_mode)
	Opens a video source given by its URL, trying to use requested options, mode, speed and output scale sizes.
bool	open (const QString &url_string)
	Opens a video source given by its URL, using default opening values.
bool	grab ()
	Grabs next frame in video source, saving corresponding image(s) in class internal state.
void	getGrayImage (QVImage< uChar > &imageGray)
	Gets current frame in the form of a gray image.
void	getRGBImage (QVImage< uChar, 3 > &imageRGB)
	Gets current frame in the form of a 3 channel RGB image.
void	getRGBImage (QVImage< uChar > &imageR, QVImage< uChar > &imageG, QVImage< uChar > &imageB)
	Gets current frame in the form of three separated Red, Green and Blue channel images.
void	getYUVImage (QVImage< uChar > &imageY, QVImage< uChar > &imageU, QVImage< uChar > &imageV)
	Gets current frame in the form of a gray image channel (Y) and two chrominance image channels (U and V).
int	getLength () const
	Gets the length of the video source.
int	getPos () const
	Gets the current position in the video source.
const QString	getURL () const
	Returns the complete URL of the video source.
const QString	getScheme () const
	Returns the scheme of the video source.
unsigned int	getCols () const
	Returns the number of cols for current frame in the video source.
unsigned int	getRows () const
	Returns the number of rows for current frame in the video source.
unsigned int	getFPS () const
	Returns the number of frames per second of the video source.

Detailed Description

Extremely versatile class to read from multiple video devices and video/image file formats.

This class implements a generic video reader interface to read images from different video sources. Currently, it uses one of the following underlying mechanisms to read from them (though programmers could also easily extend this functionality by inheriting from the QVBaseReader class; see documentation on that class for details):

Qt native read of several image formats (possibly read in sequence from a given directory).
QVision implemented read of raw (uncompressed) YUV4MPEG2 video format.
OpenCV library as a backend for reading video files and locally connected cameras (USB or firewire).
MPlayer as a backend application, to open and read frames from a wide variety of video sources, including video files encoded with very different media formats, webcams, digital cameras, internet video streams, or even DVB/TDT devices.

The class internally implements scaling and RGB/YUV/gray color conversions, so that the programmer can transparently ask for the desired image size and color format when grabbing images.

Video source identifiers

Any video source (video files, webcams, remote videos, etc...) is identified by a URL string, with the following available formats: (Notation: [] means optional, {} means alternative):

Local directory of images:
```
dir://path-to-dir-of-images/ 
```
Reads every file in the given directory with one of the supported image file formats (jpg, png, bmp, pgm, gif, pbm, ppm, tiff, xbm, xpm). Path can be relative, or absolute. Absolute paths begin with an extra slash. Example:
```
dir:///home/user/images/ 
```

Local directory of images filtered by name pattern:
```
dir://path-to-dir-of-images/glob-pattern 
```
Again, path can be relative, or absolute, and absolute paths begin with an extra slash. The glob-pattern can include the typical * and ? wildcard characters. Example:
```
dir:///home/user/images/p*-???.jpg 
```

Reading directly an uncompressed yuv4mpeg file:
```
yuv4mpeg://[path-to-dir-of-videos/]video.yuv 
```
Again, path can be relative, or absolute, and absolute paths begin with an extra slash. Example:
```
yuv4mpeg:///home/user/videos/football.yuv 
```

Reading a local video file through OpenCV (needs the OpenCV library):
```
cvf://[path-to-dir-of-videos/]video.{avi, mpg, dv, ...} 
```
Again, path can be relative, or absolute, and absolute paths begin with an extra slash. Example:
```
cvf:///home/user/videos/sequence.avi 
```

Reading a webcam/firewire camera through OpenCV (needs the OpenCV library):
```
cvc://#number_of_camera 
```
Example:
```
cvc://#0 
```

Reading a local video file compatible with mplayer (needs mplayer compatibility enabled):
```
file://[path-to-file/]file-name.{avi, mpg, dv, ...} 
```
Again, path can be relative, or absolute, and absolute paths begin with an extra slash. Examples:
```
file:///home/vision/penguin.dv 
```
```
file://../videos/football.avi 
```

Remote video file (via http, rtsp, ftp) (needs mplayer compatibility enabled):

{http,rtsp,ftp}://domain-name/path-to-file/file.{avi, mpg, dv, ...}

Examples:

rtsp://ficheros.7rm.es/7RM/7rm06-01-071430.rm

http://perception.inf.um.es/public_data/videos/misc/minuto.avi

ftp://user:passwd@server.dom/data/video.avi

DVD | VCD video track: (needs mplayer compatibility enabled):
```
{dvd,vcd}://{video track}
```
See mplayer system man page for correct URL formation for a specific title, track, device, etc. Examples:
```
dvd://2 
```
```
vcd://1 
```

Video 4 linux, video 4 linux 2 camera through mplayer (needs mplayer compatibility enabled):
```
{v4l,v4l2}://{device file} 
```
Needs mplayer compatibility enabled. Example:
```
v4l2:///dev/video0 
```

TDT channels (needs mplayer compatibility enabled):
```
dvb://CHANNEL-NAME 
```
Of course, valid only for systems with adequate DVB hardware and Mplayer DVB subsystem correctly configured (i.e., mplayer/channels.conf must have been configured before, using the corresponding channel scan utility; for example, the scan utility from the package dvd-apps, in the case of Ubuntu Linux). Example:
```
dvb://TVE1 
```

Abbreviated video source identifiers

If you do not explicitly specify any of the former URL schemes (dir://, yuv4mpeg://, ...), the following simplified formats are used by default:

If it is specified just the path to a video file, by default file:// is used, except if the file has .yuv extension, in which case yuv4mpeg:// is used by default.

If it is specified just the path to a directory, dir:// is used by default. The same is valid if the user specifies a file pattern with a relative or absolute path (i.e. /home/user/dir/imag*.jpg or ./img?.bmp, for example).

If it is specified just the path to a video device, for example, /dev/video0 (only in linux), v4l2:// is used by default.

If it is specified a number preceded by # (i.e. #0, #1), cvc:// is used by default.

If it is specified a string starting with ftp. or www., the corresponding schemes ftp:// and http:// will be used by default.

Additional source-specific parameters

In some cases, the URL string can be used to specify additional source-specific parameters. For example, specifying a frame-rate is commonly required to open v4l2 webcams through mplayer. Both extended and simplified formats can include special parameters for tuning device input options. Some additional examples of these parameters include:

width=<value>
sets the width of the image frames to be read from the video device.
height=<value>
sets the height of the image frames to be read from the video device.
fps=<value>
sets the number of frames per second to be read from the video device.
[brightness|contrast|hue|saturation]=[-100, 100]
sets the brightness, contrast, hue or saturation for the device.

You can get a complete list of these options in the MPlayer documentation (option -tv). All these options work only for video 4 Linux, video 4 Linux 2 cameras. They can be included appending a ? sign after the URL for the device, and separated with & signs. Some example usages of these URL options follow:

URL to open a V4L2 device specifying 25 frames per second, image size of 640x480, and minimum brightness:
```
v4l2:///dev/video0?height=480&width=640&brightness=-100&fps=25 
```

The same device and configuration using a simplified URL:

/dev/video0?height=480&width=640&brightness=-100&fps=25

Remarks:: Please take into account that setting the width and height for the images read from the input device using parameters width and height differs from using rows and cols parameters of the open() method. The former tries to configure the device to capture images using a higher or lesser resolution, while the latter simply (post-)scale the images as MPlayer reads them from the input device in their original sizes.

See also:: QVVideoReaderBlock QVBaseReader

Definition at line 164 of file qvvideoreader.h.

Member Typedef Documentation

typedef QFlags<OpenOption> QVVideoReader::OpenOptions

Open options for a video source.

See also:: QVVideoReader::OpenOption

Definition at line 184 of file qvvideoreader.h.

Member Enumeration Documentation

enum QVVideoReader::OpenOption

Open options for a video source. Combine them using OR (|) to form a valid QVVideoReader::OpenOptions value.

(Note that not all source types support all options).

Enumerator:

Default	Default options: don't include any of the other options.
RealTime	Do not try to ignore frame duration (i.e., do not use `-benchmark` when calling mplayer, or simulate requested fps in other sources such as dir://, yuv4mpeg://, etc.).
Deinterlaced	(Mplayer only) Make mplayer deinterlace the image (odd lines).
NoLoop	Continue from the beginning of the video source when it reaches the end.

Definition at line 171 of file qvvideoreader.h.

enum QVVideoReader::TSourceMode

Possible preferred modes for video sources.

Enumerator:

YUVMode	Source outputs YUV images by default.
RGBMode	Source outputs RGB images by default.
GrayOnlyMode	Source outputs gray only (BW) images by default.

Definition at line 188 of file qvvideoreader.h.

Constructor & Destructor Documentation

QVVideoReader::QVVideoReader ( )

Constructs a QVVideoReader.

Definition at line 76 of file qvvideoreader.cpp.

QVVideoReader::~QVVideoReader ( )

Destroys a QVVideoReader.

Definition at line 87 of file qvvideoreader.cpp.

Member Function Documentation

bool QVVideoReader::open	(	const QString &	url_string,
		unsigned int &	suggested_cols,
		unsigned int &	suggested_rows,
		unsigned int &	suggested_fps,
		QVVideoReader::OpenOptions &	suggested_opts,
		QVVideoReader::TSourceMode &	suggested_source_mode
	)

Opens a video source given by its URL, trying to use requested options, mode, speed and output scale sizes.

Note: Please observe that though this class has image scaling capabilities, and thus it always tries to fulfill the user size request, the method could still slightly change the suggested size when opening the video (for example, an odd number of cols is not allowed, due to YUV422 format restrictions). On output, the suggested_rows and suggested_cols parameters will contain the correct values. This is specially useful when suggested_cols = suggested_rows = 0, which is interpreted as asking the grabbed frames to be in its original resolution (i.e. no scaling is performed). Of course, you can also use methods getCols() and getRows() on the subsequent grabbed frames to confirm these output values.

Parameters:

	url_string	Video source identifying URL string. See above for availabe URL formats.
	suggested_cols	Number of requested output cols (0 => ask for default width of video; otherwise scale).
	suggested_rows	Number of requested output rows (0 => ask for default height of video; otherwise scale).
	suggested_fps	Number of requested output fps (0 => default value of source; otherwise simulate delay).
	opts	Camera opening options (see QVVideoReader::OpenOptions).
	source_mode	On output, mode preferred by the video source (see QVVideoReader::TSourceMode).

Returns:: True if the video source was opened successfully, false otherwise.

Definition at line 97 of file qvvideoreader.cpp.

Referenced by open().

bool QVVideoReader::open ( const QString & url_string ) [inline]

Opens a video source given by its URL, using default opening values.

This is an overloaded form of the former method, provided by convenience. It will open the requested video source using default values of for the rest of input parameters (i.e. suggested_cols = suggested_rows = suggested_fps = 0, suggested_opts = Default, source_mode = YUVMode).

Parameters:

url_string

Video source identifying URL string. See above for availabe URL formats.

Returns:: True if the video source was successfully opened, false otherwise.

Definition at line 239 of file qvvideoreader.h.

bool QVVideoReader::grab ( )

Grabs next frame in video source, saving corresponding image(s) in class internal state.

This is the only method which makes the video source to advance to the next frame. Use any of the QVVideoReader::getGrayImage(), QVVideoReader::getRGBImage(), or QVVideoReader::getYUVImage() methods after grabbing to get the corresponding grabbed image(s).

Returns:: True if the video frame was successfully captured, false otherwise.

Definition at line 315 of file qvvideoreader.cpp.

void QVVideoReader::getGrayImage ( QVImage< uChar > & imageGray )

Gets current frame in the form of a gray image.

This method does NOT captures a new image; instead, it returns the last captured one. Use the QVVideoReader::grab() to advance to the next frame.

Parameters:

imageGray

captured gray image.

Definition at line 423 of file qvvideoreader.cpp.

void QVVideoReader::getRGBImage ( QVImage< uChar, 3 > & imageRGB )

Gets current frame in the form of a 3 channel RGB image.

This method does NOT captures a new image; instead, it returns the last captured one. Use the QVVideoReader::grab() to advance to the next frame.

Parameters:

imageRGB

captured RGB image.

Definition at line 456 of file qvvideoreader.cpp.

void QVVideoReader::getRGBImage	(	QVImage< uChar > &	imageR,
		QVImage< uChar > &	imageG,
		QVImage< uChar > &	imageB
	)

Gets current frame in the form of three separated Red, Green and Blue channel images.

This method does NOT captures a new image; instead, it returns the last captured one. Use the QVVideoReader::grab() to advance to the next frame.

Parameters:

	imageR	captured Red image.
	imageG	captured Green image.
	imageB	captured Blue image.

Definition at line 486 of file qvvideoreader.cpp.

void QVVideoReader::getYUVImage	(	QVImage< uChar > &	imageY,
		QVImage< uChar > &	imageU,
		QVImage< uChar > &	imageV
	)

Gets current frame in the form of a gray image channel (Y) and two chrominance image channels (U and V).

The U and V images will be at half the resolution ( $rows/2 \times cols/2$ ) with respect to the Y image. This method does NOT captures a new image; instead, it returns the last captured one. Use the QVVideoReader::grab() to advance to the next frame.

Parameters:

	imageY	captured Y image.
	imageU	captured U image.
	imageV	captured V image.

Definition at line 537 of file qvvideoreader.cpp.

int QVVideoReader::getLength ( ) const

Gets the length of the video source.

Returns:: Gets the length of the video source (if possible), usually in number of frames (though, depending on the type of source, it could be in any othe unit, such as seconds or milliseconds, for example). It returns 0 if the value is not available.

Definition at line 619 of file qvvideoreader.cpp.

int QVVideoReader::getPos ( ) const

Gets the current position in the video source.

Returns:: Gets the current position in the video source length of the video source (if possible), usually in number of frames (though, depending on the type of source, it could be in any othe unit, such as seconds or milliseconds, for example). It returns 0 if the value is not available.

Definition at line 624 of file qvvideoreader.cpp.

bool QVVideoReader::close ( ) [slot]

Closes the video source.

Returns:: True if the video source was successfully closed, false otherwise.

Definition at line 587 of file qvvideoreader.cpp.

Referenced by ~QVVideoReader(), and QVVideoReaderBlock::~QVVideoReaderBlock().

bool QVVideoReader::seek ( int pos ) [slot]

Tries to move to a given position in the video source (if possible).

Parameters:

pos

Position to move to (usually in number of frames, but other units, such as seconds or milliseconds are also possible, depending on the specific source).

Returns:: True on success, false otherwise.

Definition at line 614 of file qvvideoreader.cpp.

void QVVideoReader::sourceOpened ( ) [signal]

Signal emitted when video source has been opened.

Referenced by open().

void QVVideoReader::sourceClosed ( ) [signal]

Signal emitted when video source has been closed.

Referenced by close().

void QVVideoReader::newGrab ( ) [signal]

Signal emitted when a new frame has been grabbed.

Referenced by grab().

const QString QVVideoReader::getURL ( ) const [inline]

Returns the complete URL of the video source.

Returns:: Complete URL of the video source.

Definition at line 336 of file qvvideoreader.h.

const QString QVVideoReader::getScheme ( ) const [inline]

Returns the scheme of the video source.

Returns:: Scheme (file, dir, yuv4mpeg, cvc, cvf, ...; see above) of the video source.

Definition at line 341 of file qvvideoreader.h.

unsigned int QVVideoReader::getCols ( ) const [inline]

Returns the number of cols for current frame in the video source.

Returns:: Number of cols for current frame in video source.

Definition at line 346 of file qvvideoreader.h.

unsigned int QVVideoReader::getRows ( ) const [inline]

Returns the number of rows for current frame in the video source.

Returns:: Number of rows for current frame in video source.

Definition at line 351 of file qvvideoreader.h.

unsigned int QVVideoReader::getFPS ( ) const [inline]

Returns the number of frames per second of the video source.

Returns:: Number of fps in video source.

Definition at line 356 of file qvvideoreader.h.

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

src/qvio/qvvideoreader.h
src/qvio/qvvideoreader.cpp

QVVideoReader Class Reference

Public Types

Public Slots

Signals

Public Member Functions

Detailed Description

Video source identifiers

Abbreviated video source identifiers

Additional source-specific parameters

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation