FeatureLine¶

class FeatureLine(self)¶

Bases: BasicFeature

Class that defines a 2D line visual feature \(s\) which is composed by two parameters that are \(\rho\) and \(\theta\) , the polar coordinates of a line.

In this class, the equation of the line in the image plane is given by :

\[x \; cos(\theta) + y \; sin(\theta) -\rho = 0 \]

Here \(x\) and \(y\) are the coordinates of a point belonging to the line and they are given in meter. The following image shows the meanings of the distance \(\rho\) and the angle \(\theta\) .

You have to note that the \(\theta\) angle has its value between \(-\pi\) and \(\pi\) and that the \(\rho\) distance can be positive or negative. The conventions are illustrated by the image above.

The visual features can be set easily from an instance of the classes vpLine , vpMeLine or vpCylinder . For more precision see the class vpFeatureBuilder .

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 line feature \((\rho,\theta)\) that correspond to the 2D equation of a line in the image plan. To control six degrees of freedom, at least four other features must be considered like two other line features for example. First we create a current ( \(s\) ) 2D line 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/vpFeatureLine.h>
#include <visp3/vs/vpServo.h>

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

  vpFeatureLine sd; //The desired line feature.
  // Sets the desired features rho and theta
  double rhod = 0;
  double thetad = 0;
  // Sets the parameters which describe the equation of a plane in the camera frame : AX+BY+CZ+D=0.
  // The line described by the features belongs to this plan.
  // Normally two plans are needed to describe a line. But to compute the interaction matrix only
  // one equation of the two plans is needed.
  // Notes that the Dd value must not be equal to zero !
  double Ad = 0;
  double Bd = 0;
  double Cd = 1;
  double Dd = -1;
  // Set the line feature thanks to the desired parameters.
  sd.buildfrom(rhod, thetad, Ad,Bd, Cd, Dd);

  vpFeatureLine s; //The current line feature.
  // Sets the current features rho and theta
  double rho;    // You have to compute the value of rho.
  double theta;  // You have to compute the value of theta.
  // Set the line feature thanks to the current parameters.
  s.buildfrom(rho, theta);
  // In this case the parameters A, B, C, D are not needed 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 line feature to the task
  task.addFeature(s, sd);

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

    // Update the current line visual feature
    s.buildfrom(rho, theta);

    // 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 line 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/vpFeatureLine.h>

