Visual Servoing Platform  version 3.4.0
vpFeatureMoment Class Referenceabstract

#include <vpFeatureMoment.h>

+ Inheritance diagram for vpFeatureMoment:

Public Types

enum  { FEATURE_ALL = 0xffff }
enum  vpBasicFeatureDeallocatorType { user, vpServo }

Public Member Functions

 vpFeatureMoment (vpMomentDatabase &data_base, double A_=0.0, double B_=0.0, double C_=0.0, vpFeatureMomentDatabase *featureMoments=NULL, unsigned int nbmatrices=1)
virtual ~vpFeatureMoment ()
Inherited functionalities from vpFeatureMoment
virtual void compute_interaction (void)
vpBasicFeatureduplicate () const
void display (const vpCameraParameters &cam, const vpImage< unsigned char > &I, const vpColor &color=vpColor::green, unsigned int thickness=1) const
void display (const vpCameraParameters &cam, const vpImage< vpRGBa > &I, const vpColor &color=vpColor::green, unsigned int thickness=1) const
int getDimension (unsigned int select=FEATURE_ALL) const
void init (void)
vpMatrix interaction (unsigned int select=FEATURE_ALL)
void linkTo (vpFeatureMomentDatabase &featureMoments)
virtual const char * momentName () const =0
virtual const char * name () const =0
void print (unsigned int select=FEATURE_ALL) const
virtual void printDependencies (std::ostream &os) const
void update (double A, double B, double C)
Inherited functionalities from vpBasicFeature
unsigned int dimension_s ()
virtual vpColVector error (const vpBasicFeature &s_star, unsigned int select=FEATURE_ALL)
vpColVector get_s (unsigned int select=FEATURE_ALL) const
vpBasicFeatureDeallocatorType getDeallocate ()
virtual double operator[] (unsigned int i) const
void setDeallocate (vpBasicFeatureDeallocatorType d)
void setFlags ()

Static Public Member Functions

static unsigned int selectAll ()

Static Public Attributes

static const unsigned int FEATURE_LINE [32]

Protected Member Functions

const vpMomentgetMoment () const
void resetFlags ()

Protected Attributes

const vpMomentmoment
std::vector< vpMatrixinteraction_matrices
double A
double B
double C
char _name [255]
vpColVector s
unsigned int dim_s
bool * flags
unsigned int nbParameters
vpBasicFeatureDeallocatorType deallocate


VISP_EXPORT std::ostream & operator<< (std::ostream &os, const vpFeatureMoment &featM)

Detailed Description

This class defines shared system methods/attributes for 2D moment features but no functional code. It is used to compute interaction matrices for moment features.

While vpMoment-type classes do only compute moment values and can by used for almost anything, vpFeatureMoment-type classes are specifically designed for visual servoing. More importantly, a vpFeatureMoment is used to compute the interaction matrix associated to it's moment primitive.

This class is virtual and cannot be used directly. It defines the following characteristics common to all moment features:

  • Plane orientation parameters (A,B,C): Each camera frame corresponds to a physical planar object contained in a plane. This plane's equation has the following form: $ A \times x+B \times y + C = \frac{1}{Z} $. These parameters can be updated anytime.
  • Get corresponding moment primitive: for example a vpFeatureMomentCInvariant will provide access to a vpMomentCInvariant instance.
  • Provide access to a feature database (vpFeatureMomentDatabase).
  • All interaction matrices (different from vpBasicFeature::interaction which selects the required interaction matrix).

Like vpMoment, vpFeatureMoment provides a vpFeatureMoment::update() method. But unlike vpMoment::update() which only acknowledges the new object, the vpFeatureMoment::update() acknowledges the new plane parameters AND computes the interaction matrices associated with the feature.

A vpFeatureMoment will be often part of a vpFeatureMomentDatabase in the same way a vpMoment is part of a vpMomentDatabase. This database is specified inside the vpFeatureMoment::vpFeatureMoment() constructor. As a result, a vpFeatureMoment will be able to access other vpFeatureMoments through this database.

A vpBasicFeature can be duplicated into a vpMomentGenericFeature. In that case, all data in the vpBasicFeature is copied but the feature's name is lost. For example if a vpFeatureMomentCInvariant is duplicated, the duplicata will be operational but could not be used in a vpFeatureMomentDatabase.

