Visual Servoing Platform  version 3.2.0 under development (2018-10-20)
Tutorial: Contours extraction from a binary image

Introduction

This tutorial will show you how to extract the contours from a binary image. The contour extraction algorithm is based on [39] article and most of the implementation has been ported from [16] library.

The function to call is vp::findContours(const vpImage<unsigned char> &, vpContour &, std::vector<std::vector<vpImagePoint> > &, const vpContourRetrievalType&):

  • the first argument is the image where '0' pixel value means the background and '1' pixel value means the foreground. Other values are not allowed.
  • the second argument is a vp::vpContour structure that contains the list of contours in a tree
  • the third argument is the list of contours
  • the last argument is an option to choose the type of contour extraction, see vp::vpContourRetrievalType

The vp::vpContour structure is composed of:

The different contour extraction methods are:

  • vp::CONTOUR_RETR_TREE, all the contours are extracted and stored in a hierarchical tree.
  • vp::CONTOUR_RETR_LIST, all the contours are extracted and stored in a list. The top level contour contains in m_children the list of all the extracted contours.
  • vp::CONTOUR_RETR_EXTERNAL, only the external contours are extracted and stored in a list. The top level contour contains in m_children the list of the external extracted contours.

The next section will provide a concrete example for better understanding.

Example code

The following example also available in tutorial-contour.cpp will demonstrate on a sample image the result of each of these methods:

#include <cstdlib>
#include <iostream>
#include <visp3/core/vpImage.h>
#include <visp3/gui/vpDisplayGDI.h>
#include <visp3/gui/vpDisplayOpenCV.h>
#include <visp3/gui/vpDisplayX.h>
#include <visp3/io/vpImageIo.h>
#if defined(VISP_HAVE_MODULE_IMGPROC) && (defined(VISP_HAVE_X11) || defined(VISP_HAVE_GDI) || defined(VISP_HAVE_OPENCV))
#include <visp3/imgproc/vpImgproc.h>
namespace
{
void displayContourInfo(const vp::vpContour &contour, const int level)
{
std::cout << "\nContour:" << std::endl;
std::cout << "\tlevel: " << level << std::endl;
std::cout << "\tcontour type: " << (contour.m_contourType == vp::CONTOUR_OUTER ? "outer contour" : "hole contour")
<< std::endl;
std::cout << "\tcontour size: " << contour.m_points.size() << std::endl;
std::cout << "\tnb children: " << contour.m_children.size() << std::endl;
for (std::vector<vp::vpContour *>::const_iterator it = contour.m_children.begin(); it != contour.m_children.end();
++it) {
displayContourInfo(**it, level + 1);
}
}
void drawContoursTree(vpImage<vpRGBa> &I, const vp::vpContour &contour)
{
std::vector<std::vector<vpImagePoint> > contours;
contours.push_back(contour.m_points);
for (std::vector<vp::vpContour *>::const_iterator it = contour.m_children.begin(); it != contour.m_children.end();
++it) {
drawContoursTree(I, **it);
}
}
} // namespace
#endif
int main(int argc, const char **argv)
{
#if defined(VISP_HAVE_MODULE_IMGPROC) && (defined(VISP_HAVE_X11) || defined(VISP_HAVE_GDI) || defined(VISP_HAVE_OPENCV))
std::string input_filename = "grid36-03.pgm";
bool white_foreground = false;
for (int i = 1; i < argc; i++) {
if (std::string(argv[i]) == "--input" && i + 1 < argc) {
input_filename = std::string(argv[i + 1]);
} else if (std::string(argv[i]) == "--white_foreground") {
white_foreground = true;
} else if (std::string(argv[i]) == "--method" && i + 1 < argc) {
extraction_method = (vp::vpContourRetrievalType)atoi(argv[i + 1]);
} else if (std::string(argv[i]) == "--help" || std::string(argv[i]) == "-h") {
std::cout << "Usage: " << argv[0]
<< " [--input <input image>] [--method <0: "
"CONTOUR_RETR_TREE, 1: CONTOUR_RETR_LIST, 2: "
"CONTOUR_RETR_EXTERNAL>]"
" [--white_foreground] [--help]"
<< std::endl;
return EXIT_SUCCESS;
}
}
vpImageIo::read(I, input_filename);
vpImage<vpRGBa> I_draw_contours(I.getHeight(), I.getWidth());
#ifdef VISP_HAVE_X11
vpDisplayX d, d2;
#elif defined(VISP_HAVE_GDI)
vpDisplayGDI d, d2;
#elif defined(VISP_HAVE_OPENCV)
#endif
d.init(I_bin, 0, 0, "After binarisation");
d2.init(I_draw_contours, I_bin.getWidth(), 10, "Contours");
vp::autoThreshold(I, vp::AUTO_THRESHOLD_OTSU, white_foreground ? 0 : 1, white_foreground ? 1 : 0);
for (unsigned int i = 0; i < I_bin.getSize(); i++) {
I_bin.bitmap[i] = 255 * I.bitmap[i];
}
vp::vpContour vp_contours;
std::vector<std::vector<vpImagePoint> > contours;
vp::findContours(I, vp_contours, contours, extraction_method);
vp::drawContours(I_draw_contours, contours, vpColor::red);
vpDisplay::display(I_draw_contours);
vpDisplay::displayText(I_draw_contours, 20, 20, "Click to draw outer / hole contours.", vpColor::red);
vpDisplay::flush(I_draw_contours);
vpDisplay::getClick(I_draw_contours);
I_draw_contours = 0;
drawContoursTree(I_draw_contours, vp_contours);
displayContourInfo(vp_contours, 0);
vpDisplay::display(I_draw_contours);
vpDisplay::displayText(I_draw_contours, 20, 20, "Click to quit.", vpColor::red);
vpDisplay::displayText(I_draw_contours, 20, I_draw_contours.getWidth() - 200, "Outer contour", vpColor::red);
vpDisplay::displayText(I_draw_contours, 20, I_draw_contours.getWidth() - 100, "Hole contour", vpColor::green);
vpDisplay::flush(I_draw_contours);
vpDisplay::getClick(I_draw_contours);
return EXIT_SUCCESS;
#else
(void)argc;
(void)argv;
return 0;
#endif
}

