FeaturePoint¶

class FeaturePoint(self)¶

Bases: BasicFeature

Class that defines a 2D point visual feature \(s\) which is composed by two parameters that are the cartesian coordinates \(x\) and \(y\) .

In this class \(x\) and \(y\) are the 2D coordinates in the image plane and are given in meter. \(Z\) which is the 3D coordinate representing the depth is also a parameter of the point. It is needed during the computation of the interaction matrix \(L\) .

The visual features can be set easily from an instance of the classes vpPoint , vpDot or vpDot2 . For more precision see the vpFeatureBuilder class.

Once the values of the visual features are set, the interaction() method allows to compute the interaction matrix \(L\) associated to the visual feature, while the error() method computes the error vector \((s - s^*)\) between the current visual feature and the desired one.

The code below shows how to create a eye-in hand visual servoing task using a 2D point feature \((x,y)\) that correspond to the 2D coordinates of a point in the image plane. To control six degrees of freedom, at least four other features must be considered like two other point features for example. First we create a current ( \(s\) ) 2D point feature. Then we set the task to use the interaction matrix associated to the current feature \(L_s\) . And finally we compute the camera velocity \(v=-\lambda \; L_s^+ \; (s-s^*)\) . The current feature \(s\) is updated in the while() loop.

#include <visp3/visual_features/vpFeaturePoint.h>
#include <visp3/vs/vpServo.h>

#ifdef ENABLE_VISP_NAMESPACE
using namespace VISP_NAMESPACE_NAME;
#endif

int main()
{
  vpServo task; // Visual servoing task

  vpFeaturePoint sd; //The desired point feature.
  // Set the desired features x and y
  double xd = 0;
  double yd = 0;
  // Set the depth of the point in the camera frame.
  double Zd = 1;
  // Set the point feature thanks to the desired parameters.
  sd.buildFrom(xd, yd, Zd);

  vpFeaturePoint s; //The current point feature.
  // Set the current features x and y
  double x;  // You have to compute the value of x.
  double y;  // You have to compute the value of y.
  double Z;  // You have to compute the value of Z.
  // Set the point feature thanks to the current parameters.
  s.buildFrom(x, y, Z);
  // In this case the parameter Z is not necessary because the interaction matrix is computed
  // with the desired visual feature.

  // Set eye-in-hand control law.
  // The computed velocities will be expressed in the camera frame
  task.setServo(vpServo::EYEINHAND_CAMERA);
  // Interaction matrix is computed with the desired visual features sd
  task.setInteractionMatrixType(vpServo::DESIRED);

  // Add the 2D point feature to the task
  task.addFeature(s, sd);

  // Control loop
  for ( ; ; ) {
    // The new parameters x and y must be computed here.

    // Update the current point visual feature
    s.buildFrom(x, y, Z);

    // Compute the control law
    vpColVector v = task.computeControlLaw(); // camera velocity
  }
  return 0;
}

If you want to build your own control law, this other example shows how to create a current ( \(s\) ) and desired ( \(s^*\) ) 2D point visual feature, compute the corresponding error vector \((s-s^*)\) and finally build the interaction matrix \(L_s\) .

#include <visp3/core/vpMatrix.h>
#include <visp3/visual_features/vpFeaturePoint.h>

#ifdef ENABLE_VISP_NAMESPACE
using namespace VISP_NAMESPACE_NAME;
#endif

int main()
{
  vpFeaturePoint sd; //The desired point feature.
  // Set the desired features x and y
  double xd = 0;
  double yd = 0;
  // Set the depth of the point in the camera frame.
  double Zd = 1;
  // Set the point feature thanks to the desired parameters.
  sd.buildFrom(xd, yd, Zd);

  vpFeaturePoint s; //The current point feature.
  // Set the current features x and y
  double x;  // You have to compute the value of x.
  double y;  // You have to compute the value of y.
  double Z;  // You have to compute the value of Z.
  // Set the point feature thanks to the current parameters.
  s.buildFrom(x, y, Z);

  // Compute the interaction matrix L_s for the current point feature
  vpMatrix L = s.interaction();
  // You can also compute the interaction matrix L_s for the desired point feature
  // The corresponding line of code is : vpMatrix L = sd.interaction();

  // Compute the error vector (s-sd) for the point feature
  s.error(s_star);
}

An other fully explained example is given in the tutorial-ibvs.

Default constructor that build a visual feature.

Methods

