#include <visp3/blob/vpDot2.h>

Inheritance diagram for vpDot2:

Public Member Functions
	vpDot2 ()

VP_EXPLICIT	vpDot2 (const vpImagePoint &ip)

	vpDot2 (const vpDot2 &twinDot)

void	display (const vpImage< unsigned char > &I, vpColor color=vpColor::red, unsigned int thickness=1) const

vpColVector	get_nij () const

double	getArea () const

vpRect	getBBox () const

vpImagePoint	getCog () const

double	getDistance (const vpDot2 &distantDot) const

void	getEdges (std::list< vpImagePoint > &edges_list) const

std::list< vpImagePoint >	getEdges () const

double	getEllipsoidBadPointsPercentage () const

double	getEllipsoidShapePrecision () const

void	getFreemanChain (std::list< unsigned int > &freeman_chain) const

double	getGamma () const

unsigned int	getGrayLevelMin () const

unsigned int	getGrayLevelMax () const

double	getGrayLevelPrecision () const

double	getHeight () const

double	getMaxSizeSearchDistPrecision () const

double	getMeanGrayLevel () const

vpPolygon	getPolygon () const

double	getSizePrecision () const

double	getWidth () const

void	initTracking (const vpImage< unsigned char > &I, unsigned int size=0)

void	initTracking (const vpImage< unsigned char > &I, const vpImagePoint &ip, unsigned int size=0)

void	initTracking (const vpImage< unsigned char > &I, const vpImagePoint &ip, unsigned int gray_lvl_min, unsigned int gray_lvl_max, unsigned int size=0)

vpDot2 &	operator= (const vpDot2 &twinDot)

void	print (std::ostream &os)

void	searchDotsInArea (const vpImage< unsigned char > &I, int area_u, int area_v, unsigned int area_w, unsigned int area_h, std::list< vpDot2 > &niceDots)

void	searchDotsInArea (const vpImage< unsigned char > &I, std::list< vpDot2 > &niceDots)

void	setArea (const double &area)

void	setCog (const vpImagePoint &ip)

void	setComputeMoments (bool activate)

void	setEllipsoidBadPointsPercentage (const double &percentage=0.0)

void	setEllipsoidShapePrecision (const double &ellipsoidShapePrecision)

void	setGraphics (bool activate)

void	setGraphicsThickness (unsigned int thickness)

void	setGrayLevelMin (const unsigned int &min)

void	setGrayLevelMax (const unsigned int &max)

void	setGrayLevelPrecision (const double &grayLevelPrecision)

void	setHeight (const double &height)

void	setMaxSizeSearchDistPrecision (const double &maxSizeSearchDistancePrecision)

void	setSizePrecision (const double &sizePrecision)

void	setWidth (const double &width)

void	track (const vpImage< unsigned char > &I, bool canMakeTheWindowGrow=true)

void	track (const vpImage< unsigned char > &I, vpImagePoint &cog, bool canMakeTheWindowGrow=true)

Public Member Functions Inherited from vpTracker
vpColVector	get_p () const

vpColVector	get_cP () const

Static Public Member Functions
static vpMatrix	defineDots (vpDot2 dot[], const unsigned int &n, const std::string &dotFile, vpImage< unsigned char > &I, vpColor col=vpColor::blue, bool trackDot=true)

static void	trackAndDisplay (vpDot2 dot[], const unsigned int &n, vpImage< unsigned char > &I, std::vector< vpImagePoint > &cogs, vpImagePoint *cogStar=nullptr)

static void	display (const vpImage< unsigned char > &I, const vpImagePoint &cog, const std::list< vpImagePoint > &edges_list, vpColor color=vpColor::red, unsigned int thickness=1)

static void	display (const vpImage< vpRGBa > &I, const vpImagePoint &cog, const std::list< vpImagePoint > &edges_list, vpColor color=vpColor::red, unsigned int thickness=1)

Public Attributes
Public Attributes Inherited from vpTracker
vpColVector	p

vpColVector	cP

bool	cPAvailable

Friends
VISP_EXPORT std::ostream &	operator<< (std::ostream &os, vpDot2 &d)

Detailed Description

This tracker is meant to track a blob (connex pixels with same gray level) on a vpImage.

The underground algorithm is based on a binarization of the image and then on a contour detection using the Freeman chain coding to determine the blob characteristics (location, moments, size...).

The binarization is done using gray level minimum and maximum values that define the admissible gray levels of the blob. You can specify these levels by setGrayLevelMin() and setGrayLevelMax(). These levels are also set automatically by setGrayLevelPrecision(). The algorithm allows to track white objects on a black background and vice versa.

When a blob is found, some tests are done to see if it is valid:

A blob is considered by default as ellipsoid. The found blob could be rejected if the shape is not ellipsoid. To determine if the shape is ellipsoid the algorithm consider an inner and outside ellipse. Sampled points on these two ellipses should have the right gray levels. Along the inner ellipse the sampled points should have gray levels that are in the gray level minimum and maximum bounds, while on the outside ellipse, the gray levels should be out of the gray level bounds. To set the percentage of the sample points which should have the right levels use setEllipsoidBadPointsPercentage(). The distance between the inner ellipsoid and the blob contour, as well the distance between the blob contour and the outside ellipse is fixed by setEllipsoidShapePrecision(). If you want to track a non ellipsoid shape, and turn off this validation test, you have to call setEllipsoidShapePrecision(0).
The width, height and surface of the blob are compared to the corresponding values of the previous blob. If they differ to much the blob could be rejected. To set the admissible distance you can use setSizePrecision().

Note that track() and searchDotsInArea() are the most important features of this class.

track() estimate the current position of the dot using its previous position, then try to compute the new parameters of the dot. If everything went ok, tracking succeeds, otherwise we search this dot in a window around the last position of the dot.
searchDotsInArea() enable to find dots similar to this dot in a window. It is used when there was a problem performing basic tracking of the dot, but can also be used to find a certain type of dots in the full image.

The following sample code available in tutorial-blob-tracker-live-firewire.cpp shows how to grab images from a firewire camera, track a blob and display the tracking results.

#include <visp3/core/vpConfig.h>
#ifdef VISP_HAVE_MODULE_SENSOR
#include <visp3/sensor/vp1394CMUGrabber.h>
#include <visp3/sensor/vp1394TwoGrabber.h>
#endif
#include <visp3/blob/vpDot2.h>
#include <visp3/gui/vpDisplayGDI.h>
#include <visp3/gui/vpDisplayOpenCV.h>
#include <visp3/gui/vpDisplayX.h>
 
