Visual Servoing Platform  version 3.6.1 under development (2024-04-20)
vpCircle Class Reference

#include <visp3/core/vpCircle.h>

+ Inheritance diagram for vpCircle:

Public Types

enum  vpForwardProjectionDeallocatorType { user , vpDisplayForwardProjection }
 

Public Member Functions

 vpCircle ()
 
 vpCircle (const vpColVector &oP)
 
 vpCircle (double oA, double oB, double oC, double oX, double oY, double oZ, double R)
 
virtual ~vpCircle () vp_override
 
void changeFrame (const vpHomogeneousMatrix &noMo, vpColVector &noP) const vp_override
 
void changeFrame (const vpHomogeneousMatrix &cMo) vp_override
 
void display (const vpImage< unsigned char > &I, const vpCameraParameters &cam, const vpColor &color=vpColor::green, unsigned int thickness=1) vp_override
 
void display (const vpImage< unsigned char > &I, const vpHomogeneousMatrix &cMo, const vpCameraParameters &cam, const vpColor &color=vpColor::green, unsigned int thickness=1) vp_override
 
void display (const vpImage< vpRGBa > &I, const vpCameraParameters &cam, const vpColor &color=vpColor::green, unsigned int thickness=1)
 
void display (const vpImage< vpRGBa > &I, const vpHomogeneousMatrix &cMo, const vpCameraParameters &cam, const vpColor &color=vpColor::green, unsigned int thickness=1)
 
vpCircleduplicate () const vp_override
 
double get_x () const
 
double get_y () const
 
double get_n20 () const
 
double get_n11 () const
 
double get_n02 () const
 
double getA () const
 
double getB () const
 
double getC () const
 
double getX () const
 
double getY () const
 
double getZ () const
 
double getR () const
 
void projection () vp_override
 
void projection (const vpColVector &cP, vpColVector &p) const vp_override
 
void setWorldCoordinates (const vpColVector &oP) vp_override
 
void setWorldCoordinates (double oA, double oB, double oC, double oX, double oY, double oZ, double R)
 
Deprecated functions
vp_deprecated double get_mu20 () const
 
vp_deprecated double get_mu11 () const
 
vp_deprecated double get_mu02 () const
 
Public Member Functions Inherited from vpForwardProjection
vpColVector get_oP () const
 
vpForwardProjectionDeallocatorType getDeallocate ()
 
virtual void print () const
 
void project ()
 
void project (const vpHomogeneousMatrix &cMo)
 
void setDeallocate (vpForwardProjectionDeallocatorType d)
 
void track (const vpHomogeneousMatrix &cMo)
 
Public Member Functions Inherited from vpTracker
vpColVector get_p () const
 
vpColVector get_cP () const
 

Static Public Member Functions

static void computeIntersectionPoint (const vpCircle &circle, const vpCameraParameters &cam, const double &rho, const double &theta, double &i, double &j)
 

Public Attributes

Public Attributes Inherited from vpForwardProjection
vpColVector oP
 
Public Attributes Inherited from vpTracker
vpColVector p
 
vpColVector cP
 
bool cPAvailable
 

Protected Member Functions

void init () vp_override
 

Detailed Description

Class that defines a 3D circle in the object frame and allows forward projection of a 3D circle in the camera frame and in the 2D image plane by perspective projection. All the parameters must be set in meter.

Note that a 3D circle is defined from the intersection between a 3D plane and a 3D sphere.

A 3D circle has the followings parameters:

Examples
manGeometricFeatures.cpp, servoSimuCircle2DCamVelocity.cpp, servoSimuCircle2DCamVelocityDisplay.cpp, simulateCircle2DCamVelocity.cpp, and testPoseFeatures.cpp.

Definition at line 85 of file vpCircle.h.

Member Enumeration Documentation

◆ vpForwardProjectionDeallocatorType

Used for memory issue especially in the vpServo class.

Enumerator
user 
vpDisplayForwardProjection 

Definition at line 68 of file vpForwardProjection.h.

