The VirtualToolCoupler couples a rigid object to an input/output device through a spring and damper. More...

#include <VirtualToolCoupler.h>

Inheritance diagram for SurgSim::Physics::VirtualToolCoupler:

Public Member Functions
	VirtualToolCoupler (const std::string &name)
	Constructor. More...

	SURGSIM_CLASSNAME (SurgSim::Physics::VirtualToolCoupler)

const std::shared_ptr< Framework::Component >	getInput ()

void	setInput (const std::shared_ptr< Framework::Component > input)
	Set the Input Component. More...

const std::shared_ptr< Framework::Component >	getOutput ()

void	setOutput (const std::shared_ptr< Framework::Component > output)
	Set the Output Component (if any) More...

const std::shared_ptr< Framework::Component >	getRepresentation ()

void	setRepresentation (const std::shared_ptr< Framework::Component > rigid)
	Set the Physics Representation which follows the input. More...

bool	isHapticOutputOnlyWhenColliding () const
	Get whether or not the haptic forces should be provided only during collisions. More...

void	setHapticOutputOnlyWhenColliding (bool haptic)
	Set whether or not the haptic forces should be provided only during collisions. More...

const std::string &	getPoseName ()

void	setPoseName (const std::string &poseName=DataStructures::Names::POSE)
	Set the name of the pose entry in the input DataGroup. More...

void	update (double dt) override
	Update the behavior. More...

void	overrideLinearStiffness (double linearStiffness)
	Override the linear stiffness connecting the input device and the physics representation If this value is not provided, the stiffness will be automatically tuned using the properties of the Representation. More...

double	getLinearStiffness ()

void	overrideLinearDamping (double linearDamping)
	Override the linear damping connecting the input device and the physics representation If this value is not provided, the damping will be automatically tuned using the properties of the Representation. More...

double	getLinearDamping ()

void	overrideAngularStiffness (double angularStiffness)
	Override the angular stiffness connecting the input device and the physics representation If this value is not provided, the stiffness will be automatically tuned using the properties of the Representation. More...

double	getAngularStiffness ()

void	overrideAngularDamping (double angularDamping)
	Override the angular damping connecting the input device and the physics representation If this value is not provided, the damping will be automatically tuned using the properties of the Representation. More...

double	getAngularDamping ()

void	overrideAttachmentPoint (const Math::Vector3d &attachment)
	Override the point of attachment to the Representation If this value is not provided, the point of attachment will be automatically set to the Representation's center of mass. More...

const Math::Vector3d &	getAttachmentPoint ()
	Get the point of attachment on the Representation. More...

void	setCalculateInertialTorques (bool calculateInertialTorques)
	Enable/disable torques that simulate inertia. More...

bool	getCalculateInertialTorques () const
	Get whether the calculated torques will simulate inertia. More...

void	setInitializeRigidWithInputPose (bool val)
	Set whether the pose of the attached rigid is initialized with the first input pose received by the VTC this will 'teleport' the rigid into the first pose of the vtc. More...

bool	isInitializingRigidWithInputPose () const
	Get whether the pose of the attached rigid is initialized with the first input pose received by the VTC. More...

void	doRetire () override
	Interface to be implemented by derived classes Has a default implementation, does nothing.

void	setLocalActive (bool val) override
	Set the component's active state. More...

Public Member Functions inherited from SurgSim::Framework::Behavior
	Behavior (const std::string &name)

Public Member Functions inherited from SurgSim::Framework::Component
	Component (const std::string &name)
	Constructor. More...

virtual	~Component ()
	Destructor.

std::string	getName () const
	Gets component name. More...

std::string	getFullName () const
	Gets a string containing the name of the Component and (if it has one) its SceneElement. More...

void	setName (const std::string &name)
	Sets the name of component. More...

boost::uuids::uuid	getUuid () const
	Gets the id of the component.

bool	isInitialized () const

bool	initialize (const std::weak_ptr< Runtime > &runtime)
	Initialize this component, this needs to be called before wakeUp() can be called. More...

bool	isAwake () const

bool	wakeUp ()
	Wakeup this component, this will be called when the component is inserted into the ComponentManager that is responsible for handling this component. More...