#if defined(HAVE_OPENCV_VIDEOIO)
#include <opencv2/videoio.hpp>
#endif
 
int main()
{
#if (defined(VISP_HAVE_DC1394) || defined(VISP_HAVE_CMU1394) || defined(HAVE_OPENCV_VIDEOIO)) &&             \
    (defined(VISP_HAVE_X11) || defined(VISP_HAVE_GDI) || defined(VISP_HAVE_OPENCV))
#ifdef ENABLE_VISP_NAMESPACE
  using namespace VISP_NAMESPACE_NAME;
#endif
 
  vpImage<unsigned char> I; // Create a gray level image container
 
#if defined(VISP_HAVE_DC1394)
  vp1394TwoGrabber g(false);
  g.open(I);
#elif defined(VISP_HAVE_CMU1394)
  vp1394CMUGrabber g;
  g.open(I);
#elif defined(HAVE_OPENCV_VIDEOIO)
  cv::VideoCapture g(0); // open the default camera
  if (!g.isOpened()) {   // check if we succeeded
    std::cout << "Failed to open the camera" << std::endl;
    return EXIT_FAILURE;
  }
  cv::Mat frame;
  g >> frame; // get a new frame from camera
  vpImageConvert::convert(frame, I);
#endif
 
#if defined(VISP_HAVE_X11)
  vpDisplayX d(I, 0, 0, "Camera view");
#elif defined(VISP_HAVE_GDI)
  vpDisplayGDI d(I, 0, 0, "Camera view");
#elif defined(HAVE_OPENCV_HIGHGUI)
  vpDisplayOpenCV d(I, 0, 0, "Camera view");
#endif
 
  vpDot2 blob;
  blob.setGraphics(true);
  blob.setGraphicsThickness(2);
 
  vpImagePoint germ;
  bool init_done = false;
 
  while (1) {
    try {
#if defined(VISP_HAVE_DC1394) || defined(VISP_HAVE_CMU1394)
      g.acquire(I);
#elif defined(HAVE_OPENCV_VIDEOIO)
      g >> frame;
      vpImageConvert::convert(frame, I);
#endif
      vpDisplay::display(I);
 
      if (!init_done) {
        vpDisplay::displayText(I, vpImagePoint(10, 10), "Click in the blob to initialize the tracker", vpColor::red);
        if (vpDisplay::getClick(I, germ, false)) {
          blob.initTracking(I, germ);
          init_done = true;
        }
      }
      else {
        blob.track(I);
      }
 
      vpDisplay::flush(I);
    }
    catch (...) {
      init_done = false;
    }
}
#endif
}

A line by line explanation of the previous example is provided in Tutorial: Blob tracking.

This other example available in tutorial-blob-auto-tracker.cpp shows firstly how to detect in the first image all the blobs that match some characteristics in terms of size, area, gray level. Secondly, it shows how to track all the dots that are detected.

#include <visp3/core/vpConfig.h>
#include <visp3/blob/vpDot2.h>
#include <visp3/gui/vpDisplayGDI.h>
#include <visp3/gui/vpDisplayOpenCV.h>
#include <visp3/gui/vpDisplayX.h>
#include <visp3/io/vpImageIo.h>
 
int main()
{
#ifdef ENABLE_VISP_NAMESPACE
  using namespace VISP_NAMESPACE_NAME;
#endif
 
  try {
    bool learn = false;
    vpImage<unsigned char> I; // Create a gray level image container
 
    vpImageIo::read(I, "./target.pgm");
 
#if defined(VISP_HAVE_X11)
    vpDisplayX d(I, 0, 0, "Camera view");
#elif defined(VISP_HAVE_GDI)
    vpDisplayGDI d(I, 0, 0, "Camera view");
#elif defined(HAVE_OPENCV_HIGHGUI)
    vpDisplayOpenCV d(I, 0, 0, "Camera view");
#else
    std::cout << "No image viewer is available..." << std::endl;
#endif
    vpDisplay::display(I);
    vpDisplay::flush(I);
 
    vpDot2 blob;
    if (learn) {
      // Learn the characteristics of the blob to auto detect
      blob.setGraphics(true);
      blob.setGraphicsThickness(1);
      blob.initTracking(I);
      blob.track(I);
      std::cout << "Blob characteristics: " << std::endl;
      std::cout << " width : " << blob.getWidth() << std::endl;
      std::cout << " height: " << blob.getHeight() << std::endl;
#if VISP_VERSION_INT > VP_VERSION_INT(2, 7, 0)
      std::cout << " area: " << blob.getArea() << std::endl;
#endif
      std::cout << " gray level min: " << blob.getGrayLevelMin() << std::endl;
      std::cout << " gray level max: " << blob.getGrayLevelMax() << std::endl;
      std::cout << " grayLevelPrecision: " << blob.getGrayLevelPrecision() << std::endl;
      std::cout << " sizePrecision: " << blob.getSizePrecision() << std::endl;
      std::cout << " ellipsoidShapePrecision: " << blob.getEllipsoidShapePrecision() << std::endl;
    }
    else {
      // Set blob characteristics for the auto detection
      blob.setWidth(50);
      blob.setHeight(50);
#if VISP_VERSION_INT > VP_VERSION_INT(2, 7, 0)
      blob.setArea(1700);
#endif
      blob.setGrayLevelMin(0);
      blob.setGrayLevelMax(30);
      blob.setGrayLevelPrecision(0.8);
      blob.setSizePrecision(0.65);
      blob.setEllipsoidShapePrecision(0.65);
    }
 
    std::list<vpDot2> blob_list;
    blob.searchDotsInArea(I, 0, 0, I.getWidth(), I.getHeight(), blob_list);
 
    if (learn) {
      // The blob that is tracked by initTracking() is not in the list of auto
      // detected blobs We add it:
      blob_list.push_back(blob);
    }
    std::cout << "Number of auto detected blob: " << blob_list.size() << std::endl;
    std::cout << "A click to exit..." << std::endl;
 
    while (1) {
      vpDisplay::display(I);
 
      for (std::list<vpDot2>::iterator it = blob_list.begin(); it != blob_list.end(); ++it) {
        (*it).setGraphics(true);
        (*it).setGraphicsThickness(3);
        (*it).track(I);
      }
 
      vpDisplay::flush(I);
 
      if (vpDisplay::getClick(I, false))
        break;
 
      vpTime::wait(40);
    }
  }
  catch (const vpException &e) {
    std::cout << "Catch an exception: " << e << std::endl;
  }
}

