VideoReader¶

class VideoReader(self)¶

Bases: FrameGrabber

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/core/vpConfig.h>
#include <visp3/gui/vpDisplayFactory.h>
#include <visp3/core/vpTime.h>
#include <visp3/io/vpVideoReader.h>

int main(int argc, char **argv)
{
#if defined(VISP_HAVE_OPENCV) && defined(HAVE_OPENCV_HIGHGUI) && defined(HAVE_OPENCV_VIDEOIO)
#ifdef ENABLE_VISP_NAMESPACE
  using namespace VISP_NAMESPACE_NAME ;
#endif
  try {
    std::string videoname = "video.mp4";

    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 EXIT_SUCCESS;
      }
    }

    vpImage<unsigned char>  I;
    vpVideoReader  g;
    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_DISPLAY
    vpDisplay  *d = vpDisplayFactory::allocateDisplay (I);
#else
    std::cout << "No image viewer is available..." << std::endl;
#endif
    vpDisplay::setTitle (I, "Video reader");

    unsigned cpt = 1;
    bool quit = false;
    while ((!g. end ()) && (!quit)) {
      double t = vpTime::measureTimeMs ();
      g. acquire (I);
      vpDisplay::display (I);
      vpDisplay::displayText (I, 20, 20, "Click to quit", vpColor::red );
      std::stringstream ss;
      ss << "Frame: " << ++cpt;
      std::cout << "Read " << ss.str() << std::endl;
      vpDisplay::displayText (I, 40, 20, ss.str(), vpColor::red );
      vpDisplay::flush (I);
      if ( vpDisplay::getClick (I, false)) {
        quit = true;
      }
      vpTime::wait (t, 1000. / g. getFramerate ());
    }
    if (!quit) {
      std::cout << "End of video was reached" << std::endl;
    }
#ifdef VISP_HAVE_DISPLAY
    delete d;
#endif
  }
  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
  return EXIT_SUCCESS;
}

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>

#ifdef ENABLE_VISP_NAMESPACE
using namespace VISP_NAMESPACE_NAME;
#endif

int main()
{
#ifdef VISP_HAVE_OPENCV
  vpImage<vpRGBa> I;

  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 positioning 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>

#ifdef ENABLE_VISP_NAMESPACE
using namespace VISP_NAMESPACE_NAME;
#endif

int main()
{
  vpImage<vpRGBa> I;

  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>

#ifdef ENABLE_VISP_NAMESPACE
using namespace VISP_NAMESPACE_NAME;
#endif

int main()
{
  vpImage<vpRGBa> I;

  vpVideoReader reader;

  // Initialize the reader.
  reader.setFileName("./image/image%04d.jpeg");
  reader.open(I);

  // Read the 3th frame
  reader.getFrame(I,2);

  return 0;
}

Basic constructor.

Methods

`__init__`	Basic constructor.
`acquire`	Overloaded function.
`close`	This virtual function is used to de-allocate the memory used by a specific frame grabber
`end`	return: true if the end of the sequence is reached.
`getFirstFrameIndex`	Gets the first frame index.
`getFrame`	Overloaded function.
`getFrameIndex`	Get the frame index of the current image.
`getFrameName`	Return the name of the file in which the last frame was read.
`getFrameStep`	Gets the frame step.
`getFramerate`	Return the frame rate in Hz used to encode the video stream.
`getLastFrameIndex`	Gets the last frame index.
`isVideoFormat`	Indicate if the video is an encoded single video file.
`open`	Overloaded function.
`resetFrameCounter`	Reset the frame counter and sets it to the first image index.
`setFileName`	It enables to set the path and the name of the video which has to be read.
`setFirstFrameIndex`	Enables to set the first frame index if you want to use the class like a grabber (ie with the acquire method).
`setFrameStep`	Sets the frame step index.
`setLastFrameIndex`	Enables to set the last frame index.

Inherited Methods

`init`
`getHeight`	Return the number of rows in the image.
`getWidth`	Return the number of columns in the image.

Operators

`__doc__`
`__init__`	Basic constructor.
`__module__`

Attributes

`__annotations__`
`init`

__init__(self)¶: Basic constructor.

acquire(*args, **kwargs)¶

Overloaded function.

acquire(self: visp._visp.io.VideoReader, I: visp._visp.core.ImageRGBa) -> None

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.

acquire(self: visp._visp.io.VideoReader, I: visp._visp.core.ImageGray) -> None

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.

close(self) → None¶: This virtual function is used to de-allocate the memory used by a specific frame grabber

end(self) → bool¶

Returns:: true if the end of the sequence is reached.

getFirstFrameIndex(self) → int¶

Gets the first frame index.

Returns:: Returns the first frame index.

getFrame(*args, **kwargs)¶

Overloaded function.

getFrame(self: visp._visp.io.VideoReader, I: visp._visp.core.ImageRGBa, frame: int) -> bool

Gets the \(frame\) th frame and stores it in the image \(I\) .

Parameters:

I: The vpImage used to stored the frame.

Returns:

It returns true if the frame could be read. Else it returns false.

getFrame(self: visp._visp.io.VideoReader, I: visp._visp.core.ImageGray, frame: int) -> bool

Gets the \(frame\) th frame and stores it in the image \(I\) .

Parameters:

I: The vpImage used to stored the frame.

Returns:

It returns true if the frame could be read. Else it returns false.

getFrameIndex(self) → int¶

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() ).

Note

See end()

Returns:: Returns the current frame index.

getFrameName(self) → str¶: Return the name of the file in which the last frame was read.

getFrameStep(self) → int¶

Gets the frame step.

Returns:: Returns the frame step value.

getFramerate(self) → float¶

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

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

getHeight(self) → int¶: Return the number of rows in the image.

getLastFrameIndex(self) → int¶

Gets the last frame index.

Returns:: Returns the last frame index.

getWidth(self) → int¶: Return the number of columns in the image.

isVideoFormat(self) → bool¶

Indicate if the video is an encoded single video file.

Returns:: true if the video format corresponds to an encoded single video file like one of the following avi, mpeg, mp4, mts, mov, ogv, wmv, flv, mkv. Return false, if the video is a sequence of successive images (png, jpeg, ppm, pgm…).

open(*args, **kwargs)¶

Overloaded function.

open(self: visp._visp.io.VideoReader, I: visp._visp.core.ImageRGBa) -> None

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.

open(self: visp._visp.io.VideoReader, I: visp._visp.core.ImageGray) -> None

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.

resetFrameCounter(self) → None¶

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 the acquire method).

setFileName(self, filename: str) → None¶

It enables to set the path and the name of the video which has to be read.

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

If you want to read a sequence of images, filename corresponds rather 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: str¶: Path to a video file or file name template of a image sequence.

setFirstFrameIndex(self, first_frame: int) → None¶

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

Note

See setLastFrameIndex()

Parameters:

first_frame: int¶: The first frame index.

setFrameStep(self, frame_step: int) → None¶

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

Note

See setFrameStep()

Parameters:

frame_step: int¶: The frame index step.

setLastFrameIndex(self, last_frame: int) → None¶

Enables to set the last frame index.

Note

See setFirstFrameIndex()

Parameters:

last_frame: int¶: The last frame index.