void	retire ()
	Retire this component, this will be called when the component is removed from the ComponentManager that is responsible for handling this component. More...

void	setScene (std::weak_ptr< Scene > scene)
	Sets the scene. More...

std::shared_ptr< Scene >	getScene ()
	Gets the scene. More...

void	setSceneElement (std::weak_ptr< SceneElement > sceneElement)
	Sets the scene element. More...

std::shared_ptr< SceneElement >	getSceneElement ()
	Gets the scene element. More...

std::shared_ptr< const SceneElement >	getSceneElement () const
	Gets the scene element, constant version. More...

std::shared_ptr< Runtime >	getRuntime () const
	Get the runtime which contains this component. More...

virtual std::string	getClassName () const
	The class name for this class, this being the base class it should return SurgSim::Framework::Component but this would make missing implemenentations of this hard to catch, therefore this calls SURGSIM_FAILURE. More...

std::shared_ptr< Component >	getSharedPtr ()
	Gets a shared pointer to this component. More...

bool	isActive () const

bool	isLocalActive () const

Public Member Functions inherited from SurgSim::Framework::Accessible
	Accessible ()
	Default Constructor.

	~Accessible ()
	Destructor.

template<class T >
T	getValue (const std::string &name) const
	Retrieves the value with the name by executing the getter if it is found and tries to convert it to the given type. More...

boost::any	getValue (const std::string &name) const
	Retrieves the value with the name by executing the getter if it is found. More...

template<class T >
bool	getValue (const std::string &name, T *value) const
	Retrieves the value with the name by executing the getter if it is found, and converts it to the type of the output parameter. More...

void	setValue (const std::string &name, const boost::any &value)
	Sets a value of a property that has setter. More...

bool	isReadable (const std::string &name) const
	Check whether a property is readable. More...

bool	isWriteable (const std::string &name) const
	Check whether a property is writable. More...

void	setGetter (const std::string &name, GetterType func)
	Sets a getter for a given property. More...

void	setSetter (const std::string &name, SetterType func)
	Sets a setter for a given property. More...

void	setAccessors (const std::string &name, GetterType getter, SetterType setter)
	Sets the accessors getter and setter in one function. More...

void	removeAccessors (const std::string &name)
	Removes all the accessors (getter and setter) for a given property. More...

void	forwardProperty (const std::string &name, const Accessible &target, const std::string &targetProperty)
	Adds a property with the given name that uses the targets accessors, in effect forwarding the value to the target. More...

void	setSerializable (const std::string &name, EncoderType encoder, DecoderType decoder)
	Sets the functions used to convert data from and to a YAML::Node. More...

void	setDecoder (const std::string &name, DecoderType decoder)
	Sets the functions used to convert data from a YAML::Node. More...

YAML::Node	encode () const
	Encode this Accessible to a YAML::Node. More...

void	decode (const YAML::Node &node, const std::vector< std::string > &ignoredProperties=std::vector< std::string >())
	Decode this Accessible from a YAML::Node, will throw an exception if the data type cannot be converted. More...

std::vector< std::string >	getProperties ()

template<>
boost::any	getValue (const std::string &name) const

Protected Member Functions
bool	doInitialize () override
	Interface to be implemented by derived classes. More...

bool	doWakeUp () override
	Interface to be implemented by derived classes. More...

int	getTargetManagerType () const override
	Specifies which manger will handle this behavior.

void	setInitialInputPose (const SurgSim::Math::RigidTransform3d &pose)

virtual DataStructures::DataGroup	buildOutputData ()

void	setOptionalLinearStiffness (const DataStructures::OptionalValue< double > &linearStiffness)
	Used for Serialization. More...

const DataStructures::OptionalValue< double > &	getOptionalLinearStiffness () const
	Used for Serialization. More...

void	setOptionalLinearDamping (const DataStructures::OptionalValue< double > &linearDamping)
	Used for Serialization. More...

const DataStructures::OptionalValue< double > &	getOptionalLinearDamping () const
	Used for Serialization. More...

void	setOptionalAngularStiffness (const DataStructures::OptionalValue< double > &angularStiffness)
	Used for Serialization. More...