A line by line explanation of this last example is also provided in Tutorial: Blob tracking, section Blob tracking.

See also: vpDot

Examples: AROgre.cpp, AROgreBasic.cpp, manSimu4Dots.cpp, servoAfma4Point2DCamVelocityKalman.cpp, servoPioneerPanSegment3D.cpp, servoPioneerPoint2DDepth.cpp, servoPioneerPoint2DDepthWithoutVpServo.cpp, servoPtu46Point2DArtVelocity.cpp, servoViper650Point2DCamVelocity.cpp, servoViper850FourPoints2DArtVelocityLs_cur.cpp, servoViper850FourPoints2DCamVelocityLs_cur.cpp, servoViper850FourPointsKinect.cpp, servoViper850Point2DArtVelocity-jointAvoidance-basic.cpp, servoViper850Point2DArtVelocity-jointAvoidance-gpa.cpp, servoViper850Point2DArtVelocity-jointAvoidance-large.cpp, servoViper850Point2DArtVelocity.cpp, servoViper850Point2DCamVelocity.cpp, servoViper850Point2DCamVelocityKalman.cpp, testTrackDot.cpp, trackDot2WithAutoDetection.cpp, tutorial-blob-auto-tracker.cpp, tutorial-blob-tracker-live-firewire.cpp, and tutorial-blob-tracker-live-v4l2.cpp.

Definition at line 124 of file vpDot2.h.

Constructor & Destructor Documentation

◆ vpDot2() [1/3]

vpDot2::vpDot2 ( )

Default constructor. Just do basic default initialization.

Definition at line 110 of file vpDot2.cpp.

◆ vpDot2() [2/3]

vpDot2::vpDot2 ( const vpImagePoint & ip )

Constructor initialize the coordinates of the gravity center of the dot to the image point ip. Rest is the same as the default constructor.

Parameters

ip	: An image point with sub-pixel coordinates.

Definition at line 131 of file vpDot2.cpp.

◆ vpDot2() [3/3]

vpDot2::vpDot2 ( const vpDot2 & twinDot )

Copy constructor.

Definition at line 147 of file vpDot2.cpp.

Member Function Documentation

◆ defineDots()

vpMatrix vpDot2::defineDots	(	vpDot2	dot[],
		const unsigned int &	n,
		const std::string &	dotFile,
		vpImage< unsigned char > &	I,
		vpColor	col = `vpColor::blue`,
		bool	trackDot = `true`
	)

static

Define a number of dots from a file. If the file does not exist, define it by clicking an image, the dots are then saved into the file.

If the dots from the file cannot be tracked in the image, will ask to click them.

Parameters

dot	: dot2 array
n	: number of dots, array dimension
dotFile	: path for the file
I	: image
col	: color to print the dots (default Blue)
trackDot	: if true, tracks the dots in the image, if false simply loads the coordinates (default true)

Returns: an nx2 matrix with the coordinates of the dots

Definition at line 1714 of file vpDot2.cpp.

References vpIoTools::checkFilename(), vpDisplay::display(), vpDisplay::displayCross(), vpDisplay::flush(), vpImagePoint::get_u(), vpImagePoint::get_v(), vpDisplay::getClick(), getCog(), getDistance(), getHeight(), vpArray2D< Type >::getRows(), getWidth(), initTracking(), vpMatrix::loadMatrix(), vpMatrix::saveMatrix(), vpImagePoint::set_uv(), setCog(), setGraphics(), vpMath::sqr(), and track().

◆ display() [1/3]

void vpDot2::display	(	const vpImage< unsigned char > &	I,
		const vpImagePoint &	cog,
		const std::list< vpImagePoint > &	edges_list,
		vpColor	color = `vpColor::red`,
		unsigned int	thickness = `1`
	)

static

Display the dot center of gravity and its list of edges.

Parameters

I	: The image used as background.
cog	: The center of gravity.
edges_list	: The list of edges;
color	: Color used to display the dot.
thickness	: Thickness of the dot.

Definition at line 1867 of file vpDot2.cpp.

References vpDisplay::displayCross(), and vpDisplay::displayPoint().

◆ display() [2/3]

void vpDot2::display	(	const vpImage< unsigned char > &	I,
		vpColor	color = `vpColor::red`,
		unsigned int	t = `1`
	)		const

Display in overlay the dot edges and center of gravity.

Parameters

I	: Image.
color	: The color used for the display.
t	: Thickness of the displayed cross located at the dot cog.

Examples: AROgre.cpp, and AROgreBasic.cpp.

Definition at line 225 of file vpDot2.cpp.

References vpDisplay::displayCross(), and vpDisplay::displayPoint().

◆ display() [3/3]

void vpDot2::display	(	const vpImage< vpRGBa > &	I,
		const vpImagePoint &	cog,
		const std::list< vpImagePoint > &	edges_list,
		vpColor	color = `vpColor::red`,
		unsigned int	thickness = `1`
	)

static

Display the dot center of gravity and its list of edges.

Parameters

I	: The image used as background.
cog	: The center of gravity.
edges_list	: The list of edges;
color	: Color used to display the dot.
thickness	: Thickness of the dot.

Definition at line 1896 of file vpDot2.cpp.

References vpDisplay::displayCross(), and vpDisplay::displayPoint().

◆ get_cP()

vpColVector vpTracker::get_cP ( ) const

inlineinherited

Return object parameters expressed in the 3D camera frame.

Definition at line 95 of file vpTracker.h.

◆ get_nij()

vpColVector vpDot2::get_nij ( ) const

inline

Gets the second order normalized centered moment $n_{ij}$ as a 3-dim vector containing $n_{20}, n_{11}, n_{02}$ such as $n_{ij} = \mu_{ij}/m_{00}$

Returns: The 3-dim vector containing $n_{20}, n_{11}, n_{02}$ .

See also: getCog(), getArea()

Definition at line 145 of file vpDot2.h.

◆ get_p()

vpColVector vpTracker::get_p ( ) const

inlineinherited

