Visual Servoing Platform  version 3.0.1
 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Friends Groups Pages
vpDot2 Class Reference

#include <visp3/blob/vpDot2.h>

+ Inheritance diagram for vpDot2:

Public Member Functions

 vpDot2 ()
 
 vpDot2 (const vpImagePoint &ip)
 
 vpDot2 (const vpDot2 &twinDot)
 
virtual ~vpDot2 ()
 
void display (const vpImage< unsigned char > &I, vpColor color=vpColor::red, unsigned int thickness=1) 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< vpImagePointgetEdges () 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 getMaxSizeSearchDistancePrecision () 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)
 
vpDot2operator= (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 (const bool activate)
 
void setEllipsoidBadPointsPercentage (const double &percentage=0.0)
 
void setEllipsoidShapePrecision (const double &ellipsoidShapePrecision)
 
void setGraphics (const bool activate)
 
void setGraphicsThickness (unsigned int t)
 
void setGrayLevelMin (const unsigned int &min)
 
void setGrayLevelMax (const unsigned int &max)
 
void setGrayLevelPrecision (const double &grayLevelPrecision)
 
void setHeight (const double &height)
 
void setMaxSizeSearchDistancePrecision (const double &maxSizeSearchDistancePrecision)
 
void setSizePrecision (const double &sizePrecision)
 
void setWidth (const double &width)
 
void track (const vpImage< unsigned char > &I)
 
void track (const vpImage< unsigned char > &I, vpImagePoint &cog)
 

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=NULL)
 
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

double m00
 
double m10
 
double m01
 
double m11
 
double m20
 
double m02
 
double mu11
 
double mu20
 
double mu02
 
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 binarisation of the image and then on a contour detection using the Freeman chain coding to determine the blob characteristics (location, moments, size...).

