Visual Servoing Platform  version 3.3.0
vpVideoReader Class Reference

#include <vpVideoReader.h>

+ Inheritance diagram for vpVideoReader:

Public Member Functions

 vpVideoReader ()
 
virtual ~vpVideoReader ()
 
void acquire (vpImage< vpRGBa > &I)
 
void acquire (vpImage< unsigned char > &I)
 
void close ()
 
bool end ()
 
bool getFrame (vpImage< vpRGBa > &I, long frame)
 
bool getFrame (vpImage< unsigned char > &I, long frame)
 
double getFramerate ()
 
long getFrameIndex () const
 
long getFirstFrameIndex ()
 
long getLastFrameIndex ()
 
long getFrameStep () const
 
void open (vpImage< vpRGBa > &I)
 
void open (vpImage< unsigned char > &I)
 
vpVideoReaderoperator>> (vpImage< unsigned char > &I)
 
vpVideoReaderoperator>> (vpImage< vpRGBa > &I)
 
void resetFrameCounter ()
 
void setFileName (const std::string &filename)
 
void setFirstFrameIndex (const long first_frame)
 
void setLastFrameIndex (const long last_frame)
 
void setFrameStep (const long frame_step)
 
Inherited functionalities from vpFramegrabber
unsigned int getHeight () const
 
unsigned int getWidth () const
 

Public Attributes

bool init
 

Protected Attributes

unsigned int height
 
unsigned int width
 

Detailed Description

Class that enables to manipulate easily a video file or a sequence of images. As it inherits from the vpFrameGrabber Class, it can be used like an other frame grabber class.

This class has its own implementation to read a sequence of PGM and PPM images.

This class may benefit from optional 3rd parties:

  • libpng: If installed this optional 3rd party is used to read a sequence of PNG images. Installation instructions are provided here https://visp.inria.fr/3rd_png.
  • libjpeg: If installed this optional 3rd party is used to read a sequence of JPEG images. Installation instructions are provided here https://visp.inria.fr/3rd_jpeg.
  • OpenCV: If installed this optional 3rd party is used to read a sequence of images where images could be in TIFF, BMP, DIB, PBM, RASTER, JPEG2000 format. If libpng or libjpeg is not installed, OpenCV is also used to consider these image formats. OpenCV allows also to consider AVI, MPEG, MPEG4, MOV, OGV, WMV, FLV, MKV video formats. Installation instructions are provided here https://visp.inria.fr/3rd_opencv.

The following example available in tutorial-video-reader.cpp shows how this class is really easy to use. It enables to read a video file named video.mpeg.

#include <visp3/gui/vpDisplayGDI.h>
#include <visp3/gui/vpDisplayOpenCV.h>
#include <visp3/gui/vpDisplayX.h>
#include <visp3/core/vpTime.h>
#include <visp3/io/vpVideoReader.h>
int main(int argc, char **argv)
{
#if (VISP_HAVE_OPENCV_VERSION >= 0x020100)
try {
std::string videoname = "video.mpg";
for (int i = 0; i < argc; i++) {
if (std::string(argv[i]) == "--name")
videoname = std::string(argv[i + 1]);
else if (std::string(argv[i]) == "--help" || std::string(argv[i]) == "-h") {
std::cout << "\nUsage: " << argv[0] << " [--name <video name> (default: " << videoname << ")] [--help] [-h]\n" << std::endl;
return 0;
}
}
g.setFileName(videoname);
g.open(I);
std::cout << "Video name : " << videoname << std::endl;
std::cout << "Video framerate: " << g.getFramerate() << "Hz" << std::endl;
std::cout << "Video dimension: " << I.getWidth() << " " << I.getHeight() << std::endl;
#ifdef VISP_HAVE_X11
vpDisplayX d(I);
#elif defined(VISP_HAVE_GDI)
#elif defined(VISP_HAVE_OPENCV)
#else
std::cout << "No image viewer is available..." << std::endl;
#endif
vpDisplay::setTitle(I, "Video reader");
unsigned cpt = 1;
while (!g.end()) {
double t = vpTime::measureTimeMs();
g.acquire(I);
vpDisplay::displayText(I, 20, 20, "Click to quit", vpColor::red);
std::stringstream ss;
ss << "Frame: " << cpt ++;
vpDisplay::displayText(I, 40, 20, ss.str(), vpColor::red);
if (vpDisplay::getClick(I, false))
break;
vpTime::wait(t, 1000. / g.getFramerate());
}
std::cout << "End of video was reached" << std::endl;
} catch (const vpException &e) {
std::cout << e.getMessage() << std::endl;
}
#else
(void)argc;
(void)argv;
std::cout << "Install OpenCV and rebuild ViSP to use this example." << std::endl;
#endif
}

