FeaturePoint3D¶

class FeaturePoint3D(self)¶

Bases: BasicFeature

Class that defines the 3D point visual feature.

A 3D point visual feature corresponds to a 3D point with \({\bf X} = (X,Y,Z)\) coordinates in the camera frame.

This class is intended to manipulate the 3D point visual feature \(s = (X,Y,Z)\) . The interaction matrix related to \(s\) is given by:

\[\begin{split}L = \left[ \begin{array}{rrrrrr} -1 & 0 & 0 & 0 & -Z & Y \\0 & -1 & 0 & Z & 0 & -X \\0 & 0 & -1 & -Y & X & 0 \\\end{array} \right] \end{split}\]

Two ways are allowed to initialize the feature.

The first way by setting the feature values \((X,Y,Z)\) using vpFeaturePoint3D member functions like set_X() , set_Y() , set_Z() , or also buildFrom() .
The second by using the feature builder functionalities to initialize the feature from a point structure like vpFeatureBuilder::create ( vpFeaturePoint3D &, const vpPoint &).

The interaction() method allows to compute the interaction matrix \(L\) associated to the 3D point 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 3D point feature \((X,Y,Z)\) that correspond to the 3D point coordinates in the camera frame. To control six degrees of freedom, at least three other features must be considered like vpFeatureThetaU visual features. First we create a current ( \(s\) ) and desired ( \(s^*\) ) 3D point feature, set the task to use the interaction matrix associated to the desired feature \(L_{s^*}\) and than compute the camera velocity \(v=-\lambda \; {L_{s^*}}^+ \; (s-s^*)\) . The current feature \(s\) is updated in the while() loop while \(s^*\) is set to \(Z^*=1\) .

