#include <vpAdaptiveGain.h>

Public Member Functions
	vpAdaptiveGain ()

	vpAdaptiveGain (double c)

	vpAdaptiveGain (double gain_at_zero, double gain_at_infinity, double slope_at_zero)

void	initFromConstant (double c)

void	initFromVoid (void)

void	initStandard (double gain_at_zero, double gain_at_infinity, double slope_at_zero)

double	setConstant (void)

double	value_const (double x) const

double	value (double x) const

double	limitValue_const (void) const

double	limitValue (void) const

double	getLastValue (void) const

double	operator() (double x) const

double	operator() (const vpColVector &x) const

double	operator() (void) const

Static Public Attributes
static const double	DEFAULT_LAMBDA_ZERO = 1.666

static const double	DEFAULT_LAMBDA_INFINITY = 0.1666

static const double	DEFAULT_LAMBDA_SLOPE = 1.666

Friends
VISP_EXPORT std::ostream &	operator<< (std::ostream &os, const vpAdaptiveGain &lambda)

Detailed Description

Adaptive gain computation.

As described in [Kermorgant14a], a varying gain $\lambda$ could be used in the visual servoing control law

${\bf v}_c = -\lambda {\bf L}^{+}_{e} {\bf e}$

with

$\lambda (|| {\bf e}||) = (\lambda_0 - \lambda_\infty) e^{ -\frac{ \lambda'_0}{\lambda_0 - \lambda_\infty}||{\bf e}||} + \lambda_\infty$

where:

$\lambda_0 = \lambda(0)$ is the gain in 0, that is for very small values of $||{\bf e}||$
$\lambda_\infty = \lambda_{||{\bf e}|| \rightarrow \infty}\lambda(||{\bf e}||)$ is the gain to infinity, that is for very high values of $||{\bf e}||$
$\lambda'_0$ is the slope of $\lambda$ at $||{\bf e}|| = 0$

As described in Tutorial: How to boost your visual servo control law, the interest of Using an adaptive gain is to reduce the time to convergence in order to speed up the servo.

The following example shows how to use this class in order to use an adaptive gain with the following parameters $\lambda_0 = 4$ , $\lambda_\infty = 0.4$ and $\lambda'_0 = 30$ .

#include <visp3/vs/vpAdaptiveGain.h>
#include <visp3/vs/vpServo.h>
 
int main()
{
  vpAdaptiveGain lambda(4, 0.4, 30);   // lambda(0)=4, lambda(oo)=0.4 and lambda'(0)=30
 
  vpServo servo;
  servo.setLambda(lambda);
 
  while(1) {
 
    vpColVector v = servo.computeControlLaw();
  }
}

This other example shows how to use this class in order to set a constant gain $\lambda = 0.5$ that will ensure an exponential decrease of the task error.

#include <visp3/vs/vpAdaptiveGain.h>
#include <visp3/vs/vpServo.h>
 
int main()
{
  vpAdaptiveGain lambda(0.5);
 
  vpServo servo;
  servo.setLambda(lambda);
 
  while(1) {
 
    vpColVector v = servo.computeControlLaw();
  }
}

Examples: mbot-apriltag-2D-half-vs.cpp, mbot-apriltag-ibvs.cpp, mbot-apriltag-pbvs.cpp, servoAfma4Point2DCamVelocityKalman.cpp, servoBebop2.cpp, servoFlirPtuIBVS.cpp, servoFrankaIBVS.cpp, servoFrankaPBVS.cpp, servoViper850Point2DCamVelocityKalman.cpp, tutorial-ibvs-4pts-plotter-continuous-gain-adaptive.cpp, and tutorial-ibvs-4pts-plotter-gain-adaptive.cpp.

Definition at line 120 of file vpAdaptiveGain.h.

Constructor & Destructor Documentation

◆ vpAdaptiveGain() [1/3]

vpAdaptiveGain::vpAdaptiveGain ( )

Basic constructor which initializes all the parameters with their default value:

$\lambda_0 = 1.666$ using vpAdaptiveGain::DEFAULT_LAMBDA_ZERO
$\lambda_\infty = 0.1666$ using vpAdaptiveGain::DEFAULT_LAMBDA_INFINITY
$\lambda'_0 = 1.666$ using vpAdaptiveGain::DEFAULT_LAMBDA_SLOPE

Definition at line 70 of file vpAdaptiveGain.cpp.

◆ vpAdaptiveGain() [2/3]

vpAdaptiveGain::vpAdaptiveGain ( double c )

explicit

Constructor that initializes the gain as constant. In that case $\lambda(||{\bf e}||) = c$ .

Parameters

c	: Value of the constant gain. A typical value is 0.5.

Definition at line 83 of file vpAdaptiveGain.cpp.

◆ vpAdaptiveGain() [3/3]

vpAdaptiveGain::vpAdaptiveGain	(	double	gain_at_zero,
		double	gain_at_infinity,
		double	slope_at_zero
	)

Constructor that initializes the gain as adaptive.

Parameters

gain_at_zero	: the expected gain when $\|\|{\bf e}\|\|=0$ : $\lambda_0$ .
gain_at_infinity	: the expected gain when $\|\|{\bf e}\|\|\rightarrow\infty$ : $\lambda_\infty$ .
slope_at_zero	: the expected slope of $\lambda(\|\|{\bf e}\|\|)$ when $\|\|{\bf e}\|\|=0$ : $\lambda'_0$ .

Definition at line 95 of file vpAdaptiveGain.cpp.

Member Function Documentation

◆ getLastValue()

double vpAdaptiveGain::getLastValue ( void ) const

inline

Gets the last adaptive gain value which was stored in the class.

Returns: It returns the last adaptive gain value which was stored in the class.

Definition at line 194 of file vpAdaptiveGain.h.

◆ initFromConstant()

void vpAdaptiveGain::initFromConstant ( double c )

Initializes the parameters to have a constant gain. In that case $\lambda(||{\bf e}||) = c$ .

Parameters

c	: Value of the constant gain. A typical value is 0.5.

Examples: servoAfma4Point2DCamVelocityKalman.cpp.

Definition at line 114 of file vpAdaptiveGain.cpp.

◆ initFromVoid()

void vpAdaptiveGain::initFromVoid ( void )

Initializes the parameters with the default value :

$\lambda_0 = 1.666$ using vpAdaptiveGain::DEFAULT_LAMBDA_ZERO
$\lambda_\infty = 0.1666$ using vpAdaptiveGain::DEFAULT_LAMBDA_INFINITY
$\lambda'_0 = 1.666$ using vpAdaptiveGain::DEFAULT_LAMBDA_SLOPE

Definition at line 129 of file vpAdaptiveGain.cpp.

◆ initStandard()

void vpAdaptiveGain::initStandard	(	double	gain_at_zero,
		double	gain_at_infinity,
		double	slope_at_zero
	)

Set the parameters $\lambda_0, \lambda_\infty, \lambda'_0$ used to compute $\lambda(||{\bf e}||)$ .

Parameters

gain_at_zero	: the expected gain when $\|\|{\bf e}\|\|=0$ : $\lambda_0$ .
gain_at_infinity	: the expected gain when $\|\|{\bf e}\|\|\rightarrow\infty$ : $\lambda_\infty$ .
slope_at_zero	: the expected slope of $\lambda(\|\|{\bf e}\|\|)$ when $\|\|{\bf e}\|\|=0$ : $\lambda'_0$ .

Examples: mbot-apriltag-2D-half-vs.cpp, mbot-apriltag-ibvs.cpp, mbot-apriltag-pbvs.cpp, servoAfma4Point2DCamVelocityKalman.cpp, and servoViper850Point2DCamVelocityKalman.cpp.

Definition at line 146 of file vpAdaptiveGain.cpp.

◆ limitValue()

double vpAdaptiveGain::limitValue ( void ) const

Gets the value of the gain at infinity (ie the value of $\lambda_\infty = c$ ) and stores it as a parameter of the class.

Returns: It returns the value of the gain at infinity.

Definition at line 251 of file vpAdaptiveGain.cpp.

◆ limitValue_const()

double vpAdaptiveGain::limitValue_const ( void ) const

Gets the value of the gain at infinity (ie the value of $\lambda_\infty = c$ ). This function is similar to limitValue() except that here the value is not stored as a parameter of the class.

Returns: It returns the value of the gain at infinity.

Definition at line 217 of file vpAdaptiveGain.cpp.

◆ operator()() [1/3]

double vpAdaptiveGain::operator() ( const vpColVector & x ) const

Operator which computes $\lambda({||x||}_{\infty})$ where

$\lambda ({||x||}_{\infty}) = (\lambda_0 - \lambda_\infty) e^{ -\frac{ \lambda'_0}{\lambda_0 - \lambda_\infty}{||x||}_{\infty}} + \lambda_\infty$

Parameters

x	: Input vector $\bf x$ to consider.

Returns: It returns the value of the computed gain.

Definition at line 302 of file vpAdaptiveGain.cpp.

◆ operator()() [2/3]

double vpAdaptiveGain::operator() ( double x ) const

Operator that computes $\lambda(x)$ where

$\lambda (x) = (\lambda_0 - \lambda_\infty) e^{ -\frac{ \lambda'_0}{\lambda_0 - \lambda_\infty}x} + \lambda_\infty$

Parameters

x	: Input value to consider. During a visual servo this value can be the euclidian norm $\|\|{\bf e}\|\|$ or the infinity norm $\|\|{\bf e}\|\|_{\infty}$ of the task function.

Returns: It returns the value of the computed gain.

See also: value()

Definition at line 279 of file vpAdaptiveGain.cpp.

◆ operator()() [3/3]

double vpAdaptiveGain::operator() ( void ) const

Gets the value of the gain at infinity (ie the value of $\lambda_\infty = c$ ).

Returns: It returns the value of the gain at infinity.

See also: limitValue()

Definition at line 289 of file vpAdaptiveGain.cpp.

◆ setConstant()

double vpAdaptiveGain::setConstant ( void )

Sets the internal parameters in order to obtain a constant gain equal to the gain in 0 set through the parameter $\lambda_0$ .

Returns: It returns the value of the constant gain $\lambda_0$ .

Definition at line 173 of file vpAdaptiveGain.cpp.

◆ value()

double vpAdaptiveGain::value ( double x ) const

Computes the value of the adaptive gain $\lambda(x)$ using:

$\lambda (x) = (\lambda_0 - \lambda_\infty) e^{ -\frac{ \lambda'_0}{\lambda_0 - \lambda_\infty}x} + \lambda_\infty$

This value is stored as a parameter of the class.

Parameters

x	: Input value to consider. During a visual servo this value can be the euclidian norm $\|\|{\bf e}\|\|$ or the infinity norm $\|\|{\bf e}\|\|_{\infty}$ of the task function.

Returns: It returns the value of the computed gain.

Definition at line 238 of file vpAdaptiveGain.cpp.

◆ value_const()

double vpAdaptiveGain::value_const ( double x ) const

Computes the value of the adaptive gain $\lambda(x)$ using:

$\lambda (x) = (\lambda_0 - \lambda_\infty) e^{ -\frac{ \lambda'_0}{\lambda_0 - \lambda_\infty}x} + \lambda_\infty$

Parameters

x	: Input value to consider. During a visual servo this value can be the euclidian norm $\|\|{\bf e}\|\|$ or the infinity norm $\|\|{\bf e}\|\|_{\infty}$ of the task function.

Returns: It returns the value of the computed gain.

Definition at line 203 of file vpAdaptiveGain.cpp.

Friends And Related Function Documentation

◆ operator<<

VISP_EXPORT std::ostream& operator<<	(	std::ostream &	os,
		const vpAdaptiveGain &	lambda
	)

friend

Prints the adaptive gain parameters $\lambda_0, \lambda_\infty, \lambda'_0$ .

Parameters

os	: The stream where to print the adaptive gain parameters.
lambda	: The adaptive gain containing the parameters to print.

Definition at line 318 of file vpAdaptiveGain.cpp.

Member Data Documentation

◆ DEFAULT_LAMBDA_INFINITY

const double vpAdaptiveGain::DEFAULT_LAMBDA_INFINITY = 0.1666

static

Definition at line 124 of file vpAdaptiveGain.h.

◆ DEFAULT_LAMBDA_SLOPE

const double vpAdaptiveGain::DEFAULT_LAMBDA_SLOPE = 1.666

static

Definition at line 125 of file vpAdaptiveGain.h.

◆ DEFAULT_LAMBDA_ZERO

const double vpAdaptiveGain::DEFAULT_LAMBDA_ZERO = 1.666

static

Definition at line 123 of file vpAdaptiveGain.h.

Public Member Functions

Static Public Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

◆ vpAdaptiveGain() [1/3]

◆ vpAdaptiveGain() [2/3]

◆ vpAdaptiveGain() [3/3]

Member Function Documentation

◆ getLastValue()

◆ initFromConstant()

◆ initFromVoid()

◆ initStandard()

◆ limitValue()

◆ limitValue_const()

◆ operator()() [1/3]

◆ operator()() [2/3]

◆ operator()() [3/3]

◆ setConstant()

◆ value()

◆ value_const()

Friends And Related Function Documentation

◆ operator<<

Member Data Documentation

◆ DEFAULT_LAMBDA_INFINITY

◆ DEFAULT_LAMBDA_SLOPE

◆ DEFAULT_LAMBDA_ZERO