As shown in the next example, this class allows also to access to a specific frame. But be careful, for video files, the getFrame() method is not precise and returns the nearest intra key frame from the expected frame. You can use the getFrame() method to position the reader in the video and then use the acquire() method to get the following frames one by one.

#include <visp3/io/vpVideoReader.h>
int main()
{
#ifdef VISP_HAVE_OPENCV
vpVideoReader reader;
// Initialize the reader.
reader.setFileName("video.mpeg");
reader.open(I);
// Read the nearest key frame from the 3th frame
reader.getFrame(I, 2);
// After positionning the video reader use acquire to read the video frame by frame
reader.acquire(I);
return 0;
#endif
}

The other following example explains how to use the class to read a sequence of images. The images are stored in the folder "./image" and are named "image0000.jpeg", "image0001.jpeg", "image0002.jpeg", ... As explained in setFirstFrameIndex() and setLastFrameIndex() it is also possible to set the first and last image numbers to read a portion of the sequence. If these two functions are not used, first and last image numbers are set automatically to match the first and image images of the sequence.

#include <visp3/io/vpVideoReader.h>
int main()
{
vpVideoReader reader;
// Initialize the reader.
reader.setFileName("./image/image%04d.jpeg");
reader.setFirstFrameIndex(10);
reader.setLastFrameIndex(20);
reader.open(I);
while (! reader.end() )
reader.acquire(I);
return 0;
}

Note that it is also possible to access to a specific frame using getFrame().

#include <visp3/io/vpVideoReader.h>
int main()
{
vpVideoReader reader;
// Initialize the reader.
reader.setFileName("./image/image%04d.jpeg");
reader.open(I);
// Read the 3th frame
reader.getFrame(I,2);
return 0;
}
Examples
AROgre.cpp, AROgreBasic.cpp, imageSequenceReader.cpp, mbtEdgeKltMultiTracking.cpp, mbtEdgeKltTracking.cpp, mbtEdgeMultiTracking.cpp, mbtEdgeTracking.cpp, mbtGenericTracking.cpp, mbtGenericTracking2.cpp, mbtKltMultiTracking.cpp, mbtKltTracking.cpp, templateTracker.cpp, testImageNormalizedCorrelation.cpp, testImageTemplateMatching.cpp, testKeyPoint-2.cpp, testKeyPoint-3.cpp, testKeyPoint-4.cpp, testKeyPoint.cpp, trackMeNurbs.cpp, tutorial-chessboard-pose.cpp, tutorial-detection-object-mbt-deprecated.cpp, tutorial-detection-object-mbt.cpp, tutorial-detection-object-mbt2-deprecated.cpp, tutorial-detection-object-mbt2.cpp, tutorial-face-detector.cpp, tutorial-klt-tracker-with-reinit.cpp, tutorial-klt-tracker.cpp, tutorial-matching-keypoint-homography.cpp, tutorial-matching-keypoint-SIFT.cpp, tutorial-matching-keypoint.cpp, tutorial-matching-surf-deprecated.cpp, tutorial-matching-surf-homography-deprecated.cpp, tutorial-mb-edge-tracker.cpp, tutorial-mb-generic-tracker-full.cpp, tutorial-mb-generic-tracker-stereo-mono.cpp, tutorial-mb-generic-tracker-stereo.cpp, tutorial-mb-generic-tracker.cpp, tutorial-mb-hybrid-tracker.cpp, tutorial-mb-klt-tracker.cpp, tutorial-mb-tracker-full.cpp, tutorial-mb-tracker-stereo-mono.cpp, tutorial-mb-tracker-stereo.cpp, tutorial-mb-tracker.cpp, tutorial-template-tracker.cpp, tutorial-video-reader.cpp, and videoReader.cpp.

