Visual Servoing Platform  version 3.3.1 under development (2020-07-03)
vpLine Class Reference

#include <visp3/core/vpLine.h>

+ Inheritance diagram for vpLine:

Public Types

enum  vpForwardProjectionDeallocatorType { user, vpDisplayForwardProjection }
 

Public Member Functions

 vpLine ()
 
virtual ~vpLine ()
 
void changeFrame (const vpHomogeneousMatrix &cMo, vpColVector &cP) const
 
void changeFrame (const vpHomogeneousMatrix &cMo)
 
void display (const vpImage< unsigned char > &I, const vpCameraParameters &cam, const vpColor &color=vpColor::green, unsigned int thickness=1)
 
void display (const vpImage< unsigned char > &I, const vpHomogeneousMatrix &cMo, const vpCameraParameters &cam, const vpColor &color=vpColor::green, unsigned int thickness=1)
 
vpLineduplicate () const
 
double getRho () const
 
double getTheta () const
 
void setRho (double rho)
 
void setTheta (double theta)
 
void setWorldCoordinates (const double &oA1, const double &oB1, const double &oC1, const double &oD1, const double &oA2, const double &oB2, const double &oC2, const double &oD2)
 
void setWorldCoordinates (const vpColVector &oP1, const vpColVector &oP2)
 
void setWorldCoordinates (const vpColVector &oP)
 
void projection ()
 
void projection (const vpColVector &cP, vpColVector &p) 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
 

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

Detailed Description

Class that defines a 3D line in the object frame and allows forward projection of the line 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 line is defined from the intersection between two 3D planes.

A 3D line has the followings parameters:

  • in the 3D object frame: parameters are located in vpForwardProjection::oP 8-dim internal vector. They correspond to the parameters oA1, oB1, oC1, oD1 and oA2, oB2, oC2, oD2 defining the equations of the two planes. Each point $ (X, Y, Z) $ which belongs to the 3D line is a solution of those two equations:

    \[ oA1*X + oB1*Y + oC1*Z + oD1 = 0 \]

    \[ oA2*X + oB2*Y + oC2*Z + oD2 = 0 \]

    To update these line parameters you may use setWorldCoordinates(). To get theses parameters use get_oP().
  • in the 3D camera frame: parameters are saved in vpTracker::cP 8-dim internal vector. They correspond to the parameters cA1, cB1, cC1, cD1 and cA2, cB2, cC2, cD2 defining the equations of the two planes. Each point $ (X, Y, Z) $ which belongs to the 3D line is a solution of those two equations:

    \[ cA1*X + cB1*Y + cC1*Z + cD1 = 0 \]

    \[ cA2*X + cB2*Y + cC2*Z + cD2 = 0 \]

    It is easily possible to compute these parameters thanks to the corresponding 3D parameters oP in the object frame. But you have to note that four constraints are added in the planes equations.

    \[ cD1 = 0 \]

    \[ cD2 > 0 \]

    \[ cA1*cA2 + cB1*cB2 + cC1*cC2 = 0 \]

    \[ || cA2 || = 1 \]

    To compute these parameters you may use changeFrame(). To get these parameters use get_cP().
  • in the 2D image plane: parameters are saved in vpTracker::p 2-dim vector. They correspond to the parameters ( $\rho$, $\theta$). These 2D parameters are obtained from the perspective projection of the 3D line parameters expressed in the camera frame. They are defined thanks to the 2D equation of a line.

    \[ x \; cos(\theta) + y \; sin(\theta) -\rho = 0 \]

    Here $ x $ and $ y $ are the coordinates of a point belonging to the line in the image plane while $ \rho $ and $ \theta $ are the parameters used to define the line. The value of $ \theta $ is between $ -\pi/2 $ and $ \pi/2 $ and the value of $ \rho $ can be positive or negative. The conventions used to choose the sign of $ \rho $ and the value of $ \theta $ are illustrated by the following image.
    vpFeatureLine.gif
    The line parameters corresponding to the image frame are located in the vpTracker::p public attribute, where p is a vector defined as:

    \[ p = \left[\begin{array}{c} \rho \\ \theta \end{array}\right] \]

    To compute these parameters use projection(). To get the corresponding values use get_p().
