MeEllipse¶

class MeEllipse(*args, **kwargs)¶

Bases: MeTracker

Class that tracks an ellipse using moving edges.

In this class, an ellipse is defined as the set of image points \((u,v)\) (for more information about the image frame see the vpImagePoint documentation) that satisfy the homogeneous equation:

\[K_0 u^2 + K_1 v^2 + 2K_2 u v + 2K_3 u + 2K_4 v + K5 = 0 \]

with \(K_0 = n_{02}\) , \(K_1 = n_{20}\) , \(K_2 = -n_{11}\) , etc. (see Eq. (25) of Chaumette TRO 2004 paper [5] )

If \(K_0 = K1\) and \(K_2 = 0\) , the ellipse is a circle.

The six parameters are stored in the private attribute K.

An ellipse is also represented thanks to five parameters that are the center \((uc,vc)\) of the ellipse and either:

three normalized moments \(n_{ij}\) of order 2,
or the semi major axis \(A\) , the semi minor axis \(B\) and the ellipse orientation \(E \in [-\pi/2;\pi/2]\) defined by the angle between the major axis and the u axis of the image frame.

For more details, see [5] . The following figure illustrates these parameters.

The example below available in tutorial-me-ellipse-tracker.cpp and described in tutorial-tracking-me, section tracking_me_ellipse shows how to use this class.

#include <visp3/core/vpConfig.h>
#ifdef VISP_HAVE_MODULE_SENSOR
#include <visp3/sensor/vp1394CMUGrabber.h>
#include <visp3/sensor/vp1394TwoGrabber.h>
#include <visp3/sensor/vpV4l2Grabber.h>
#endif
#include <visp3/gui/vpDisplayGDI.h>
#include <visp3/gui/vpDisplayOpenCV.h>
#include <visp3/gui/vpDisplayX.h>
#include <visp3/me/vpMeEllipse.h>

#if defined(HAVE_OPENCV_VIDEOIO)
#include <opencv2/videoio.hpp>
#endif

int main()
{
#if (defined(VISP_HAVE_DC1394) || defined(VISP_HAVE_CMU1394) || defined(VISP_HAVE_V4L2) || defined(HAVE_OPENCV_VIDEOIO))
#ifdef ENABLE_VISP_NAMESPACE
  using namespace VISP_NAMESPACE_NAME ;
#endif
  try {
    vpImage<unsigned char>  I;

#if defined(VISP_HAVE_DC1394)
    vp1394TwoGrabber  g(false);
#elif defined(VISP_HAVE_CMU1394)
    vp1394CMUGrabber  g;
#elif defined(VISP_HAVE_V4L2)
    vpV4l2Grabber  g;
#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;
#endif

#if defined(VISP_HAVE_DC1394) || defined(VISP_HAVE_V4L2) || defined(VISP_HAVE_CMU1394)
    g. acquire (I);
#elif defined(HAVE_OPENCV_VIDEOIO)
    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");
#else
    std::cout << "No image viewer is available..." << std::endl;
#endif

    vpDisplay::display (I);
    vpDisplay::flush (I);

    vpMe  me;
    me. setRange (25);
    me. setLikelihoodThresholdType ( vpMe::NORMALIZED_THRESHOLD );
    me. setThreshold (20);
    me. setSampleStep (10);

    vpMeEllipse  ellipse;
    ellipse. setMe (&me);
    ellipse. setDisplay ( vpMeSite::RANGE_RESULT );
    ellipse. initTracking (I);

    while (1) {
#if defined(VISP_HAVE_DC1394) || defined(VISP_HAVE_V4L2) || defined(VISP_HAVE_CMU1394)
      g. acquire (I);
#elif defined(HAVE_OPENCV_VIDEOIO)
      g >> frame;
      vpImageConvert::convert (frame, I);
#endif
      vpDisplay::display (I);
      ellipse. track (I);
      ellipse. display (I, vpColor::red );
      vpDisplay::flush (I);
    }
  }
  catch (const vpException  &e) {
    std::cout << "Catch an exception: " << e << std::endl;
  }
#endif
}