`__init__`	Default constructor that build a visual feature.
`buildFrom`	Build a 2D point visual feature from the point coordinates in the image plan \(x\) and \(y\) .
`display`	Overloaded function.
`error`	Overloaded function.
`get_Z`	Get the value of \(Z\) which represents the depth in the 3D camera frame.
`get_x`	Get the value of \(x\) which represents the x coordinate of the point in the image plan.
`get_y`	Get the value of \(y\) which represents the x coordinate of the point in the image plan.
`init`	Initialize the memory space requested for 2D point visual feature.
`interaction`	Compute and return the interaction matrix \(L\) .
`print`	Print to stdout the values of the current visual feature \(s\) .
`selectX`	Function used to select the \(x\) subset of the point visual feature.
`selectY`	Function used to select the \(y\) subset of the point visual feature.
`set_Z`	Set the value of \(Z\) which represents the depth in the 3D camera frame.
`set_x`	Set the value of \(x\) which represents the x coordinate of the point in image plan.
`set_xyZ`	Set the value of \(x\) , \(y\) and \(Z\) .
`set_y`	Set the value of \(y\) which represents the x coordinate of the point in the image plan.

Inherited Methods

`dimension_s`	Return the dimension of the feature vector \(\bf s\) .
`vpServo`
`BasicFeatureSelect`	Indicates who should deallocate the feature.
`getDimension`	Get the feature vector dimension.
`dim_s`
`deallocate`
`BasicFeatureDeallocatorType`	Indicates who should deallocate the feature.
`s`
`setDeallocate`
`user`
`nbParameters`
`FEATURE_ALL`
`setFlags`	Set feature flags to true to prevent warning when re-computing the interaction matrix without having updated the feature.
`get_s`	Get the feature vector \(\bf s\) .
`getDeallocate`
`selectAll`	Select all the features.

Operators

`__doc__`
`__init__`	Default constructor that build a visual feature.
`__module__`

Attributes

