PARP Research Group University of Murcia, Spain


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

Video source class for reading many video file formats, webcams and digital cameras. More...

#include <qvio/qvmplayercamera.h>

Inherits QVCamera.

List of all members.

Public Types

enum  OpenOption {
  Default = 0x0, RealTime = 0x1, Deinterlaced = 0x2, NoLoop = 0x4,
  RGBMEncoder = 0x8
}
 Open options for a mplayer camera. Combine them using OR (|). More...

Public Slots

bool grab ()
 Grabs a frame from camera input.
void pauseCam ()
 Pauses the camera.
void unpauseCam ()
 Unpauses the camera.
void nextFrameCam ()
 Go to the next frame.
void setSpeedCam (double d)
 Set the camera speed.
void seekCam (QVCamera::TSeekType type, double pos)
 Moves the camera file to a given position.
void closeCam ()
 Closes the camera.

Public Member Functions

 QVMPlayerCamera (QString name=QString())
 Constructs a QVMPlayerCamera, which is initially in "Closed" status.
 ~QVMPlayerCamera ()
 Destroys a QVMPlayerCamera.
bool openCam (const QString &url, OpenOptions opts=Default)
 Opens a video source for image frames reading.
bool openCam (const QString &urlstring, unsigned int r, unsigned int c, OpenOptions opts=Default)
 Opens a mplayer source given by its URL, and scales output to a requested size.
bool openCam ()
 Opens a video source for image reading. This is an overloaded version for openCam(const QString &, unsigned int, unsigned int, OpenOptions) function that will get the url and the configuration options from dynamic properties defined in the camera object.
bool grab (QVImage< uChar, 3 > &image)
 Grabs a frame in RGB format.
bool grab (QVImage< uChar, 1 > &image)
 Grabs a gray scale 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.
int getBufferSize () const
 Returns the current frame buffer size.
unsigned int getFramesUpdated () const
 Returns the total number of updated frames.
unsigned int getRows () const
 Returns the number of rows of the buffer.
unsigned int getCols () const
 Returns the number of cols 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.
double getSpeed () const
 Returns the current video speed.
unsigned int getFramesGrabbed () const
 Returns number of frames grabbed.
unsigned int getFramesRead () const
 Returns number of frames read.
bool isLiveCamera () const
 Tells if the camera is a live camera.

Static Public Member Functions

static bool getFrame (const QString uri, QVImage< uChar, 3 > &img, int frame=0)
 Grabs a RGB image, from a camera specified with an URI.
static bool getFrame (const QString uri, QVImage< uChar, 1 > &img, int frame=0)
 Grabs a gray image, from a camera specified with an URI.
static bool getFrame (const QString uri, QVImage< uChar > &imgY, QVImage< uChar > &imgU, QVImage< uChar > &imgV, int frame=0)
 Grabs a YUV image, from a camera specified with an URI.


Detailed Description

Video source class for reading many video file formats, webcams and digital cameras.

This is an implementation of the class QVCamera, based on the program MPlayer. This program can read videos from a wide variety of media formats, webcams and digital cameras, and the class QVMPlayerCamera takes advantage of that feature. Thus the QVMPlayerCamera is a good, robust and versatile video input reader class.

Internally, when used to read from a video source compatible with MPlayer, the QVMPlayerCamera object will launch a copy of the MPlayer program, and redirect its output to a named pipe, from which will read the frames from the video source.

For a detailed usage of this class in a QVision application, see section ProgrammingModel.

Video source identifier URL formats

Each video source is identified by a URL string, even for video files, webcams, remote videos, etc... this class opens a video source, and reads frames from it, until a stop condition arises or the video finishes.

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.

With previous format there can be incompleteness, ambiguous video input, and other problems. More specific URL formats follows: The format of this string depends of 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 
    Note: Optional specifiers H and W are used by mplayer to open the camera in a given source size. Note that this is not the same as opening the camera in a default size and then scaling the output image to a given size using the r and c parameters (see overloaded function). Check manual page for mplayer, for a complete list of options, at parameter '-tv' option specifications.

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 at the MPlayer documentation, about the user line input parameter -tv.

Setting the with and height for the images read from the input device using parameters width and height differs from doing so with options --Cols and --Rows of the input command line. The former can configure the device to capture images using a higher or lesser resolution, while the latter scale the image as MPlayer reads them from the input device.

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 