Examples:
manGeometricFeatures.cpp, servoAfma6Line2DCamVelocity.cpp, servoAfma6SquareLines2DCamVelocity.cpp, servoAfma6TwoLines2DCamVelocity.cpp, servoSimuLine2DCamVelocityDisplay.cpp, servoSimuSquareLine2DCamVelocityDisplay.cpp, and testPoseFeatures.cpp.

Definition at line 104 of file vpLine.h.

Member Enumeration Documentation

◆ vpForwardProjectionDeallocatorType

Used for memory issue especially in the vpServo class.

Enumerator
user 
vpDisplayForwardProjection 

Definition at line 73 of file vpForwardProjection.h.

Constructor & Destructor Documentation

◆ vpLine()

vpLine::vpLine ( )

Default constructor.

Definition at line 67 of file vpLine.cpp.

References init().

Referenced by duplicate().

◆ ~vpLine()

virtual vpLine::~vpLine ( )
inlinevirtual

Member Function Documentation

◆ changeFrame() [1/2]

void vpLine::changeFrame ( const vpHomogeneousMatrix cMo,
vpColVector cP_ 
) const
virtual

Computes the line parameters cP in the camera frame thanks to the line parameters oP given in the object frame and the homogeneous matrix relative to the pose between the camera frame and the object frame. Thus the computation gives the equations of the two planes needed to define the line in the desired frame thanks to the equations of the same two planes in the object frame.

In input of this method, the line parameters oP in the object frame are those from the vpForwardProjection::oP public attribute.

Parameters
cMo: The homogeneous matrix relative to the pose between the desired frame and the object frame.
cP_: The vector which will contain the parameters of the two planes in the camera frame.

\[ cP = \left[\begin{array}{c}cA1 \\ cB1 \\ cC1 \\ cD1 \\ cA2 \\ cB2 \\ cC2 \\ cD2 \end{array}\right] \]

The code below shows how to use this method.

//Create the line
vpLine line;
//Set the coordinates of the line in the object frame in meter.
line.setWorldCoordinates( 1, 0, 0, -0.5, 0, 0, 1, 0.5)
//The line is define by the intersection between the plane X = 0.5m and Z = 0.5m
//Create the homogeneous matrix
//Computes or set here the homogeneous matrix
//Creates the vector which will contain the line features
//Computes the equations of the two planes in the camera frame
line.changeFrame(cMo, cP);

Implements vpForwardProjection.

Definition at line 333 of file vpLine.cpp.

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

Referenced by changeFrame(), vpMbtDistanceLine::computeInteractionMatrixError(), display(), vpMbtDistanceLine::initMovingEdge(), and vpMbtDistanceLine::updateMovingEdge().

◆ changeFrame() [2/2]

void vpLine::changeFrame ( const vpHomogeneousMatrix cMo)
virtual

Computes the line parameters cP in the camera frame thanks to the line parameters oP given in the object frame and the homogeneous matrix relative to the pose cMo between the object frame and the camera frame. Thus the computation gives the equations of the two planes needed to define the line in the camera frame thanks to the equations of the same two planes in the object frame.

In input of this method, the line parameters oP in the object frame are those from the vpForwardProjection::oP public attribute.

As a result of this method, line parameters cP in the camera frame are updated in the vpTracker::cP public attribute.

Parameters
cMo: The homogeneous matrix corresponding to the pose between the camera frame and the object frame.

The code below shows how to use this method.

