FeaturePointPolar¶

class FeaturePointPolar(self)¶

Bases: BasicFeature

Class that defines 2D image point visual feature with polar coordinates \((\rho,\theta)\) described in [9] .

Let us denote \((\rho,\theta)\) the polar coordinates of an image point, with \(\rho\) the radius of the feature point with respect to the optical center and \(\theta\) the angle. From cartesian coordinates \((x,y)\) of a image point, polar coordinates are obtained by:

\[\rho = \sqrt{x^2+y^2} \hbox{,}\; \; \theta = \arctan \frac{y}{x}\]

From polar coordinates, cartesian coordinates of the feature point can be obtained by:

\[x = \rho \cos\theta \hbox{,}\; \; y = \rho \sin\theta\]

This class is intended to manipulate the 2D image point visual feature in polar coordinates \(s = (\rho, \theta)\) . The interaction matrix related to \(s\) is given by:

\[\begin{split}L = \left[ \begin{array}{l} L_{\rho} \\\; \\L_{\theta}\\\end{array} \right] = \left[ \begin{array}{cccccc} \frac{-\cos \theta}{Z} & \frac{-\sin \theta}{Z} & \frac{\rho}{Z} & (1+\rho^2)\sin\theta& -(1+\rho^2)\cos\theta & 0 \\\;\\\\frac{\sin\theta}{\rho Z} & \frac{-\cos\theta}{\rho Z} & 0 & \cos\theta /\rho & \sin\theta/\rho & -1 \\\end{array} \right] \end{split}\]

where \(Z\) is the 3D depth of the considered point in the camera frame.

Two ways are allowed to initialize the feature.

• The first way by setting the feature values \((\rho,\theta,Z)\) using vpFeaturePointPolar members like set_rho() , set_theta() , set_Z() , or set_rhoThetaZ() , or also buildFrom() .

• The second way by using the feature builder functionalities to initialize the feature from a dot tracker, like vpFeatureBuilder::create ( vpFeaturePointPolar &, const vpCameraParameters &, const vpDot &) or vpFeatureBuilder::create ( vpFeaturePointPolar &, const vpCameraParameters &, const vpDot2 &). Be aware, that in that case only \((\rho,\theta)\) are initialized. You may also initialize the 3D depth \(Z\) . It is also possible to initialize the feature from a point structure, like vpFeatureBuilder::create ( vpFeaturePointPolar &, const vpPoint &) or vpFeatureBuilder::create ( vpFeaturePointPolar &, const vpCameraParameters &, const vpCameraParameters &, const vpPoint &). In that case all the feature parameters \((\rho,\theta,Z)\) would be initialized.

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 four 2D point features with polar coordinates. First we create four current features \(s\) (p var name in the code) and four desired \(s^*\) (pd var name in the code) point features with polar coordinates, set the task to use the interaction matrix associated to the current 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 initialized at the beginning.

#include <visp3/core/vpPoint.h>
#include <visp3/visual_features/vpFeatureBuilder.h>
#include <visp3/visual_features/vpFeaturePointPolar.h>
#include <visp3/vs/vpServo.h>