Overloaded function.

__init__(self: visp._visp.me.MeEllipse) -> None

Basic constructor that calls the constructor of the class vpMeTracker .

__init__(self: visp._visp.me.MeEllipse, me_ellipse: visp._visp.me.MeEllipse) -> None

Copy constructor.

Methods

`__init__`	Overloaded function.
`display`	Overloaded function.
`displayEllipse`	Overloaded function.
`getArea`	Gets the area of the ellipse corresponding also to the zero order moment of the ellipse.
`getCenter`	Gets the center of the ellipse.
`getExpectedDensity`	return: Expected number of moving edges to track along the ellipse.
`getFirstEndpoint`	Gets the first endpoint of the ellipse arc (corresponding to alpha1, not alphamin) when an arc is tracked.
`getHighestAngle`	Gets the highest \(alpha\) angle of the moving edges tracked \(\alpha_{max} \in [\alpha_min;\alpha_2]\) .
`getNumberOfGoodPoints`	return: Number of valid edges tracked along the ellipse.
`getSecondEndpoint`	Gets the second endpoint of the ellipse arc (corresponding to alpha2, not alphamax) when an arc is tracked.
`getSmallestAngle`	Gets the smallest \(alpha\) angle of the moving edges tracked \(\alpha_{min} \in [\alpha_1;\alpha_2]\) .
`get_ABE`	Gets the ellipse parameters as a 3-dim vector containing \(A, B, E\) .
`get_nij`	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}\)
`initTracking`	Overloaded function.
`printParameters`	Print the parameters \(K = {K_0, ..., K_5}\) , the coordinates of the ellipse center, the normalized moments, and the A, B, E parameters.
`setEndpoints`	Set the two endpoints of the ellipse arc when an arc is tracked.
`setThresholdRobust`	Set the threshold for the weights in the robust estimation of the ellipse parameters.
`track`	Overloaded function.

Inherited Methods

`cPAvailable`
`setInitRange`	Set the initial range.
`setMeList`	Set the list of moving edges.
`setDisplay`	Set type of moving-edges display.
`getNbPoints`	Return the number of points that has not been suppressed.
`get_cP`	Return object parameters expressed in the 3D camera frame.
`outOfImage`	Overloaded function.
`numberOfSignal`	Return number of moving-edges that are tracked.
`p`
`getInitRange`	Return the initial range.
`get_p`	Return object parameters expressed in the 2D image plane computed by perspective projection.
`reset`	Reset the tracker by removing all the moving edges.
`totalNumberOfSignal`	Return the total number of moving-edges.
`getMeList`	Overloaded function.
`cP`
`setMask`	Set the mask.
`init`	Initialize the tracker.

Operators

`__doc__`
`__init__`	Overloaded function.
`__module__`

Attributes

`__annotations__`
`cP`
`cPAvailable`
`p`

__init__(*args, **kwargs)¶

Overloaded function.

__init__(self: visp._visp.me.MeEllipse) -> None

Basic constructor that calls the constructor of the class vpMeTracker .

__init__(self: visp._visp.me.MeEllipse, me_ellipse: visp._visp.me.MeEllipse) -> None

Copy constructor.

display(*args, **kwargs)¶

Overloaded function.

display(self: visp._visp.me.MeEllipse, I: visp._visp.core.ImageGray, col: visp._visp.core.Color, thickness: int = 1) -> None

Display the ellipse or arc of ellipse

Warning

To effectively display the ellipse a call to vpDisplay::flush() is needed.

Parameters:

I: Image in which the ellipse appears.
col: Color of the displayed ellipse.
thickness: Thickness of the drawing.

display(self: visp._visp.me.MeTracker, I: visp._visp.core.ImageGray) -> None

Display the moving edge sites with a color corresponding to their state.