const DataStructures::OptionalValue< double > &	getOptionalAngularStiffness () const
	Used for Serialization. More...

void	setOptionalAngularDamping (const DataStructures::OptionalValue< double > &angularDamping)
	Used for Serialization. More...

const DataStructures::OptionalValue< double > &	getOptionalAngularDamping () const
	Used for Serialization. More...

void	setOptionalAttachmentPoint (const DataStructures::OptionalValue< Math::Vector3d > &attachmentPoint)
	Used for Serialization. More...

const DataStructures::OptionalValue< Math::Vector3d > &	getOptionalAttachmentPoint () const
	Used for Serialization. More...

Protected Member Functions inherited from SurgSim::Framework::Component
virtual std::shared_ptr< PoseComponent >	getPoseComponent ()
	Get the PoseComponent for this component. More...

virtual std::shared_ptr< const PoseComponent >	getPoseComponent () const
	Get the PoseComponent for this component, constant access. More...

Protected Attributes
DataStructures::OptionalValue< double >	m_optionalLinearStiffness
	User supplied Vtc stiffness parameter in linear mode (in N·m-1)

DataStructures::OptionalValue< double >	m_optionalLinearDamping
	User supplied Vtc damping parameter in linear mode (in N·s·m-1 or Kg·s-1)

DataStructures::OptionalValue< double >	m_optionalAngularStiffness
	User supplied Vtc stiffness parameter in angular mode (in N·m rad-1)

DataStructures::OptionalValue< double >	m_optionalAngularDamping
	User supplied Vtc damping parameter in angular mode (in N·m·s·rad-1)

DataStructures::OptionalValue< Math::Vector3d >	m_optionalAttachmentPoint
	User supplied attachment point.

DataStructures::DataGroup	m_outputData
	The DataGroup to output.

std::shared_ptr< Input::InputComponent >	m_input
	The input component.

std::shared_ptr< Input::OutputComponent >	m_output
	The output component.

Additional Inherited Members
Public Types inherited from SurgSim::Framework::Accessible
typedef std::function< boost::any(void)>	GetterType

typedef std::function< void(boost::any)>	SetterType

typedef std::function< YAML::Node(void)>	EncoderType

typedef std::function< void(const YAML::Node *)>	DecoderType

Public Types inherited from SurgSim::Framework::FactoryBase1< Component, std::string >
typedef ObjectFactory1< Component, std::string >	FactoryType

Static Public Member Functions inherited from SurgSim::Framework::FactoryBase1< Component, std::string >
static FactoryType &	getFactory ()

Detailed Description

The VirtualToolCoupler couples a rigid object to an input/output device through a spring and damper.

The object will follow the pose provided by the device. If an Output is connected, it is provided forces and torques that will push the device towards matching the object's pose and velocity. This "virtual coupling" or "god-object" paradigm is common for haptic applications utilizing a device that may update significantly faster than the physics computation thread.

For an overview of haptics see: Salisbury, Kenneth, Francois Conti, and Federico Barbagli. "Haptic rendering: introductory concepts." Computer Graphics and Applications, IEEE 24.2 (2004): 24-32.

For an introduction to virtual coupling see: Colgate, J. Edward, Michael C. Stanley, and J. Michael Brown. "Issues in the haptic display of tool use." Intelligent Robots and Systems 95.'Human Robot Interaction and Cooperative Robots', Proceedings. 1995 IEEE/RSJ International Conference on. Vol. 3. IEEE, 1995.

Constructor & Destructor Documentation

§ VirtualToolCoupler()

SurgSim::Physics::VirtualToolCoupler::VirtualToolCoupler ( const std::string & name )

explicit

Constructor.

Parameters

name	Name of the behavior

Member Function Documentation

§ buildOutputData()

SurgSim::DataStructures::DataGroup SurgSim::Physics::VirtualToolCoupler::buildOutputData ( )

protectedvirtual

Returns: The DataGroup to be sent to the device via the OutputComponent.

§ doInitialize()

bool SurgSim::Physics::VirtualToolCoupler::doInitialize ( )

overrideprotectedvirtual

Interface to be implemented by derived classes.

Returns: True if component is initialized successfully; otherwise, false.