Definition at line 170 of file vpVideoReader.h.

Constructor & Destructor Documentation

◆ vpVideoReader()

vpVideoReader::vpVideoReader ( )

Basic constructor.

Definition at line 56 of file vpVideoReader.cpp.

◆ ~vpVideoReader()

vpVideoReader::~vpVideoReader ( )
virtual

Basic destructor.

Definition at line 69 of file vpVideoReader.cpp.

Member Function Documentation

◆ acquire() [1/2]

void vpVideoReader::acquire ( vpImage< unsigned char > &  I)
virtual

Grabs the kth image in the stack of frames and increments the frame counter in order to grab the next image (k+1) during the next use of the method.

This method enables to use the class as frame grabber.

Parameters
I: The image where the frame is stored.

Implements vpFrameGrabber.

Definition at line 320 of file vpVideoReader.cpp.

◆ acquire() [2/2]

void vpVideoReader::acquire ( vpImage< vpRGBa > &  I)
virtual

Grabs the current (k) image in the stack of frames and increments the frame counter in order to grab the next image (k+1) during the next use of the method. If open() was not called previously, this method opens the video reader.

This method enables to use the class as frame grabber.

Parameters
I: The image where the frame is stored.

Implements vpFrameGrabber.

Examples
AROgre.cpp, AROgreBasic.cpp, mbtEdgeKltMultiTracking.cpp, mbtEdgeKltTracking.cpp, mbtEdgeMultiTracking.cpp, mbtEdgeTracking.cpp, mbtGenericTracking.cpp, mbtGenericTracking2.cpp, mbtKltMultiTracking.cpp, mbtKltTracking.cpp, templateTracker.cpp, testImageTemplateMatching.cpp, testKeyPoint-2.cpp, testKeyPoint-3.cpp, testKeyPoint-4.cpp, testKeyPoint.cpp, tutorial-chessboard-pose.cpp, tutorial-detection-object-mbt-deprecated.cpp, tutorial-detection-object-mbt.cpp, tutorial-detection-object-mbt2-deprecated.cpp, tutorial-detection-object-mbt2.cpp, tutorial-face-detector.cpp, tutorial-klt-tracker-with-reinit.cpp, tutorial-klt-tracker.cpp, tutorial-matching-keypoint-homography.cpp, tutorial-matching-keypoint-SIFT.cpp, tutorial-matching-keypoint.cpp, tutorial-matching-surf-deprecated.cpp, tutorial-matching-surf-homography-deprecated.cpp, tutorial-mb-edge-tracker.cpp, tutorial-mb-generic-tracker-full.cpp, tutorial-mb-generic-tracker-stereo-mono.cpp, tutorial-mb-generic-tracker-stereo.cpp, tutorial-mb-generic-tracker.cpp, tutorial-mb-hybrid-tracker.cpp, tutorial-mb-klt-tracker.cpp, tutorial-mb-tracker-full.cpp, tutorial-mb-tracker-stereo-mono.cpp, tutorial-mb-tracker-stereo.cpp, tutorial-mb-tracker.cpp, tutorial-template-tracker.cpp, tutorial-video-reader.cpp, and videoReader.cpp.

Definition at line 243 of file vpVideoReader.cpp.

◆ close()

void vpVideoReader::close ( )
inlinevirtual

◆ end()

◆ getFirstFrameIndex()

long vpVideoReader::getFirstFrameIndex ( )
inline

◆ getFrame() [1/2]

bool vpVideoReader::getFrame ( vpImage< unsigned char > &  I,
long  frame_index 
)

Gets the $ frame $ th frame and stores it in the image $ I $.