If green : The vpMeSite is a good point.
If blue : The point is removed because of the vpMeSite tracking phase (contrast problem).
If purple : The point is removed because of the vpMeSite tracking phase (threshold problem).
If red : The point is removed because of the robust method in the virtual visual servoing (M-Estimator problem).
If cyan : The point is removed because it’s too close to another.
Yellow otherwise.

Parameters:

I: The image.

display(self: visp._visp.me.MeTracker, I: visp._visp.core.ImageRGBa) -> None

Display the moving edge sites with a color corresponding to their state.

If green : The vpMeSite is a good point.
If blue : The point is removed because of the vpMeSite tracking phase (contrast problem).
If purple : The point is removed because of the vpMeSite tracking phase (threshold problem).
If red : The point is removed because of the robust method in the virtual visual servoing (M-Estimator problem).
If cyan : The point is removed because it’s too close to another.
Yellow otherwise.

Parameters:

I: The image.

static displayEllipse(*args, **kwargs)¶

Overloaded function.

displayEllipse(I: visp._visp.core.ImageGray, center: visp._visp.core.ImagePoint, A: float, B: float, E: float, smallalpha: float, highalpha: float, color: visp._visp.core.Color = vpColor::green, thickness: int = 1) -> None

Display the ellipse or the arc of ellipse thanks to the ellipse parameters.

Note

See vpDisplay::displayEllipse()

Parameters:

I: The image used as background.
center: Center of the ellipse.
A: Semi major axis of the ellipse.
B: Semi minor axis of the ellipse.
E: Angle made by the major axis and the u axis of the image frame \((u,v)\) (in rad).
smallalpha: Smallest \(alpha\) angle in rad (0 for a complete ellipse).
highalpha: Highest \(alpha\) angle in rad (2 \(\Pi\) for a complete ellipse).
color: Color used to display the ellipse.
thickness: Thickness of the drawings.

displayEllipse(I: visp._visp.core.ImageRGBa, center: visp._visp.core.ImagePoint, A: float, B: float, E: float, smallalpha: float, highalpha: float, color: visp._visp.core.Color = vpColor::green, thickness: int = 1) -> None

Display the ellipse or the arc of ellipse thanks to the ellipse parameters.

Note

See vpDisplay::displayEllipse()

Parameters:

I: The image used as background.
center: Center of the ellipse
A: Semi-major axis of the ellipse.
B: Semi-minor axis of the ellipse.
E: Angle made by the major axis and the u axis of the image frame \((u,v)\) (in rad)
smallalpha: Smallest \(alpha\) angle in rad (0 for a complete ellipse)
highalpha: Highest \(alpha\) angle in rad ( \(2 \Pi\) for a complete ellipse)
color: Color used to display th lines.
thickness: Thickness of the drawings.

getArea(self) → float¶

Gets the area of the ellipse corresponding also to the zero order moment of the ellipse.

Note

See getCenter() , get_nij() , get_ABE()

Returns:: The ellipse area.

getCenter(self) → visp._visp.core.ImagePoint¶: Gets the center of the ellipse.

Note

See get_nij() , get_ABE() , getArea()

getExpectedDensity(self) → int¶

Returns:: Expected number of moving edges to track along the ellipse.

getFirstEndpoint(self) → visp._visp.core.ImagePoint¶: Gets the first endpoint of the ellipse arc (corresponding to alpha1, not alphamin) when an arc is tracked.

Note

See getSecondEndpoint()

getHighestAngle(self) → float¶: Gets the highest \(alpha\) angle of the moving edges tracked \(\alpha_{max} \in [\alpha_min;\alpha_2]\) .

Note

See getSmallestAngle()

getInitRange(self) → int¶

Return the initial range.

Returns:: Value of init_range.

getMeList(*args, **kwargs)¶

Overloaded function.

getMeList(self: visp._visp.me.MeTracker) -> list[visp._visp.me.MeSite]

