Public Member Functions | Private Member Functions | Private Attributes | List of all members
SurgSim::Device::PoseTransform Class Reference

A device filter that transforms the input pose. More...

#include <SurgSim/Devices/DeviceFilters/PoseTransform.h>

Inheritance diagram for SurgSim::Device::PoseTransform:
SurgSim::Input::CommonDevice SurgSim::Input::InputConsumerInterface SurgSim::Input::OutputProducerInterface SurgSim::Input::DeviceInterface

Public Member Functions

 PoseTransform (const std::string &name)
 Constructor. More...
 
virtual ~PoseTransform ()
 Destructor. More...
 
virtual bool initialize () override
 Fully initialize the device. More...
 
virtual void initializeInput (const std::string &device, const SurgSim::DataStructures::DataGroup &inputData) override
 Set the initial input data. More...
 
virtual void handleInput (const std::string &device, const SurgSim::DataStructures::DataGroup &inputData) override
 Notifies the consumer that the application input coming from the device has been updated. More...
 
virtual bool requestOutput (const std::string &device, SurgSim::DataStructures::DataGroup *outputData) override
 Asks the producer to provide output state to the device. More...
 
void setTranslationScale (double translationScale)
 Set the translation scale factor so that each direction has the same scale. More...
 
void setTransform (const SurgSim::Math::RigidTransform3d &transform)
 Set the constant transform. More...
 
- Public Member Functions inherited from SurgSim::Input::CommonDevice
 CommonDevice (const std::string &name)
 Constructor. More...
 
 CommonDevice (const std::string &name, const SurgSim::DataStructures::DataGroup &inputData)
 Constructor. More...
 
 CommonDevice (const std::string &name, SurgSim::DataStructures::DataGroup &&inputData)
 Constructor. More...
 
virtual ~CommonDevice ()
 Destructor. More...
 
virtual std::string getName () const override
 Return a (hopefully unique) device name. More...
 
void setNameForCallback (const std::string &name)
 Set the name used for calling the input consumers and output producer. More...
 
std::string getNameForCallback () const
 Get the name used for calling the input consumers and output producer. More...
 
virtual bool addInputConsumer (std::shared_ptr< InputConsumerInterface > inputConsumer) override
 Connect this device to an InputConsumerInterface, which will receive the data that comes from this device. More...
 
virtual bool removeInputConsumer (std::shared_ptr< InputConsumerInterface > inputConsumer) override
 Disconnect this device from an InputConsumerInterface, which will no longer receive data from this device. More...
 
virtual bool setOutputProducer (std::shared_ptr< OutputProducerInterface > outputProducer) override
 Connect this device to an OutputProducerInterface, which will send data to this device. More...
 
virtual bool removeOutputProducer (std::shared_ptr< OutputProducerInterface > outputProducer) override
 Disconnect this device from an OutputProducerInterface, which will no longer send data to this device. More...
 
virtual bool hasOutputProducer () override
 Getter for whether or not this device is connected with an OutputProducerInterface. More...
 
- Public Member Functions inherited from SurgSim::Input::DeviceInterface
virtual ~DeviceInterface ()
 Virtual destructor (empty). More...
 
- Public Member Functions inherited from SurgSim::Input::InputConsumerInterface
virtual ~InputConsumerInterface ()
 Virtual destructor (empty). More...
 
- Public Member Functions inherited from SurgSim::Input::OutputProducerInterface
virtual ~OutputProducerInterface ()
 Virtual destructor (empty). More...
 

Private Member Functions

virtual bool finalize () override
 Finalize (de-initialize) the device. More...
 
void inputFilter (const SurgSim::DataStructures::DataGroup &dataToFilter, SurgSim::DataStructures::DataGroup *result)
 Filter the input data. More...
 
void outputFilter (const SurgSim::DataStructures::DataGroup &dataToFilter, SurgSim::DataStructures::DataGroup *result)
 Filter the output data. More...
 

Private Attributes

boost::mutex m_mutex
 The mutex that protects the transform and scaling factor. More...
 