Warning
For the video files this method is not precise, and returns the nearest key frame from the expected frame. But this method enables to position the reader where you want. Then, use the acquire method to grab the following images one after one.
Parameters
I: The vpImage used to stored the frame.
frame_index: The index of the frame which has to be read.
Returns
It returns true if the frame could be read. Else it returns false.

Definition at line 468 of file vpVideoReader.cpp.

◆ getFrame() [2/2]

bool vpVideoReader::getFrame ( vpImage< vpRGBa > &  I,
long  frame_index 
)

Gets the $ frame $ th frame and stores it in the image $ I $.

Warning
For the video files this method is not precise, and returns the nearest key frame from the expected frame. But this method enables to position the reader where you want. Then, use the acquire method to grab the following images one after one.
Parameters
I: The vpImage used to stored the frame.
frame_index: The index of the frame which has to be read.
Returns
It returns true if the frame could be read. Else it returns false.
Examples
imageSequenceReader.cpp, and trackMeNurbs.cpp.

Definition at line 398 of file vpVideoReader.cpp.

◆ getFrameIndex()

long vpVideoReader::getFrameIndex ( ) const
inline

Get the frame index of the current image. This index is updated at each call of the acquire method. It can be used to detect the end of a file (comparison with getLastFrameIndex()).

Returns
Returns the current frame index.
See also
end()
Examples
imageSequenceReader.cpp, mbtEdgeKltMultiTracking.cpp, mbtEdgeKltTracking.cpp, mbtEdgeMultiTracking.cpp, mbtEdgeTracking.cpp, mbtGenericTracking.cpp, mbtGenericTracking2.cpp, mbtKltMultiTracking.cpp, mbtKltTracking.cpp, templateTracker.cpp, testImageTemplateMatching.cpp, testKeyPoint-2.cpp, testKeyPoint-4.cpp, tutorial-chessboard-pose.cpp, tutorial-klt-tracker-with-reinit.cpp, tutorial-klt-tracker.cpp, and videoReader.cpp.

Definition at line 294 of file vpVideoReader.h.

◆ getFramerate()

double vpVideoReader::getFramerate ( )
inline

Return the frame rate in Hz used to encode the video stream.

If the video is a sequence of images, return -1.

Examples
tutorial-video-reader.cpp.

Definition at line 277 of file vpVideoReader.h.

◆ getFrameStep()

long vpVideoReader::getFrameStep ( ) const
inline

Gets the frame step.

Returns
Returns the frame step value.

Definition at line 325 of file vpVideoReader.h.

◆ getHeight()

unsigned int vpFrameGrabber::getHeight ( ) const
inlineinherited

Return the number of rows in the image.

Examples
AROgre.cpp, AROgreBasic.cpp, and testPylonGrabber.cpp.

Definition at line 113 of file vpFrameGrabber.h.

◆ getLastFrameIndex()

long vpVideoReader::getLastFrameIndex ( )
inline

◆ getWidth()

unsigned int vpFrameGrabber::getWidth ( ) const
inlineinherited

Return the number of columns in the image.

Examples
AROgre.cpp, AROgreBasic.cpp, and testPylonGrabber.cpp.

Definition at line 115 of file vpFrameGrabber.h.

◆ open() [1/2]

void vpVideoReader::open ( vpImage< unsigned char > &  I)
virtual

Sets all the parameters needed to read the video or the image sequence.

Grab the first frame and stores it in the image $ I $.

Parameters
I: The image where the frame is stored.

Implements vpFrameGrabber.

Definition at line 207 of file vpVideoReader.cpp.

◆ open() [2/2]

◆ operator>>() [1/2]

vpVideoReader & vpVideoReader::operator>> ( vpImage< unsigned char > &  I)

Operator that allows to capture a grey level image.

Parameters
I: The captured image.
#include <visp3/io/vpVideoReader.h>
int main()
{
vpVideoReader reader;
// Initialize the reader.
reader.setFileName("./image/image%04d.jpeg");
reader.setFirstFrameIndex(10);
reader.setLastFrameIndex(20);
reader.open(I);
while (! reader.end() )
reader >> I;
}