These functions are provided in a vp:: namespace and accessible using this include:

#include <visp3/imgproc/vpImgproc.h>

The first steps are:

The result images for each step are:

img-auto-threshold-grid36-03.png
Input image
img-tutorial-contour-binarisation.png
Image after binarization using the Otsu method
img-tutorial-contour-draw-contours.png
Contours extracted and displayed on a new image

To understand how the hierarchical contours extraction works, let's switch on another example. In a terminal, run:

$ ./tutorial-contour --input Contours_tree.pgm --white_foreground

The image after binarisation:

img-tutorial-contour-binarisation2.png
Image after binarization using the Otsu method

Instead of drawing all the contours with the same color, we can assign a first color for vp::CONTOUR_OUTER contour and a second color for vp::CONTOUR_HOLE contour.

The function to navigate in the contour tree is the following:

void drawContoursTree(vpImage<vpRGBa> &I, const vp::vpContour &contour)
{
std::vector<std::vector<vpImagePoint> > contours;
contours.push_back(contour.m_points);
for (std::vector<vp::vpContour *>::const_iterator it = contour.m_children.begin(); it != contour.m_children.end();
++it) {
drawContoursTree(I, **it);
}
}

The call to draw the hierarchical contours:

drawContoursTree(I_draw_contours, vp_contours);

The result image is:

img-tutorial-contour-draw-contours2.png
Contours extracted and displayed on a new image, in red outer contours, in green hole contours

To display the hierarchy, we can use this function:

void displayContourInfo(const vp::vpContour &contour, const int level)
{
std::cout << "\nContour:" << std::endl;
std::cout << "\tlevel: " << level << std::endl;
std::cout << "\tcontour type: " << (contour.m_contourType == vp::CONTOUR_OUTER ? "outer contour" : "hole contour")
<< std::endl;
std::cout << "\tcontour size: " << contour.m_points.size() << std::endl;
std::cout << "\tnb children: " << contour.m_children.size() << std::endl;
for (std::vector<vp::vpContour *>::const_iterator it = contour.m_children.begin(); it != contour.m_children.end();
++it) {
displayContourInfo(**it, level + 1);
}
}

For the vp::CONTOUR_RETR_TREE method, the output is:

Contour:
level: 0
contour type: hole contour
contour size: 0
nb children: 3

Contour:
level: 1
contour type: outer contour
contour size: 438
nb children: 0

Contour:
level: 1
contour type: outer contour
contour size: 748
nb children: 0

Contour:
level: 1
contour type: outer contour
contour size: 2012
nb children: 1

Contour:
level: 2
contour type: hole contour
contour size: 1906
nb children: 1

Contour:
level: 3
contour type: outer contour
contour size: 1610
nb children: 1

Contour:
level: 4
contour type: hole contour
contour size: 1494
nb children: 1

Contour:
level: 5
contour type: outer contour
contour size: 792
nb children: 2

Contour:
level: 6
contour type: hole contour
contour size: 372
nb children: 0

Contour:
level: 6
contour type: hole contour
contour size: 392
nb children: 0

The top level contour is always the root contour with zero contour point and which contains the list of contours.

For the vp::CONTOUR_RETR_EXTERNAL method, the output is:

Contour:
level: 0
contour type: hole contour
contour size: 0
nb children: 3
Contour:
level: 1
contour type: outer contour
contour size: 438
nb children: 0
Contour:
level: 1
contour type: outer contour
contour size: 748
nb children: 0
Contour:
level: 1
contour type: outer contour
contour size: 2012
nb children: 0

The result image is:

img-tutorial-contour-draw-contours3.png
External contours extracted and displayed on a new image

For the vp::CONTOUR_RETR_LIST method, the output is:

Contour:
level: 0
contour type: hole contour
contour size: 0
nb children: 9
Contour:
level: 1
contour type: outer contour
contour size: 438
nb children: 0
Contour:
level: 1
contour type: outer contour
contour size: 748
nb children: 0
Contour:
level: 1
contour type: outer contour
contour size: 2012
nb children: 0
Contour:
level: 1
contour type: hole contour
contour size: 1906
nb children: 0
Contour:
level: 1
contour type: outer contour
contour size: 1610
nb children: 0
Contour:
level: 1
contour type: hole contour
contour size: 1494
nb children: 0
Contour:
level: 1
contour type: outer contour
contour size: 792
nb children: 0
Contour:
level: 1
contour type: hole contour
contour size: 372
nb children: 0
Contour:
level: 1
contour type: hole contour
contour size: 392
nb children: 0

Next tutorial

You can now read the Tutorial: Connected-components labeling, for a similar method to extract the connected-components in a grayscale image.