Interface for visual servoing controllers. More...

#include <yarp/dev/IVisualServoing.h>

Public Types
enum	CamSel { CamSel::left, CamSel::right }
	Enumeration class to select left or right camera. More...

Public Member Functions
virtual	~IVisualServoing ()
	Destructor. More...

virtual bool	initFacilities (bool use_direct_kin)=0
	Initialize support classes, modules and connections to perform visual servoing. More...

virtual bool	resetFacilities ()=0
	Reset support classes, modules and connections to perform visual servoing. More...

virtual bool	stopFacilities ()=0
	Deallocate support classes, stop modules and disconnect connections used for visual servoing. More...

virtual bool	goToGoal (const std::vector< yarp::sig::Vector > &vec_px_l, const std::vector< yarp::sig::Vector > &vec_px_r)=0
	Set the goal points on both left and right camera image plane and start visual servoing. More...

virtual bool	goToGoal (const yarp::sig::Vector &vec_x, const yarp::sig::Vector &vec_o)=0
	Set the goal point (3D for the position + 4D axis-angle for the orientation) and start visual servoing. More...

virtual bool	setModality (const std::string &mode)=0
	Set visual servoing operating mode between: More...

virtual bool	setVisualServoControl (const std::string &control)=0
	Set visual servo control law. More...

virtual bool	setControlPoint (const std::string &point)=0
	Set the point controlled during visual servoing. More...

virtual bool	getVisualServoingInfo (yarp::os::Bottle &info)=0
	Return useful information for visual servoing. More...

virtual bool	setGoToGoalTolerance (const double tol)=0
	Set visual servoing goal tolerance. More...

virtual bool	checkVisualServoingController ()=0
	Check once whether the visual servoing controller is running or not. More...

virtual bool	waitVisualServoingDone (const double period=0.1, const double timeout=0.0)=0
	Wait until visual servoing reaches the goal. More...

virtual bool	stopController ()=0
	Ask for an immediate stop of the visual servoing controller. More...

virtual bool	setTranslationGain (const double K_x_1, const double K_x_2)=0
	Set the translation gains of the visual servoing control algorithm. More...

virtual bool	setMaxTranslationVelocity (const double max_x_dot)=0
	Set the maximum translation velocity of the visual servoing control algorithm (same for each axis). More...

virtual bool	setTranslationGainSwitchTolerance (const double K_x_tol)=0
	Set the tolerance, in pixels, at which the translation control law swithces its gain value. More...

virtual bool	setOrientationGain (const double K_o_1, const double K_o_2)=0
	Set the orientation gains of the visual servoing control algorithm. More...

virtual bool	setMaxOrientationVelocity (const double max_o_dot)=0
	Set the maximum angular velocity of the axis-angle velocity vector of the visual servoing control algorithm. More...

virtual bool	setOrientationGainSwitchTolerance (const double K_o_tol)=0
	Set the tolerance, in pixels, at which the orientation control law swithces its gain value. More...

virtual std::vector< yarp::sig::Vector >	get3DGoalPositionsFrom3DPose (const yarp::sig::Vector &x, const yarp::sig::Vector &o)=0
	Helper function: extract four Cartesian points lying on the plane defined by the frame o in the position x relative to the robot base frame. More...

virtual std::vector< yarp::sig::Vector >	getGoalPixelsFrom3DPose (const yarp::sig::Vector &x, const yarp::sig::Vector &o, const CamSel &cam)=0
	Helper function: extract four 2D pixel points lying on the plane defined by the frame o in the position x relative to the robot base frame. More...

virtual bool	storedInit (const std::string &label)=0
	Initialize the robot to an initial position. More...

virtual bool	storedGoToGoal (const std::string &label)=0
	Set the robot visual servoing goal. More...

virtual bool	goToSFMGoal ()=0
	Get goal point from SFM module. More...

Detailed Description

Interface for visual servoing controllers.

Definition at line 29 of file IVisualServoing.h.

Member Enumeration Documentation

◆ CamSel

enum yarp::dev::IVisualServoing::CamSel

strong

Enumeration class to select left or right camera.

Enumerator
left
right

Definition at line 35 of file IVisualServoing.h.

Constructor & Destructor Documentation

◆ ~IVisualServoing()

yarp::dev::IVisualServoing::~IVisualServoing ( )

virtualdefault

Destructor.

Member Function Documentation

◆ checkVisualServoingController()

virtual bool yarp::dev::IVisualServoing::checkVisualServoingController ( )

pure virtual

Check once whether the visual servoing controller is running or not.

Returns: true/false on it is running/not running.

Note: The visual servoing controller may be terminated due to many different reasons, not strictly related to reaching the goal.

◆ get3DGoalPositionsFrom3DPose()

virtual std::vector<yarp::sig::Vector> yarp::dev::IVisualServoing::get3DGoalPositionsFrom3DPose	(	const yarp::sig::Vector &	x,
		const yarp::sig::Vector &	o
	)

pure virtual

Helper function: extract four Cartesian points lying on the plane defined by the frame o in the position x relative to the robot base frame.

Parameters