Definition at line 775 of file vpVideoReader.cpp.

◆ operator>>() [2/2]

vpVideoReader & vpVideoReader::operator>> ( vpImage< vpRGBa > &  I)

Operator that allows to capture a grey level image.

Parameters
I: The captured image.
#include <visp3/io/vpVideoReader.h>
int main()
{
vpVideoReader reader;
// Initialize the reader.
reader.setFileName("./image/image%04d.jpeg");
reader.setFirstFrameIndex(10);
reader.setLastFrameIndex(20);
reader.open(I);
while (! reader.end() )
reader >> I;
}

Definition at line 805 of file vpVideoReader.cpp.

◆ resetFrameCounter()

void vpVideoReader::resetFrameCounter ( )
inline

Reset the frame counter and sets it to the first image index.

By default the first frame index is set to 0.

This method is useful if you use the class like a frame grabber (ie with theacquire method).

Definition at line 340 of file vpVideoReader.h.

◆ setFileName()

void vpVideoReader::setFileName ( const std::string &  filename)

It enables to set the path and the name of the file(s) which as/have to be read.

If you want to read a video file, $ filename $ corresponds to the path to the file (example : /local/video.mpeg).

If you want to read a sequence of images, $ filename $ corresponds to the path followed by the image name template. For example, if you want to read different images named image0001.jpeg, image0002.jpg, ... and located in the folder /local/image, $ filename $ will be "/local/image/image%04d.jpg".

Parameters
filename: Path to a video file or file name template of a image sequence.
Examples
AROgre.cpp, AROgreBasic.cpp, imageSequenceReader.cpp, mbtEdgeKltMultiTracking.cpp, mbtEdgeKltTracking.cpp, mbtEdgeMultiTracking.cpp, mbtEdgeTracking.cpp, mbtGenericTracking.cpp, mbtGenericTracking2.cpp, mbtKltMultiTracking.cpp, mbtKltTracking.cpp, templateTracker.cpp, testImageNormalizedCorrelation.cpp, testImageTemplateMatching.cpp, testKeyPoint-2.cpp, testKeyPoint-3.cpp, testKeyPoint-4.cpp, testKeyPoint.cpp, trackMeNurbs.cpp, tutorial-chessboard-pose.cpp, tutorial-detection-object-mbt-deprecated.cpp, tutorial-detection-object-mbt.cpp, tutorial-detection-object-mbt2-deprecated.cpp, tutorial-detection-object-mbt2.cpp, tutorial-face-detector.cpp, tutorial-klt-tracker-with-reinit.cpp, tutorial-klt-tracker.cpp, tutorial-matching-keypoint-homography.cpp, tutorial-matching-keypoint-SIFT.cpp, tutorial-matching-keypoint.cpp, tutorial-matching-surf-deprecated.cpp, tutorial-matching-surf-homography-deprecated.cpp, tutorial-mb-edge-tracker.cpp, tutorial-mb-generic-tracker-full.cpp, tutorial-mb-generic-tracker-stereo-mono.cpp, tutorial-mb-generic-tracker-stereo.cpp, tutorial-mb-generic-tracker.cpp, tutorial-mb-hybrid-tracker.cpp, tutorial-mb-klt-tracker.cpp, tutorial-mb-tracker-full.cpp, tutorial-mb-tracker-stereo-mono.cpp, tutorial-mb-tracker-stereo.cpp, tutorial-mb-tracker.cpp, tutorial-template-tracker.cpp, tutorial-video-reader.cpp, and videoReader.cpp.

Definition at line 91 of file vpVideoReader.cpp.

◆ setFirstFrameIndex()

void vpVideoReader::setFirstFrameIndex ( const long  first_frame)
inline

Enables to set the first frame index if you want to use the class like a grabber (ie with the acquire method).

Parameters
first_frame: The first frame index.
See also
setLastFrameIndex()
Examples
AROgre.cpp, AROgreBasic.cpp, imageSequenceReader.cpp, templateTracker.cpp, and trackMeNurbs.cpp.