Implements SurgSim::Framework::Component.

§ doWakeUp()

bool SurgSim::Physics::VirtualToolCoupler::doWakeUp ( )

overrideprotectedvirtual

Interface to be implemented by derived classes.

Returns: True if component is woken up successfully; otherwise, false.

Implements SurgSim::Framework::Component.

§ getAngularDamping()

double SurgSim::Physics::VirtualToolCoupler::getAngularDamping ( )

Returns: The damping of the vtc in angular mode (in N·m·s·rad-1)

§ getAngularStiffness()

double SurgSim::Physics::VirtualToolCoupler::getAngularStiffness ( )

Returns: The stiffness of the vtc in angular mode (in N·m rad-1)

§ getAttachmentPoint()

const SurgSim::Math::Vector3d & SurgSim::Physics::VirtualToolCoupler::getAttachmentPoint ( )

Get the point of attachment on the Representation.

Returns: The attachment point in the Representations local coordinate frame

§ getCalculateInertialTorques()

bool SurgSim::Physics::VirtualToolCoupler::getCalculateInertialTorques ( ) const

Get whether the calculated torques will simulate inertia.

This setting only has an effect if the attachment point is not the mass center.

See also: overrideAttachmentPoint

Returns: true if inertia is being simulated.

§ getInput()

const std::shared_ptr< SurgSim::Framework::Component > SurgSim::Physics::VirtualToolCoupler::getInput ( )

Returns: Input Component to get the pose from

§ getLinearDamping()

double SurgSim::Physics::VirtualToolCoupler::getLinearDamping ( )

Returns: The damping of the vtc in linear mode (in N·s·m-1 or Kg·s-1)

§ getLinearStiffness()

double SurgSim::Physics::VirtualToolCoupler::getLinearStiffness ( )

Returns: The stiffness of the vtc in linear mode (in N·m-1)

§ getOptionalAngularDamping()

const SurgSim::DataStructures::OptionalValue< double > & SurgSim::Physics::VirtualToolCoupler::getOptionalAngularDamping ( ) const

protected

Used for Serialization.

Returns: The OptionalValue object containing the damping of the vtc in angular mode (in N·m·s·rad-1)

§ getOptionalAngularStiffness()

const SurgSim::DataStructures::OptionalValue< double > & SurgSim::Physics::VirtualToolCoupler::getOptionalAngularStiffness ( ) const

protected

Used for Serialization.

Returns: The OptionalValue object containing the stiffness of the vtc in angular mode (in N·m rad-1)

§ getOptionalAttachmentPoint()

const SurgSim::DataStructures::OptionalValue< SurgSim::Math::Vector3d > & SurgSim::Physics::VirtualToolCoupler::getOptionalAttachmentPoint ( ) const

protected

Used for Serialization.

Returns: The OptionalValue object containing the attachment point.

§ getOptionalLinearDamping()

const SurgSim::DataStructures::OptionalValue< double > & SurgSim::Physics::VirtualToolCoupler::getOptionalLinearDamping ( ) const

protected

Used for Serialization.

Returns: The OptionalValue object containing the damping of the vtc in linear mode (in N·s·m-1 or Kg·s-1)

§ getOptionalLinearStiffness()

const SurgSim::DataStructures::OptionalValue< double > & SurgSim::Physics::VirtualToolCoupler::getOptionalLinearStiffness ( ) const

protected

Used for Serialization.

Returns: The OptionalValue object containing the stiffness of the vtc in linear mode (in N·m-1)

§ getOutput()

const std::shared_ptr< SurgSim::Framework::Component > SurgSim::Physics::VirtualToolCoupler::getOutput ( )

Returns: Output Component to send forces and torques

§ getPoseName()

const std::string & SurgSim::Physics::VirtualToolCoupler::getPoseName ( )

Returns: Name of the pose data in the input to transfer

§ getRepresentation()

const std::shared_ptr< SurgSim::Framework::Component > SurgSim::Physics::VirtualToolCoupler::getRepresentation ( )

Returns: Rigid Representation that provides state and receives external forces and torques

§ isHapticOutputOnlyWhenColliding()

bool SurgSim::Physics::VirtualToolCoupler::isHapticOutputOnlyWhenColliding ( ) const