Return object parameters expressed in the 2D image plane computed by perspective projection.

Definition at line 93 of file vpTracker.h.

◆ getArea()

double vpDot2::getArea ( ) const

Return the area of the dot.

The area of the dot is also given by .

Examples: tutorial-blob-auto-tracker.cpp.

Definition at line 628 of file vpDot2.cpp.

Referenced by track().

◆ getBBox()

vpRect vpDot2::getBBox ( ) const

inline

Return the dot bounding box.

See also: getWidth(), getHeight()

Definition at line 166 of file vpDot2.h.

References vpRect::setRect().

◆ getCog()

vpImagePoint vpDot2::getCog ( ) const

inline

Return the location of the dot center of gravity.

Returns: The coordinates of the center of gravity.

Examples: AROgre.cpp, AROgreBasic.cpp, servoAfma4Point2DCamVelocityKalman.cpp, servoViper650Point2DCamVelocity.cpp, servoViper850FourPoints2DArtVelocityLs_cur.cpp, servoViper850FourPoints2DCamVelocityLs_cur.cpp, servoViper850FourPointsKinect.cpp, servoViper850Point2DArtVelocity-jointAvoidance-basic.cpp, servoViper850Point2DArtVelocity-jointAvoidance-gpa.cpp, servoViper850Point2DArtVelocity-jointAvoidance-large.cpp, servoViper850Point2DArtVelocity.cpp, servoViper850Point2DCamVelocity.cpp, and servoViper850Point2DCamVelocityKalman.cpp.

Definition at line 181 of file vpDot2.h.

Referenced by defineDots(), getDistance(), searchDotsInArea(), track(), and trackAndDisplay().

◆ getDistance()

double vpDot2::getDistance ( const vpDot2 & distantDot ) const

Return the distance between the two center of dots.

Definition at line 664 of file vpDot2.cpp.

References vpImagePoint::get_u(), vpImagePoint::get_v(), and getCog().

Referenced by defineDots().

◆ getEdges() [1/2]

std::list<vpImagePoint> vpDot2::getEdges ( ) const

inline

Return the list of all the image points on the dot border.

Returns: The list of all the images points on the dot border. This list is update after a call to track().

Definition at line 200 of file vpDot2.h.

◆ getEdges() [2/2]

void vpDot2::getEdges ( std::list< vpImagePoint > & edges_list ) const

inline

Return the list of all the image points on the dot border.

Parameters

edges_list : The list of all the images points on the dot border. This list is update after a call to track().

Definition at line 191 of file vpDot2.h.

◆ getEllipsoidBadPointsPercentage()

double vpDot2::getEllipsoidBadPointsPercentage ( ) const

inline

Get the percentage of sampled points that are considered non conform in terms of the gray level on the inner and the outside ellipses.

See also: setEllipsoidBadPointsPercentage()

Definition at line 208 of file vpDot2.h.

◆ getEllipsoidShapePrecision()

double vpDot2::getEllipsoidShapePrecision ( ) const

Return the precision of the ellipsoid shape of the dot. It is a double precision float which value is in [0,1]. 1 means full precision, whereas values close to 0 show a very bad precision.

See also: setEllipsoidShapePrecision()

Examples: tutorial-blob-auto-tracker.cpp.

Definition at line 651 of file vpDot2.cpp.

◆ getFreemanChain()

BEGIN_VISP_NAMESPACE void vpDot2::getFreemanChain ( std::list< unsigned int > & freeman_chain ) const

Gets the list of Freeman chain code used to turn around the dot counterclockwise.

Parameters

[out]

freeman_chain

: List of Freeman chain list [0, ..., 7]

0 : right
1 : top right
2 : top
3 : top left
4 : left
5 : down left
6 : down
7 : down right

Definition at line 139 of file vpDot2_freeman.cpp.

◆ getGamma()

double vpDot2::getGamma ( ) const

inline

Definition at line 213 of file vpDot2.h.

◆ getGrayLevelMax()

unsigned int vpDot2::getGrayLevelMax ( ) const

inline

Return the color level of pixels inside the dot.

See also: getGrayLevelMin()

Examples: tutorial-blob-auto-tracker.cpp.

Definition at line 225 of file vpDot2.h.

◆ getGrayLevelMin()

unsigned int vpDot2::getGrayLevelMin ( ) const

inline

Return the color level of pixels inside the dot.

See also: getGrayLevelMax()

Examples: tutorial-blob-auto-tracker.cpp.

Definition at line 219 of file vpDot2.h.

◆ getGrayLevelPrecision()

double vpDot2::getGrayLevelPrecision ( ) const

Return the precision of the gray level of the dot. It is a double precision float which value is in [0,1]. 1 means full precision, whereas values close to 0 show a very bad precision.

Examples: tutorial-blob-auto-tracker.cpp.

Definition at line 635 of file vpDot2.cpp.

◆ getHeight()

double vpDot2::getHeight ( ) const

Return the height of the dot.

See also: getWidth()

Examples: tutorial-blob-auto-tracker.cpp.

Definition at line 621 of file vpDot2.cpp.

Referenced by defineDots(), searchDotsInArea(), and track().

◆ getMaxSizeSearchDistPrecision()

double vpDot2::getMaxSizeSearchDistPrecision ( ) const

Return the precision of the search maximum distance to get the starting point on a dot border. It is a double precision float which value is in [0.05,1]. 1 means full precision, whereas values close to 0 show a very bad precision.

Definition at line 659 of file vpDot2.cpp.

◆ getMeanGrayLevel()

double vpDot2::getMeanGrayLevel ( ) const

inline

Returns: The mean gray level value of the dot.

Definition at line 234 of file vpDot2.h.

Referenced by track().

◆ getPolygon()

vpPolygon vpDot2::getPolygon ( ) const

inline

Returns: a vpPolygon made from the edges of the dot.

Definition at line 239 of file vpDot2.h.

◆ getSizePrecision()

double vpDot2::getSizePrecision ( ) const

Return the precision of the size of the dot. It is a double precision float which value is in [0.05,1]. 1 means full precision, whereas values close to 0 show a very bad precision.

Examples: tutorial-blob-auto-tracker.cpp.

Definition at line 642 of file vpDot2.cpp.

◆ getWidth()

double vpDot2::getWidth ( ) const

Return the width of the dot.

See also: getHeight()

