Introduction

In this tutorial you will learn how to use ViSP filtering functions implemented in vpImageFilter class.

All the material (source code and images) described in this tutorial is part of ViSP source code and could be downloaded using the following command:

$ svn export https://github.com/lagadic/visp.git/trunk/tutorial/image

Let us consider the following source code that comes from tutorial-image-filter.cpp.

#include <visp3/gui/vpDisplayD3D.h>
#include <visp3/gui/vpDisplayGDI.h>
#include <visp3/gui/vpDisplayGTK.h>
#include <visp3/gui/vpDisplayX.h>
#include <visp3/gui/vpDisplayOpenCV.h>
#include <visp3/io/vpImageIo.h>
#include <visp3/core/vpImageFilter.h>
void display(vpImage<unsigned char> &I, const std::string &title);
void display(vpImage<double> &D, const std::string &title);
void display(vpImage<unsigned char> &I, const std::string &title)
{
#if defined(VISP_HAVE_X11)
  vpDisplayX d(I);
#elif defined(VISP_HAVE_OPENCV)
  vpDisplayOpenCV d(I);
#elif defined(VISP_HAVE_GTK)
  vpDisplayGTK d(I);
#elif defined(VISP_HAVE_GDI)
  vpDisplayGDI d(I);
#elif defined(VISP_HAVE_D3D9)
  vpDisplayD3d d(I);
#else
  std::cout << "No image viewer is available..." << std::endl;
#endif
  vpDisplay::setTitle(I, title.c_str());
  vpDisplay::display(I);
  vpDisplay::displayText(I, 15,15, "Click to continue...", vpColor::red);
  vpDisplay::flush(I);
  vpDisplay::getClick(I);
}
void display(vpImage<double> &D, const std::string &title)
{
  vpImage<unsigned char> I; // Image to display
  vpImageConvert::convert(D, I);
  display(I, title);
}
int main(int argc, char** argv )
{
  try {
    if(argc != 2) {
      printf( "Usage: %s <image name.[pgm,ppm,jpeg,png,bmp]>\n", argv[0] );
      return -1;
    }
    vpImage<unsigned char> I;
    try {
      vpImageIo::read(I, argv[1]);
    }
    catch(...) {
      std::cout << "Cannot read image \"" << argv[1] << "\"" << std::endl;
      return -1;
    }
    display(I, "Original image");
    vpImage<double> F;
    vpImageFilter::gaussianBlur(I, F);
    display(F, "Blur (default)");
    vpImageFilter::gaussianBlur(I, F, 7, 2);
    display(F, "Blur (var=2)");
    vpImage<double> dIx;
    vpImageFilter::getGradX(I, dIx);
    display(dIx, "Gradient dIx");
    vpImage<double> dIy;
    vpImageFilter::getGradY(I, dIy);
    display(dIy, "Gradient dIy");
#if (VISP_HAVE_OPENCV_VERSION >= 0x020100)
    vpImage<unsigned char> C;
    vpImageFilter::canny(I, C, 5, 15, 3);
    display(C, "Canny");
#endif
    vpMatrix K(3,3); // Sobel kernel along x
    K[0][0] = 1; K[0][1] = 0; K[0][2] = -1;
    K[1][0] = 2; K[1][1] = 0; K[1][2] = -2;
    K[2][0] = 1; K[2][1] = 0; K[2][2] = -1;
    vpImage<double> Gx;
    vpImageFilter::filter(I, Gx, K);
    display(Gx, "Sobel x");
    size_t nlevel = 3;
    std::vector< vpImage<unsigned char> > pyr(nlevel);
    pyr[0] = I;
    for (size_t i=1; i < nlevel; i++) {
      vpImageFilter::getGaussPyramidal(pyr[i-1], pyr[i]);
      display(pyr[i], "Pyramid");
    }
    return 0;
  }
  catch(vpException &e) {
    std::cout << "Catch an exception: " << e << std::endl;
    return 1;
  }
}

Once build, you should have tutorial-image-filter binary. It shows how to apply different filters on an input image. Here we will consider monkey.pgm as input image.

To see the resulting filtered images, just run:

./tutorial-image-filter monkey.pgm

The following sections give a line by line explanation of the source code dedicated to image filtering capabilities.

Gaussian blur

Monkey input image is read from disk and is stored in I which is a gray level image declared as

vpImage<unsigned char> I;

To apply a Gaussian blur to this image we first have to declare a resulting floating-point image F. Then the blurred image could be obtained using the default Gaussian filter:

vpImage<double> F;

vpImageFilter::gaussianBlur(I, F);

The resulting image is the following:

It is also possible to specify the Gaussian filter kernel size and the Gaussian standard deviation (sigma) using:

vpImageFilter::gaussianBlur(I, F, 7, 2); // Kernel size: 7, sigma: 2

We thus obtain the following image:

Gradients computation

To compute the gradients or the spatial derivative along X use:

vpImage<double> dIx;

vpImageFilter::getGradX(I, dIx);

Gradients along Y could be obtained using:

vpImage<double> dIy;

vpImageFilter::getGradY(I, dIy);

The resulting floating-point images dIx, dIy are the following:

Canny edge detector

Canny edge detector function is only available if ViSP was build with OpenCV 2.1 or higher.

After the declaration of a new image container C, Canny edge detector is applied using:

#if (VISP_HAVE_OPENCV_VERSION >= 0x020100)
    vpImage<unsigned char> C;
    vpImageFilter::canny(I, C, 5, 15, 3);
    display(C, "Canny");
#endif

Where:

5: is the low threshold
15: is the high threshold set in the program as three times the lower threshold (following Canny’s recommendation)
3: is the size of the Sobel kernel used internally.

The resulting image C is the following:

Convolution

To apply a convolution to an image, we first have to define a kernel. For example, let us consider the 3x3 Sobel kernel defined in K.

${\bf K} = \begin{tabular}{|c|c|c|} \hline 1 & 0 & -1 \\ \hline 2 & 0 & -2 \\ \hline 1 & 0 & -1 \\ \hline \end{tabular}$

    vpMatrix K(3,3); // Sobel kernel along x
    K[0][0] = 1; K[0][1] = 0; K[0][2] = -1;
    K[1][0] = 2; K[1][1] = 0; K[1][2] = -2;
    K[2][0] = 1; K[2][1] = 0; K[2][2] = -1;

After the declaration of a new floating-point image Gx, the convolution is obtained using:

vpImage<double> Gx;

vpImageFilter::filter(I, Gx, K);

The content of the filtered image Gx is the following.

Gaussian image pyramid

To construct a pyramid of Gaussian filtered images as a vector of images implemented in pyr[] you may use:

    size_t nlevel = 3;
    std::vector< vpImage<unsigned char> > pyr(nlevel);
    pyr[0] = I;
    for (size_t i=1; i < nlevel; i++) {
      vpImageFilter::getGaussPyramidal(pyr[i-1], pyr[i]);
      display(pyr[i], "Pyramid");
    }

The content of pyr[0], pyr[1], pyr[2] is the following:

Next tutorial

You are now ready to see the next Tutorial: Blob tracking.

Table of Contents