FeatureMoment¶

class FeatureMoment¶

Bases: BasicFeature

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 duplicate 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.

Warning

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 .

Warning

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 specialized 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()
{
  vpPoint p;
  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)
  vec_p.push_back(p);
  p.set_x(2); p.set_y(2); // coordinates in meters in the image plane (vertex 2)
  vec_p.push_back(p);

  //////////////////////////////REFERENCE VALUES////////////////////////////////
  // Init object of order 3 because we need vpFeatureMomentBasic of order 2 which
  // implies third-order moment primitives
  vpMomentObject obj(3);
  obj.setType(vpMomentObject::DISCRETE); // Discrete mode for object
  obj.fromVector(vec_p);

  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,nullptr);

  //update and compute the vpMoment BEFORE doing any operations with vpFeatureMoment
  bm.update(obj);
  bm.compute();

  fmb.update(0,0,1); //update the vpFeatureMoment with a plane
  //configuration
  std::cout << fmb.interaction(1,1) << std::endl;
}

Methods

`__init__`
`compute_interaction`
`display`	Overloaded function.
`getDimension`	Overloaded function.
`init`	Initialize common parameters for moment features.
`interaction`	Retrieves the interaction matrix.
`linkTo`	Links the feature to the feature's database.
`print`	Outputs the content of the feature: it's corresponding selected moments.
`printDependencies`	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.
`update`	Updates the interaction matrices with the image plane the camera is facing.

Inherited Methods

`user`
`BasicFeatureSelect`	Indicates who should deallocate the feature.
`error`	Compute the error between two visual features from a subset of the possible features.
`setFlags`	Set feature flags to true to prevent warning when re-computing the interaction matrix without having updated the feature.
`FEATURE_ALL`
`getDeallocate`
`dimension_s`	Return the dimension of the feature vector \(\bf s\) .
`setDeallocate`
`selectAll`	Select all the features.
`get_s`	Get the feature vector \(\bf s\) .
`BasicFeatureDeallocatorType`	Indicates who should deallocate the feature.
`vpServo`

Operators

`__doc__`
`__init__`
`__module__`
`__repr__`

Attributes

`FEATURE_ALL`
`__annotations__`
`user`
`vpServo`

class BasicFeatureDeallocatorType(self, value: int)¶

Bases: pybind11_object

Indicates who should deallocate the feature.

Values:

user
vpServo

__and__(self, other: object) → object¶

__eq__(self, other: object) → bool¶

__ge__(self, other: object) → bool¶

__getstate__(self) → int¶

__gt__(self, other: object) → bool¶

__hash__(self) → int¶

__index__(self) → int¶

__init__(self, value: int)¶

__int__(self) → int¶

__invert__(self) → object¶

__le__(self, other: object) → bool¶

__lt__(self, other: object) → bool¶

__ne__(self, other: object) → bool¶

__or__(self, other: object) → object¶

__rand__(self, other: object) → object¶

__ror__(self, other: object) → object¶

__rxor__(self, other: object) → object¶

__setstate__(self, state: int) → None¶

__xor__(self, other: object) → object¶

property name : str¶

class BasicFeatureSelect(self, value: int)¶

Bases: pybind11_object

Indicates who should deallocate the feature.

Values:

user
vpServo

__and__(self, other: object) → object¶

__eq__(self, other: object) → bool¶

__ge__(self, other: object) → bool¶

__getstate__(self) → int¶

__gt__(self, other: object) → bool¶

__hash__(self) → int¶

__index__(self) → int¶

__init__(self, value: int)¶

__int__(self) → int¶

__invert__(self) → object¶

__le__(self, other: object) → bool¶

__lt__(self, other: object) → bool¶

__ne__(self, other: object) → bool¶

__or__(self, other: object) → object¶

__rand__(self, other: object) → object¶

__ror__(self, other: object) → object¶

__rxor__(self, other: object) → object¶

__setstate__(self, state: int) → None¶

__xor__(self, other: object) → object¶

property name : str¶

__init__(*args, **kwargs)¶

compute_interaction(self) → None¶

dimension_s(self) → int¶: Return the dimension of the feature vector \(\bf s\) .

display(*args, **kwargs)¶

Overloaded function.

display(self: visp._visp.visual_features.FeatureMoment, cam: visp._visp.core.CameraParameters, I: visp._visp.core.ImageGray, color: visp._visp.core.Color = vpColor::green, thickness: int = 1) -> None

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

display(self: visp._visp.visual_features.FeatureMoment, cam: visp._visp.core.CameraParameters, I: visp._visp.core.ImageRGBa, color: visp._visp.core.Color = vpColor::green, thickness: int = 1) -> None

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

error(self, s_star: visp._visp.visual_features.BasicFeature, select: int = FEATURE_ALL) → visp._visp.core.ColVector¶: Compute the error between two visual features from a subset of the possible features.

getDeallocate(self) → visp._visp.visual_features.BasicFeature.BasicFeatureDeallocatorType¶

getDimension(*args, **kwargs)¶

Overloaded function.

getDimension(self: visp._visp.visual_features.FeatureMoment, select: int = FEATURE_ALL) -> int

Feature’s dimension according to selection.

getDimension(self: visp._visp.visual_features.BasicFeature, select: int = FEATURE_ALL) -> int

Get the feature vector dimension.

get_s(self, select: int = FEATURE_ALL) → visp._visp.core.ColVector¶: Get the feature vector \(\bf s\) .

init(self) → None¶: Initialize common parameters for moment features.

interaction(self, select: int = FEATURE_ALL) → visp._visp.core.Matrix¶

Retrieves the interaction matrix. No computation is done.

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.

Parameters:

select: int = FEATURE_ALL¶: Feature selector.

Returns:

The corresponding interaction matrix.

linkTo(self, featureMoments: visp._visp.visual_features.FeatureMomentDatabase) → None¶

Links the feature to the feature’s database.

Note

The feature’s database is different from the moment’s database.

Parameters:

featureMoments: visp._visp.visual_features.FeatureMomentDatabase¶: database in which the moment features are stored.

print(self, select: int = FEATURE_ALL) → None¶: Outputs the content of the feature: it’s corresponding selected moments.

printDependencies(self: visp._visp.visual_features.FeatureMoment, os: std::ostream) → None¶: 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.

static selectAll() → int¶: Select all the features.

setDeallocate(self, d: visp._visp.visual_features.BasicFeature.BasicFeatureDeallocatorType) → None¶

setFlags(self) → None¶: Set feature flags to true to prevent warning when re-computing the interaction matrix without having updated the feature.

update(self, A: float, B: float, C: float) → None¶

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 .

Warning

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.