Examples: tutorial-blob-auto-tracker.cpp.

Definition at line 614 of file vpDot2.cpp.

Referenced by defineDots(), searchDotsInArea(), and track().

◆ initTracking() [1/3]

void vpDot2::initTracking	(	const vpImage< unsigned char > &	I,
		const vpImagePoint &	ip,
		unsigned int	gray_lvl_min,
		unsigned int	gray_lvl_max,
		unsigned int	size = `0`
	)

Initialize the tracking for a dot supposed to be located at (u,v) and update the dot characteristics (center of gravity, moments) by a call to track().

The sub pixel coordinates of the dot are updated. To get the center of gravity coordinates of the dot, use getCog(). To compute the moments use setComputeMoments(true) before a call to initTracking().

Parameters

I	: Image to process.
ip	: Location of the starting point from which the dot will be tracked in the image.
gray_lvl_min	: Minimum gray level threshold used to segment the dot; value comprised between 0 and 255.
gray_lvl_max	: Maximum gray level threshold used to segment the dot; value comprised between 0 and 255. gray_level_max should be greater than gray_level_min.
size	: Size of the dot to track.

If no valid dot was found in the window, return an exception.

Exceptions

vpTrackingException::featureLostError

: If the dot initialization failed. The initialization can fail if the following characteristics are not valid;

The gray level is between gray level min and gray level max.
The shape should be ellipsoid if setEllipsoidShapePrecision(ellipsoidShapePrecision) is used. This is the default case. To track a non ellipsoid shape use setEllipsoidShapePrecision(0).

See also: track(), getCog()

Definition at line 397 of file vpDot2.cpp.

References setHeight(), setWidth(), and track().

◆ initTracking() [2/3]

void vpDot2::initTracking	(	const vpImage< unsigned char > &	I,
		const vpImagePoint &	ip,
		unsigned int	size = `0`
	)

Initialize the tracking for a dot supposed to be located at (u,v) and update the dot characteristics (center of gravity, moments) by a call to track().

Parameters

I	: Image to process.
ip	: Location of the starting point from which the dot will be tracked in the image.
size	: Size of the dot to track.

To get center of gravity of the dot, see getCog(). To compute the moments see setComputeMoments().

If no valid dot was found in the window, return an exception.

Exceptions

vpTrackingException::featureLostError

: If the dot initialization failed. The initialization can fail if the following characteristics are not valid;

The gray level is between gray level min and gray level max.
The shape should be ellipsoid if setEllipsoidShapePrecision(ellipsoidShapePrecision) is used. This is the default case. To track a non ellipsoid shape use setEllipsoidShapePrecision(0).

Definition at line 328 of file vpDot2.cpp.

References vpImagePoint::get_i(), vpImagePoint::get_j(), setHeight(), setWidth(), and track().

◆ initTracking() [3/3]

void vpDot2::initTracking	(	const vpImage< unsigned char > &	I,
		unsigned int	size = `0`
	)

Initialize the tracking with a mouse click on the image and update the dot characteristics (center of gravity, moments) by a call to track().

Wait a user click in a white area in the image. The clicked pixel will be the starting point from which the dot will be tracked.

To get center of gravity of the dot, see getCog(). To compute the moments see setComputeMoments(). To get the width or height of the dot, call getWidth() and getHeight(). The area of the dot is given by getArea().

Parameters

I	: Image.
size	: Size of the dot to track.

If no valid dot was found in the window, return an exception.

Exceptions

vpTrackingException::featureLostError

: If the dot initialization failed. The initialization can fail if the following characteristics are not valid;

The gray level is between gray level min and gray level max.
The shape should be ellipsoid if setEllipsoidShapePrecision(ellipsoidShapePrecision) is used. This is the default case. To track a non ellipsoid shape use setEllipsoidShapePrecision(0).

See also: track()

Definition at line 269 of file vpDot2.cpp.

References vpImagePoint::get_i(), vpImagePoint::get_j(), vpDisplay::getClick(), setHeight(), setWidth(), and track().

Referenced by defineDots().

◆ operator=()

vpDot2 & vpDot2::operator= ( const vpDot2 & twinDot )

= operator.

Definition at line 165 of file vpDot2.cpp.

◆ print()

void vpDot2::print ( std::ostream & os )

inline

Definition at line 251 of file vpDot2.h.

◆ searchDotsInArea() [1/2]

void vpDot2::searchDotsInArea	(	const vpImage< unsigned char > &	I,
		int	area_u,
		int	area_v,
		unsigned int	area_w,
		unsigned int	area_h,
		std::list< vpDot2 > &	niceDots
	)

Look for a list of dot matching this dot parameters within a region of interest defined by a rectangle in the image. The rectangle upper-left coordinates are given by (area_u, area_v). The size of the rectangle is given by area_w and area_h.

Parameters

I	: Image to process.
area_u	: Coordinate (column) of the upper-left area corner.
area_v	: Coordinate (row) of the upper-left area corner.
area_w	: Width or the area in which a dot is searched.
area_h	: Height or the area in which a dot is searched.
niceDots	List of the dots that are found.

Warning: Allocates memory for the list of vpDot2 returned by this method. Desallocation has to be done by yourself, see searchDotsInArea()

See also: searchDotsInArea(vpImage<unsigned char>& I, std::list<vpDot2> &)

Examples: tutorial-blob-auto-tracker.cpp.

Definition at line 224 of file vpDot2_search.cpp.

References vpColor::blue, vpDisplay::displayRectangle(), vpDisplay::flush(), vpImagePoint::get_u(), vpImagePoint::get_v(), vpRect::getBottom(), getCog(), getHeight(), vpRect::getLeft(), vpRect::getRight(), vpRect::getTop(), getWidth(), and setArea().

Referenced by searchDotsInArea(), and track().

◆ searchDotsInArea() [2/2]

void vpDot2::searchDotsInArea	(	const vpImage< unsigned char > &	I,
		std::list< vpDot2 > &	niceDots
	)

Look for a list of dot matching this dot parameters within the entire image.

Warning: Allocates memory for the list of dots returned by this method. Desallocation has to be done by yourself.

Parameters

I	: Image.
niceDots	List of the dots that are found.

Before calling this method, dot characteristics to found have to be set like:

vpDot2 d;
 