Note that you can use vpFeatureMoment to do visual servoing but it is not it's only purpose. You may compute your interaction matrices with vpFeatureMoment::update() and use them for any purpose.

- A vpFeatureMoment is not responsible for updating the moment primitives it depends on. Make sure your vpMoments are all up to date before computing an interaction matrix using vpFeatureMoment.
- Be careful with orders. Often, computing a feature of order n requires vpMoment primitives of order n+1. Make sure to check the documentation of the specialised vpFeatureMoment classes when deciding to which order you want to initialize the object. An object of order 6 should be sufficient for all classic implementations of vpFeatureMoment.

Here is an example of how to use a vpFeatureMoment (in this case vpFeatureMomentBasic).

#include <visp3/core/vpMomentBasic.h>
#include <visp3/core/vpMomentDatabase.h>
#include <visp3/core/vpMomentObject.h>
#include <visp3/core/vpPoint.h>
#include <visp3/visual_features/vpFeatureMoment.h>
#include <visp3/visual_features/vpFeatureMomentBasic.h>
int main()
std::vector<vpPoint> vec_p; // vector that contains the vertices
p.set_x(1); p.set_y(1); // coordinates in meters in the image plane (vertex 1)
p.set_x(2); p.set_y(2); // coordinates in meters in the image plane (vertex 2)
// Init object of order 3 because we need vpFeatureMomentBasic of order 2 which
// implies third-order moment primitives
obj.setType(vpMomentObject::DISCRETE); // Discrete mode for object
vpMomentDatabase mdb; //database for moment primitives. This will
//only contain the basic moment.
vpMomentBasic bm; //basic moment (this particular moment is nothing
//more than a shortcut to the vpMomentObject)
bm.linkTo(mdb); //add basic moment to moment database
vpFeatureMomentBasic fmb(mdb,0,0,1,NULL);
//update and compute the vpMoment BEFORE doing any operations with vpFeatureMoment
fmb.update(0,0,1); //update the vpFeatureMoment with a plane
std::cout << fmb.interaction(1,1) << std::endl;

Definition at line 159 of file vpFeatureMoment.h.

Member Enumeration Documentation

anonymous enum

Definition at line 82 of file vpBasicFeature.h.

Indicates who should deallocate the feature.


Definition at line 88 of file vpBasicFeature.h.

Constructor & Destructor Documentation