Get whether or not the haptic forces should be provided only during collisions.

Returns: false if the VTC forces and torques are sent to the output device (if any) at all times. true if zeros are sent for the forces and torques unless the tool is colliding.

§ isInitializingRigidWithInputPose()

bool SurgSim::Physics::VirtualToolCoupler::isInitializingRigidWithInputPose ( ) const

Get whether the pose of the attached rigid is initialized with the first input pose received by the VTC.

Returns: true if the rigid will be initialized in the first frame

§ overrideAngularDamping()

void SurgSim::Physics::VirtualToolCoupler::overrideAngularDamping ( double angularDamping )

Override the angular damping connecting the input device and the physics representation If this value is not provided, the damping will be automatically tuned using the properties of the Representation.

Parameters

angularDamping The damping of the vtc in angular mode (in N·m·s·rad-1)

§ overrideAngularStiffness()

void SurgSim::Physics::VirtualToolCoupler::overrideAngularStiffness ( double angularStiffness )

Override the angular stiffness connecting the input device and the physics representation If this value is not provided, the stiffness will be automatically tuned using the properties of the Representation.

Parameters

angularStiffness The stiffness of the vtc in angular mode (in N·m rad-1)

§ overrideAttachmentPoint()

void SurgSim::Physics::VirtualToolCoupler::overrideAttachmentPoint ( const Math::Vector3d & attachment )

Override the point of attachment to the Representation If this value is not provided, the point of attachment will be automatically set to the Representation's center of mass.

Parameters

attachment The attachment point in the Representations local coordinate frame

§ overrideLinearDamping()

void SurgSim::Physics::VirtualToolCoupler::overrideLinearDamping ( double linearDamping )

Override the linear damping connecting the input device and the physics representation If this value is not provided, the damping will be automatically tuned using the properties of the Representation.

Parameters

linearDamping The damping of the vtc in linear mode (in N·s·m-1 or Kg·s-1)

§ overrideLinearStiffness()

void SurgSim::Physics::VirtualToolCoupler::overrideLinearStiffness ( double linearStiffness )

Override the linear stiffness connecting the input device and the physics representation If this value is not provided, the stiffness will be automatically tuned using the properties of the Representation.

Parameters

linearStiffness The stiffness of the vtc in linear mode (in N·m-1)

§ setCalculateInertialTorques()

void SurgSim::Physics::VirtualToolCoupler::setCalculateInertialTorques ( bool calculateInertialTorques )

Enable/disable torques that simulate inertia.

This setting only has an effect if the attachment point is not the mass center.

See also: overrideAttachmentPoint

Parameters

calculateInertialTorques true to simulate inertia.

§ setHapticOutputOnlyWhenColliding()

void SurgSim::Physics::VirtualToolCoupler::setHapticOutputOnlyWhenColliding ( bool haptic )

Set whether or not the haptic forces should be provided only during collisions.

Parameters

haptic false to send the VTC forces and torques to the output device (if any) at all times. true to send zeros for the forces and torques unless the tool is colliding.

§ setInitializeRigidWithInputPose()

void SurgSim::Physics::VirtualToolCoupler::setInitializeRigidWithInputPose ( bool val )

Set whether the pose of the attached rigid is initialized with the first input pose received by the VTC this will 'teleport' the rigid into the first pose of the vtc.

When this is not set, the rigid would be pulled to this pose, potentially pulling the rigid through other objects. Default true

Parameters

val	true to enable the initialization of the rigid

§ setInput()

void SurgSim::Physics::VirtualToolCoupler::setInput ( const std::shared_ptr< Framework::Component > input )

Set the Input Component.

The force calculations rely upon pose and velocity. If the input DataGroup does not contain a pose, no forces will be calculated. If the input DataGroup does not contain linear velocity or angular velocity, they will be estimated.

Parameters

input Input Component to get the pose from

§ setLocalActive()

void SurgSim::Physics::VirtualToolCoupler::setLocalActive ( bool val )

overridevirtual

Set the component's active state.

Parameters

val	If true component is active, inactive if false.

Reimplemented from SurgSim::Framework::Component.