#include <iostream>
#include <visp3/core/vpHomogeneousMatrix.h>
#include <visp3/visual_features/vpFeaturePoint3D.h>
#include <visp3/vs/vpServo.h>

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

  // Set the 3D point coordinates in the object frame: oP
  vpPoint point(0.1, -0.1, 0);

  vpHomogeneousMatrix cMo; // Pose between the camera and the object frame
  cMo.buildFrom(0, 0, 1.2, 0, 0, 0);
  // ... cMo need here to be computed from a pose estimation

  point.changeFrame(cMo); // Compute the 3D point coordinates in the camera frame cP = cMo * oP

  // Creation of the current feature s
  vpFeaturePoint3D s;
  s.buildFrom(point); // Initialize the feature from the 3D point coordinates in the camera frame: s=(X,Y,Z)
  s.print();

  // Creation of the desired feature s*.
  vpFeaturePoint3D s_star;
  s_star.buildFrom(0, 0, 1); // Z*=1 meter
  s_star.print();

  // 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 s*
  task.setInteractionMatrixType(vpServo::DESIRED);
  // Set the constant gain
  double lambda = 0.8;
  task.setLambda(lambda);

  // Add the 3D point feature to the task
  task.addFeature(s, s_star);

  // Control loop
  for ( ; ; ) {
    // ... cMo need here to be estimated from for example a pose estimation.
    point.changeFrame(cMo); // Compute the 3D point coordinates in the camera frame cP = cMo * oP

    // Update the current 3D point visual feature
    s.buildFrom(point);

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

If you want to deal only with the \((X,Y)\) subset feature from the 3D point feature, you have just to modify the addFeature() call in the previous example by the following line. In that case, the dimension of \(s\) is two.

// Add the (X,Y) subset feature from the 3D point visual feature to the task
task.addFeature(s, s_star, vpFeaturePoint3D::selectX() | vpFeaturePoint3D::selectY());

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

#include <iostream>
#include <visp3/core/vpHomogeneousMatrix.h>
#include <visp3/core/vpMatrix.h>
#include <visp3/visual_features/vpFeaturePoint3D.h>

int main()
{
  // Set the 3D point coordinates in the object frame: oP
  vpPoint point(0.1, -0.1, 0);

  vpHomogeneousMatrix cMo; // Pose between the camera and the object frame
  cMo.buildFrom(0, 0, 1.2, 0, 0, 0);
  // ... cMo need here to be computed from a pose estimation

  point.changeFrame(cMo); // Compute the 3D point coordinates in the camera frame cP = cMo * oP

  // Creation of the current feature s
  vpFeaturePoint3D s;
  s.buildFrom(point); // Initialize the feature from the 3D point coordinates in the camera frame
  s.print();

  // Creation of the desired feature s*.
  vpFeaturePoint3D s_star;
  s_star.buildFrom(0, 0, 1); // Z*=1 meter
  s_star.print();

  // Compute the L_s interaction matrix associated to the current feature
  vpMatrix L = s.interaction();
  std::cout << "L: " << L << std::endl;

  // Compute the error vector (s-s*) for the 3D point feature
  vpColVector e = s.error(s_star); // e = (s-s*)

  std::cout << "e: " << e << std::endl;
}

Default constructor that build a 3D point visual feature and initialize it to \({\bf X} = (0, 0, 1)\) .

Methods

`__init__`	Default constructor that build a 3D point visual feature and initialize it to \({\bf X} = (0, 0, 1)\) .
`buildFrom`	Overloaded function.
`display`	Overloaded function.
`error`	Overloaded function.
`get_X`	Return the \(X\) coordinate in the camera frame of the 3D point.
`get_Y`	Return the \(Y\) coordinate in the camera frame of the 3D point.
`get_Z`	Return the \(Z\) coordinate in the camera frame of the 3D point.
`init`	Initialise the memory space requested for a 3D point visual feature.
`interaction`	Compute and return the interaction matrix \(L\) associated to a subset of the possible 3D point features \((X,Y,Z)\) that represent the 3D point coordinates expressed in the camera frame.
`print`	Print to stdout the values of the current visual feature \(s\) .
`selectX`	Function used to select the \(X\) subset coordinate of the 3D point visual feature.
`selectY`	Function used to select the \(Y\) subset coordinate of the 3D point visual feature.
`selectZ`	Function used to select the \(Z\) subset coordinate of the 3D point visual feature.
`set_X`	Initialise the \(X\) coordinate in the camera frame of the 3D Point visual feature \({\bf X} = (X,Y,Z)\) .
`set_XYZ`	Initialize the 3D point coordinates.
`set_Y`	Initialise the \(Y\) coordinate in the camera frame of the 3D Point visual feature \({\bf X} = (X,Y,Z)\) .
`set_Z`	Initialise the \(Z\) coordinate in the camera frame of the 3D Point visual feature \({\bf X} = (X,Y,Z)\) .

Inherited Methods

`user`
`BasicFeatureSelect`	Indicates who should deallocate the feature.
`setFlags`	Set feature flags to true to prevent warning when re-computing the interaction matrix without having updated the feature.
`FEATURE_ALL`
`getDimension`	Get the feature vector dimension.
`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__`	Default constructor that build a 3D point visual feature and initialize it to \({\bf X} = (0, 0, 1)\) .
`__module__`

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__(self)¶: Default constructor that build a 3D point visual feature and initialize it to \({\bf X} = (0, 0, 1)\) .

buildFrom(*args, **kwargs)¶

Overloaded function.

buildFrom(self: visp._visp.visual_features.FeaturePoint3D, p: visp._visp.core.Point) -> None

Build a 3D point visual feature from the camera frame coordinates \((X,Y,Z)\) of a point.

Parameters:

p: A point with camera frame coordinates \({^c}P=(X,Y,Z)\) up to date (see vpPoint class).

buildFrom(self: visp._visp.visual_features.FeaturePoint3D, X: float, Y: float, Z: float) -> None

Build a 3D point visual feature from the camera frame coordinates \((X,Y,Z)\) of a point.

Parameters:

X: Camera frame coordinates \((X,Y,Z)\) of a 3D point.
Y: Camera frame coordinates \((X,Y,Z)\) of a 3D point.
Z: Camera frame coordinates \((X,Y,Z)\) of a 3D point.

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

display(*args, **kwargs)¶

Overloaded function.

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

Not implemented.

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

Not implemented.

error(*args, **kwargs)¶

Overloaded function.

error(self: visp._visp.visual_features.FeaturePoint3D, 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 \(Z\) subset:

// Creation of the current feature s
vpFeaturePoint3D s;
s.set_Z(0.8); // Initialization of the current Z feature

// Creation of the desired feature s*.
vpFeatureTranslation s_star;
s_star.set_Z(1); // Initialization of the current Z* feature to Z*=1 meter

// Compute the interaction matrix for the Z coordinate feature
vpMatrix L_Z = s.interaction( vpFeaturePoint3D::selectZ() );

// Compute the error vector (s-s*) for the Z feature
s.error(s_star, vpFeaturePoint3D::selectZ());

To manipulate the subset features \(s=(Y, Z)\) , the code becomes:

// Compute the interaction matrix for the Y, Z feature coordinates
vpMatrix L_YZ = s.interaction( vpFeaturePoint3D::selectY() |
vpFeaturePoint3D::selectZ() );

// Compute the error vector e = (s-s*) for the Y, Z feature coordinates
vpColVector e = s.error(s_star, vpFeaturePoint3D::selectY() |
vpFeaturePoint3D::selectZ());

Parameters:

s_star

Desired 3D point visual feature.

select

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

To compute the error for all the three coordinates use vpBasicFeature::FEATURE_ALL . In that case the error vector is a 3 dimension column vector.
To compute the error for only one of the coordinate feature \((X,Y, or Z)\) use one of the corresponding function selectX() , selectY() or selectZ() . 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_X(self) → float¶: Return the \(X\) coordinate in the camera frame of the 3D point.

get_Y(self) → float¶: Return the \(Y\) coordinate in the camera frame of the 3D point.

get_Z(self) → float¶: Return the \(Z\) coordinate in the camera frame of the 3D point.

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

init(self) → None¶

Initialise the memory space requested for a 3D point visual feature.

By default this feature is initialized to \({\bf X} = (0, 0, 1)\) .

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

Compute and return the interaction matrix \(L\) associated to a subset of the possible 3D point features \((X,Y,Z)\) that represent the 3D point coordinates expressed in the camera frame.

\[\begin{split}L = \left[ \begin{array}{rrrrrr} -1 & 0 & 0 & 0 & -Z & Y \\0 & -1 & 0 & Z & 0 & -X \\0 & 0 & -1 & -Y & X & 0 \\\end{array} \right] \end{split}\]

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

vpPoint point;
...
// Creation of the current feature s
vpFeaturePoint3D s;
s.buildFrom(point);

vpMatrix L_X = s.interaction( vpFeaturePoint3D::selectX() );

The code below shows how to compute the interaction matrix associated to the \(s = (X,Y)\) subset visual feature:

vpMatrix L_XY = s.interaction( vpFeaturePoint3D::selectX() | vpFeaturePoint3D::selectY() );

L_XY is here now a 2 by 6 matrix. The first line corresponds to the \(X\) visual feature while the second one to the \(Y\) visual feature.

It is also possible to build the interaction matrix from all the 3D point coordinates by:

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

In that case, L_XYZ is a 3 by 6 interaction matrix where the last line corresponds to the \(Z\) visual feature.

Parameters:

select: int = FEATURE_ALL¶

Selection of a subset of the possible 3D point coordinate features.

To compute the interaction matrix for all the three subset features \((X,Y,Z)\) use vpBasicFeature::FEATURE_ALL . In that case the dimension of the interaction matrix is \([3 \times 6]\)
To compute the interaction matrix for only one of the subset ( \(X, Y,Z\) ) use one of the corresponding function selectX() , selectY() or selectZ() . In that case the returned interaction matrix is \([1 \times 6]\) dimension.

Returns:

The interaction matrix computed from the 3D point coordinate features.

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

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

vpPoint point;

// Creation of the current feature s
vpFeaturePoint3D s;
s.buildFrom(point);

s.print(); // print all the 3 components of the translation feature
s.print(vpBasicFeature::FEATURE_ALL); // same behavior then previous line
s.print(vpFeaturePoint3D::selectZ()); // print only the Z component

Parameters:

select: int = FEATURE_ALL¶

Selection of a subset of the possible 3D point feature coordinates.

To print all the three coordinates used as features use vpBasicFeature::FEATURE_ALL .
To print only one of the coordinate feature \((X,Y,Z)\) use one of the corresponding function selectX() , selectX() or selectZ() .

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

static selectX() → int¶

Function used to select the \(X\) subset coordinate of the 3D point visual feature.

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

See the interaction() method for an usage example.

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:

vpFeaturePoint3D p;
vpServo task;
...
// Add the (X,Y) subset coordinates features from a 3D point to the task
task.addFeature(p, vpFeaturePoint3D::selectX() |
vpFeaturePoint3D::selectY());

Note

See selectY() , selectZ()

static selectY() → int¶

Function used to select the \(Y\) subset coordinate of the 3D point visual feature.

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

See the interaction() method for an usage example.

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:

vpFeaturePoint3D p;
vpServo task;
...
// Add the (X,Y) subset coordinates features from a 3D point to the task
task.addFeature(p, vpFeaturePoint3D::selectX() |
vpFeaturePoint3D::selectY());

Note

See selectX() , selectZ()

static selectZ() → int¶

Function used to select the \(Z\) subset coordinate of the 3D point visual feature.

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

See the interaction() method for an usage example.

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:

vpFeaturePoint3D p;
vpServo task;
...
// Add the (Z) subset coordinate feature from a 3D point to the task
task.addFeature(p, vpFeaturePoint3D::selectZ());

Note

See selectX() , 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_X(self, X: float) → None¶

Initialise the \(X\) coordinate in the camera frame of the 3D Point visual feature \({\bf X} = (X,Y,Z)\) .

Note

See get_X()

Parameters:

X: float¶: math:X coordinate of the visual feature.

set_XYZ(self, X: float, Y: float, Z: float) → None¶

Initialize the 3D point coordinates.

Note

See set_X() , set_Y() , set_Z()

Parameters:

X: float¶: math:(X,Y,Z) coordinates in the camera frame of the 3D point visual feature.
Y: float¶: math:(X,Y,Z) coordinates in the camera frame of the 3D point visual feature.
Z: float¶: math:(X,Y,Z) coordinates in the camera frame of the 3D point visual feature.

set_Y(self, Y: float) → None¶

Initialise the \(Y\) coordinate in the camera frame of the 3D Point visual feature \({\bf X} = (X,Y,Z)\) .

Note

See get_Y()

Parameters:

Y: float¶: math:Y coordinate of the visual feature.

set_Z(self, Z: float) → None¶

Initialise the \(Z\) coordinate in the camera frame of the 3D Point visual feature \({\bf X} = (X,Y,Z)\) .

Note

See get_Z()

Parameters:

Z: float¶: math:Z coordinate or depth of the visual feature.