int main()
{
  // Create 4 points to specify the object of interest
  vpPoint point[4];

  // Set the 3D point coordinates in the object frame: oP
  point[0].setWorldCoordinates(-0.1, -0.1, 0);
  point[1].setWorldCoordinates( 0.1, -0.1, 0);
  point[2].setWorldCoordinates( 0.1,  0.1, 0);
  point[3].setWorldCoordinates(-0.1,  0.1, 0);

  // Initialize the desired pose between the camera and the object frame
  vpHomogeneousMatrix cMod;
  cMod.buildFrom(0, 0, 1, 0, 0, 0);

  // Compute the desired position of the point
  for (int i = 0 ; i < 4 ; i++) {
    // Compute the 3D point coordinates in the camera frame cP = cMod * oP
    point[i].changeFrame(cMod);
    // Compute the perspective projection to set (x,y)
    point[i].projection();
  }

  // Create 4 desired visual features as 2D points with polar coordinates
  vpFeaturePointPolar pd[4];
  // Initialize the desired visual feature from the desired point positions
  for (int i = 0 ; i < 4 ; i++)
    vpFeatureBuilder::create(pd[i], point[i]);

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

  for (int i = 0 ; i < 4 ; i++) {
    // Compute the 3D point coordinates in the camera frame cP = cMo * oP
    point[i].changeFrame(cMo);
    // Compute the perspective projection to set (x,y)
    point[i].projection();
  }
  // Create 4 current visual features as 2D points with polar coordinates
  vpFeaturePointPolar p[4];
  // Initialize the current visual feature from the current point positions
  for (int i = 0 ; i < 4 ; i++)
    vpFeatureBuilder::create(p[i], point[i]);

  // Visual servo task initialization
  vpServo task;
  // - Camera is mounted on the robot end-effector and velocities are
  //   computed in the camera frame
  task.setServo(vpServo::EYEINHAND_CAMERA);
  // - Interaction matrix is computed with the current visual features s
  task.setInteractionMatrixType(vpServo::CURRENT);
  // - Set the constant gain to 1
  task.setLambda(1);
  // - Add current and desired features
  for (int i = 0 ; i < 4 ; i++)
    task.addFeature(p[i], pd[i]);

  // Control loop
  for ( ; ; ) {
    // ... cMo need here to be estimated from for example a pose estimation.
    // Computes the point coordinates in the camera frame and its 2D
    // coordinates in the image plane
    for (int i = 0 ; i < 4 ; i++)
      point[i].track(cMo) ;

    // Update the current 2D point visual feature with polar coordinates
    for (int i = 0 ; i < 4 ; i++)
      vpFeatureBuilder::create(p[i], point[i]);

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

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

// Add the rho subset feature from the 2D point polar coordinates visual features
task.addFeature(p[i], pd[i], vpFeaturePointPolar::selectRho());

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 with polar coordinates, compute the corresponding error vector \((s-s^*)\) and finally build the interaction matrix \(L_s\) .

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

int main()
{
  // Creation of the current feature s
  vpFeaturePointPolar s;
  // Initialize the current feature
  s.buildFrom(0.1, M_PI, 1); // rho=0.1m, theta=pi, Z=1m

  // Creation of the desired feature s
  vpFeaturePointPolar s_star;
  // Initialize the desired feature
  s.buildFrom(0.15, 0, 0.8); // rho=0.15m, theta=0, Z=0.8m

  // Compute the interaction matrix L_s for the current feature
  vpMatrix L = s.interaction();

  // Compute the error vector (s-s*) for the point feature with polar coordinates
  s.error(s_star);

  return 0;
}

Default constructor that build a 2D point visual feature with polar coordinates and initialize it to \((\rho, \theta) = (0, 0)\) .

The 3D depth of the point requested in the interaction matrix (see interaction() ) is initialized to \(Z=1\) .

Methods

__init__	Default constructor that build a 2D point visual feature with polar coordinates and initialize it to \((\rho, \theta) = (0, 0)\) .
buildFrom	Build a 2D image point visual feature with polar coordinates.
display	Overloaded function.
error	Overloaded function.
get_Z	Get the 3D point depth in the camera frame.
get_rho	Get the image point \(\rho\) polar coordinate.
get_theta	Get the image point \(\theta\) polar coordinate.
init	Initialise the memory space requested for a 2D point visual feature with polar coordinates.
interaction	Compute and return the interaction matrix \(L\) associated to a subset of the possible 2D image point features with polar coordinates \((\rho,\theta)\) .
print	Print to stdout the values of the current visual feature.
selectRho	Function used to select the \(\rho\) subset polar coordinate of the image point visual feature.
selectTheta	Function used to select the \(\theta\) subset polar coordinate of the image point visual feature.
set_Z	Set the 3D point depth in the camera frame.
set_rho	Set the image point \(\rho\) polar coordinate.
set_rhoThetaZ	Initialize the image point visual feature with polar coordinates.
set_theta	Set the image point \(\theta\) polar coordinate.

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 2D point visual feature with polar coordinates and initialize it to \((\rho, \theta) = (0, 0)\) .
__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 2D point visual feature with polar coordinates and initialize it to \((\rho, \theta) = (0, 0)\) .

The 3D depth of the point requested in the interaction matrix (see interaction() ) is initialized to \(Z=1\) .

buildFrom(self, rho: float, theta: float, Z: float) → None¶

Build a 2D image point visual feature with polar coordinates.

Parameters:

rho: float¶

Polar coordinates \((\rho,\theta)\) of the image point.

theta: float¶

Polar coordinates \((\rho,\theta)\) of the image point.

dimension_s(self) → int¶

Return the dimension of the feature vector \(\bf s\) .

display(*args, **kwargs)¶

Overloaded function.

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

Display image point feature.

Parameters:

cam

Camera parameters.

I

Image.

color

Color to use for the display

thickness

Thickness of the feature representation.

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

Display image 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.

1. error(self: visp._visp.visual_features.FeaturePointPolar, 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.

For the angular component \(\theta\) , we define the error as \(\theta \ominus \theta^*\) , where \(\ominus\) is modulo \(2\pi\) subtraction.

The code below shows how to use this method to manipulate the \(\rho\) component.

vpFeaturePointPolar s;
// Creation of the current feature s
s.buildFrom(0.2, ..., 1);         // rho and Z need to be set
// Build the interaction matrix L associated to rho component
vpMatrix L_rho = s.interaction( vpFeaturePointPolar::selectRho() );

vpFeaturePointPolar s_star;
// Creation of the desired feature s*
s_star.buildFrom(0.45, ..., 1.2); // rho and Z need to be set

// Compute the error vector (s-s*) for the rho feature
vpColVector e = s.error(s_star, vpFeaturePointPolar::selectRho());

Parameters:

s_star

Desired 2D image point visual feature with polar coordinates.

select

The error can be computed for a selection of a subset of the possible 2D point polar 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 polar coordinate feature \((\rho,\theta)\) use one of the corresponding function selectRho() or selectTheta() . 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.

2. 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 3D point depth in the camera frame.

get_rho(self) → float¶

Get the image point \(\rho\) polar coordinate.

Note

See get_theta()

get_s(self, select: int = FEATURE_ALL) → visp._visp.core.ColVector¶

Get the feature vector \(\bf s\) .

get_theta(self) → float¶

Get the image point \(\theta\) polar coordinate.

Note

See get_rho()

init(self) → None¶

Initialise the memory space requested for a 2D point visual feature with polar coordinates.

By default this feature is initialized to \((\rho, \theta) = (0, 0)\) . The 3D depth of the point requested in the interaction matrix (see interaction() ) is initialized to \(Z=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 2D image point features with polar coordinates \((\rho,\theta)\) .

\[\begin{split}L = \left[ \begin{array}{l} L_{\rho} \\\; \\L_{\theta}\\\end{array} \right] = \left[ \begin{array}{cccccc} \frac{-\cos \theta}{Z} & \frac{-\sin \theta}{Z} & \frac{\rho}{Z} & (1+\rho^2)\sin\theta & -(1+\rho^2)\cos\theta & 0 \\\; \\\frac{\sin\theta}{\rho Z} & \frac{-\cos\theta}{\rho Z} & 0 & \cos\theta /\rho & \sin\theta/\rho & -1 \\\end{array} \right] \end{split}\]

where \(Z\) is the 3D depth of the considered point.

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

vpFeaturePointPolar s;
double rho   = 0.3;
double theta = M_PI;
double Z     = 1;
// Creation of the current feature s
s.buildFrom(rho, theta, Z);
// Build the interaction matrix L_s
vpMatrix L = s.interaction();

The interaction matrix could also be build by:

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

In both cases, L is a 2 by 6 matrix. The first line corresponds to the \(\rho\) visual feature while the second one to the \(\theta\) visual feature.

It is also possible to build the interaction matrix associated to one of the possible features. The code below shows how to consider only the \(\theta\) component.

vpMatrix L_theta = s.interaction( vpFeaturePointPolar::selectTheta() );

In that case, L_theta is a 1 by 6 matrix.

Parameters:

select: int = FEATURE_ALL¶

Selection of a subset of the possible polar point coordinate features.

• To compute the interaction matrix for all the two subset features \((\rho,\theta)\) 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 subset ( \(\rho,\theta\) ) use one of the corresponding function selectRho() or selectTheta() . In that case the returned interaction matrix is \([1 \times 6]\) dimension.

Returns:

The interaction matrix computed from the 2D point polar coordinate features.

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

Print to stdout the values of the current visual feature.

// Creation of the current feature s
vpFeaturePointPolar s;
s.buildFrom(0.1, M_PI_2, 1.3);

s.print(); // print all the 2 components of the image point feature
s.print(vpBasicFeature::FEATURE_ALL); // same behavior then previous line
s.print(vpFeaturePointPolar::selectRho()); // print only the rho component

Parameters:

select: int = FEATURE_ALL¶

Selection of a subset of the possible 2D image point feature coordinates.

• To print all the two polar coordinates \((\rho,\theta)\) used as features use vpBasicFeature::FEATURE_ALL .

• To print only one of the polar coordinate feature \((\rho,\theta)\) use one of the corresponding function selectRho() or selectTheta() .

static selectAll() → int¶

Select all the features.

static selectRho() → int¶

Function used to select the \(\rho\) subset polar coordinate of the image point visual feature.

This function is to use in conjunction with interaction() in order to compute the interaction matrix associated to \(\rho\) 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:

vpFeaturePointPolar p;
vpServo task;
...
// Add only the rho subset coordinate feature from an image point to the
task task.addFeature(p, vpFeaturePointPolar::selectRho());

Note

See selectTheta()

static selectTheta() → int¶

Function used to select the \(\theta\) subset polar coordinate of the image point visual feature.

This function is to use in conjunction with interaction() in order to compute the interaction matrix associated to \(\theta\) 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:

vpFeaturePointPolar p;
vpServo task;
...
// Add only the theta subset coordinate feature from an image point to the
task task.addFeature(p, vpFeaturePointPolar::selectTheta()); 

Note

See selectRho()

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 3D point depth in the camera frame.

set_rho(self, rho: float) → None¶

Set the image point \(\rho\) polar coordinate.

Note

See set_theta()

set_rhoThetaZ(self, rho: float, theta: float, Z: float) → None¶

Initialize the image point visual feature with polar coordinates.

Note

See set_rho() , set_theta() , set_Z()

Parameters:

rho: float¶

Polar coordinates \((\rho,\theta)\) of the image point.

theta: float¶

Polar coordinates \((\rho,\theta)\) of the image point.

set_theta(self, theta: float) → None¶

Set the image point \(\theta\) polar coordinate.

Note

See set_rho()