Visual Servoing Platform  version 3.6.1 under development (2024-05-27)

Example of grey level images framegrabbing using vpV4l2Grabber class.

Test frame grabbing capabilities using video for linux two (V4L2) video device. Only grabbing of grey level images is possible in this example. Display these images using X11 or GTK.

* ViSP, open source Visual Servoing Platform software.
* Copyright (C) 2005 - 2023 by Inria. All rights reserved.
* This software is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
* (at your option) any later version.
* See the file LICENSE.txt at the root directory of this source
* distribution for additional information about the GNU GPL.
* For using ViSP with software that can not be combined with the GNU
* GPL, please contact Inria about acquiring a ViSP Professional
* Edition License.
* See for more information.
* This software was developed at:
* Inria Rennes - Bretagne Atlantique
* Campus Universitaire de Beaulieu
* 35042 Rennes Cedex
* France
* If you have questions regarding the use of this file, please contact
* Inria at
* This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
* Description:
* Acquire images using 1394 device with cfox (MAC OSX) and display it
* using GTK or GTK.
#include <stdlib.h>
#include <visp3/core/vpConfig.h>
#include <visp3/core/vpDebug.h>
#ifdef VISP_HAVE_V4L2
#if (defined(VISP_HAVE_X11) || defined(VISP_HAVE_GTK))
#include <visp3/core/vpDisplay.h>
#include <visp3/core/vpImage.h>
#include <visp3/core/vpTime.h>
#include <visp3/gui/vpDisplayGTK.h>
#include <visp3/gui/vpDisplayX.h>
#include <visp3/io/vpImageIo.h>
#include <visp3/io/vpParseArgv.h>
#include <visp3/sensor/vpV4l2Grabber.h>
// List of allowed command line options
#define GETOPTARGS "df:i:hn:o:p:s:t:v:x"
typedef enum {
grey_image = 0, // for ViSP unsigned char grey images
color_image // for ViSP vpRGBa color images
} vpImage_type;
void usage(const char *name, const char *badparam, unsigned fps, unsigned input, unsigned scale, long niter,
const std::string &device, vpV4l2Grabber::vpV4l2PixelFormatType pixelformat, const vpImage_type &image_type,
const std::string &opath)
fprintf(stdout, "\n\
Grab grey level images using the Video For Linux Two framegrabber. \n\
Display these images using X11 or GTK.\n\
%s [-v <video device>] [-f <fps=25|50>] \n\
[-i <input=0|1|2|3> [-s <scale=1|2|4>] [-p <pixel format>]\n\
[-n <niter>] [-t <image type>] [-o <filename>] [-x] [-d] [-h]\n",
fprintf(stdout, "\n\
OPTIONS: Default\n\
-v <video device> %s\n\
Video device to access to the camera\n\
-f <fps> %u\n\
Framerate in term od number of images per second.\n\
Possible values are 25 (for 25Hz) or 50 (for %%) Hz)\n\
-i <input> %u\n\
Framegrabber active input. Values can be 0, 1, 2, 4\n\
-p <pixel format> %d\n\
Camera pixel format. Values must be in [0-%d]:\n\
0 for gray format\n\
1 for RGB24 format\n\
2 for RGB32 format\n\
3 for BGR24 format\n\
4 for YUYV format\n\
-t <image type> %d\n\
Kind of images that are acquired/displayed by ViSP. \n\
Values must be in [0-1]:\n\
0 for grey images in unsigned char \n\
1 for color images in vpRGBa\n\
-s <scale> %u\n\
Framegrabber subsampling factor. \n\
If 1, full resolution image acquisition.\n\
If 2, half resolution image acquisition. The \n\
subsampling is achieved by the hardware.\n\
-n <niter> %ld\n\
Number of images to acquire.\n\
-d \n\
Turn off the display.\n\
-x \n\
Activates the extra verbose mode.\n\
-o [%%s] : Filename for image saving. \n\
Example: -o %s\n\
The %%d is for the image numbering. The format is set \n\
by the extension of the file (ex .png, .pgm, ...) \n\
-h \n\
Print the help.\n\n",
device.c_str(), fps, input, pixelformat, vpV4l2Grabber::V4L2_MAX_FORMAT - 1, image_type, scale, niter,
if (badparam)
fprintf(stdout, "\nERROR: Bad parameter [%s]\n", badparam);
bool getOptions(int argc, const char **argv, unsigned &fps, unsigned &input, unsigned &scale, bool &display,
bool &verbose, long &niter, std::string &device, vpV4l2Grabber::vpV4l2PixelFormatType &pixelformat,
vpImage_type &image_type, bool &save, std::string &opath)
const char *optarg_;
int c;
while ((c = vpParseArgv::parse(argc, argv, GETOPTARGS, &optarg_)) > 1) {
switch (c) {
case 'd':
display = false;
case 'f':
fps = (unsigned)atoi(optarg_);
case 'i':
input = (unsigned)atoi(optarg_);
case 'n':
niter = atol(optarg_);
case 'o':
save = true;
opath = optarg_;
case 'p':
pixelformat = (vpV4l2Grabber::vpV4l2PixelFormatType)atoi(optarg_);
case 's':
scale = (unsigned)atoi(optarg_);
case 't':
image_type = (vpImage_type)atoi(optarg_);
case 'v':
device = std::string(optarg_);
case 'x':
verbose = true;
case 'h':
usage(argv[0], nullptr, fps, input, scale, niter, device, pixelformat, image_type, opath);
return false;
usage(argv[0], optarg_, fps, input, scale, niter, device, pixelformat, image_type, opath);
return false;
if ((c == 1) || (c == -1)) {
// standalone param or error
usage(argv[0], nullptr, fps, input, scale, niter, device, pixelformat, image_type, opath);
std::cerr << "ERROR: " << std::endl;
std::cerr << " Bad argument " << optarg_ << std::endl << std::endl;
return false;
return true;
int main(int argc, const char **argv)
try {
unsigned int opt_fps = 25;
unsigned int opt_input = 0;
unsigned int opt_scale = 1;
long opt_iter = 100;
bool opt_verbose = false;
bool opt_display = true;
std::string opt_device = "/dev/video0";
bool opt_save = false;
// Default output path for image saving
std::string opt_opath = "/tmp/I%04d.ppm";
vpImage_type opt_image_type = color_image;
// Read the command line options
if (getOptions(argc, argv, opt_fps, opt_input, opt_scale, opt_display, opt_verbose, opt_iter, opt_device,
opt_pixelformat, opt_image_type, opt_save, opt_opath) == false) {
// Declare an image, this is a gray level image (unsigned char) and
// an other one that is a color image. There size is not defined
// yet. It will be defined when the image will acquired the first
// time.
vpImage<unsigned char> Ig; // grey level image
vpImage<vpRGBa> Ic; // color image
// Creates the grabber
// Initialize the grabber
if (opt_fps == 25)
if (opt_image_type == grey_image) {
// Open the framegrabber with the specified settings on grey images;
// Acquire an image
std::cout << "Grey image size: width : " << Ig.getWidth() << " height: " << Ig.getHeight() << std::endl;
} else {
// Open the framegrabber with the specified settings on color images;
// Acquire an image
std::cout << "Color image size: width : " << Ic.getWidth() << " height: " << Ic.getHeight() << std::endl;
// We open a window using either X11 or GTK.
// Its size is automatically defined by the image (I) size
#if defined(VISP_HAVE_X11)
#elif defined(VISP_HAVE_GTK)
if (opt_display) {
// Display the image
// The image class has a member that specify a pointer toward
// the display that has been initialized in the display declaration
// therefore is is no longer necessary to make a reference to the
// display variable.
if (opt_image_type == grey_image) {
display.init(Ig, 100, 100, "V4L2 grey images framegrabbing");
} else {
display.init(Ic, 100, 100, "V4L2 color images framegrabbing");
// Acquisition loop
long cpt = 1;
while (cpt++ < opt_iter) {
// Measure the initial time of an iteration
double t = vpTime::measureTimeMs();
// Acquire the image
if (opt_image_type == grey_image) {
if (opt_display) {
// Display the image
// Flush the display
} else {
if (opt_display) {
// Display the image
// Flush the display
if (opt_save) {
char buf[FILENAME_MAX];
snprintf(buf, FILENAME_MAX, opt_opath.c_str(), cpt);
std::string filename(buf);
std::cout << "Write: " << filename << std::endl;
if (opt_image_type == grey_image) {
vpImageIo::write(Ig, filename);
} else {
vpImageIo::write(Ic, filename);
// Print the iteration duration
std::cout << "time: " << vpTime::measureTimeMs() - t << " (ms)" << std::endl;
} catch (const vpException &e) {
std::cout << "Catch an exception: " << e << std::endl;
int main()
std::cout << "You do not have X11, or GTK functionalities to display images..." << std::endl;
std::cout << "Tip if you are on a unix-like system:" << std::endl;
std::cout << "- Install X11, configure again ViSP using cmake and build again this example" << std::endl;
std::cout << "Tip if you are on a windows-like system:" << std::endl;
std::cout << "- Install GTK, configure again ViSP using cmake and build again this example" << std::endl;
int main()
std::cout << "You do not have Video 4 Linux 2 functionality enabled" << std::endl;
std::cout << "Tip if you are on a unix-like system:" << std::endl;
std::cout << "- Install libv4l2, configure again ViSP using cmake and build again this example" << std::endl;
The vpDisplayGTK allows to display image using the GTK 3rd party library. Thus to enable this class G...
Definition: vpDisplayGTK.h:128
Use the X11 console to display images on unix-like OS. Thus to enable this class X11 should be instal...
Definition: vpDisplayX.h:128
static void display(const vpImage< unsigned char > &I)
static void flush(const vpImage< unsigned char > &I)
error that can be emitted by ViSP classes.
Definition: vpException.h:59
static void write(const vpImage< unsigned char > &I, const std::string &filename, int backend=IO_DEFAULT_BACKEND)
Definition: vpImageIo.cpp:287
unsigned int getWidth() const
Definition: vpImage.h:245
unsigned int getHeight() const
Definition: vpImage.h:184
static bool parse(int *argcPtr, const char **argv, vpArgvInfo *argTable, int flags)
Definition: vpParseArgv.cpp:69
Class that is a wrapper over the Video4Linux2 (V4L2) driver.
@ framerate_50fps
50 frames per second
@ framerate_25fps
25 frames per second
void setFramerate(vpV4l2FramerateType framerate)
void setVerboseMode(bool verbose)
void setInput(unsigned input=vpV4l2Grabber::DEFAULT_INPUT)
void open(vpImage< unsigned char > &I)
void setScale(unsigned scale=vpV4l2Grabber::DEFAULT_SCALE)
void setPixelFormat(vpV4l2PixelFormatType pixelformat)
void setDevice(const std::string &devname)
void acquire(vpImage< unsigned char > &I)
void display(vpImage< unsigned char > &I, const std::string &title)
Display a gray-scale image.
VISP_EXPORT double measureTimeMs()