Constructor & Destructor Documentation

◆ vpCircle() [1/3]

vpCircle::vpCircle ( )

Default constructor that initialize internal vectors.

Definition at line 83 of file vpCircle.cpp.

References init().

Referenced by duplicate().

◆ vpCircle() [2/3]

vpCircle::vpCircle ( const vpColVector oP_)
explicit

Construct the circle from the intersection of a plane and a sphere.

Parameters
oP_: This 7-dim vector defines the parameters oP[0], oP[1], oP[2] corresponding to parameters oA, oB, oC of the plane with equation oA*(X-oX)+oB*(Y-oY)+oC*(Z-oZ)=0 passing through the 3D sphere center. oP[3], oP[4], oP[5] correspond to oX, oY, oZ the coordinates of the center of the sphere. oP[6] corresponds to the radius of the sphere.
See also
setWorldCoordinates()

Definition at line 96 of file vpCircle.cpp.

References init(), and setWorldCoordinates().

◆ vpCircle() [3/3]

vpCircle::vpCircle ( double  oA,
double  oB,
double  oC,
double  oX,
double  oY,
double  oZ,
double  R 
)

Construct the 3D circle from the intersection of a plane and a sphere with coordinates expressed in the object frame.

Parameters
oA,oB,oC: Parameters of the plane with equation oA*(X-oX)+oB*(Y-oY)+oC*(Z-oZ)=0 passing through the 3D sphere center.
oX: Coordinate of the center of the sphere along X-axis in the object frame.
oY: Coordinate of the center of the sphere along Y-axis in the object frame.
oZ: Coordinate of the center of the sphere along Z-axis in the object frame.
R: Radius of the sphere.
See also
setWorldCoordinates()

Definition at line 115 of file vpCircle.cpp.

References init(), and setWorldCoordinates().

◆ ~vpCircle()

vpCircle::~vpCircle ( )
virtual

Default destructor that does nothing.

Definition at line 124 of file vpCircle.cpp.

Member Function Documentation

◆ changeFrame() [1/2]

void vpCircle::changeFrame ( const vpHomogeneousMatrix cMo)
virtual

Perspective projection of the circle. Internal circle parameters are modified in cP.

Parameters
cMo: Homogeneous transformation from camera frame to object frame.

Implements vpForwardProjection.

Definition at line 281 of file vpCircle.cpp.

References vpTracker::cP, and vpForwardProjection::oP.

◆ changeFrame() [2/2]

void vpCircle::changeFrame ( const vpHomogeneousMatrix noMo,
vpColVector noP 
) const
virtual

From the 3D coordinates of the circle in the object frame oP that are set using for example vpCircle(double oA, double oB, double oC, double oX, double oY, double oZ, double R) or setWorldCoordinates(), compute the 3D coordinates of the circle in a new object frame noP = noMo * oP. Internal parameters of the circle remain unchanged.

Parameters
noMo: Transformation from camera to object frame.
noP: 3D normalized coordinates of the circle in the a new ojbect frame noP = (noA, noB, noC, noX, noY, noZ, R).

Implements vpForwardProjection.

Definition at line 249 of file vpCircle.cpp.

References vpForwardProjection::oP, and vpColVector::resize().

Referenced by vpMbtDistanceCircle::computeInteractionMatrixError(), vpMbtDistanceCylinder::computeInteractionMatrixError(), display(), vpMbtDistanceKltCylinder::getModelForDisplay(), vpMbtDistanceCircle::getModelForDisplay(), vpMbtDistanceCylinder::getModelForDisplay(), vpMbtDistanceCircle::initMovingEdge(), vpMbtDistanceCylinder::initMovingEdge(), vpMbtDistanceCircle::updateMovingEdge(), and vpMbtDistanceCylinder::updateMovingEdge().

◆ computeIntersectionPoint()

void vpCircle::computeIntersectionPoint ( const vpCircle circle,
const vpCameraParameters cam,
const double &  rho,
const double &  theta,
double &  i,
double &  j 
)
static