The binarisation 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 ellpsoid 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/gui/vpDisplayGDI.h>
#include <visp3/gui/vpDisplayOpenCV.h>
#include <visp3/gui/vpDisplayX.h>
#include <visp3/blob/vpDot2.h>
int main()
{
#if (defined(VISP_HAVE_DC1394) || defined(VISP_HAVE_CMU1394) || (VISP_HAVE_OPENCV_VERSION >= 0x020100)) && (defined(VISP_HAVE_X11) || defined(VISP_HAVE_GDI) || defined(VISP_HAVE_OPENCV))
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)
g.open(I);
#elif defined(VISP_HAVE_OPENCV)
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 -1;
}
cv::Mat frame;
g >> frame; // get a new frame from camera
#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(VISP_HAVE_OPENCV)
vpDisplayOpenCV d(I, 0, 0, "Camera view");
#endif
vpDot2 blob;
blob.setGraphics(true);
bool init_done = false;
while(1) {
try {
#if defined(VISP_HAVE_DC1394) || defined(VISP_HAVE_CMU1394)
g.acquire(I);
#elif defined(VISP_HAVE_OPENCV)
g >> frame;
#endif
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);
}
}
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/gui/vpDisplayGDI.h>
#include <visp3/gui/vpDisplayOpenCV.h>
#include <visp3/gui/vpDisplayX.h>
#include <visp3/blob/vpDot2.h>
#include <visp3/io/vpImageIo.h>
int main()
{
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(VISP_HAVE_OPENCV)
vpDisplayOpenCV d(I, 0, 0, "Camera view");
#else
std::cout << "No image viewer is available..." << std::endl;
#endif
vpDot2 blob;
if (learn) {
// Learn the characteristics of the blob to auto detect
blob.setGraphics(true);
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.setSizePrecision(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) {
for(std::list<vpDot2>::iterator it=blob_list.begin(); it != blob_list.end(); ++it) {
(*it).setGraphics(true);
(*it).setGraphicsThickness(3);
(*it).track(I);
}
if (vpDisplay::getClick(I, false))
break;
}
}
catch(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, servoAfma6FourPoints2DCamVelocityInteractionCurrent.cpp, servoAfma6FourPoints2DCamVelocityInteractionDesired.cpp, servoPioneerPanSegment3D.cpp, servoPioneerPoint2DDepth.cpp, servoPioneerPoint2DDepthWithoutVpServo.cpp, servoPtu46Point2DArtVelocity.cpp, servoViper650FourPoints2DArtVelocityInteractionCurrent.cpp, servoViper650FourPoints2DCamVelocityInteractionCurrent.cpp, servoViper650Point2DCamVelocity.cpp, servoViper850FourPoints2DArtVelocityInteractionCurrent.cpp, servoViper850FourPoints2DCamVelocityInteractionCurrent.cpp, servoViper850FourPointsKinect.cpp, servoViper850Point2DArtVelocity-jointAvoidance-basic.cpp, servoViper850Point2DArtVelocity-jointAvoidance-gpa.cpp, servoViper850Point2DArtVelocity-jointAvoidance-large.cpp, servoViper850Point2DArtVelocity.cpp, servoViper850Point2DCamVelocity.cpp, servoViper850Point2DCamVelocityKalman.cpp, testTrackDot.cpp, trackDot2.cpp, trackDot2WithAutoDetection.cpp, tutorial-blob-auto-tracker.cpp, tutorial-blob-tracker-live-firewire.cpp, and tutorial-blob-tracker-live-v4l2.cpp.

Definition at line 125 of file vpDot2.h.

Constructor & Destructor Documentation

vpDot2::vpDot2 ( )

Default constructor. Just do basic default initialization.

Definition at line 104 of file vpDot2.cpp.

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 123 of file vpDot2.cpp.

vpDot2::vpDot2 ( const vpDot2 twinDot)

Copy constructor.

Definition at line 138 of file vpDot2.cpp.

vpDot2::~vpDot2 ( )
virtual

Destructor... do nothing for the moment.

Definition at line 204 of file vpDot2.cpp.

Member Function Documentation

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 2436 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().

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 219 of file vpDot2.cpp.

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

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 2581 of file vpDot2.cpp.

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

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 2608 of file vpDot2.cpp.

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

double vpDot2::getArea ( ) const

Return the area of the dot.

The area of the dot is also given by $|m00|$.

Examples:
trackDot2.cpp, trackDot2WithAutoDetection.cpp, and tutorial-blob-auto-tracker.cpp.

Definition at line 663 of file vpDot2.cpp.

Referenced by track().

vpRect vpDot2::getBBox ( ) const
inline

Return the dot bounding box.

See Also
getWidth(), getHeight()

Definition at line 146 of file vpDot2.h.

References vpRect::setRect().

double vpDot2::getDistance ( const vpDot2 distantDot) const

Return the distance between the two center of dots.

Definition at line 712 of file vpDot2.cpp.

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

Referenced by defineDots().

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().
Examples:
trackDot2.cpp.

Definition at line 175 of file vpDot2.h.

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 187 of file vpDot2.h.

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 ouside ellipses.

See Also
setEllipsoidBadPointsPercentage()

Definition at line 196 of file vpDot2.h.

double vpDot2::getEllipsoidShapePrecision ( ) const

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

See Also
setEllipsoidShapePrecision()
Examples:
trackDot2WithAutoDetection.cpp, and tutorial-blob-auto-tracker.cpp.

Definition at line 695 of file vpDot2.cpp.

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

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

Returns
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 1631 of file vpDot2.cpp.

double vpDot2::getGamma ( ) const
inline

Definition at line 204 of file vpDot2.h.

unsigned int vpDot2::getGrayLevelMax ( ) const
inline

Return the color level of pixels inside the dot.

See Also
getGrayLevelMin()
Examples:
trackDot2.cpp, trackDot2WithAutoDetection.cpp, and tutorial-blob-auto-tracker.cpp.

Definition at line 218 of file vpDot2.h.

Referenced by searchDotsInArea().

unsigned int vpDot2::getGrayLevelMin ( ) const
inline

Return the color level of pixels inside the dot.

See Also
getGrayLevelMax()
Examples:
trackDot2.cpp, trackDot2WithAutoDetection.cpp, and tutorial-blob-auto-tracker.cpp.

Definition at line 210 of file vpDot2.h.

Referenced by searchDotsInArea().

double vpDot2::getGrayLevelPrecision ( ) const

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

Examples:
trackDot2.cpp, trackDot2WithAutoDetection.cpp, and tutorial-blob-auto-tracker.cpp.

Definition at line 673 of file vpDot2.cpp.

Referenced by searchDotsInArea().

double vpDot2::getHeight ( ) const

Return the height of the dot.

See Also
getWidth()
Examples:
trackDot2.cpp, trackDot2WithAutoDetection.cpp, and tutorial-blob-auto-tracker.cpp.

Definition at line 653 of file vpDot2.cpp.

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

double vpDot2::getMaxSizeSearchDistancePrecision ( ) const

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

Definition at line 705 of file vpDot2.cpp.

double vpDot2::getMeanGrayLevel ( ) const
inline
Returns
The mean gray level value of the dot.

Definition at line 228 of file vpDot2.h.

Referenced by track().

vpPolygon vpDot2::getPolygon ( ) const
inline
Returns
a vpPolygon made from the edges of the dot.

Definition at line 234 of file vpDot2.h.

double vpDot2::getSizePrecision ( ) const

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

Examples:
trackDot2.cpp, trackDot2WithAutoDetection.cpp, and tutorial-blob-auto-tracker.cpp.

Definition at line 683 of file vpDot2.cpp.

Referenced by searchDotsInArea().

double vpDot2::getWidth ( ) const

Return the width of the dot.

See Also
getHeight()
Examples:
trackDot2.cpp, trackDot2WithAutoDetection.cpp, and tutorial-blob-auto-tracker.cpp.

Definition at line 643 of file vpDot2.cpp.

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

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()
Examples:
AROgre.cpp, AROgreBasic.cpp, manSimu4Dots.cpp, servoAfma4Point2DCamVelocityKalman.cpp, servoAfma6FourPoints2DCamVelocityInteractionCurrent.cpp, servoAfma6FourPoints2DCamVelocityInteractionDesired.cpp, servoPioneerPanSegment3D.cpp, servoPioneerPoint2DDepth.cpp, servoPioneerPoint2DDepthWithoutVpServo.cpp, servoViper650FourPoints2DArtVelocityInteractionCurrent.cpp, servoViper650FourPoints2DCamVelocityInteractionCurrent.cpp, servoViper650Point2DCamVelocity.cpp, servoViper850FourPoints2DArtVelocityInteractionCurrent.cpp, servoViper850FourPoints2DCamVelocityInteractionCurrent.cpp, servoViper850FourPointsKinect.cpp, servoViper850Point2DArtVelocity-jointAvoidance-basic.cpp, servoViper850Point2DArtVelocity-jointAvoidance-gpa.cpp, servoViper850Point2DArtVelocity-jointAvoidance-large.cpp, servoViper850Point2DArtVelocity.cpp, servoViper850Point2DCamVelocity.cpp, servoViper850Point2DCamVelocityKalman.cpp, testTrackDot.cpp, trackDot2.cpp, trackDot2WithAutoDetection.cpp, tutorial-blob-auto-tracker.cpp, tutorial-blob-tracker-live-firewire.cpp, and tutorial-blob-tracker-live-v4l2.cpp.

Definition at line 262 of file vpDot2.cpp.

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

Referenced by defineDots().

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 323 of file vpDot2.cpp.

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

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().

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

= operator.

Definition at line 154 of file vpDot2.cpp.

References m00, m01, m02, m10, m11, m20, mu02, mu11, and mu20.

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

Definition at line 250 of file vpDot2.h.

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.
niceDotsList 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:
trackDot2WithAutoDetection.cpp, and tutorial-blob-auto-tracker.cpp.

Definition at line 1040 of file vpDot2.cpp.

References vpColor::blue, vpDisplay::displayRectangle(), vpDisplay::flush(), vpImagePoint::get_u(), vpImagePoint::get_v(), vpRect::getBottom(), getCog(), getGrayLevelMax(), getGrayLevelMin(), getGrayLevelPrecision(), getHeight(), vpRect::getLeft(), vpRect::getRight(), getSizePrecision(), vpRect::getTop(), getWidth(), vpMath::maximum(), vpImagePoint::set_u(), vpImagePoint::set_v(), setArea(), setCog(), setComputeMoments(), setEllipsoidBadPointsPercentage(), setEllipsoidShapePrecision(), setGraphics(), setGraphicsThickness(), setGrayLevelMax(), setGrayLevelMin(), setGrayLevelPrecision(), setSizePrecision(), and vpTRACE.

Referenced by searchDotsInArea(), and track().

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.
niceDotsList of the dots that are found.

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

// Set dot characteristics for the auto detection
d.setWidth(24);
d.setHeight(23);
d.setArea(412);

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 1014 of file vpDot2.cpp.

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

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:
trackDot2WithAutoDetection.cpp, and tutorial-blob-auto-tracker.cpp.

Definition at line 762 of file vpDot2.cpp.

Referenced by searchDotsInArea(), and track().

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(), searchDotsInArea(), and track().

void vpDot2::setComputeMoments ( const bool  activate)
inline

Activates the dot's moments computation.

Parameters
activatetrue, 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.

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, testTrackDot.cpp, and trackDot2.cpp.

Definition at line 278 of file vpDot2.h.

Referenced by searchDotsInArea().

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 ouside 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 292 of file vpDot2.h.

Referenced by searchDotsInArea().

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, trackDot2WithAutoDetection.cpp, and tutorial-blob-auto-tracker.cpp.

Definition at line 858 of file vpDot2.cpp.

Referenced by searchDotsInArea().

void vpDot2::setGraphicsThickness ( unsigned int  t)
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 322 of file vpDot2.h.

Referenced by searchDotsInArea().

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:
trackDot2WithAutoDetection.cpp, and tutorial-blob-auto-tracker.cpp.

Definition at line 351 of file vpDot2.h.

Referenced by searchDotsInArea().

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:
trackDot2WithAutoDetection.cpp, and tutorial-blob-auto-tracker.cpp.

Definition at line 335 of file vpDot2.h.

Referenced by searchDotsInArea().

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,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 an epsilon>0
  • 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, trackDot2.cpp, trackDot2WithAutoDetection.cpp, and tutorial-blob-auto-tracker.cpp.

Definition at line 783 of file vpDot2.cpp.

Referenced by searchDotsInArea().

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:
trackDot2WithAutoDetection.cpp, and tutorial-blob-auto-tracker.cpp.

Definition at line 748 of file vpDot2.cpp.

Referenced by initTracking(), and track().

void vpDot2::setMaxSizeSearchDistancePrecision ( 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 887 of file vpDot2.cpp.

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, trackDot2WithAutoDetection.cpp, and tutorial-blob-auto-tracker.cpp.

Definition at line 813 of file vpDot2.cpp.

Referenced by searchDotsInArea().

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:
trackDot2WithAutoDetection.cpp, and tutorial-blob-auto-tracker.cpp.

Definition at line 733 of file vpDot2.cpp.

Referenced by initTracking(), and track().

void vpDot2::track ( const vpImage< unsigned char > &  I)

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.
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().

Examples:
AROgre.cpp, AROgreBasic.cpp, manSimu4Dots.cpp, servoAfma4Point2DCamVelocityKalman.cpp, servoAfma6FourPoints2DCamVelocityInteractionCurrent.cpp, servoAfma6FourPoints2DCamVelocityInteractionDesired.cpp, servoPioneerPoint2DDepth.cpp, servoPioneerPoint2DDepthWithoutVpServo.cpp, servoPtu46Point2DArtVelocity.cpp, servoViper650FourPoints2DArtVelocityInteractionCurrent.cpp, servoViper650FourPoints2DCamVelocityInteractionCurrent.cpp, servoViper650Point2DCamVelocity.cpp, servoViper850FourPoints2DArtVelocityInteractionCurrent.cpp, servoViper850FourPoints2DCamVelocityInteractionCurrent.cpp, servoViper850FourPointsKinect.cpp, servoViper850Point2DArtVelocity-jointAvoidance-basic.cpp, servoViper850Point2DArtVelocity-jointAvoidance-gpa.cpp, servoViper850Point2DArtVelocity-jointAvoidance-large.cpp, servoViper850Point2DArtVelocity.cpp, servoViper850Point2DCamVelocity.cpp, servoViper850Point2DCamVelocityKalman.cpp, testTrackDot.cpp, trackDot2.cpp, tutorial-blob-auto-tracker.cpp, tutorial-blob-tracker-live-firewire.cpp, and tutorial-blob-tracker-live-v4l2.cpp.

Definition at line 461 of file vpDot2.cpp.

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

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

void vpDot2::track ( const vpImage< unsigned char > &  I,
vpImagePoint ip 
)

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

Parameters
I: Image to process.
ip[out] : Sub pixel coordinate of the tracked dot center of gravity.

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

d.track(I);
vpImagePoint cog = d.getCog();
See Also
track()

Definition at line 629 of file vpDot2.cpp.

References track().

void vpDot2::trackAndDisplay ( vpDot2  dot[],
const unsigned int &  n,
vpImage< unsigned char > &  I,
std::vector< vpImagePoint > &  cogs,
vpImagePoint cogStar = NULL 
)
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 NULL), will be displayed in red

Definition at line 2542 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

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 2626 of file vpDot2.cpp.

Member Data Documentation

bool vpTracker::cPAvailable
inherited

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

Definition at line 83 of file vpTracker.h.

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

double vpDot2::m00

Considering the general distribution moments for $ N $ points defined by the relation $ m_{ij} = \sum_{h=0}^{N} u_h^i v_h^j $, $ m_{00} $ is a zero order moment obtained with $i = j = 0 $. This moment corresponds to the dot surface.

See Also
setComputeMoments()
Examples:
servoPioneerPoint2DDepth.cpp, servoPioneerPoint2DDepthWithoutVpServo.cpp, and trackDot2.cpp.

Definition at line 370 of file vpDot2.h.

Referenced by vpFeatureBuilder::create(), operator=(), and track().

double vpDot2::m01

Considering the general distribution moments for $ N $ points defined by the relation $ m_{ij} = \sum_{h=0}^{N} u_h^i v_h^j $, $ m_{01} $ is a first order moment obtained with $i = 0 $ and $ j = 1 $. $ m_{01} $ corresponds to the inertia first order moment along the u axis.

See Also
setComputeMoments()
Examples:
trackDot2.cpp.

Definition at line 386 of file vpDot2.h.

Referenced by vpFeatureBuilder::create(), operator=(), and track().

double vpDot2::m02

Considering the general distribution moments for $ N $ points defined by the relation $ m_{ij} = \sum_{h=0}^{N} u_h^i v_h^j $, $ m_{02} $ is a second order moment obtained with $i = 0 $ and $ j = 2 $. $ m_{02} $ corresponds to the inertia second order moment along the u axis.

See Also
setComputeMoments()
Examples:
trackDot2.cpp.

Definition at line 410 of file vpDot2.h.

Referenced by vpFeatureBuilder::create(), operator=(), and track().

double vpDot2::m10

Considering the general distribution moments for $ N $ points defined by the relation $ m_{ij} = \sum_{h=0}^{N} u_h^i v_h^j $, $ m_{10} $ is a first order moment obtained with $i = 1 $ and $ j = 0 $. $ m_{10} $ corresponds to the inertia first order moment along the v axis.

See Also
setComputeMoments()
Examples:
trackDot2.cpp.

Definition at line 378 of file vpDot2.h.

Referenced by vpFeatureBuilder::create(), operator=(), and track().

double vpDot2::m11

Considering the general distribution moments for $ N $ points defined by the relation $ m_{ij} = \sum_{h=0}^{N} u_h^i v_h^j $, $ m_{11} $ is a first order moment obtained with $i = 1 $ and $ j = 1 $.

See Also
setComputeMoments()
Examples:
trackDot2.cpp.

Definition at line 394 of file vpDot2.h.

Referenced by vpFeatureBuilder::create(), operator=(), and track().

double vpDot2::m20

Considering the general distribution moments for $ N $ points defined by the relation $ m_{ij} = \sum_{h=0}^{N} u_h^i v_h^j $, $ m_{20} $ is a second order moment obtained with $i = 2 $ and $ j = 0 $. $ m_{20} $ corresponds to the inertia second order moment along the v axis.

See Also
setComputeMoments()
Examples:
trackDot2.cpp.

Definition at line 401 of file vpDot2.h.

Referenced by vpFeatureBuilder::create(), operator=(), and track().

double vpDot2::mu02

$ \mu_{02} $ is a second order central moments defined by: $ \mu_{02} = m_{02} - \frac{m_{01}}{m_{00}}m_{01} $

See Also
setComputeMoments()
Examples:
trackDot2.cpp.

Definition at line 429 of file vpDot2.h.

Referenced by operator=().

double vpDot2::mu11

$ \mu_{11} $ is a second order central moments defined by: $ \mu_{11} = m_{11} - \frac{m_{10}}{m_{00}}m_{01} $

See Also
setComputeMoments()
Examples:
trackDot2.cpp.

Definition at line 419 of file vpDot2.h.

Referenced by operator=().

double vpDot2::mu20

$ \mu_{20} $ is a second order central moments defined by: $ \mu_{20} = m_{20} - \frac{m_{10}}{m_{00}}m_{10} $

See Also
setComputeMoments()
Examples:
trackDot2.cpp.

Definition at line 424 of file vpDot2.h.

Referenced by operator=().