Visual Servoing Platform  version 3.6.1 under development (2024-10-10)

#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< 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 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)
 
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 (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)
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
#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);
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;
#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
}
Firewire cameras video capture based on CMU 1394 Digital Camera SDK.
void acquire(vpImage< unsigned char > &I)
void open(vpImage< unsigned char > &I)
Class for firewire ieee1394 video devices using libdc1394-2.x api.
static const vpColor red
Definition: vpColor.h:217
Display for windows using GDI (available on any windows 32 platform).
Definition: vpDisplayGDI.h:130
The vpDisplayOpenCV allows to display image using the OpenCV library. Thus to enable this class OpenC...
static bool getClick(const vpImage< unsigned char > &I, bool blocking=true)
static void display(const vpImage< unsigned char > &I)
static void flush(const vpImage< unsigned char > &I)
static void displayText(const vpImage< unsigned char > &I, const vpImagePoint &ip, const std::string &s, const vpColor &color)
This tracker is meant to track a blob (connex pixels with same gray level) on a vpImage.
Definition: vpDot2.h:125
void track(const vpImage< unsigned char > &I, bool canMakeTheWindowGrow=true)
Definition: vpDot2.cpp:452
void setGraphics(bool activate)
Definition: vpDot2.h:318
void setGraphicsThickness(unsigned int thickness)
Definition: vpDot2.h:326
void initTracking(const vpImage< unsigned char > &I, unsigned int size=0)
Definition: vpDot2.cpp:269
static void convert(const vpImage< unsigned char > &src, vpImage< vpRGBa > &dest)
Class that defines a 2D point in an image. This class is useful for image processing and stores only ...
Definition: vpImagePoint.h:82

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
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 (const vpException &e) {
std::cout << "Catch an exception: " << e << std::endl;
}
}
unsigned int getGrayLevelMin() const
Definition: vpDot2.h:219
unsigned int getGrayLevelMax() const
Definition: vpDot2.h:225
double getEllipsoidShapePrecision() const
Definition: vpDot2.cpp:651
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 setGrayLevelMax(const unsigned int &max)
Definition: vpDot2.h:357
double getArea() const
Definition: vpDot2.cpp:628
void setSizePrecision(const double &sizePrecision)
Definition: vpDot2.cpp:756
void setGrayLevelPrecision(const double &grayLevelPrecision)
Definition: vpDot2.cpp:726
void setGrayLevelMin(const unsigned int &min)
Definition: vpDot2.h:338
void setHeight(const double &height)
Definition: vpDot2.cpp:695
double getSizePrecision() const
Definition: vpDot2.cpp:642
double getGrayLevelPrecision() const
Definition: vpDot2.cpp:635
void setWidth(const double &width)
Definition: vpDot2.cpp:683
double getWidth() const
Definition: vpDot2.cpp:614
void setEllipsoidShapePrecision(const double &ellipsoidShapePrecision)
Definition: vpDot2.cpp:801
void setArea(const double &area)
Definition: vpDot2.cpp:707
double getHeight() const
Definition: vpDot2.cpp:621
error that can be emitted by ViSP classes.
Definition: vpException.h:60
static void read(vpImage< unsigned char > &I, const std::string &filename, int backend=IO_DEFAULT_BACKEND)
Definition: vpImageIo.cpp:147
unsigned int getWidth() const
Definition: vpImage.h:242
unsigned int getHeight() const
Definition: vpImage.h:181
VISP_EXPORT int wait(double t0, double t)

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 $|m00|$.

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

◆ 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()
Examples
AROgre.cpp, AROgreBasic.cpp, manSimu4Dots.cpp, servoAfma4Point2DCamVelocityKalman.cpp, servoPioneerPanSegment3D.cpp, servoPioneerPoint2DDepth.cpp, servoPioneerPoint2DDepthWithoutVpServo.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, tutorial-blob-auto-tracker.cpp, tutorial-blob-tracker-live-firewire.cpp, and tutorial-blob-tracker-live-v4l2.cpp.

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.
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
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.
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);
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
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 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
activateIf 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.
canMakeTheWindowGrowif 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().

Examples
AROgre.cpp, AROgreBasic.cpp, manSimu4Dots.cpp, servoAfma4Point2DCamVelocityKalman.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, tutorial-blob-auto-tracker.cpp, tutorial-blob-tracker-live-firewire.cpp, and tutorial-blob-tracker-live-v4l2.cpp.

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:

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

◆ 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