Computes the coordinates of the point corresponding to the intersection between a circle and a line.

Warning
This functions assumes changeFrame() and projection() have already been called.
See also
changeFrame(), projection()
Parameters
circle: Circle to consider for the intersection.
cam: Camera parameters that have to be used for the intersection computation.
rho: The rho parameter of the line.
theta: The theta parameter of the line.
i: resulting i-coordinate of the intersection point.
j: resulting j-coordinate of the intersection point.

Definition at line 399 of file vpCircle.cpp.

References vpCameraParameters::get_px(), vpCameraParameters::get_py(), vpCameraParameters::get_u0(), vpCameraParameters::get_v0(), vpTracker::p, and vpMath::sqr().

Referenced by vpMbtDistanceKltCylinder::getModelForDisplay(), vpMbtDistanceCylinder::getModelForDisplay(), vpMbtDistanceCylinder::initMovingEdge(), and vpMbtDistanceCylinder::updateMovingEdge().

◆ display() [1/4]

void vpCircle::display ( const vpImage< unsigned char > &  I,
const vpCameraParameters cam,
const vpColor color = vpColor::green,
unsigned int  thickness = 1 
)
virtual

Display the projection of a 3D circle in image I using internal coordinates in the image plane (x,y,n20,n11,n02) available in p vector. These coordinates may be updated using projection().

Parameters
I: Image used as background.
cam: Camera parameters.
color: Color used to draw the circle.
thickness: Thickness used to draw the circle.

Implements vpForwardProjection.

Examples
manGeometricFeatures.cpp.

Definition at line 314 of file vpCircle.cpp.

References vpFeatureDisplay::displayEllipse(), and vpTracker::p.

◆ display() [2/4]

void vpCircle::display ( const vpImage< unsigned char > &  I,
const vpHomogeneousMatrix cMo,
const vpCameraParameters cam,
const vpColor color = vpColor::green,
unsigned int  thickness = 1 
)
virtual

Display the projection of a sphere in image I. This method is non destructive wrt. cP and p internal circle parameters.

Parameters
I: Image used as background.
cMo: Homogeneous transformation from camera frame to object frame. The circle is considered as viewed from this camera position.
cam: Camera parameters.
color: Color used to draw the sphere.
thickness: Thickness used to draw the circle.

Implements vpForwardProjection.

Definition at line 346 of file vpCircle.cpp.

References changeFrame(), vpFeatureDisplay::displayEllipse(), and projection().

◆ display() [3/4]

void vpCircle::display ( const vpImage< vpRGBa > &  I,
const vpCameraParameters cam,
const vpColor color = vpColor::green,
unsigned int  thickness = 1 
)

Display the projection of a 3D circle in image I using internal coordinates in the image plane (x,y,n20,n11,n02) available in p vector. These coordinates may be updated using projection().

Parameters
I: Image used as background.
cam: Camera parameters.
color: Color used to draw the circle.
thickness: Thickness used to draw the circle.

Definition at line 329 of file vpCircle.cpp.

References vpFeatureDisplay::displayEllipse(), and vpTracker::p.

◆ display() [4/4]

void vpCircle::display ( const vpImage< vpRGBa > &  I,
const vpHomogeneousMatrix cMo,
const vpCameraParameters cam,
const vpColor color = vpColor::green,
unsigned int  thickness = 1 
)

Display the projection of a sphere in image I. This method is non destructive wrt. cP and p internal circle parameters.

Parameters
I: Image used as background.
cMo: Homogeneous transformation from camera frame to object frame. The circle is considered as viewed from this camera position.
cam: Camera parameters.
color: Color used to draw the sphere.
thickness: Thickness used to draw the circle.

Definition at line 366 of file vpCircle.cpp.

References changeFrame(), vpFeatureDisplay::displayEllipse(), and projection().

◆ duplicate()

vpCircle * vpCircle::duplicate ( ) const
virtual

For memory issue (used by the vpServo class only)

Implements vpForwardProjection.