// Set dot characteristics for the auto detection
d.setWidth(24);
d.setHeight(23);
d.setArea(412);
d.setGrayLevelMin(160);
d.setGrayLevelMax(255);
d.setGrayLevelPrecision(0.8);
d.setSizePrecision(0.65);
d.setEllipsoidShapePrecision(0.65);

To search dots in the whole image:

std::list<vpDot2> list_d;

d.searchDotsInArea(I, 0, 0, I.getWidth(), I.getHeight(), list_d) ;

The number of dots found in the area is given by:

std::cout << list_d.size();

To parse all the dots:

std::list<vpDot2>::iterator it;
for (it = list_d.begin(); it != list_d.end(); ++it) {
    vpDot2 tmp_d = *it;
}

See also: searchDotsInArea(vpImage<unsigned char>&, int, int, unsigned int, unsigned int, std::list<vpDot2> &)

Definition at line 957 of file vpDot2.cpp.

References vpImage< Type >::getHeight(), vpImage< Type >::getWidth(), and searchDotsInArea().

◆ setArea()

void vpDot2::setArea ( const double & a )

Set the area of the dot. This is meant to be used to search a dot in a region of interest.

Parameters

a	: Area of a dot to search in a region of interest.

See also: setWidth(), setHeight(), setSizePrecision()

Examples: tutorial-blob-auto-tracker.cpp.

Definition at line 707 of file vpDot2.cpp.

Referenced by searchDotsInArea(), and track().

◆ setCog()

void vpDot2::setCog ( const vpImagePoint & ip )

inline

Initialize the dot coordinates with ip.

Examples: servoPtu46Point2DArtVelocity.cpp.

Definition at line 261 of file vpDot2.h.

Referenced by defineDots(), and track().

◆ setComputeMoments()

void vpDot2::setComputeMoments ( bool activate )

inline

Activates the dot's moments computation.

Parameters

activate true, if you want to compute the moments. If false, moments are not computed.

Computed moment are vpDot::m00, vpDot::m10, vpDot::m01, vpDot::m11, vpDot::m20, vpDot::m02 and second order centered moments vpDot::mu11, vpDot::mu20, vpDot::mu02 computed with respect to the blob centroid.

The coordinates of the region's centroid (u, v) can be computed from the moments by $u=\frac{m10}{m00}$ and $v=\frac{m01}{m00}$ .

Examples: servoPioneerPanSegment3D.cpp, servoPioneerPoint2DDepth.cpp, servoPioneerPoint2DDepthWithoutVpServo.cpp, and testTrackDot.cpp.

Definition at line 276 of file vpDot2.h.

◆ setEllipsoidBadPointsPercentage()

void vpDot2::setEllipsoidBadPointsPercentage ( const double & percentage = 0.0 )

inline

Set the percentage of sampled points that are considered non conform in terms of the gray level on the inner and the outside ellipses. Points located on the inner ellipse should have the same gray level than the blob, while points located on the outside ellipse should have a different gray level.

Parameters

percentage : Percentage of points sampled with bad gray level on the inner and outside ellipses that are admissible. 0 means that all the points should have a right level, while a value of 1 means that all the points can have a bad gray level.

Examples: servoPioneerPanSegment3D.cpp, servoPioneerPoint2DDepth.cpp, and servoPioneerPoint2DDepthWithoutVpServo.cpp.

Definition at line 290 of file vpDot2.h.

◆ setEllipsoidShapePrecision()

void vpDot2::setEllipsoidShapePrecision ( const double & precision )

Indicates if the dot should have an ellipsoid shape to be valid.

Parameters

precision : It is a double precision float which value is in [0,1]:

1 means full precision, whereas values close to 0 show a very bad accuracy.
Values lower or equal to 0 are brought back to 0.
Values higher than 1 are brought back to 1. To track a non ellipsoid shape use setEllipsoidShapePrecision(0).

The following example show how to track a blob with a height constraint on an ellipsoid shape. The tracking will fail if the shape is not ellipsoid.

vpDot2 dot;
dot.setEllipsoidShapePrecision(0.9); // to track a blob with a height
constraint attendee on a circle shape
...
dot.track();

This other example shows how to remove any constraint on the shape. Here the tracker will be able to track any shape, including square or rectangular shapes.

vpDot2 dot;
dot.setEllipsoidShapePrecision(0.); // to track a blob without any constraint on the shape
...
dot.track();

See also: getEllipsoidShapePrecision()

Examples: servoPioneerPanSegment3D.cpp, servoPioneerPoint2DDepth.cpp, servoPioneerPoint2DDepthWithoutVpServo.cpp, and tutorial-blob-auto-tracker.cpp.

Definition at line 801 of file vpDot2.cpp.

◆ setGraphics()

void vpDot2::setGraphics ( bool activate )

inline

Activates the display of the border of the dot during the tracking. The default thickness of the overlayed drawings can be modified using setGraphicsThickness().

Warning: To effectively display the dot graphics a call to vpDisplay::flush() is needed.

Parameters

activate If true, the border of the dot will be painted. false to turn off border painting.

See also: setGraphicsThickness()

Examples: AROgre.cpp, AROgreBasic.cpp, manSimu4Dots.cpp, servoAfma4Point2DCamVelocityKalman.cpp, servoPioneerPanSegment3D.cpp, servoPioneerPoint2DDepth.cpp, servoPioneerPoint2DDepthWithoutVpServo.cpp, servoViper650Point2DCamVelocity.cpp, servoViper850FourPoints2DArtVelocityLs_cur.cpp, servoViper850FourPoints2DCamVelocityLs_cur.cpp, servoViper850Point2DCamVelocity.cpp, servoViper850Point2DCamVelocityKalman.cpp, testTrackDot.cpp, tutorial-blob-auto-tracker.cpp, tutorial-blob-tracker-live-firewire.cpp, and tutorial-blob-tracker-live-v4l2.cpp.

Definition at line 318 of file vpDot2.h.

Referenced by defineDots().

◆ setGraphicsThickness()

void vpDot2::setGraphicsThickness ( unsigned int thickness )

inline

Modify the default thickness that is set to 1 of the drawings in overlay when setGraphics() is enabled.

See also: setGraphics()

Examples: tutorial-blob-auto-tracker.cpp, tutorial-blob-tracker-live-firewire.cpp, and tutorial-blob-tracker-live-v4l2.cpp.

Definition at line 326 of file vpDot2.h.

◆ setGrayLevelMax()