x	a 3D vector which is filled with the actual position (x, y, z) [m].
o	a 4D vector which is filled with the actual orientation using axis-angle representation (xa, ya, za) and (theta) [rad].

Returns: on success: a collection of four Cartesian points (position only) extracted from the plane defined by x and o; on failure: an empty list.

◆ getGoalPixelsFrom3DPose()

virtual std::vector<yarp::sig::Vector> yarp::dev::IVisualServoing::getGoalPixelsFrom3DPose	(	const yarp::sig::Vector &	x,
		const yarp::sig::Vector &	o,
		const CamSel &	cam
	)

pure virtual

Helper function: extract four 2D pixel points lying on the plane defined by the frame o in the position x relative to the robot base frame.

Parameters

x	a 3D vector which is filled with the actual position (x, y, z) [m].
o	a 4D vector which is filled with the actual orientation using axis-angle representation (xa, ya, za) and (theta) [m]/[rad].
cam	either "left" or "right" to select left or right camera.

Returns: on success: a collection of three (u, v) pixel points extracted from the plane defined by x and o; on failure: an empty list.

◆ getVisualServoingInfo()

virtual bool yarp::dev::IVisualServoing::getVisualServoingInfo ( yarp::os::Bottle & info )

pure virtual

Return useful information for visual servoing.

Parameters

info	YARP Bottle cotaining all the visual servoing information.

Returns: true/false on success/failure.

◆ goToGoal() [1/2]

virtual bool yarp::dev::IVisualServoing::goToGoal	(	const std::vector< yarp::sig::Vector > &	vec_px_l,
		const std::vector< yarp::sig::Vector > &	vec_px_r
	)

pure virtual

Set the goal points on both left and right camera image plane and start visual servoing.

Parameters

vec_px_l	a collection of four 2D vectors which contains the (u, v) coordinates of the pixels within the left image plane.
vec_px_r	a collection of four 2D vectors which contains the (u, v) coordinates of the pixels within the right image plane.

Note: By invoking this method, the visual servoing goal will be reached in orientation first, then in position. This is because there may not be a feasible position solution for every possible orientation.

Returns: true/false on success/failure.

◆ goToGoal() [2/2]

virtual bool yarp::dev::IVisualServoing::goToGoal	(	const yarp::sig::Vector &	vec_x,
		const yarp::sig::Vector &	vec_o
	)

pure virtual

Set the goal point (3D for the position + 4D axis-angle for the orientation) and start visual servoing.

Parameters

vec_x	a 3D vector which contains the (x, y, z) Cartesian coordinates of the goal.
vec_o	a 4D vector which contains the (x, y, z) axis and theta angle of rotation of the goal.

Note: By invoking this method, the visual servoing goal will be reached in position and orientation together with two parallel tasks.

Returns: true/false on success/failure.

◆ goToSFMGoal()

virtual bool yarp::dev::IVisualServoing::goToSFMGoal ( )

pure virtual

Get goal point from SFM module.

The point is taken by clicking on a dedicated 'yarpview' GUI and the orientation is hard-coded.

Note: This service is experimental and should be used with care.

Returns: true upon success, false otherwise.

◆ initFacilities()

virtual bool yarp::dev::IVisualServoing::initFacilities ( bool use_direct_kin )

pure virtual

Initialize support classes, modules and connections to perform visual servoing.

This method must be called before any other visual servoing methods. Returns upon successful or failure setup.

Parameters

use_direct_kin instruct the visual servoing control to either use direct kinematic or an estimated/refined pose of the end-effector.

Returns: true/false on success/failure.

◆ resetFacilities()

virtual bool yarp::dev::IVisualServoing::resetFacilities ( )

pure virtual

Reset support classes, modules and connections to perform visual servoing.

Returns upon successful or failure setup.

Returns: true/false on success/failure.

◆ setControlPoint()

virtual bool yarp::dev::IVisualServoing::setControlPoint ( const std::string & point )

pure virtual

Set the point controlled during visual servoing.

Parameters

point label of the point to control.

Returns: true/false on success/failure.

Note: The points available to control are identified by a distinct, unique label. Such labels can are stored in the bottle returned by the getInfo() method.

◆ setGoToGoalTolerance()

virtual bool yarp::dev::IVisualServoing::setGoToGoalTolerance ( const double tol )

pure virtual

Set visual servoing goal tolerance.

Parameters

tol	the tolerance in pixel.

Returns: true/false on success/failure.

◆ setMaxOrientationVelocity()

virtual bool yarp::dev::IVisualServoing::setMaxOrientationVelocity ( const double max_o_dot )

pure virtual

Set the maximum angular velocity of the axis-angle velocity vector of the visual servoing control algorithm.

Parameters

max_x_dot the maximum allowed angular velocity [rad/s].

Returns: true/false on success/failure.

◆ setMaxTranslationVelocity()

virtual bool yarp::dev::IVisualServoing::setMaxTranslationVelocity ( const double max_x_dot )

pure virtual

Set the maximum translation velocity of the visual servoing control algorithm (same for each axis).

Parameters

max_x_dot the maximum allowed velocity for x, y, z coordinates [m/s].

Returns: true/false on success/failure.

◆ setModality()