Definition at line 376 of file vpCircle.cpp.

References vpCircle().

◆ get_cP()

vpColVector vpTracker::get_cP ( ) const
inlineinherited

Return object parameters expressed in the 3D camera frame.

Definition at line 93 of file vpTracker.h.

◆ get_mu02()

vp_deprecated double vpCircle::get_mu02 ( ) const
inline
Deprecated:
You should rather use get_n02(). This function is incorrectly named and is confusing since it returns second order centered moments of the ellipse normalized by its area that corresponds to $n_02 = mu_02/a$.

Definition at line 165 of file vpCircle.h.

◆ get_mu11()

vp_deprecated double vpCircle::get_mu11 ( ) const
inline
Deprecated:
You should rather use get_n11(). This function is incorrectly named and is confusing since it returns second order centered moments of the ellipse normalized by its area that corresponds to $n_11 = mu@name Deprecated functions_11/a$.

Definition at line 158 of file vpCircle.h.

◆ get_mu20()

vp_deprecated double vpCircle::get_mu20 ( ) const
inline
Deprecated:
You should rather use get_n20(). This function is incorrectly named and is confusing since it returns second order centered moments of the ellipse normalized by its area that corresponds to $n_20 = mu_20/a$.

Definition at line 151 of file vpCircle.h.

◆ get_n02()

double vpCircle::get_n02 ( ) const
inline

Definition at line 112 of file vpCircle.h.

◆ get_n11()

double vpCircle::get_n11 ( ) const
inline

Definition at line 111 of file vpCircle.h.

◆ get_n20()

double vpCircle::get_n20 ( ) const
inline

Definition at line 110 of file vpCircle.h.

◆ get_oP()

vpColVector vpForwardProjection::get_oP ( ) const
inlineinherited

Return object parameters expressed in the 3D object frame.

Definition at line 153 of file vpForwardProjection.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 91 of file vpTracker.h.

◆ get_x()

double vpCircle::get_x ( ) const
inline

Definition at line 107 of file vpCircle.h.

◆ get_y()

double vpCircle::get_y ( ) const
inline

Definition at line 108 of file vpCircle.h.

◆ getA()

double vpCircle::getA ( ) const
inline

Definition at line 114 of file vpCircle.h.

◆ getB()

double vpCircle::getB ( ) const
inline

Definition at line 115 of file vpCircle.h.

◆ getC()

double vpCircle::getC ( ) const
inline

Definition at line 116 of file vpCircle.h.

◆ getDeallocate()

vpForwardProjectionDeallocatorType vpForwardProjection::getDeallocate ( )
inlineinherited

Definition at line 155 of file vpForwardProjection.h.

◆ getR()

double vpCircle::getR ( ) const
inline

Definition at line 122 of file vpCircle.h.

◆ getX()

double vpCircle::getX ( ) const
inline

Definition at line 118 of file vpCircle.h.

◆ getY()

double vpCircle::getY ( ) const
inline

Definition at line 119 of file vpCircle.h.

◆ getZ()

double vpCircle::getZ ( ) const
inline

Definition at line 120 of file vpCircle.h.

◆ init()

void vpCircle::init ( )
protectedvirtual

Default initialisation of the feature parameters:

  • in the object frame: oP
  • in the camera frame: cP
  • in the image plane: p.

Implements vpForwardProjection.

Definition at line 40 of file vpCircle.cpp.

References vpTracker::cP, vpForwardProjection::oP, vpTracker::p, and vpColVector::resize().

Referenced by vpCircle().

◆ print()

void vpForwardProjection::print ( ) const
virtualinherited

Print to stdout the feature parameters in:

  • the object frame
  • the camera frame
  • the image plane.
Examples
servoSimuCircle2DCamVelocityDisplay.cpp, servoSimuLine2DCamVelocityDisplay.cpp, and servoSimuSquareLine2DCamVelocityDisplay.cpp.

Definition at line 50 of file vpForwardProjection.cpp.