void vpDot2::setGrayLevelMax ( const unsigned int & max )

inline

Set the color level of pixels surrounding the dot. This is meant to be used to search a dot in a region of interest.

Parameters

max	: Intensity level of a dot to search in a region of interest.

See also: setGrayLevelMin(), setGrayLevelPrecision()

Examples: tutorial-blob-auto-tracker.cpp.

Definition at line 357 of file vpDot2.h.

◆ setGrayLevelMin()

void vpDot2::setGrayLevelMin ( const unsigned int & min )

inline

Set the color level of the dot to search a dot in a region of interest. This level will be used to know if a pixel in the image belongs to the dot or not. Only pixels with higher level can belong to the dot. If the level is lower than the minimum level for a dot, set the level to MIN_IN_LEVEL.

Parameters

min	: Color level of a dot to search in a region of interest.

See also: setGrayLevelMax(), setGrayLevelPrecision()

Examples: tutorial-blob-auto-tracker.cpp.

Definition at line 338 of file vpDot2.h.

◆ setGrayLevelPrecision()

void vpDot2::setGrayLevelPrecision ( const double & precision )

Set the precision of the gray level of the dot.

Parameters

precision

: It is a double precision float which value is in [0.05,1]:

1 means full precision, whereas values close to 0 show a very bad accuracy.
Values lower or equal to 0.05 are brought back to 0.05.
Values higher than 1 are brought back to 1 If the initial gray level is I, the gray levels of the dot will be between : $Imin=255*\big((\frac{I}{255})^{{\gamma}^{-1}}-(1-grayLevelPrecision)\big)^{\gamma}$ and $Imax=255*\big((\frac{I}{255})^{{\gamma}^{-1}}+(1-grayLevelPrecision)\big)^{\gamma}$ with $\gamma=1.5$ .

See also: setGrayLevelMin(), setGrayLevelMax()

Examples: AROgre.cpp, AROgreBasic.cpp, servoPioneerPanSegment3D.cpp, servoPioneerPoint2DDepth.cpp, servoPioneerPoint2DDepthWithoutVpServo.cpp, and tutorial-blob-auto-tracker.cpp.

Definition at line 726 of file vpDot2.cpp.

◆ setHeight()

void vpDot2::setHeight ( const double & h )

Set the height of the dot. This is meant to be used to search a dot in an area.

Parameters

h	: Height of a dot to search in a region of interest.

See also: setWidth(), setArea(), setSizePrecision()

Examples: tutorial-blob-auto-tracker.cpp.

Definition at line 695 of file vpDot2.cpp.

Referenced by initTracking(), and track().

◆ setMaxSizeSearchDistPrecision()

void vpDot2::setMaxSizeSearchDistPrecision ( const double & precision )

Set the precision of the search maximum distance to get the starting point on a dot border. A too low value mean a large search area.

Parameters

precision

: It is a double precision float which value is in [0.05,1]:

this is the limit ratio between the tested parameter and the measured one. distance < getWidth()/(getSizePrecision()+epsilon);
1 means full precision, whereas values close to 0 show a very bad accuracy.
Values lower or equal to 0.05 are brought back to 0.05
Values higher than 1 are brought back to 1.

Definition at line 830 of file vpDot2.cpp.

◆ setSizePrecision()

void vpDot2::setSizePrecision ( const double & precision )

Set the precision of the size of the dot. Used to test the validity of the dot

Parameters

precision

: It is a double precision float which value is in [0,1]:

this is the limit ratio between the tested parameter and the measured one. minSize = sizePrecision*originalSize ; maxSize = originalSize/sizePrecision ;
1 means full precision, whereas values close to 0 show a very bad accuracy.
Values lower or equal to 0 are brought back to 0.
Values higher than 1 are brought back to 1.
To desactivate validity test set sizePrecision to 0

See also: setWidth(), setHeight(), setArea()

Examples: AROgre.cpp, AROgreBasic.cpp, and tutorial-blob-auto-tracker.cpp.

Definition at line 756 of file vpDot2.cpp.

◆ setWidth()

void vpDot2::setWidth ( const double & w )

Set the width of the dot. This is meant to be used to search a dot in an area.

Parameters

w	: Width of a dot to search in a region of interest.

See also: setHeight(), setArea(), setSizePrecision()

Examples: tutorial-blob-auto-tracker.cpp.

Definition at line 683 of file vpDot2.cpp.

Referenced by initTracking(), and track().

◆ track() [1/2]

void vpDot2::track	(	const vpImage< unsigned char > &	I,
		bool	canMakeTheWindowGrow = `true`
	)

Try to locate the dot in the image:

First, estimate the new position of the dot, using its previous position.
Then compute the center of gravity (surface, width height) of the tracked entity from the Freeman chain elements.
If the dot is lost (estimated point too dark, too much surface change,...), search the dot in a window around the previous position.
If no valid dot was found in the window, return an exception.

Parameters

I	: Image.
canMakeTheWindowGrow	if true, the size of the searching area is increased if the blob is not found, otherwise it stays the same. Default value is true.

Exceptions

vpTrackingException::featureLostError

: If the dot tracking failed. The tracking can fail if the following characteristics are not valid;

The gray level is between gray level min and gray level max.
The size (width or height) and the surface (in terms of number of pixels) should not differ to much with the previous dot.
The shape should be ellipsoid if setEllipsoidShapePrecision(ellipsoidShapePrecision) is used. This is the default case. To track a non ellipsoid shape use setEllipsoidShapePrecision(0).

To get the center of gravity of the dot, call getCog(). To get the width or height of the dot, call getWidth() and getHeight(). The area of the dot is given by getArea().

To compute all the inertia moments associated to the dot see setComputeMoments().

To get the pixels coordinates on the dot boundary, see getList_u() and getList_v().

Definition at line 452 of file vpDot2.cpp.

References vpDisplay::displayCross(), vpTrackingException::featureLostError, vpImagePoint::get_u(), vpImagePoint::get_v(), getArea(), getCog(), getHeight(), getMeanGrayLevel(), getWidth(), vpColor::red, searchDotsInArea(), setArea(), setCog(), setHeight(), and setWidth().

Referenced by defineDots(), initTracking(), track(), and trackAndDisplay().

◆ track() [2/2]

void vpDot2::track	(	const vpImage< unsigned char > &	I,
		vpImagePoint &	ip,
		bool	canMakeTheWindowGrow = `true`
	)