virtual bool yarp::dev::IVisualServoing::setModality ( const std::string & mode )

pure virtual

Set visual servoing operating mode between:

'position': position-only visual servo control;
'orientation': orientation-only visual servo control;
'pose': position + orientation visual servo control.

Parameters

mode	a label referring to one of the three operating mode, i.e. 'position', 'orientation' or 'pose'.

Returns: true/false on success/failure.

◆ setOrientationGain()

virtual bool yarp::dev::IVisualServoing::setOrientationGain	(	const double	K_o_1,
		const double	K_o_2
	)

pure virtual

Set the orientation gains of the visual servoing control algorithm.

The two values are used, respectively, when the end-effector is far away from and close to the goal.

Returns: true/false on success/failure.

Note: Warning: higher values of the gain corresponds to higher orientation velocities and oscillation about the goal.

◆ setOrientationGainSwitchTolerance()

virtual bool yarp::dev::IVisualServoing::setOrientationGainSwitchTolerance ( const double K_o_tol )

pure virtual

Set the tolerance, in pixels, at which the orientation control law swithces its gain value.

Returns: true/false on success/failure.

◆ setTranslationGain()

virtual bool yarp::dev::IVisualServoing::setTranslationGain	(	const double	K_x_1,
		const double	K_x_2
	)

pure virtual

Set the translation gains of the visual servoing control algorithm.

The two values are used, respectively, when the end-effector is far away from and close to the goal.

Returns: true/false on success/failure.

Note: Warning: higher values of the gain corresponds to higher translation velocities and oscillation about the goal.

◆ setTranslationGainSwitchTolerance()

virtual bool yarp::dev::IVisualServoing::setTranslationGainSwitchTolerance ( const double K_x_tol )

pure virtual

Set the tolerance, in pixels, at which the translation control law swithces its gain value.

Returns: true/false on success/failure.

◆ setVisualServoControl()

virtual bool yarp::dev::IVisualServoing::setVisualServoControl ( const std::string & control )

pure virtual

Set visual servo control law.

The available control law are implementation dependent. Check the used implementation to know which ones are available.

Parameters

mode	a label referring to one of the visual servo controls.

Returns: true/false on success/failure.

◆ stopController()

virtual bool yarp::dev::IVisualServoing::stopController ( )

pure virtual

Ask for an immediate stop of the visual servoing controller.

[wait for reply]

Returns: true/false on success/failure.

◆ stopFacilities()

virtual bool yarp::dev::IVisualServoing::stopFacilities ( )

pure virtual

Deallocate support classes, stop modules and disconnect connections used for visual servoing.

This method must be called when visual servoing is no longer needed or a new visual servoing instance is needed.

Returns: true/false on success/failure.

◆ storedGoToGoal()

virtual bool yarp::dev::IVisualServoing::storedGoToGoal ( const std::string & label )

pure virtual

Set the robot visual servoing goal.

The goals are stored on an external file and are referenced by a unique label.

Parameters

label a label referring to one of the available goals; the string shall be one of the available modes returned by the get_info() method.

Returns: true upon success, false otherwise.

◆ storedInit()

virtual bool yarp::dev::IVisualServoing::storedInit ( const std::string & label )

pure virtual

Initialize the robot to an initial position.

The initial positions are stored on an external file and are referenced by a unique label.

Parameters

label a label referring to one of the available initial positions; the string shall be one of the available modes returned by the get_info() method.

Returns: true upon success, false otherwise.

◆ waitVisualServoingDone()

virtual bool yarp::dev::IVisualServoing::waitVisualServoingDone	(	const double	period = `0.1`,
		const double	timeout = `0.0`
	)

pure virtual

Wait until visual servoing reaches the goal.

[wait for reply]

Parameters

period	the check time period [s].
timeout	the check expiration time [s]. If timeout <= 0 (as by default) the check will be performed without time limitation.

Returns: true for success, false for failure and timeout expired.

Note: The tolerance to which the goal is considered achieved can be set with the method setGoToGoalTolerance().

The documentation for this class was generated from the following files:

src/libYARP_dev/src/yarp/dev/IVisualServoing.h
src/libYARP_dev/src/yarp/dev/IVisualServoing.cpp

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ CamSel

Constructor & Destructor Documentation

◆ ~IVisualServoing()

Member Function Documentation

◆ checkVisualServoingController()

◆ get3DGoalPositionsFrom3DPose()

◆ getGoalPixelsFrom3DPose()

◆ getVisualServoingInfo()

◆ goToGoal() [1/2]

◆ goToGoal() [2/2]

◆ goToSFMGoal()

◆ initFacilities()

◆ resetFacilities()

◆ setControlPoint()

◆ setGoToGoalTolerance()

◆ setMaxOrientationVelocity()

◆ setMaxTranslationVelocity()

◆ setModality()

◆ setOrientationGain()

◆ setOrientationGainSwitchTolerance()

◆ setTranslationGain()

◆ setTranslationGainSwitchTolerance()

◆ setVisualServoControl()

◆ stopController()

◆ stopFacilities()

◆ storedGoToGoal()

◆ storedInit()

◆ waitVisualServoingDone()