References vpTracker::cP, vpForwardProjection::oP, vpTracker::p, and vpColVector::t().

◆ project() [1/2]

◆ project() [2/2]

void vpForwardProjection::project ( const vpHomogeneousMatrix cMo)
inherited

Compute the feature parameters in the camera frame (vpTracker::cP) and than compute the projection of these parameters in the image plane (vpTracker::p).

Warning
The feature parameters in the object frame (vpForwardProjection:oP) need to be set prior the use of this method. To initialize these parameters see setWorldCoordinates().
Parameters
cMo: The homogeneous matrix corresponding to the pose between the camera frame and the object frame.

Definition at line 81 of file vpForwardProjection.cpp.

References vpForwardProjection::changeFrame(), and vpForwardProjection::projection().

◆ projection() [1/2]

void vpCircle::projection ( )
virtual

Perspective projection of the circle.

From the 3D parameters of the circle in the camera frame available in cP, computes the 2D parameters of the ellipse resulting from the perspective projection in the image plane. Those 2D parameters are available in p vector.

See vpCircle::projection(const vpColVector &, vpColVector &) const for a more detailed description of the parameters.

Implements vpForwardProjection.

Definition at line 137 of file vpCircle.cpp.

References vpTracker::cP, and vpTracker::p.

Referenced by vpMbtDistanceCircle::computeInteractionMatrixError(), vpMbtDistanceCylinder::computeInteractionMatrixError(), display(), vpMbtDistanceKltCylinder::getModelForDisplay(), vpMbtDistanceCircle::getModelForDisplay(), vpMbtDistanceCylinder::getModelForDisplay(), vpMbtDistanceCircle::initMovingEdge(), vpMbtDistanceCylinder::initMovingEdge(), vpMbtDistanceCircle::updateMovingEdge(), and vpMbtDistanceCylinder::updateMovingEdge().

◆ projection() [2/2]

void vpCircle::projection ( const vpColVector cP_,
vpColVector p_ 
) const
virtual

Perspective projection of the circle.

Parameters
cP_3D cercle input parameters expressed in the camera frame. This 7-dim vector contains the following parameters: cA, cB, cC, cX, cY, cZ, R where
  • cA, cB, cC are the parameters of the plane with equation cA*(x-cX)+cB*(y-cY)+cC*(z-cZ)=0 passing through the 3D sphere center.
  • cX, cY, cZ are the 3D coordinates of the circle in the camera frame
  • R is the circle radius in [m].
p_2D circle output parameters. This is a 5 dimension vector. It contains the following parameters: x, y, n20, n11, n02 where:
  • x, y are the normalized coordinates of the ellipse centroid (ie the perspective projection of a 3D circle becomes a 2D ellipse in the image) in the image plane.
  • n20, n11, n02 which are the second order centered moments of the ellipse normalized by its area (i.e., such that $n_{ij} = \mu_{ij}/a$ where $\mu_{ij}$ are the centered moments and a the area).

Implements vpForwardProjection.

Definition at line 157 of file vpCircle.cpp.

References vpException::divideByZeroError, vpColVector::resize(), and vpMath::sqr().

◆ setDeallocate()

void vpForwardProjection::setDeallocate ( vpForwardProjectionDeallocatorType  d)
inlineinherited

Definition at line 183 of file vpForwardProjection.h.

◆ setWorldCoordinates() [1/2]

void vpCircle::setWorldCoordinates ( const vpColVector oP_)
virtual

Set the parameters of the 3D circle in the object frame.

Parameters
oP_: This 7-dim vector defines the parameters oP[0], oP[1], oP[2] corresponding to parameters oA, oB, oC of the plane with equation oA*(X-oX)+oB*(Y-oY)+oC*(Z-oZ)=0 passing through the 3D sphere center. oP[3], oP[4], oP[5] correspond to oX, oY, oZ the coordinates of the center of the sphere. oP[6] corresponds to the radius of the sphere.

Implements vpForwardProjection.