Track and get the new dot coordinates. See track() for a more complete description

Parameters

[in]	I	: Image to process.
[out]	ip	: Sub pixel coordinate of the tracked dot center of gravity.
[in]	canMakeTheWindowGrow	: if true, the size of the searching area is increased if the blob is not found, otherwise it stays the same. Default value is true.

The behavior of this method is similar to the following code:

vpDot2 d;
d.track(I);
vpImagePoint cog = d.getCog();

See also: track()

Definition at line 599 of file vpDot2.cpp.

References track().

◆ trackAndDisplay()

void vpDot2::trackAndDisplay	(	vpDot2	dot[],
		const unsigned int &	n,
		vpImage< unsigned char > &	I,
		std::vector< vpImagePoint > &	cogs,
		vpImagePoint *	cogStar = `nullptr`
	)

static

Tracks a number of dots in an image and displays their trajectories

Parameters

dot	: dot2 array
n	: number of dots, array dimension
I	: image
cogs	: vector of vpImagePoint that will be updated with the new dots, will be displayed in green
cogStar	(optional) : array of vpImagePoint indicating the desired position (default nullptr), will be displayed in red

Definition at line 1823 of file vpDot2.cpp.

References vpColor::blue, vpDisplay::displayCircle(), vpDisplay::displayDotLine(), vpDisplay::flush(), getCog(), vpColor::green, vpColor::red, and track().

Friends And Related Function Documentation

◆ operator<<

VISP_EXPORT std::ostream& operator<<	(	std::ostream &	os,
		vpDot2 &	d
	)

friend

Writes the dot center of gravity coordinates in the frame (i,j) (For more details about the orientation of the frame see the vpImagePoint documentation) to the stream os, and returns a reference to the stream.

Definition at line 1914 of file vpDot2.cpp.

Member Data Documentation

◆ cP

vpColVector vpTracker::cP

inherited

Feature coordinates expressed in the camera frame cP.

Examples: testPoint.cpp.

Definition at line 73 of file vpTracker.h.

Referenced by vpFeaturePoint3D::buildFrom(), vpCircle::changeFrame(), vpCylinder::changeFrame(), vpLine::changeFrame(), vpPoint::changeFrame(), vpSphere::changeFrame(), vpFeatureBuilder::create(), vpPoint::get_W(), vpPoint::get_X(), vpPoint::get_Y(), vpPoint::get_Z(), vpCircle::init(), vpCylinder::init(), vpLine::init(), vpPoint::init(), vpSphere::init(), vpMbtPolygon::isVisible(), vpTracker::operator=(), vpForwardProjection::print(), vpPose::printPoint(), vpForwardProjection::project(), vpCircle::projection(), vpCylinder::projection(), vpLine::projection(), vpPoint::projection(), vpSphere::projection(), vpPoint::set_W(), vpPoint::set_X(), vpPoint::set_Y(), and vpPoint::set_Z().

◆ cPAvailable

bool vpTracker::cPAvailable

inherited

Flag used to indicate if the feature parameters cP expressed in the camera frame are available.

Definition at line 79 of file vpTracker.h.

Referenced by vpTracker::init(), and vpTracker::operator=().

◆ p

vpColVector vpTracker::p

inherited

Feature coordinates expressed in the image plane p. They correspond to 2D normalized coordinates expressed in meters.

Definition at line 69 of file vpTracker.h.

Referenced by vpMbtDistanceCircle::computeInteractionMatrixError(), vpCircle::computeIntersectionPoint(), vpMeterPixelConversion::convertEllipse(), vpFeatureBuilder::create(), vpCircle::display(), vpCylinder::display(), vpLine::display(), vpPoint::display(), vpSphere::display(), vpProjectionDisplay::display(), vpProjectionDisplay::displayCamera(), vpFeatureDisplay::displayEllipse(), vpPose::displayModel(), vpImageDraw::drawFrame(), vpPoint::get_w(), vpPoint::get_x(), vpPoint::get_y(), vpMeTracker::init(), vpCircle::init(), vpCylinder::init(), vpLine::init(), vpPoint::init(), vpSphere::init(), vpTracker::operator=(), vpForwardProjection::print(), vpPose::printPoint(), vpForwardProjection::project(), vpCircle::projection(), vpCylinder::projection(), vpLine::projection(), vpPoint::projection(), vpSphere::projection(), vpPoint::set_w(), vpPoint::set_x(), and vpPoint::set_y().

Public Member Functions

Static Public Member Functions

Public Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

◆ vpDot2() [1/3]

◆ vpDot2() [2/3]

◆ vpDot2() [3/3]

Member Function Documentation

◆ defineDots()

◆ display() [1/3]

◆ display() [2/3]

◆ display() [3/3]

◆ get_cP()

◆ get_nij()

◆ get_p()

◆ getArea()

◆ getBBox()

◆ getCog()

◆ getDistance()

◆ getEdges() [1/2]

◆ getEdges() [2/2]

◆ getEllipsoidBadPointsPercentage()

◆ getEllipsoidShapePrecision()

◆ getFreemanChain()

◆ getGamma()

◆ getGrayLevelMax()

◆ getGrayLevelMin()

◆ getGrayLevelPrecision()

◆ getHeight()

◆ getMaxSizeSearchDistPrecision()

◆ getMeanGrayLevel()

◆ getPolygon()

◆ getSizePrecision()

◆ getWidth()

◆ initTracking() [1/3]

◆ initTracking() [2/3]

◆ initTracking() [3/3]

◆ operator=()

◆ print()

◆ searchDotsInArea() [1/2]

◆ searchDotsInArea() [2/2]

◆ setArea()

◆ setCog()

◆ setComputeMoments()

◆ setEllipsoidBadPointsPercentage()

◆ setEllipsoidShapePrecision()

◆ setGraphics()

◆ setGraphicsThickness()

◆ setGrayLevelMax()

◆ setGrayLevelMin()

◆ setGrayLevelPrecision()

◆ setHeight()

◆ setMaxSizeSearchDistPrecision()

◆ setSizePrecision()

◆ setWidth()

◆ track() [1/2]

◆ track() [2/2]

◆ trackAndDisplay()

Friends And Related Function Documentation

◆ operator<<

Member Data Documentation

◆ cP

◆ cPAvailable

◆ p