Definition at line 237 of file qvmplayercamera.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  Camera runs in an independent, real time thread.
Deinterlaced  Make mplayer deinterlace the image (odd lines).
NoLoop  Continue from the beginning of the video when it ends.
RGBMEncoder  Camera will produce interleave RGB images (instead of YUV).

Definition at line 250 of file qvmplayercamera.h.


Member Function Documentation

bool QVMPlayerCamera::openCam ( const QString &  url,
OpenOptions  opts = Default 
)

Opens a video source for image frames reading.

Parameters:
url URL identifying the device and opening options to open. See Video source identifier URL formats for URL formats.
opts Or'ed set of opening options (see QVMPlayerCamera::OpenOption).
Returns:
True if the camera was opened successfully, false otherwise.

Definition at line 591 of file qvmplayercamera.cpp.

Referenced by getFrame().

bool QVMPlayerCamera::openCam ( const QString &  urlstring,
unsigned int  r,
unsigned int  c,
OpenOptions  opts = Default 
)

Opens a mplayer source given by its URL, and scales output to a requested size.

(Overloaded function, provided by convenience).

Parameters:
url Camera identifying URL string. See Video source identifier URL formats for URL formats.
r Number of requested output rows.
c Number of requested output cols.
opts Camera opening options (see QVMPlayerCamera::openCam(const QString&,OpenOptions))
Returns:
True if the camera was opened successfully, false otherwise.

Definition at line 595 of file qvmplayercamera.cpp.

bool QVMPlayerCamera::openCam (  ) 

Opens a video source for image reading. This is an overloaded version for openCam(const QString &, unsigned int, unsigned int, OpenOptions) function that will get the url and the configuration options from dynamic properties defined in the camera object.

Used properties:

  • URL (QString)
    URL identifying the device and opening options to open. See Video source identifier URL formats for URL formats.
  • Rows (int)
    Number of requested output rows.
  • Cols (int)
    Number of requested output cols.
  • RealTime (bool)
    If the camera should be opened in RealTime mode
  • Deinterlaced (bool)
    If the camera should be opened in Deinterlaced mode
  • RGBMEncoder (bool)
    If the camera should be opened in RGBMEncoder mode
  • NoLoop (bool)
    If the camera should be opened in NoLoop mode

For further info about the usage of these parameters see QVMPlayerCamera::OpenOption flags.

Returns:
True if the camera was opened successfully, false otherwise.
See also:
openCam(const QString &, unsigned int, unsigned int, OpenOptions)

Definition at line 576 of file qvmplayercamera.cpp.

Referenced by openCam().

bool QVMPlayerCamera::grab ( QVImage< uChar, 3 > &  image  ) 

Grabs a frame in RGB format.

If the camera is not opened with RGBMencoderMode option, this function will set parameter QVImage to null image.

Parameters:
image QVImage that will store grabbed frame.
Returns:
TRUE if success, FALSE if fail.

Definition at line 792 of file qvmplayercamera.cpp.

Referenced by getFrame().

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

Grabs a gray scale frame.

If the camera is opened with RGBMencoderMode option, this function will set param QVImage to null image.

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

Definition at line 813 of file qvmplayercamera.cpp.

bool QVMPlayerCamera::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. YUV format would be 422, thus QVImage corresponding to plane Y will be four times bigger than those corresponding to planes U and V.

If the camera is opened with RGBMencoderMode option, this function will set param QVImage's to null images.

Parameters:
imgY QVImage that will store grabbed frame Y channel.
imgU QVImage that will store grabbed frame U channel.
imgV QVImage that will store grabbed frame V channel.
Returns:
True if success, false otherwise.

Definition at line 774 of file qvmplayercamera.cpp.

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

Returns the current camera name (without path).

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

Definition at line 333 of file qvmplayercamera.h.

OpenOptions QVMPlayerCamera::getOptions (  )  const [inline]

Returns current camera options.

Returns:
Current camera options.

Definition at line 337 of file qvmplayercamera.h.

int QVMPlayerCamera::getBufferSize (  )  const [inline]

Returns the current frame buffer size.

Returns:
Current frame buffer size.

Definition at line 341 of file qvmplayercamera.h.

unsigned int QVMPlayerCamera::getFramesUpdated (  )  const [inline]

Returns the total number of updated frames.

Returns:
Current total number of updated frames.

Definition at line 345 of file qvmplayercamera.h.

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

Returns the number of rows of the buffer.

Returns:
Number of rows.

Definition at line 349 of file qvmplayercamera.h.

Referenced by openCam().

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