Return the list of moving edges

Returns:: List of Moving Edges.

getMeList(self: visp._visp.me.MeTracker) -> list[visp._visp.me.MeSite]

Return the list of moving edges

Returns:: List of Moving Edges.

getNbPoints(self) → int¶

Return the number of points that has not been suppressed.

Returns:: Number of good points.

getNumberOfGoodPoints(self) → int¶

Returns:: Number of valid edges tracked along the ellipse.

getSecondEndpoint(self) → visp._visp.core.ImagePoint¶: Gets the second endpoint of the ellipse arc (corresponding to alpha2, not alphamax) when an arc is tracked.

Note

See getFirstEndpoint()

getSmallestAngle(self) → float¶: Gets the smallest \(alpha\) angle of the moving edges tracked \(\alpha_{min} \in [\alpha_1;\alpha_2]\) .

Note

See getHighestAngle()

get_ABE(self) → visp._visp.core.ColVector¶

Gets the ellipse parameters as a 3-dim vector containing \(A, B, E\) .

Note

See getCenter() , get_nij() , getArea()

Returns:: The 3-dim vector containing \(A, B, E\) corresponding respectively to the semi major axis, the semi minor axis and the angle in rad made by the major axis and the u axis of the image frame \((u,v)\) , \(e \in [-\pi/2;pi/2]\) .

get_cP(self) → visp._visp.core.ColVector¶: Return object parameters expressed in the 3D camera frame.

get_nij(self) → visp._visp.core.ColVector¶

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}\)

Note

See getCenter() , get_ABE() , getArea()

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

get_p(self) → visp._visp.core.ColVector¶: Return object parameters expressed in the 2D image plane computed by perspective projection.

init(self) → None¶: Initialize the tracker.

initTracking(*args, **kwargs)¶

Overloaded function.

initTracking(self: visp._visp.me.MeEllipse, I: visp._visp.core.ImageGray, trackCircle: bool = false, trackArc: bool = false) -> None

Initialize the tracking of an ellipse or an arc of an ellipse when trackArc is set to true. Ask the user to click on five points located on the ellipse to be tracked.

Warning

The points should be selected as far as possible from each other. When an arc of an ellipse is tracked, it is recommended to select the 5 points clockwise.

Parameters:

I: Image in which the ellipse appears.
trackCircle: When true, track a circle, when false track an ellipse.
trackArc: When true track an arc of the ellipse/circle. In that case, first and last points specify the extremities of the arc (clockwise). When false track the complete ellipse/circle.

initTracking(self: visp._visp.me.MeEllipse, I: visp._visp.core.ImageGray, opt_ips: Optional[list[visp._visp.core.ImagePoint]], trackCircle: bool = false, trackArc: bool = false) -> None

Initialize the tracking of an ellipse or an arc of an ellipse when trackArc is set to true. If ips is set, use the contained points to initialize the ME if there are some, or initialize by clicks the ME and ips will contained the clicked points. If ips is not set, call the method vpMeEllipse::initTracking(const vpImage<unsigned char>&, bool, bool) .

Note

See vpMeEllipse::initTracking()

Warning

The points should be selected as far as possible from each other. When an arc of an ellipse is tracked, it is recommended to select the 5 points clockwise.

Parameters:

I: Image in which the ellipse appears.
opt_ips: If set, either a vector that contains the vpImagePoint to use or will be filled with the clicked points.
trackCircle: When true, track a circle, when false track an ellipse.
trackArc: When true track an arc of the ellipse/circle. In that case, first and last points specify the extremities of the arc (clockwise). When false track the complete ellipse/circle.

initTracking(self: visp._visp.me.MeEllipse, I: visp._visp.core.ImageGray, iP: list[visp._visp.core.ImagePoint], trackCircle: bool = false, trackArc: bool = false) -> None

Initialize the tracking of an ellipse/circle or an arc of an ellipse/circle when trackArc is set to true. The ellipse/circle is defined thanks to a vector of image points.

