Visual Servoing Platform  version 3.5.1 under development (2023-02-04)
Tutorial: Image filtering

This tutorial supposes that you have followed the Tutorial: How to create and build a project that uses ViSP and CMake on Unix or Windows.

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/core/vpImageFilter.h>
#include <visp3/gui/vpDisplayD3D.h>
#include <visp3/gui/vpDisplayGDI.h>
#include <visp3/gui/vpDisplayGTK.h>
#include <visp3/gui/vpDisplayOpenCV.h>
#include <visp3/gui/vpDisplayX.h>
#include <visp3/io/vpImageIo.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)
#elif defined(VISP_HAVE_GTK)
#elif defined(VISP_HAVE_GDI)
#elif defined(VISP_HAVE_D3D9)
#else
std::cout << "No image viewer is available..." << std::endl;
#endif
vpDisplay::setTitle(I, title.c_str());
vpDisplay::displayText(I, 15, 15, "Click to continue...", vpColor::red);
}
void display(vpImage<double> &D, const std::string &title)
{
vpImage<unsigned char> I; // Image to display
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;
}
try {
vpImageIo::read(I, argv[1]);
} catch (...) {
std::cout << "Cannot read image \"" << argv[1] << "\"" << std::endl;
return -1;
}
display(I, "Original image");
display(F, "Blur (default)");
display(F, "Blur (var=2)");
display(dIx, "Gradient dIx");
display(dIy, "Gradient dIy");
#if (VISP_HAVE_OPENCV_VERSION >= 0x020100)
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;
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 (const vpException &e) {
std::cout << "Catch an exception: " << e << std::endl;
return 1;
}
}
static const vpColor red
Definition: vpColor.h:217
Display for windows using Direct3D 3rd party. Thus to enable this class Direct3D should be installed....
Definition: vpDisplayD3D.h:107
Display for windows using GDI (available on any windows 32 platform).
Definition: vpDisplayGDI.h:129
The vpDisplayGTK allows to display image using the GTK 3rd party library. Thus to enable this class G...
Definition: vpDisplayGTK.h:135
The vpDisplayOpenCV allows to display image using the OpenCV library. Thus to enable this class OpenC...
Use the X11 console to display images on unix-like OS. Thus to enable this class X11 should be instal...
Definition: vpDisplayX.h:135
static bool getClick(const vpImage< unsigned char > &I, bool blocking=true)
static void display(const vpImage< unsigned char > &I)
static void setTitle(const vpImage< unsigned char > &I, const std::string &windowtitle)
static void flush(const vpImage< unsigned char > &I)
static void displayText(const vpImage< unsigned char > &I, const vpImagePoint &ip, const std::string &s, const vpColor &color)
error that can be emited by ViSP classes.
Definition: vpException.h:72
static void convert(const vpImage< unsigned char > &src, vpImage< vpRGBa > &dest)
static void filter(const vpImage< double > &I, vpImage< double > &Iu, vpImage< double > &Iv, const vpMatrix &M, bool convolve=false)
static void getGradX(const vpImage< unsigned char > &I, vpImage< double > &dIx)
static void gaussianBlur(const vpImage< unsigned char > &I, vpImage< double > &GI, unsigned int size=7, double sigma=0., bool normalize=true)
static void canny(const vpImage< unsigned char > &I, vpImage< unsigned char > &Ic, unsigned int gaussianFilterSize, double thresholdCanny, unsigned int apertureSobel)
static void getGradY(const vpImage< unsigned char > &I, vpImage< double > &dIy)
static void getGaussPyramidal(const vpImage< unsigned char > &I, vpImage< unsigned char > &GI)
static void read(vpImage< unsigned char > &I, const std::string &filename, int backend=IO_DEFAULT_BACKEND)
Definition: vpImageIo.cpp:148
Implementation of a matrix and operations on matrices.
Definition: vpMatrix.h:154

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

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:

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:

Gradients along Y could be obtained using:

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)
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:

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.