Definition at line 350 of file vpVideoReader.h.

◆ setFrameStep()

void vpVideoReader::setFrameStep ( const long  frame_step)
inline

Sets the frame step index. The default frame step is 1

Parameters
frame_step: The frame index step.
See also
setFrameStep()

Definition at line 376 of file vpVideoReader.h.

◆ setLastFrameIndex()

void vpVideoReader::setLastFrameIndex ( const long  last_frame)
inline

Member Data Documentation

◆ height

unsigned int vpFrameGrabber::height
protectedinherited

Number of rows in the image.

Definition at line 106 of file vpFrameGrabber.h.

Referenced by vpDirectShowGrabber::getFormat().

◆ init

bool vpFrameGrabber::init
inherited

Set to true if the frame grabber has been initialized.

Definition at line 103 of file vpFrameGrabber.h.

◆ width

unsigned int vpFrameGrabber::width
protectedinherited

Number of columns in the image.

Definition at line 107 of file vpFrameGrabber.h.

Referenced by vpDirectShowGrabber::getFormat().

vpDisplayX
Use the X11 console to display images on unix-like OS. Thus to enable this class X11 should be instal...
Definition: vpDisplayX.h:149
vpTime::wait
VISP_EXPORT int wait(double t0, double t)
Definition: vpTime.cpp:172
vpDisplay::setTitle
static void setTitle(const vpImage< unsigned char > &I, const std::string &windowtitle)
Definition: vpDisplay_uchar.cpp:1222
vpVideoReader::getFrame
bool getFrame(vpImage< vpRGBa > &I, long frame)
Definition: vpVideoReader.cpp:398
vpVideoReader::setLastFrameIndex
void setLastFrameIndex(const long last_frame)
Definition: vpVideoReader.h:362
vpVideoReader::end
bool end()
Definition: vpVideoReader.h:259
vpDisplayGDI
Display for windows using GDI (available on any windows 32 platform).
Definition: vpDisplayGDI.h:127
vpDisplayOpenCV
The vpDisplayOpenCV allows to display image using the OpenCV library. Thus to enable this class OpenC...
Definition: vpDisplayOpenCV.h:140
vpTime::measureTimeMs
VISP_EXPORT double measureTimeMs()
Definition: vpTime.cpp:125
vpVideoReader::getFramerate
double getFramerate()
Definition: vpVideoReader.h:277
vpVideoReader::open
void open(vpImage< vpRGBa > &I)
Definition: vpVideoReader.cpp:174
vpVideoReader
Class that enables to manipulate easily a video file or a sequence of images. As it inherits from the...
Definition: vpVideoReader.h:170
vpVideoReader::setFileName
void setFileName(const std::string &filename)
Definition: vpVideoReader.cpp:91
vpDisplay::display
static void display(const vpImage< unsigned char > &I)
Definition: vpDisplay_uchar.cpp:739
vpDisplay::displayText
static void displayText(const vpImage< unsigned char > &I, const vpImagePoint &ip, const std::string &s, const vpColor &color)
Definition: vpDisplay_uchar.cpp:663
vpImage::getHeight
unsigned int getHeight() const
Definition: vpImage.h:185
vpException::getMessage
const char * getMessage(void) const
Definition: vpException.cpp:89
vpDisplay::flush
static void flush(const vpImage< unsigned char > &I)
Definition: vpDisplay_uchar.cpp:715
vpImage< unsigned char >
vpDisplay::getClick
static bool getClick(const vpImage< unsigned char > &I, bool blocking=true)
Definition: vpDisplay_uchar.cpp:764
vpException
error that can be emited by ViSP classes.
Definition: vpException.h:70
vpVideoReader::acquire
void acquire(vpImage< vpRGBa > &I)
Definition: vpVideoReader.cpp:243
vpVideoReader::setFirstFrameIndex
void setFirstFrameIndex(const long first_frame)
Definition: vpVideoReader.h:350
vpColor::red
static const vpColor red
Definition: vpColor.h:178
vpImage::getWidth
unsigned int getWidth() const
Definition: vpImage.h:243