PARP Research Group University of Murcia, Spain


QVMPlayerReader Class Reference
[Video and image input/storage group]

Class to read from many video formats and devices, based on the MPlayer application. More...

#include <qvio/qvmplayerreader.h>

List of all members.

Public Types

enum  OpenOption { Default = 0x0, RealTime = 0x1, Deinterlaced = 0x2, NoLoop = 0x4 }
enum  TSeekType { SeekCurrent = 0, SeekPercentage = 1, SeekAbsolute = 2 }

Public Slots

void closeCam ()
void seekCam (TSeekType type, double pos)
 Moves the camera file to a given position (if applicable; not valid for live cameras, for example).

Public Member Functions

 QVMPlayerReader ()
 ~QVMPlayerReader ()
bool openCam (const QString &urlstring, OpenOptions opts=Default, unsigned int suggested_cols=0, unsigned int suggested_rows=0)
 Opens a mplayer source given by its URL, in a requested mode and output scale size.
bool grab (QVImage< uChar, 1 > &image)
 Grabs a grayscale frame.
bool grab (QVImage< uChar, 3 > &imageRGB)
 Grabs a RGB frame.
bool grab (QVImage< uChar > &imgY, QVImage< uChar > &imgU, QVImage< uChar > &imgV)
 Grabs a frame in YUV format.
const QString getUrlBase () const
 Returns the current camera name (without path).
OpenOptions getOptions () const
 Returns current camera options.
unsigned int getCols () const
 Returns the number of cols of the buffer.
unsigned int getRows () const
 Returns the number of rows of the buffer.
double getFPS () const
 Returns the camera speed in frames per second.
double getTimeLength () const
 Returns the video file length in seconds.
double getTimePos () const
 Returns the current video position in seconds.
unsigned int getFramesGrabbed () const
 Returns number of frames grabbed.
bool isLiveCamera () const
 Tells if the camera is a live camera.


Detailed Description

Class to read from many video formats and devices, based on the MPlayer application.

This class is based on the MPlayer application. It can read videos from a wide variety of media formats, webcams and digital cameras.

Internally, when used to read from a video source compatible with MPlayer, the QVMPlayerReader object will launch the MPlayer application to open and read from a video source. MPlayer will be configured to redirect its output to a system pipeline (named fifo), from which the QVMPlayerRead class will read video frames.

You will probably never have to directly use this class. Usually, you will directly use a QVMPlayerCameraWorker instead, which internally (and transparently) uses this class. Anyway, it is important for you to know well the URL syntax for especifying a video source:

Video source identifier URL formats

Each video source is identified by a URL string, which will denote video files, webcams, remote videos, etc...

Simplified camera URL format.

Format: just the path to a file or files. Type of formats
  • For video files:
    path-to-file/file-name.{avi, mpg, dv, ...} 
  • For devices (webcams, digital cams, tv inputs):
    /dev/devicename 
  • For image lists:
    path-to-directory/filemask.{jpg, png, ...} 

Extended camera URL formats.

The previous formats are the mor common ones, but they can be insufficient in many cases. The more general URL formats are the following (depending on the type of the video source):