Examples
manGeometricFeatures.cpp, servoSimuCircle2DCamVelocity.cpp, servoSimuCircle2DCamVelocityDisplay.cpp, simulateCircle2DCamVelocity.cpp, and testPoseFeatures.cpp.

Definition at line 57 of file vpCircle.cpp.

References vpForwardProjection::oP.

Referenced by vpMbtDistanceCircle::buildFrom(), vpMbtDistanceCylinder::buildFrom(), vpMbtDistanceKltCylinder::buildFrom(), and vpCircle().

◆ setWorldCoordinates() [2/2]

void vpCircle::setWorldCoordinates ( double  oA,
double  oB,
double  oC,
double  oX,
double  oY,
double  oZ,
double  R 
)

Set the 3D circle coordinates in the object frame.

Parameters
oA,oB,oC: Parameters of the plane with equation oA*(X-oX)+oB*(Y-oY)+oC*(Z-oZ)=0 passing through the 3D sphere center.
oX: Coordinate of the center of the sphere along X-axis in the object frame.
oY: Coordinate of the center of the sphere along Y-axis in the object frame.
oZ: Coordinate of the center of the sphere along Z-axis in the object frame.
R: Radius of the sphere.

Definition at line 69 of file vpCircle.cpp.

References vpForwardProjection::oP.

◆ track()

void vpForwardProjection::track ( const vpHomogeneousMatrix cMo)
inherited

Track the feature parameters in the camera frame (vpTracker::cP) and than compute the projection of these parameters in the image plane (vpTracker::p).

This method is similar to project(const vpHomogeneousMatrix &).

Warning
The feature parameters in the object frame (vpForwardProjection:oP) need to be set prior the use of this method. To initialize these parameters see setWorldCoordinates().
Parameters
cMo: The homogeneous matrix corresponding to the pose between the camera frame and the object frame.
Examples
mbot-apriltag-ibvs.cpp, servoSimu4Points.cpp, servoSimuAfma6FourPoints2DCamVelocity.cpp, servoSimuCircle2DCamVelocity.cpp, servoSimuCircle2DCamVelocityDisplay.cpp, servoSimuFourPoints2DCamVelocity.cpp, servoSimuFourPoints2DCamVelocityDisplay.cpp, servoSimuFourPoints2DPolarCamVelocityDisplay.cpp, servoSimuLine2DCamVelocityDisplay.cpp, servoSimuSphere.cpp, servoSimuSphere2DCamVelocity.cpp, servoSimuSphere2DCamVelocityDisplay.cpp, servoSimuSphere2DCamVelocityDisplaySecondaryTask.cpp, servoSimuSquareLine2DCamVelocityDisplay.cpp, servoSimuViper850FourPoints2DCamVelocity.cpp, simulateCircle2DCamVelocity.cpp, simulateFourPoints2DCartesianCamVelocity.cpp, simulateFourPoints2DPolarCamVelocity.cpp, tutorial-ibvs-4pts-json.cpp, tutorial-ibvs-4pts-ogre.cpp, tutorial-ibvs-4pts-plotter-continuous-gain-adaptive.cpp, tutorial-ibvs-4pts-plotter-gain-adaptive.cpp, tutorial-ibvs-4pts-plotter.cpp, tutorial-ibvs-4pts.cpp, tutorial-simu-pioneer-continuous-gain-adaptive.cpp, tutorial-simu-pioneer-continuous-gain-constant.cpp, tutorial-simu-pioneer-pan.cpp, and tutorial-simu-pioneer.cpp.

Definition at line 103 of file vpForwardProjection.cpp.

References vpForwardProjection::project().

Referenced by vpPose::computeResidual(), vpProjectionDisplay::displayCamera(), vpImageDraw::drawFrame(), vpPose::poseVirtualVS(), vpPose::poseVirtualVSrobust(), vpWireFrameSimulator::projectCameraTrajectory(), vpSimulatorAfma6::updateArticularPosition(), and vpSimulatorViper850::updateArticularPosition().

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 77 of file vpTracker.h.

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

◆ oP

◆ p