Returns the number of cols of the buffer.

Returns:
Number of cols.

Definition at line 353 of file qvmplayercamera.h.

Referenced by openCam().

double QVMPlayerCamera::getFPS (  )  const [inline]

Returns the camera speed in frames per second.

Returns:
Camera speed in frames per second.

Definition at line 357 of file qvmplayercamera.h.

Referenced by openCam().

double QVMPlayerCamera::getTimeLength (  )  const [inline]

Returns the video file length in seconds.

Returns:
Video length in seconds.

Definition at line 361 of file qvmplayercamera.h.

double QVMPlayerCamera::getTimePos (  )  const [inline]

Returns the current video position in seconds.

Returns:
Current video position in seconds.

Definition at line 365 of file qvmplayercamera.h.

double QVMPlayerCamera::getSpeed (  )  const [inline]

Returns the current video speed.

Returns:
Current video speed (as a multiplier of the FPS).

Definition at line 369 of file qvmplayercamera.h.

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

Returns number of frames grabbed.

Returns:
Number of successful frames returned by grab's

Definition at line 373 of file qvmplayercamera.h.

unsigned int QVMPlayerCamera::getFramesRead (  )  const [inline]

Returns number of frames read.

Returns:
Number of frames actually read by a camera.

Definition at line 377 of file qvmplayercamera.h.

bool QVMPlayerCamera::isLiveCamera (  )  const [inline]

Tells if the camera is a live camera.

Returns:
True if camera is a live camera.

Definition at line 381 of file qvmplayercamera.h.

static bool QVMPlayerCamera::getFrame ( const QString  uri,
QVImage< uChar, 3 > &  img,
int  frame = 0 
) [inline, static]

Grabs a RGB image, from a camera specified with an URI.

This function grabs a frame from a video file or url, in RGB format, without having to create explicitly a mplayer camera object, open it, skip frames to the desired, and close the camera.

Parameters:
uri Camera URL (see QVMPlayerCamera::openCam(const QString&,OpenOptions)).
image QVImage that will store grabbed frame.
frame frame number, 0 for first frame.
Returns:
TRUE if success, FALSE if fail.

Definition at line 391 of file qvmplayercamera.h.

static bool QVMPlayerCamera::getFrame ( const QString  uri,
QVImage< uChar, 1 > &  img,
int  frame = 0 
) [inline, static]

Grabs a gray image, from a camera specified with an URI.

This function grabs a gray scale frame from a video file or url, without having to create explicitly a mplayer camera object, open it, skip frames to the desired, and close the camera.

Parameters:
uri Camera URL (see QVMPlayerCamera::openCam(const QString&,OpenOptions)).
image QVImage that will store grabbed frame.
frame frame number, 0 for first frame.
Returns:
TRUE if success, FALSE if fail.

Definition at line 411 of file qvmplayercamera.h.

static bool QVMPlayerCamera::getFrame ( const QString  uri,
QVImage< uChar > &  imgY,
QVImage< uChar > &  imgU,
QVImage< uChar > &  imgV,
int  frame = 0 
) [inline, static]

Grabs a YUV image, from a camera specified with an URI.

This function grabs a frame from a video file or url, in YUV format, without having to create explicitly a mplayer camera object, open it, skip frames to the desired, and close the camera.

Parameters:
uri Camera URL (see QVMPlayerCamera::openCam(const QString&,OpenOptions)).
imgY QVImage that will store grabbed frame Y channel.
imgU QVImage that will store grabbed frame U channel.
imgV QVImage that will store grabbed frame V channel.
frame frame number, 0 for first frame.
Returns:
TRUE if success, FALSE if fail.

Definition at line 436 of file qvmplayercamera.h.

bool QVMPlayerCamera::grab (  )  [slot]

Grabs a frame from camera input.

Grabs an image, and stores it in the corresponding properties of the camera: "RGB image", "Y channel image", "U channel image", and "V channel image".

Parameters:
image QVImage that will store grabbed frame.
Returns:
TRUE if success, FALSE if fail.

Definition at line 739 of file qvmplayercamera.cpp.

void QVMPlayerCamera::setSpeedCam ( double  d  )  [slot]

Set the camera speed.

Parameters:
d Camera speed (as a multiplier of the FPS)

Definition at line 909 of file qvmplayercamera.cpp.

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

Moves the camera file to a given position.

Parameters:
type Type of seek: Current=0,Percentage=1,Absolute=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.


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



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