vpFeatureMoment::vpFeatureMoment ( vpMomentDatabase data_base,
double  A_ = 0.0,
double  B_ = 0.0,
double  C_ = 0.0,
vpFeatureMomentDatabase featureMoments = NULL,
unsigned int  nbmatrices = 1 

Initializes the feature with information about the database of moment primitives, the object plane, feature database and matrix size.

data_base: Moment database. The database of moment primitives (first parameter) is mandatory. It is used to access different moment values later used to compute the final matrix.
A_: Plane coefficient in a $ A \times x+B \times y + C = \frac{1}{Z} $ plane.
B_: Plane coefficient in a $ A \times x+B \times y + C = \frac{1}{Z} $ plane.
C_: Plane coefficient in a $ A \times x+B \times y + C = \frac{1}{Z} $ plane.
featureMoments: Feature database
nbmatrices: If you want to create a new vpFeatureMoment implementation, your feature will often have a matrix size of n lines. You can specify the number of lines by this parameter.

Definition at line 204 of file vpFeatureMoment.h.

References vpBasicFeature::display(), vpBasicFeature::duplicate(), vpBasicFeature::getDimension(), vpColor::green, vpBasicFeature::init(), vpBasicFeature::interaction(), and vpBasicFeature::print().

vpFeatureMoment::~vpFeatureMoment ( )

Definition at line 258 of file vpFeatureMoment.cpp.

Member Function Documentation

unsigned int vpBasicFeature::dimension_s ( )

Return the dimension of the feature vector $\bf s$.

Definition at line 110 of file vpBasicFeature.h.

References vpColor::green.

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

Not implemented since visual representation of a moment doesn't often make sense.

Implements vpBasicFeature.

Definition at line 114 of file vpFeatureMoment.cpp.

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

Not implemented since visual representation of a moment doesn't often make sense.

Implements vpBasicFeature.

Definition at line 128 of file vpFeatureMoment.cpp.

vpBasicFeature * vpFeatureMoment::duplicate ( ) const

Duplicates the feature into a vpGenericFeature harbouring the same properties. The resulting feature is of vpMomentGenericFeature type. While it still can compute interaction matrices and has acces to it's moment primitive, it has lost all precise information about its precise type and therefore cannot be used in a feature database.

The corresponding feature.

Implements vpBasicFeature.

Definition at line 220 of file vpFeatureMoment.cpp.

References A, B, C, vpBasicFeature::dim_s, featureMomentsDataBase, vpBasicFeature::flags, interaction_matrices, moment, moments, vpBasicFeature::nbParameters, vpColVector::resize(), and vpBasicFeature::s.

vpBasicFeatureDeallocatorType vpBasicFeature::getDeallocate ( )

Definition at line 123 of file vpBasicFeature.h.

int vpFeatureMoment::getDimension ( unsigned int  select = FEATURE_ALL) const

Feature's dimension according to selection.

Definition at line 85 of file vpFeatureMoment.cpp.

References vpBasicFeature::dim_s, and vpBasicFeature::FEATURE_LINE.

const vpMoment& vpFeatureMoment::getMoment ( ) const

Definition at line 163 of file vpFeatureMoment.h.

void vpFeatureMoment::init ( void  )

Initialize common parameters for moment features.

Implements vpBasicFeature.

Definition at line 56 of file vpFeatureMoment.cpp.

References vpBasicFeature::dim_s, vpBasicFeature::flags, vpMoment::get(), moment, vpBasicFeature::nbParameters, vpColVector::resize(), and vpBasicFeature::s.

vpMatrix vpFeatureMoment::interaction ( unsigned int  select = FEATURE_ALL)

Retrieves the interaction matrix. No computation is done.

select: Feature selector.
The corresponding interaction matrix.

There is no rule about the format of the feature selector. It may be different for different features. For example, for vpFeatureMomentBasic or vpFeatureMomentCentered features, select may refer to the $ (i,j) $ couple in the $ j \times order + i $ format, but for vpFeatureMomentCInvariant the selector allows to select couples $ (i,j,k,l...) $ in the following format: 1 << i

  • 1 << j + 1 << k + 1 << l.

Implements vpBasicFeature.

Definition at line 199 of file vpFeatureMoment.cpp.

References vpBasicFeature::dim_s, vpBasicFeature::FEATURE_LINE, interaction_matrices, and vpMatrix::stack().

Referenced by vpFeatureMomentCentered::compute_interaction().

void vpFeatureMoment::linkTo ( vpFeatureMomentDatabase featureMoments)

Links the feature to the feature's database. NB: The feature's database is different from the moment's database.

featureMoments: database in which the moment features are stored.

Definition at line 244 of file vpFeatureMoment.cpp.

References _name, featureMomentsDataBase, vpException::memoryAllocationError, and name().

Referenced by vpFeatureMomentCommon::vpFeatureMomentCommon().

virtual const char* vpFeatureMoment::momentName ( ) const
pure virtual

Name of the moment corresponding to the feature. This allows to locate the moment associated with the feature in the provided database.

Implemented in vpMomentGenericFeature, vpFeatureMomentGravityCenterNormalized, vpFeatureMomentCInvariant, vpFeatureMomentGravityCenter, vpFeatureMomentAreaNormalized, vpFeatureMomentAlpha, vpFeatureMomentCentered, vpFeatureMomentBasic, and vpFeatureMomentArea.

Referenced by update().

virtual const char* vpFeatureMoment::name ( ) const
pure virtual
virtual double vpBasicFeature::operator[] ( unsigned int  i) const

Return element i in the state vector (usage : x = s[i] )

Definition at line 130 of file vpBasicFeature.h.

void vpFeatureMoment::print ( unsigned int  select = FEATURE_ALL) const

Outputs the content of the feature: it's corresponding selected moments.

Implements vpBasicFeature.

Definition at line 99 of file vpFeatureMoment.cpp.

References vpBasicFeature::dim_s, vpBasicFeature::FEATURE_LINE, and vpBasicFeature::s.

void vpFeatureMoment::printDependencies ( std::ostream &  os) const

Interface function to display the moments and other interaction matrices on which a particular vpFeatureMoment is dependent upon Not made pure to maintain compatibility Recommended : Types inheriting from vpFeatureMoment should implement this function

Definition at line 281 of file vpFeatureMoment.cpp.

static unsigned int vpBasicFeature::selectAll ( )

Select all the features.

Definition at line 142 of file vpBasicFeature.h.

void vpBasicFeature::setDeallocate ( vpBasicFeatureDeallocatorType  d)

Definition at line 137 of file vpBasicFeature.h.

Referenced by vpServo::addFeature().

void vpBasicFeature::setFlags ( )

Set feature flags to true to prevent warning when re-computing the interaction matrix without having updated the feature.

Definition at line 141 of file vpBasicFeature.cpp.

References vpBasicFeature::flags, and vpBasicFeature::nbParameters.

void vpFeatureMoment::update ( double  A_,
double  B_,
double  C_ 

Updates the interaction matrices with the image plane the camera is facing. The plane must be in the format: $ \frac{1}{Z}=Ax+By+C $ . The moment primitives MUST be updated before calling this function.

This method also computes the interaction matrix. Therefore, you must call vpFeatureMoment::update before calling vpFeatureMoment::interaction.

The behaviour of this method is not the same as vpMoment::update which only acknowledges the new object. This method also computes the interaction matrices.
A_: A coefficient of the plane.
B_: B coefficient of the plane.
C_: C coefficient of the plane.
mbot-apriltag-ibvs.cpp, and servoBebop2.cpp.

Definition at line 153 of file vpFeatureMoment.cpp.

References A, B, C, compute_interaction(), vpBasicFeature::dim_s, vpBasicFeature::flags, vpMomentDatabase::get(), vpMoment::get(), moment, momentName(), moments, vpBasicFeature::nbParameters, vpException::notInitialized, vpColVector::resize(), and vpBasicFeature::s.

Referenced by vpFeatureMomentCommon::updateAll().

Friends And Related Function Documentation

VISP_EXPORT std::ostream& operator<< ( std::ostream &  os,
const vpFeatureMoment featM 

Member Data Documentation

char vpFeatureMoment::_name[255]

Definition at line 171 of file vpFeatureMoment.h.

Referenced by linkTo().

const unsigned int vpBasicFeature::FEATURE_LINE
Initial value:
= {
(unsigned int)(1 << 0), (unsigned int)(1 << 1), (unsigned int)(1 << 2), (unsigned int)(1 << 3),
(unsigned int)(1 << 4), (unsigned int)(1 << 5), (unsigned int)(1 << 6), (unsigned int)(1 << 7),
(unsigned int)(1 << 8), (unsigned int)(1 << 9), (unsigned int)(1 << 10), (unsigned int)(1 << 11),
(unsigned int)(1 << 12), (unsigned int)(1 << 13), (unsigned int)(1 << 14), (unsigned int)(1 << 15),
(unsigned int)(1 << 16), (unsigned int)(1 << 17), (unsigned int)(1 << 18), (unsigned int)(1 << 19),
(unsigned int)(1 << 20), (unsigned int)(1 << 21), (unsigned int)(1 << 22), (unsigned int)(1 << 23),
(unsigned int)(1 << 24), (unsigned int)(1 << 25), (unsigned int)(1 << 26), (unsigned int)(1 << 27),
(unsigned int)(1 << 28), (unsigned int)(1 << 29), (unsigned int)(1 << 30), (unsigned int)(1 << 31)}

Definition at line 80 of file vpBasicFeature.h.

Referenced by vpBasicFeature::error(), vpGenericFeature::error(), vpBasicFeature::get_s(), vpBasicFeature::getDimension(), getDimension(), vpGenericFeature::interaction(), interaction(), vpGenericFeature::print(), print(), vpFeatureEllipse::select_n02(), vpFeatureEllipse::select_n11(), vpFeatureEllipse::select_n20(), vpFeatureVanishingPoint::selectAlpha(), vpFeatureSegment::selectAlpha(), vpFeatureVanishingPoint::selectAtanOneOverRho(), vpFeatureSegment::selectL(), vpFeatureEllipse::selectMu02(), vpFeatureEllipse::selectMu11(), vpFeatureEllipse::selectMu20(), vpFeatureVanishingPoint::selectOneOverRho(), vpFeatureLine::selectRho(), vpFeaturePointPolar::selectRho(), vpFeatureLine::selectTheta(), vpFeaturePointPolar::selectTheta(), vpFeatureThetaU::selectTUx(), vpFeatureThetaU::selectTUy(), vpFeatureThetaU::selectTUz(), vpFeatureTranslation::selectTx(), vpFeatureTranslation::selectTy(), vpFeatureTranslation::selectTz(), vpFeatureVanishingPoint::selectX(), vpFeatureEllipse::selectX(), vpFeaturePoint::selectX(), vpFeaturePoint3D::selectX(), vpFeatureSegment::selectXc(), vpFeatureVanishingPoint::selectY(), vpFeatureEllipse::selectY(), vpFeaturePoint::selectY(), vpFeaturePoint3D::selectY(), vpFeatureSegment::selectYc(), and vpFeaturePoint3D::selectZ().

bool* vpBasicFeature::flags

Ensure that all the parameters needed to compute the iteraction matrix are set.

Definition at line 98 of file vpBasicFeature.h.

Referenced by vpFeatureEllipse::buildFrom(), vpFeatureDepth::buildFrom(), vpFeaturePoint::buildFrom(), vpFeatureLine::buildFrom(), vpFeaturePoint3D::buildFrom(), vpFeatureThetaU::buildFrom(), vpFeaturePointPolar::buildFrom(), vpFeatureTranslation::buildFrom(), duplicate(), vpFeatureVanishingPoint::init(), vpFeatureLuminance::init(), vpFeatureEllipse::init(), vpFeatureSegment::init(), vpFeatureDepth::init(), vpFeaturePoint::init(), init(), vpFeatureLine::init(), vpFeaturePoint3D::init(), vpFeatureThetaU::init(), vpFeaturePointPolar::init(), vpFeatureTranslation::init(), vpFeatureVanishingPoint::interaction(), vpFeatureEllipse::interaction(), vpFeatureSegment::interaction(), vpFeatureDepth::interaction(), vpFeaturePoint::interaction(), vpFeatureLine::interaction(), vpFeaturePoint3D::interaction(), vpFeatureThetaU::interaction(), vpFeaturePointPolar::interaction(), vpFeatureTranslation::interaction(), vpBasicFeature::operator=(), vpBasicFeature::resetFlags(), vpFeaturePointPolar::set_rho(), vpFeaturePointPolar::set_rhoThetaZ(), vpFeaturePointPolar::set_theta(), vpFeatureThetaU::set_TUx(), vpFeatureThetaU::set_TUy(), vpFeatureThetaU::set_TUz(), vpFeatureVanishingPoint::set_x(), vpFeatureEllipse::set_x(), vpFeatureDepth::set_x(), vpFeaturePoint::set_x(), vpFeaturePoint3D::set_X(), vpFeatureEllipse::set_xy(), vpFeaturePoint::set_xyZ(), vpFeaturePoint3D::set_XYZ(), vpFeatureDepth::set_xyZLogZoverZstar(), vpFeatureVanishingPoint::set_y(), vpFeatureEllipse::set_y(), vpFeatureDepth::set_y(), vpFeaturePoint::set_y(), vpFeaturePoint3D::set_Y(), vpFeatureLuminance::set_Z(), vpFeatureDepth::set_Z(), vpFeaturePoint::set_Z(), vpFeaturePoint3D::set_Z(), vpFeaturePointPolar::set_Z(), vpFeatureEllipse::setABC(), vpFeatureLine::setABCD(), vpFeatureVanishingPoint::setAlpha(), vpFeatureVanishingPoint::setAtanOneOverRho(), vpBasicFeature::setFlags(), vpFeatureEllipse::setMoments(), vpFeatureVanishingPoint::setOneOverRho(), vpFeatureLine::setRhoTheta(), update(), vpFeatureLuminance::vpFeatureLuminance(), and vpBasicFeature::~vpBasicFeature().

vpColVector vpBasicFeature::s

State of the visual feature.

Definition at line 92 of file vpBasicFeature.h.

Referenced by vpFeatureEllipse::buildFrom(), vpFeatureLuminance::buildFrom(), vpFeatureDepth::buildFrom(), vpFeaturePoint::buildFrom(), vpFeatureLine::buildFrom(), vpFeaturePoint3D::buildFrom(), vpFeatureThetaU::buildFrom(), vpFeaturePointPolar::buildFrom(), vpFeatureTranslation::buildFrom(), vpFeatureEllipse::display(), duplicate(), vpFeatureEllipse::error(), vpFeatureVanishingPoint::error(), vpFeatureLuminance::error(), vpBasicFeature::error(), vpFeatureMomentAlpha::error(), vpFeatureDepth::error(), vpGenericFeature::error(), vpFeaturePoint::error(), vpFeatureLine::error(), vpFeaturePoint3D::error(), vpFeatureThetaU::error(), vpFeaturePointPolar::error(), vpFeatureTranslation::error(), vpFeatureDepth::get_LogZoverZstar(), vpFeaturePointPolar::get_rho(), vpBasicFeature::get_s(), vpGenericFeature::get_s(), vpFeaturePointPolar::get_theta(), vpFeatureThetaU::get_TUx(), vpFeatureThetaU::get_TUy(), vpFeatureThetaU::get_TUz(), vpFeatureTranslation::get_Tx(), vpFeatureTranslation::get_Ty(), vpFeatureTranslation::get_Tz(), vpFeatureVanishingPoint::get_x(), vpFeaturePoint::get_x(), vpFeaturePoint3D::get_X(), vpFeatureVanishingPoint::get_y(), vpFeaturePoint::get_y(), vpFeaturePoint3D::get_Y(), vpFeaturePoint3D::get_Z(), vpFeatureVanishingPoint::getAlpha(), vpFeatureVanishingPoint::getAtanOneOverRho(), vpBasicFeature::getDimension(), vpFeatureVanishingPoint::getOneOverRho(), vpFeatureVanishingPoint::init(), vpFeatureLuminance::init(), vpFeatureEllipse::init(), vpFeatureSegment::init(), vpFeatureDepth::init(), vpGenericFeature::init(), vpFeaturePoint::init(), init(), vpFeatureLine::init(), vpFeaturePoint3D::init(), vpFeatureThetaU::init(), vpFeaturePointPolar::init(), vpFeatureTranslation::init(), vpFeatureEllipse::interaction(), vpFeatureLine::interaction(), vpFeatureThetaU::interaction(), vpFeatureTranslation::interaction(), vpBasicFeature::operator=(), vpFeatureEllipse::print(), vpFeatureSegment::print(), vpGenericFeature::print(), print(), vpFeatureLine::print(), vpFeatureThetaU::print(), vpFeatureTranslation::print(), vpFeatureDepth::set_LogZoverZstar(), vpFeaturePointPolar::set_rho(), vpGenericFeature::set_s(), vpFeaturePointPolar::set_theta(), vpFeatureThetaU::set_TUx(), vpFeatureThetaU::set_TUy(), vpFeatureThetaU::set_TUz(), vpFeatureTranslation::set_Tx(), vpFeatureTranslation::set_Ty(), vpFeatureTranslation::set_Tz(), vpFeatureVanishingPoint::set_x(), vpFeatureEllipse::set_x(), vpFeaturePoint::set_x(), vpFeaturePoint3D::set_X(), vpFeatureEllipse::set_xy(), vpFeatureVanishingPoint::set_y(), vpFeatureEllipse::set_y(), vpFeaturePoint::set_y(), vpFeaturePoint3D::set_Y(), vpFeaturePoint3D::set_Z(), vpFeatureVanishingPoint::setAlpha(), vpFeatureVanishingPoint::setAtanOneOverRho(), vpFeatureEllipse::setMoments(), vpFeatureVanishingPoint::setOneOverRho(), vpFeatureLine::setRhoTheta(), update(), and vpGenericFeature::vpGenericFeature().