//Create the line
vpLine line;
//Set the coordinates of the line in the object frame in meter.
line.setWorldCoordinates( 1, 0, 0, -0.5, 0, 0, 1, 0.5)
//The line is define by the intersection between the plane X = 0.5m and Z =
0.5m
//Create the homogeneous matrix
//Computes or set here the homogeneous matrix
//Computes the equations of the two planes in the camera frame
line.changeFrame(cMo);

Implements vpForwardProjection.

Definition at line 291 of file vpLine.cpp.

References changeFrame(), and vpTracker::cP.

◆ display() [1/2]

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

Displays the line in the image I thanks to the 2D parameters of the line p in the image plane (vpTracker::p) and the camera parameters which enable to convert the parameters from meter to pixel.

Parameters
I: The image where the line must be displayed.
cam: The camera parameters to enable the conversion from meter to pixel.
color: The desired color to display the line in the image.
thickness: Thickness of the feature representation.

Implements vpForwardProjection.

Examples:
manGeometricFeatures.cpp.

Definition at line 468 of file vpLine.cpp.

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

◆ display() [2/2]

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

Displays the line in the image I thanks to the parameters in the object frame (vpForwardProjection::oP), the homogeneous matrix relative to the pose between the camera frame and the object frame and the camera parameters which enable to convert the features from meter to pixel.

This method is non destructive wrt. cP and p internal line parameters.

Parameters
I: The image where the line must be displayed in overlay.
cMo: The homogeneous matrix corresponding to the pose between the camera frame and the object frame.
cam: The camera parameters to enable the conversion from meter to pixel.
color: The desired color to display the line in the image.
thickness: Thickness of the feature representation.

Implements vpForwardProjection.

Definition at line 496 of file vpLine.cpp.

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

◆ duplicate()

vpLine * vpLine::duplicate ( ) const
virtual

Create an object with the same type.

vpLine line;
fp = line.duplicate(); // fp is now a vpLine

Implements vpForwardProjection.

Definition at line 520 of file vpLine.cpp.

References vpLine().

◆ get_cP()

vpColVector vpTracker::get_cP ( ) const
inlineinherited

Return object parameters expressed in the 3D camera frame.

Definition at line 99 of file vpTracker.h.

◆ get_oP()

vpColVector vpForwardProjection::get_oP ( ) const
inlineinherited

Return object parameters expressed in the 3D object frame.

Definition at line 165 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 97 of file vpTracker.h.

◆ getDeallocate()

vpForwardProjectionDeallocatorType vpForwardProjection::getDeallocate ( )
inlineinherited

Definition at line 167 of file vpForwardProjection.h.

◆ getRho()

double vpLine::getRho ( ) const
inline

Gets the $ \rho $ value corresponding to one of the two parameters used to define the line parametrization in the image plane.

Returns
Returns the current value of $ \rho $.
See also
getTheta()
Examples:
servoAfma6Line2DCamVelocity.cpp.

Definition at line 130 of file vpLine.h.

Referenced by vpFeatureBuilder::create(), vpMbtDistanceLine::initMovingEdge(), and vpMbtDistanceLine::updateMovingEdge().

◆ getTheta()

double vpLine::getTheta ( ) const
inline

Gets the $ \theta $ angle value corresponding to one of the two parameters used to define the line parametrization in the image plane.

Returns
Returns the current value of $ \theta $.
See also
getRho()

Definition at line 142 of file vpLine.h.

Referenced by vpFeatureBuilder::create(), vpMbtDistanceLine::initMovingEdge(), and vpMbtDistanceLine::updateMovingEdge().

◆ init()

void vpLine::init ( )
protectedvirtual

Initialize the memory space requested for the 2D line parameters (p) in the image plane and for 3D line parameters (oP and cP) respectively in the object frame and the camera frame.

Implements vpForwardProjection.

Definition at line 57 of file vpLine.cpp.

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

Referenced by vpLine().

◆ 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 53 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 84 of file vpForwardProjection.cpp.

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

◆ projection() [1/2]

void vpLine::projection ( )
virtual