Notation: [] means optional, {} means alternative:

  • Local video file compatible with mplayer:
    file://[path-to-file/]file-name.{avi, mpg, dv, ...} 
    Path can be relative, or absolute. Absolute paths begin with an extra slash. Examples:
    file:///home/vision/penguin.dv 
    file://../../home/vision/penguin.dv 
  • Remote video file (via http, rtsp, ftp):
    {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/penguin.dv 
    ftp://user:passwd@server.dom/data/video.avi 

  • DVD | VCD video track (see mplayer man page for correct URL formation for a specific title, track, device, etc.).
    {dvd,vcd}://{video track}
    Examples:
    dvd://2 
    vcd://1 

  • Sequence of multiple JPEG or PNG files:
    mf://path-to/filemask.{jpg, png, ...} 
    Examples:
    mf:///home/user/images/img*.jpg 
    mf:///./images/img*.png 

  • Video 4 linux, video 4 linux 2 camera, and analog inputs:
    {v4l,v4l2,analog}://{device file}[?options] 
    Examples:
    v4l:///dev/video0 
    analog:///dev/video0 
    See section Camera parameters por options.

Camera parameters

Both extended and simplified formats can include special parameters for tuning device input options. Some of these parameters are:
  • 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.
  • channel=<value>
    specifies the tv channel to read images from. You can get a complete list of these options in the MPlayer documentation (option -tv).

Setting the width and height for the images read from the input device using parameters width and height differs from using r and c parameters of the openCam() method. The former can 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.

These options work for video 4 Linux, video 4 Linux 2 camera, and analog inputs. 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 
  • URL to open an tv device at a 320x240 resolution, on channel 42
    analog:///dev/tv?height=240&width=320&channel=42 

See also:
QVMPlayerCameraWorker

Definition at line 145 of file qvmplayerreader.h.


Member Enumeration Documentation

Open options for a mplayer camera. Combine them using OR (|).

Enumerator:
Default  Default options: don't include any of the other options.
RealTime  Mplayer will NOT ignore frame duration (i.e., will not use -benchmark, as default).
Deinterlaced  Make mplayer deinterlace the image (odd lines).
NoLoop  Continue from the beginning of the video when it reaches the end.

Definition at line 156 of file qvmplayerreader.h.

Options for a seek through the file.

Enumerator:
SeekCurrent 
SeekPercentage 
SeekAbsolute 

Definition at line 168 of file qvmplayerreader.h.


Constructor & Destructor Documentation

QVMPlayerReader::QVMPlayerReader (  )  [inline]

Constructs a QVMPlayerReader.

Definition at line 150 of file qvmplayerreader.h.

QVMPlayerReader::~QVMPlayerReader (  )  [inline]

Destroys a QVMPlayerReader.

Definition at line 153 of file qvmplayerreader.h.


Member Function Documentation

bool QVMPlayerReader::openCam ( const QString &  urlstring,
OpenOptions  opts = Default,
unsigned int  suggested_cols = 0,
unsigned int  suggested_rows = 0 
)

Opens a mplayer source given by its URL, in a requested mode and output scale size.

Note: Please observe that mplayer could slightly change the suggested size when playing the video (for example, an even number of cols is not allowed, due to YUV422 format restrictions). You can use methods getCols() and getRows() after opening to confirm the correct values.

Parameters:
urlstring Camera identifying URL string. See Video source identifier URL formats for URL formats.
opts Camera opening options (see QVMPlayerReader::openOption)
suggested_cols Number of requested output cols (0 => default width of video).
suggested_rows Number of requested output rows (0 => default height of video).
Returns:
True if the camera was opened successfully, false otherwise.

Definition at line 251 of file qvmplayerreader.cpp.

Referenced by QVMPlayerCameraWorker::openCam().

bool QVMPlayerReader::grab ( QVImage< uChar, 1 > &  image  ) 

Grabs a grayscale frame.

Parameters:
image QVImage<uChar,1> that will store grabbed frame.
Returns:
True if success, false otherwise.

Definition at line 434 of file qvmplayerreader.cpp.

Referenced by QVMPlayerCameraWorker::grab().

bool QVMPlayerReader::grab ( QVImage< uChar, 3 > &  imageRGB  ) 

Grabs a RGB frame.

Parameters:
imageRGB QVImage<uChar,3> that will store grabbed frame.
Returns:
True if success, false otherwise.

Definition at line 446 of file qvmplayerreader.cpp.

bool QVMPlayerReader::grab ( QVImage< uChar > &  imgY,
QVImage< uChar > &  imgU,
QVImage< uChar > &  imgV 
)

Grabs a frame in YUV format.

This function grabs the image in YUV format, storing each channel Y, U and V, in a separate QVImage of one channel (note that YUV format is 422, thus QVImage corresponding to plane Y will be four times larger than those corresponding to planes U and V).

Parameters:
imgY QVImage<uChar,1> that will store grabbed frame Y channel.
imgU QVImage<uChar,1> that will store grabbed frame U channel (half sized cols and rows).
imgV QVImage<uChar,1> that will store grabbed frame V channel (half sized cols and rows).
Returns:
True if success, false otherwise.

Definition at line 459 of file qvmplayerreader.cpp.

void QVMPlayerReader::closeCam (  )  [slot]

void QVMPlayerReader::seekCam ( TSeekType  type,
double  pos 
) [slot]

Moves the camera file to a given position (if applicable; not valid for live cameras, for example).

Parameters:
type Type of seek: SeekCurrent=0, SeekPercentage=1, SeekAbsolute=2.
pos 
  • If in Current mode: Relative displacement with respect to the current position in seconds.
  • If in Percentage mode: Percentage of total video length.
  • If in Absolute mode: Absolute position in seconds.

Definition at line 473 of file qvmplayerreader.cpp.

const QString QVMPlayerReader::getUrlBase (  )  const [inline]

Returns the current camera name (without path).

Returns:
Current camera name.
Deprecated:
Use getName() instead

Definition at line 230 of file qvmplayerreader.h.

OpenOptions QVMPlayerReader::getOptions (  )  const [inline]

Returns current camera options.

Returns:
Current camera options.

Definition at line 234 of file qvmplayerreader.h.

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

Returns the number of cols of the buffer.

Returns:
Number of cols.

Definition at line 238 of file qvmplayerreader.h.

Referenced by QVMPlayerCameraWorker::openCam().

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

Returns the number of rows of the buffer.

Returns:
Number of rows.

Definition at line 242 of file qvmplayerreader.h.

Referenced by QVMPlayerCameraWorker::openCam().

double QVMPlayerReader::getFPS (  )  const [inline]

Returns the camera speed in frames per second.

Returns:
Camera speed in frames per second.

Definition at line 246 of file qvmplayerreader.h.

Referenced by QVMPlayerCameraWorker::openCam().

double QVMPlayerReader::getTimeLength (  )  const [inline]

Returns the video file length in seconds.

Note: Please observe that mplayer does not tell us the length of the video in seconds until it has read a few frames (commonly two or three). Thus, this function will return 0.0 until a few calls to any grab() function have been made.

Returns:
Video length in seconds.

Definition at line 255 of file qvmplayerreader.h.

double QVMPlayerReader::getTimePos (  )  const [inline]

Returns the current video position in seconds.

Returns:
Current video position in seconds.

Definition at line 259 of file qvmplayerreader.h.

unsigned int QVMPlayerReader::getFramesGrabbed (  )  const [inline]

Returns number of frames grabbed.

Returns:
Total number of frames grabbed by the camera.

Definition at line 263 of file qvmplayerreader.h.

bool QVMPlayerReader::isLiveCamera (  )  const [inline]

Tells if the camera is a live camera.

Returns:
True if camera is a live camera (i.e., a webcam, a TV, etc., but not a file, for example).

Definition at line 267 of file qvmplayerreader.h.

Referenced by QVMPlayerCameraWorker::openCam().


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



QVision framework. PARP research group, copyright 2007, 2008.