int main()
{
  vpFeatureLine sd; //The desired line feature.
  // Sets the desired features rho and theta
  double rhod = 0;
  double thetad = 0;
  // Sets the parameters which describe the equation of a plane in the camera frame : AX+BY+CZ+D=0.
  double Ad = 0; double Bd = 0; double Cd = 1; double Dd = -1;
  // Set the line feature thanks to the desired parameters.
  sd.buildfrom(rhod, thetad, Ad,Bd, Cd, Dd);

  vpFeatureLine s; // The current line feature.
  // Sets the current features rho and theta
  double rho;    // You have to compute the value of rho.
  double theta;  // You have to compute the value of theta.
  // Sets the parameters which describe the equation of a plane in the camera frame : AX+BY+CZ+D=0.
  double A;  // You have to compute the value of A.
  double B;  // You have to compute the value of B.
  double C;  // You have to compute the value of C.
  double D;  // You have to compute the value of D. D must not be equal to zero !
  // Set the line feature thanks to the current parameters.
  s.buildfrom(rho, theta, A, B, C, D);

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

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

Default constructor that build a visual feature.

Methods

`__init__`	Default constructor that build a visual feature.
`buildFrom`	Overloaded function.
`display`	Overloaded function.
`error`	Overloaded function.
`getRho`	Return the \(\rho\) subset value of the visual feature \(s\) .
`getTheta`	Return the \(\theta\) subset value of the visual feature \(s\) .
`init`	Initialize the memory space requested for 2D line visual feature.
`interaction`	Compute and return the interaction matrix \(L\) .
`print`	Print to stdout the values of the current visual feature \(s\) .
`selectRho`	Function used to select the \(\rho\) subset of the line visual feature.
`selectTheta`	Function used to select the \(\theta\) subset of the line visual feature.
`setABCD`	Sets the values of A, B, C and D which represent the parameters used to describe the equation of a plan in the camera frame.
`setRhoTheta`	Sets the values of \(\rho\) and \(\theta\) which represent the parameters of the 2D line feature.

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 visual feature.
`__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 visual feature.

buildFrom(*args, **kwargs)¶

Overloaded function.

buildFrom(self: visp._visp.visual_features.FeatureLine, rho: float, theta: float) -> None

Build a 2D line visual feature from the line equation parameters \(\rho\) and \(\theta\) given in the image plan.

\[x \; cos(\theta) + y \; sin(\theta) -\rho = 0 \]

See the vpFeatureLine class description for more details about \(\rho\) and \(\theta\) .

Parameters:

rho: The \(\rho\) parameter.
theta: The \(\theta\) parameter.

buildFrom(self: visp._visp.visual_features.FeatureLine, rho: float, theta: float, A: float, B: float, C: float, D: float) -> None

Build a 2D line visual feature from the line equation parameters \(\rho\) and \(\theta\) given in the image plan. The parameters A, B, C and D which describe the equation of a plan to which the line belongs, are set in the same time.

\[x \; cos(\theta) + y \; sin(\theta) -\rho = 0 \]

\[AX + BY + CZ + D = 0 \]

See the vpFeatureLine class description for more details about \(\rho\) and \(\theta\) .

The A, B, C, D parameters are needed to compute the interaction matrix associated to a visual feature. Normally, two plans are needed to describe a line (the intersection of those two plans). But to compute the interaction matrix only one plan equation is required. The only one restrictions is that the value of D must not be equal to zero !

Parameters:

rho: The \(\rho\) parameter.
theta: The \(\theta\) parameter.

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

display(*args, **kwargs)¶

Overloaded function.

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

Display line feature.

Parameters:

cam: Camera parameters.
I: Image on which features have to be displayed.
color: Color used to display the feature.
thickness: Thickness of the feature representation.

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

Display line feature.

Parameters:

cam: Camera parameters.
I: Color image on which features have to be displayed.
color: Color used to display the feature.
thickness: Thickness of the feature representation.

error(*args, **kwargs)¶

Overloaded function.

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

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

// Creation of the desired feature s*
vpFeatureLine s_star;
s_star.buildFrom(0, 0, 0, 0, 1, -5);

// Compute the interaction matrix for the theta feature
vpMatrix L_theta = s.interaction( vpFeatureLine::selectTheta() );

// Compute the error vector (s-s*) for the Theta feature
s.error(s_star, vpFeatureLine::selectTheta());

Parameters:

s_star

Desired visual feature.

select

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

To compute the error for all the two line 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 line component 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.

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.

getRho(self) → float¶: Return the \(\rho\) subset value of the visual feature \(s\) .

getTheta(self) → float¶: Return the \(\theta\) subset value of the visual feature \(s\) .

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

init(self) → None¶: Initialize the memory space requested for 2D line 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 line feature \(\rho\) and \(\theta\) and the equation of a plan to which the line belongs.

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

Where :

\[\lambda_{\rho} = (A \; \rho \; cos(\theta) + B \; \rho \; sin(\theta) + C) / D \]

\[\lambda_{\theta} = (A \; sin(\theta) - B \; cos(\theta)) / D \]

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

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

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

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

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

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

Parameters:

select: int = FEATURE_ALL¶

Selection of a subset of the possible line features.

To compute the interaction matrix for all the two line 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 line component feature ( \(\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 line features.

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

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

vpFeatureLine s; // Current visual feature s

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

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

Parameters:

select: int = FEATURE_ALL¶

Selection of a subset of the possible line features.

To print all the two line features use vpBasicFeature::FEATURE_ALL .
To print only one of the line component 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 of the line visual feature.

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

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:

vpFeatureLine s;
vpServo task;
...
// Add the (rho) subset features from the 2D line
task.addFeature(s, vpFeatureLine::selectRho());

static selectTheta() → int¶

Function used to select the \(\theta\) subset of the line visual feature.

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

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:

vpFeatureLine s;
vpServo task;
...
// Add the (rho) subset features from the 2D line
task.addFeature(s, vpFeatureLine::selectTheta());

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

Sets the values of A, B, C and D which represent the parameters used to describe the equation of a plan in the camera frame.

\[AX + BY + CZ + D = 0 \]

Those parameters are needed to compute the interaction matrix associated to a visual feature. Normally, two plans are needed to describe a line (the intersection of those two plans). But to compute the interaction matrix only one plan equation is required. The only one restrictions is that the value of D must not be equal to zero !

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.

setRhoTheta(self, rho: float, theta: float) → None¶

Sets the values of \(\rho\) and \(\theta\) which represent the parameters of the 2D line feature.

Parameters:

rho: float¶: math:rho value to set.
theta: float¶: math:theta value to set.