Warning

It is mandatory to use at least five image points to estimate the ellipse parameters while three points are needed to estimate the circle parameters.

Warning

The image points should be selected as far as possible from each other. When an arc of an ellipse/circle is tracked, it is recommended to select the 5/3 points clockwise.

Parameters:

I: Image in which the ellipse/circle appears.
iP: A vector of image points belonging to the ellipse/circle edge used to initialize the tracking.
trackCircle: When true, track a circle, when false track an ellipse.
trackArc: When true track an arc of the ellipse/circle. In that case, first and last points specify the extremities of the arc (clockwise). When false track the complete ellipse/circle.

initTracking(self: visp._visp.me.MeTracker, I: visp._visp.core.ImageGray) -> None

Virtual function that is called by lower classes vpMeEllipse , vpMeLine and vpMeNurbs .

numberOfSignal(self) → int¶: Return number of moving-edges that are tracked.

outOfImage(*args, **kwargs)¶

Overloaded function.

outOfImage(self: visp._visp.me.MeTracker, i: int, j: int, border: int, nrows: int, ncols: int) -> bool

Parameters:

i: Pixel coordinates.
j: Pixel coordinates.
border: Number of pixels along the image border to exclude. When border is set to 0, consider the complete image.
nrows: Size of the image.
ncols: Size of the image.

Returns:

true when the pixel is inside the image minus the border size, false otherwise.

outOfImage(self: visp._visp.me.MeTracker, iP: visp._visp.core.ImagePoint, border: int, nrows: int, ncols: int) -> bool

Parameters:

iP: Pixel coordinates.
border: Number of pixels along the image border to exclude. When border is set to 0, consider the complete image.
nrows: Size of the image.
ncols: Size of the image.

Returns:

true when the pixel is inside the image minus the border size, false otherwise.

printParameters(self) → None¶: Print the parameters \(K = {K_0, ..., K_5}\) , the coordinates of the ellipse center, the normalized moments, and the A, B, E parameters.

reset(self) → None¶: Reset the tracker by removing all the moving edges.

setDisplay(self, select: visp._visp.me.MeSite.MeSiteDisplayType) → None¶

Set type of moving-edges display.

Parameters:

select: visp._visp.me.MeSite.MeSiteDisplayType¶: Display type selector.

setEndpoints(self, pt1: visp._visp.core.ImagePoint, pt2: visp._visp.core.ImagePoint) → None¶: Set the two endpoints of the ellipse arc when an arc is tracked.

setInitRange(self, r: int) → None¶

Set the initial range.

Parameters:

r: int¶: initial range.

setMask(self: visp._visp.me.MeTracker, mask: vpImage<bool>) → None¶

Set the mask.

Parameters:

mask: Mask.

setMeList(self, meList: list[visp._visp.me.MeSite]) → None¶

Set the list of moving edges.

Parameters:

meList: list[visp._visp.me.MeSite]¶: List of Moving Edges.

setThresholdRobust(self, threshold: float) → None¶

Set the threshold for the weights in the robust estimation of the ellipse parameters. If the weight of a point is below this threshold, this one is removed from the list of tracked meSite. Value must be between 0 (never rejected) and 1 (always rejected).

Parameters:

threshold: float¶: The new value of the threshold.

totalNumberOfSignal(self) → int¶: Return the total number of moving-edges.

track(*args, **kwargs)¶

Overloaded function.

track(self: visp._visp.me.MeEllipse, I: visp._visp.core.ImageGray) -> None

Track a set of MEs along an ellipse or a circle. The number of valid tracked MEs is obtained from getNumberOfGoodPoints() .

Track the ellipse in the image I.

Parameters:

I: Image in which the ellipse appears.

track(self: visp._visp.me.MeTracker, I: visp._visp.core.ImageGray) -> None

Track moving-edges.

Parameters:

I: Image.