§ setOptionalAngularDamping()

void SurgSim::Physics::VirtualToolCoupler::setOptionalAngularDamping ( const DataStructures::OptionalValue< double > & angularDamping )

protected

Used for Serialization.

Parameters

angularDamping The OptionalValue object containing the damping of the vtc in angular mode (in N·m·s·rad-1)

§ setOptionalAngularStiffness()

void SurgSim::Physics::VirtualToolCoupler::setOptionalAngularStiffness ( const DataStructures::OptionalValue< double > & angularStiffness )

protected

Used for Serialization.

Parameters

angularStiffness The OptionalValue object containing the stiffness of the vtc in angular mode (in N·m rad-1)

§ setOptionalAttachmentPoint()

void SurgSim::Physics::VirtualToolCoupler::setOptionalAttachmentPoint ( const DataStructures::OptionalValue< Math::Vector3d > & attachmentPoint )

protected

Used for Serialization.

Parameters

attachmentPoint The OptionalValue object containing the attachment point.

§ setOptionalLinearDamping()

void SurgSim::Physics::VirtualToolCoupler::setOptionalLinearDamping ( const DataStructures::OptionalValue< double > & linearDamping )

protected

Used for Serialization.

Parameters

linearDamping The OptionalValue object containing the damping of the vtc in linear mode (in N·s·m-1 or Kg·s-1)

§ setOptionalLinearStiffness()

void SurgSim::Physics::VirtualToolCoupler::setOptionalLinearStiffness ( const DataStructures::OptionalValue< double > & linearStiffness )

protected

Used for Serialization.

Parameters

linearStiffness The OptionalValue object containing the stiffness of the vtc in linear mode (in N·m-1)

§ setOutput()

void SurgSim::Physics::VirtualToolCoupler::setOutput ( const std::shared_ptr< Framework::Component > output )

Set the Output Component (if any)

Parameters

output Output Component to send forces and torques

§ setPoseName()

void SurgSim::Physics::VirtualToolCoupler::setPoseName ( const std::string & poseName = DataStructures::Names::POSE )

Set the name of the pose entry in the input DataGroup.

Parameters

poseName Name of the pose data in the input to transfer

§ setRepresentation()

void SurgSim::Physics::VirtualToolCoupler::setRepresentation ( const std::shared_ptr< Framework::Component > rigid )

Set the Physics Representation which follows the input.

Parameters

rigid Rigid Representation that provides state and receives external forces and torques

§ update()

void SurgSim::Physics::VirtualToolCoupler::update ( double dt )

overridevirtual

Update the behavior.

Parameters

dt	The length of time (seconds) between update calls.

Implements SurgSim::Framework::Behavior.

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

SurgSim/Physics/VirtualToolCoupler.h
SurgSim/Physics/VirtualToolCoupler.cpp

Public Member Functions

Protected Member Functions

Protected Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

§ VirtualToolCoupler()

Member Function Documentation

§ buildOutputData()

§ doInitialize()

§ doWakeUp()

§ getAngularDamping()

§ getAngularStiffness()

§ getAttachmentPoint()

§ getCalculateInertialTorques()

§ getInput()

§ getLinearDamping()

§ getLinearStiffness()

§ getOptionalAngularDamping()

§ getOptionalAngularStiffness()

§ getOptionalAttachmentPoint()

§ getOptionalLinearDamping()

§ getOptionalLinearStiffness()

§ getOutput()

§ getPoseName()

§ getRepresentation()

§ isHapticOutputOnlyWhenColliding()

§ isInitializingRigidWithInputPose()

§ overrideAngularDamping()

§ overrideAngularStiffness()

§ overrideAttachmentPoint()

§ overrideLinearDamping()

§ overrideLinearStiffness()

§ setCalculateInertialTorques()

§ setHapticOutputOnlyWhenColliding()

§ setInitializeRigidWithInputPose()

§ setInput()

§ setLocalActive()

§ setOptionalAngularDamping()

§ setOptionalAngularStiffness()

§ setOptionalAttachmentPoint()

§ setOptionalLinearDamping()

§ setOptionalLinearStiffness()

§ setOutput()

§ setPoseName()

§ setRepresentation()

§ update()