Computes the 2D parameters p of the line in the image plane thanks to the 3D line parameters cP in the camera frame located in the vpTracker::cP public attribute. The parameters $p=(\rho, \theta)$ are updated in the vpTracker::p public attribute.

Warning
To compute these parameters p, the method exploit the feature parameters cP in the camera frame. Thus, vpTracker::cP need to be updated before the call of this method. For that, a call to changeFrame(const vpHomogeneousMatrix &) is requested.

The code below shows how to use this method.

//Create the line
vpLine line;
//Set the coordinates of the line in the object frame in meter.
line.setWorldCoordinates( 1, 0, 0, -0.5, 0, 0, 1, 0.5)
//Here the line is define by the intersection between the plane X = 0.5m and
Z = 0.5m
//Create the homogeneous matrix
//Computes or set here the homogeneous matrix
//Computes the equations of the two planes in the camera frame
line.changeFrame(cMo);
//Computes the line features in the camera frame( rho and theta)
line.projection();

Implements vpForwardProjection.

Definition at line 193 of file vpLine.cpp.

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

Referenced by vpMbtDistanceLine::computeInteractionMatrixError(), display(), vpMbtDistanceLine::initMovingEdge(), and vpMbtDistanceLine::updateMovingEdge().

◆ projection() [2/2]

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

Computes the 2D parameters p of the line in the image plane thanks to the 3D line parameters cP expressed in the camera frame. The image plane parameters $p=(\rho , \theta)$ are updated in output.

Parameters
[in]cP_: The vector containing the line parameters relative to the camera frame.

\[ cP = \left[\begin{array}{c}cA1 \\ cB1 \\ cC1 \\ cD1 \\ cA2 \\ cB2 \\ cC2 \\ cD2 \end{array}\right] \]

[out]p_: The vector which contains the 2D line features expressed in the image plane.

\[ p = \left[\begin{array}{c} \rho \\ \theta \end{array}\right] \]

Exceptions
vpException::fatalError: Degenerate case, the image of the straight line is a point.

Implements vpForwardProjection.

Definition at line 216 of file vpLine.cpp.

References vpTracker::cP, vpException::dimensionError, vpException::fatalError, vpArray2D< Type >::getRows(), and vpColVector::resize().

◆ setDeallocate()

void vpForwardProjection::setDeallocate ( vpForwardProjectionDeallocatorType  d)
inlineinherited

Definition at line 196 of file vpForwardProjection.h.

References vpTracker::init().

◆ setRho()

void vpLine::setRho ( double  rho)
inline

Sets the $ \rho $ parameter used to define the line in the image plane.

Parameters
rho: The desired value for $ \rho $.
See also
setTheta()
Examples:
servoAfma6Line2DCamVelocity.cpp, servoAfma6SquareLines2DCamVelocity.cpp, and servoAfma6TwoLines2DCamVelocity.cpp.

Definition at line 153 of file vpLine.h.

◆ setTheta()

void vpLine::setTheta ( double  theta)
inline

Sets the $ \theta $ angle value used to define the line in the image plane.

Parameters
theta: The desired value for $ \theta $ angle.
See also
setRho()
Examples:
servoAfma6Line2DCamVelocity.cpp, servoAfma6SquareLines2DCamVelocity.cpp, and servoAfma6TwoLines2DCamVelocity.cpp.

Definition at line 163 of file vpLine.h.

References vpForwardProjection::init(), vpForwardProjection::projection(), and vpForwardProjection::setWorldCoordinates().

◆ setWorldCoordinates() [1/3]

void vpLine::setWorldCoordinates ( const double &  oA1,
const double &  oB1,
const double &  oC1,
const double &  oD1,
const double &  oA2,
const double &  oB2,
const double &  oC2,
const double &  oD2 
)

Sets the parameters oP which define the line in the object frame. As said in the class description, the line is defined as the intersection of two planes. The different parameters here define the equations of the two planes in the object frame. They are used to set the vpForwardProjection::oP public attribute.