`FEATURE_ALL`
`X`
`Y`
`__annotations__`
`deallocate`
`dim_s`
`nbParameters`
`s`
`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¶

class FeaturePointType(self, value: int)¶

Bases: pybind11_object

Values:

__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__(self)¶: Default constructor that build a visual feature.

buildFrom(self, x: float, y: float, Z: float) → visp._visp.visual_features.FeaturePoint¶

Build a 2D point visual feature from the point coordinates in the image plan \(x\) and \(y\) . The parameter Z which describes the depth, is set in the same time.

See the vpFeaturePoint class description for more details about \(x\) and \(y\) .

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

display(*args, **kwargs)¶

Overloaded function.

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

Display point feature.

Parameters:

cam: Camera parameters.
I: Image.
color: Color to use for the display.
thickness: Thickness of the feature representation.

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

Display point feature.

Parameters:

cam: Camera parameters.
I: color Image.
color: Color to use for the display.
thickness: Thickness of the feature representation.

error(*args, **kwargs)¶

Overloaded function.

error(self: visp._visp.visual_features.FeaturePoint, s_star: visp._visp.visual_features.BasicFeature, select: int = FEATURE_ALL) -> visp._visp.core.ColVector

Compute the error \((s-s^*)\) between the current and the desired visual features from a subset of the possible features.

The code below shows how to use this method to manipulate the \(x\) subset:

// Creation of the current feature s
vpFeaturePoint s;
s.buildFrom(0, 0, 1);

// Creation of the desired feature s*
vpFeaturePoint s_star;
s_star.buildFrom(1, 1, 1);

// Compute the interaction matrix for the x feature
vpMatrix L_x = s.interaction( vpFeaturePoint::selectX() );

// Compute the error vector (s-s*) for the x feature
s.error(s_star, vpFeaturePoint::selectX());

Parameters:

s_star

Desired visual feature.

select

The error can be computed for a selection of a subset of the possible point features.

To compute the error for all the two point features use vpBasicFeature::FEATURE_ALL . In that case the error vector is a 2 dimension column vector.
To compute the error for only one of the point component feature ( \(x, y\) ) use one of the corresponding function selectX() or selectY() . In that case the error vector is a 1 dimension column vector.

Returns:

The error \((s-s^*)\) between the current and the desired visual feature.

error(self: visp._visp.visual_features.BasicFeature, 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(self, select: int = FEATURE_ALL) → int¶: Get the feature vector dimension.

get_Z(self) → float¶

Get the value of \(Z\) which represents the depth in the 3D camera frame.

Returns:: The value of \(Z\) .

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

get_x(self) → float¶

Get the value of \(x\) which represents the x coordinate of the point in the image plan. It is one parameter of the visual feature \(s\) .

Returns:: The value of \(x\) .

get_y(self) → float¶

Get the value of \(y\) which represents the x coordinate of the point in the image plan. It is one parameter of the visual feature \(s\) .

Returns:: The value of \(y\) .

init(self) → None¶: Initialize the memory space requested for 2D point visual feature.

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

Compute and return the interaction matrix \(L\) . The computation is made thanks to the values of the point features \(x\) and \(y\) and the depth \(Z\) .

\[\begin{split}L = \left[\begin{array}{c}L_{x} \\L_{y}\end{array}\right] = \left[\begin{array}{cccccc} -1/Z & 0 & x/Z & xy & -(1+x^2) & y \\0 & -1/Z & y/Z & 1+y^2 & -xy & -x \end{array}\right]\end{split}\]

The code below shows how to compute the interaction matrix associated to the visual feature \(s = x\) .

// Creation of the current feature s
vpFeaturePoint s;
s.buildFrom(0, 0, 1);

vpMatrix L_x = s.interaction( vpFeaturePoint::selectX() );

The code below shows how to compute the interaction matrix associated to the visual feature \(s = (x, y)\) .

// Creation of the current feature s
vpFeaturePoint s;
s.buildFrom(0, 0, 1);

vpMatrix L_x = s.interaction( vpBasicFeature::FEATURE_ALL );

Parameters:

select: int = FEATURE_ALL¶

Selection of a subset of the possible point features.

To compute the interaction matrix for all the two point features use vpBasicFeature::FEATURE_ALL . In that case the dimension of the interaction matrix is \([2 \times 6]\)
To compute the interaction matrix for only one of the point component feature ( \(x, y\) ) use one of the corresponding function selectX() or selectY() . In that case the returned interaction matrix is \([1 \times 6]\) dimension.

Returns:

The interaction matrix computed from the point features.

print(self, select: int = FEATURE_ALL) → None¶

Print to stdout the values of the current visual feature \(s\) .

vpFeaturePoint s; // Current visual feature s

// Creation of the current feature s
s.buildFrom(0, 0, 1);

s.print(); // print all the 2 components of the feature
s.print(vpBasicFeature::FEATURE_ALL);  // same behavior then previous line
s.print(vpFeaturePoint::selectX()); // print only the x component

Parameters:

select: int = FEATURE_ALL¶

Selection of a subset of the possible point features.

To print all the two point features use vpBasicFeature::FEATURE_ALL .
To print only one of the point component feature ( \(x, y\) ) use one of the corresponding function selectX() or selectY() .

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

static selectX() → int¶

Function used to select the \(x\) subset of the point visual feature.

This function is to use in conjunction with interaction() in order to compute the interaction matrix associated to \(x\) .

This function is also useful in the vpServo class to indicate that a subset of the visual feature is to use in the control law:

vpFeaturePoint s;
vpServo task;
...
// Add the (x) subset features from the 2D point
task.addFeature(s, vpFeaturePoint::selectX());

static selectY() → int¶

Function used to select the \(y\) subset of the point visual feature.

This function is to use in conjunction with interaction() in order to compute the interaction matrix associated to \(y\) .

This function is also useful in the vpServo class to indicate that a subset of the visual feature is to use in the control law:

vpFeaturePoint s;
vpServo task;
...
// Add the (y) subset features from the 2D point
task.addFeature(s, vpFeaturePoint::selectY());

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.

set_Z(self, Z: float) → None¶: Set the value of \(Z\) which represents the depth in the 3D camera frame.

set_x(self, x: float) → None¶

Set the value of \(x\) which represents the x coordinate of the point in image plan. It is one parameter of the visual feature \(s\) .

Parameters:

x: float¶: math:x value to set.

set_xyZ(self, x: float, y: float, Z: float) → None¶: Set the value of \(x\) , \(y\) and \(Z\) . \(x\) and \(y\) represent the coordinates of the point in the image plan and are the parameters of the visual feature \(s\) . \(Z\) is the 3D coordinate in the camera frame representing the depth.

set_y(self, y: float) → None¶

Set the value of \(y\) which represents the x coordinate of the point in the image plan. It is one parameter of the visual feature \(s\) .

Parameters:

y: float¶: math:y value to set.