SurgSim::Math::RigidTransform3d m_transform
 The constant pre-transform. More...
 
SurgSim::Math::RigidTransform3d m_transformInverse
 The inverse of the pre-transform. More...
 
double m_translationScale
 The scaling factor applied to each direction of the translation. More...
 
bool m_cachedOutputIndices
 True if the output DataGroup indices have been cached. More...
 
int m_poseIndex
 
int m_linearVelocityIndex
 
int m_angularVelocityIndex
 
int m_forceIndex
 
int m_torqueIndex
 
int m_springJacobianIndex
 
int m_inputPoseIndex
 
int m_damperJacobianIndex
 
int m_inputLinearVelocityIndex
 
int m_inputAngularVelocityIndex
 

Additional Inherited Members

- Protected Member Functions inherited from SurgSim::Input::CommonDevice
virtual void pushInput ()
 Push application input to consumers. More...
 
virtual bool pullOutput ()
 Pull application output from a producer. More...
 
SurgSim::DataStructures::DataGroupgetInputData ()
 Getter for the input data DataGroup. More...
 
const SurgSim::DataStructures::DataGroupgetOutputData () const
 Getter for the output data DataGroup. More...
 

Detailed Description

A device filter that transforms the input pose.

It can scale the translation, and/or apply a constant transform. Any other data in the DataGroup is passed through. For an input/output device (e.g., a haptic device), the filter should be added as one of the device's input consumers and set as the device's output producer. For a purely input device, the filter can just be added as an input consumer. If it is used for both input and output, the input data is filtered using the offset(s) and scaling, and the output data is un-filtered so the device does not need to know about the filtering. For haptic devices, so that changing the translation scaling does not alter the relationship between displayed forces and collision penetrations, the output filter does not scale the nominal forces and torques, and it does scale the Jacobians. Thereby the displayed forces and torques are appropriate for the scene (not the device-space motions). In other words, a 1 m motion by the device's scene representation generates forces according to that 1 m motion, instead of the original device motion before scaling. This means the device displays forces and torques that are "true" to the scene, with the consequence that increasing the translation scaling can negatively impact the haptic stability. As the scaling increases, the same motion would cause larger forces, until at great enough scaling the system becomes unstable (either when colliding with another scene element, or just due to over-damping). Consider chaining this device filter with a force scaling device filter to improve system stability.

See also
SurgSim::Input::CommonDevice
SurgSim::Input::InputConsumerInterface
SurgSim::Input::OutputProducerInterface

Constructor & Destructor Documentation

SurgSim::Device::PoseTransform::PoseTransform ( const std::string name)
explicit

Constructor.

Parameters
nameName of this device filter.
SurgSim::Device::PoseTransform::~PoseTransform ( )
virtual

Destructor.

Member Function Documentation

bool SurgSim::Device::PoseTransform::finalize ( )
overrideprivatevirtual

Finalize (de-initialize) the device.

Returns
True on success.

Implements SurgSim::Input::DeviceInterface.

void SurgSim::Device::PoseTransform::handleInput ( const std::string device,
const SurgSim::DataStructures::DataGroup inputData 
)
overridevirtual

Notifies the consumer that the application input coming from the device has been updated.

Used when transforming the pose coming from an input device.

Parameters
deviceThe name of the device that is producing the input. This should only be used to identify the device (e.g. if the consumer is listening to several devices at once).
inputDataThe application input state coming from the device.

Implements SurgSim::Input::InputConsumerInterface.

bool SurgSim::Device::PoseTransform::initialize ( )
overridevirtual

Fully initialize the device.

When the manager object creates the device, the internal state of the device usually isn't fully initialized yet. This method performs any needed initialization.

Returns
True on success.

Implements SurgSim::Input::DeviceInterface.

void SurgSim::Device::PoseTransform::initializeInput ( const std::string device,
const SurgSim::DataStructures::DataGroup inputData 
)
overridevirtual

Set the initial input data.

Used when transforming the pose coming from an input device.

Parameters
deviceThe name of the device that is producing the input. This should only be used to identify the device (e.g. if the consumer is listening to several devices at once).
inputDataThe application input state coming from the device.