\[ oA1 X + oB1 Y + oC1 Z + oD1 = 0 \]

\[ oA2 X + oB2 Y + oC2 Z + oD2 = 0 \]

Here $ (X, Y, Z) $ are the 3D coordinates of a point in the object frame.

Parameters
oA1,oB1,oC1,oD1: The parameters used to define the first plane in the object frame.
oA2,oB2,oC2,oD2: The parameters used to define the second plane in the object frame.
Examples:
manGeometricFeatures.cpp, servoAfma6Line2DCamVelocity.cpp, servoAfma6SquareLines2DCamVelocity.cpp, servoAfma6TwoLines2DCamVelocity.cpp, servoSimuLine2DCamVelocityDisplay.cpp, servoSimuSquareLine2DCamVelocityDisplay.cpp, and testPoseFeatures.cpp.

Definition at line 85 of file vpLine.cpp.

References vpForwardProjection::oP.

Referenced by vpMbtDistanceLine::~vpMbtDistanceLine().

◆ setWorldCoordinates() [2/3]

void vpLine::setWorldCoordinates ( const vpColVector oP1,
const vpColVector oP2 
)

Sets the parameters oP which define the line in the object frame. As said in the class description, the line is defined as the intersection of two planes. Eight parameters are required to define the equations of the two planes in the object frame. They are used to set the vpForwardProjection::oP public attribute.

\[ oA1 X + oB1 Y + oC1 Z + oD1 = 0 \]

\[ oA2 X + oB2 Y + oC2 Z + oD2 = 0 \]

Here $ (X, Y, Z) $ are the 3D coordinates of a point in the object frame.

Parameters
oP1: The column vector which contains the four parameters needed to define the equations of the first plane in the object frame.

\[ oP1 = \left[\begin{array}{c}oA1 \\ oB1 \\ oC1 \\ oD1 \end{array}\right] \]

oP2: The column vector which contains the four parameters needed to define the equations of the second plane in the object frame.

\[ oP2 = \left[\begin{array}{c} oA2 \\ oB2 \\ oC2 \\ oD2 \end{array}\right] \]

Definition at line 146 of file vpLine.cpp.

References vpException::dimensionError, vpArray2D< Type >::getRows(), and vpForwardProjection::oP.

◆ setWorldCoordinates() [3/3]

void vpLine::setWorldCoordinates ( const vpColVector oP_)
virtual

Sets the parameters oP which define the line in the object frame. As said in the class description, the line is defined as the intersection of two planes. Eight parameters are required to define the equations of the two planes in the object frame. They are used to set the vpForwardProjection::oP public attribute.

\[ oA1 X + oB1 Y + oC1 Z + oD1 = 0 \]

\[ oA2 X + oB2 Y + oC2 Z + oD2 = 0 \]

Here $ (X, Y, Z) $ are the 3D coordinates of a point in the object frame.

Parameters
oP_: The column vector which contains the eight parameters needed to define the equations of the two planes in the object frame.

\[ oP = \left[\begin{array}{c}oA1 \\ oB1 \\ oC1 \\ oD1 \\ oA2 \\ oB2 \\ oC2 \\ oD2 \end{array}\right] \]

Implements vpForwardProjection.

Definition at line 117 of file vpLine.cpp.

References vpException::dimensionError, vpArray2D< Type >::getRows(), and 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, servoBebop2.cpp, servoMomentPoints.cpp, servoMomentPolygon.cpp, servoSimu4Points.cpp, servoSimuAfma6FourPoints2DCamVelocity.cpp, servoSimuCircle2DCamVelocity.cpp, servoSimuCircle2DCamVelocityDisplay.cpp, servoSimuCylinder.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-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 106 of file vpForwardProjection.cpp.

References vpForwardProjection::project().

Referenced by vpPoseFeatures::addFeatureSegment(), 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 83 of file vpTracker.h.

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

◆ oP

◆ p