Implements SurgSim::Input::InputConsumerInterface.

void SurgSim::Device::PoseTransform::inputFilter ( const SurgSim::DataStructures::DataGroup dataToFilter,
SurgSim::DataStructures::DataGroup result 
)
private

Filter the input data.

Parameters
dataToFilterThe data that will be filtered.
[in,out]resultA pointer to a DataGroup object that must be assignable to by the dataToFilter object. Will contain the filtered data.
void SurgSim::Device::PoseTransform::outputFilter ( const SurgSim::DataStructures::DataGroup dataToFilter,
SurgSim::DataStructures::DataGroup result 
)
private

Filter the output data.

If this device filter offsets/scales input data from a haptic device, then when output data (forces, torques, Jacobians) are created for output to that device, this function incorporates the transform/scaling to correct the displayed outputs.

Parameters
dataToFilterThe data that will be filtered.
[in,out]resultA pointer to a DataGroup object that must be assignable to by the dataToFilter object. Will contain the filtered data.
bool SurgSim::Device::PoseTransform::requestOutput ( const std::string device,
SurgSim::DataStructures::DataGroup outputData 
)
overridevirtual

Asks the producer to provide output state to the device.

Passes through all data, modifying the data entries used by haptic devices. Note that devices may never call this method, e.g. because the device doesn't actually have any output capability.

Parameters
deviceThe name of the device that is requesting the output. This should only be used to identify the device (e.g. if the producer is listening to several devices at once).
[out]outputDataThe data being sent to the device.
Returns
True if the producer has provided output data. A producer that returns false should leave outputData unmodified.

Implements SurgSim::Input::OutputProducerInterface.

void SurgSim::Device::PoseTransform::setTransform ( const SurgSim::Math::RigidTransform3d transform)

Set the constant transform.

The transform is pre-applied to the input pose.

Parameters
transformThe transform, which must be invertible.
Warning
This setter is thread-safe, but after calling this function the output filter will use the new transform even if the following output data is based off input data that used the old transform.
void SurgSim::Device::PoseTransform::setTranslationScale ( double  translationScale)

Set the translation scale factor so that each direction has the same scale.

Parameters
translationScaleThe scalar scaling factor.
Warning
This setter is thread-safe, but after calling this function the output filter will use the new transform even if the following output data is based off input data that used the old transform.

Member Data Documentation

int SurgSim::Device::PoseTransform::m_angularVelocityIndex
private

The indices into the DataGroups.

bool SurgSim::Device::PoseTransform::m_cachedOutputIndices
private

True if the output DataGroup indices have been cached.

int SurgSim::Device::PoseTransform::m_damperJacobianIndex
private

The indices into the DataGroups.

int SurgSim::Device::PoseTransform::m_forceIndex
private

The indices into the DataGroups.

int SurgSim::Device::PoseTransform::m_inputAngularVelocityIndex
private

The indices into the DataGroups.

int SurgSim::Device::PoseTransform::m_inputLinearVelocityIndex
private

The indices into the DataGroups.

int SurgSim::Device::PoseTransform::m_inputPoseIndex
private

The indices into the DataGroups.

int SurgSim::Device::PoseTransform::m_linearVelocityIndex
private

The indices into the DataGroups.

boost::mutex SurgSim::Device::PoseTransform::m_mutex
private

The mutex that protects the transform and scaling factor.

int SurgSim::Device::PoseTransform::m_poseIndex
private

The indices into the DataGroups.

int SurgSim::Device::PoseTransform::m_springJacobianIndex
private

The indices into the DataGroups.

int SurgSim::Device::PoseTransform::m_torqueIndex
private

The indices into the DataGroups.

SurgSim::Math::RigidTransform3d SurgSim::Device::PoseTransform::m_transform
private

The constant pre-transform.

SurgSim::Math::RigidTransform3d SurgSim::Device::PoseTransform::m_transformInverse
private

The inverse of the pre-transform.

double SurgSim::Device::PoseTransform::m_translationScale
private

The scaling factor applied to each direction of the translation.


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