SurgSim::Devices::PoseTransform Class Reference

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

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

Inheritance diagram for SurgSim::Devices::PoseTransform:

## Public Member Functions

| PoseTransform (const std::string &name)
| Constructor. More...
| SURGSIM_CLASSNAME (SurgSim::Devices::PoseTransform)
double | getTranslationScale () const
void | setTranslationScale (double translationScale)
| Set the translation scale factor so that each direction has the same scale. More...
const Math::RigidTransform3d & | getTransform () const
void | setTransform (const Math::RigidTransform3d &transform)
| Set the constant transform. More...
Public Member Functions inherited from SurgSim::Devices::DeviceFilter
| DeviceFilter (const std::string &name)
| Constructor. More...
| SURGSIM_CLASSNAME (SurgSim::Devices::DeviceFilter)
bool | initialize () override
| Fully initialize the device. More...
bool | isInitialized () const override
void | initializeInput (const std::string &device, const DataStructures::DataGroup &inputData) override
| Set the initial input data group. More...
void | handleInput (const std::string &device, const DataStructures::DataGroup &inputData) override
| Notifies the consumer that the application input coming from the device has been updated. More...
bool | requestOutput (const std::string &device, DataStructures::DataGroup *outputData) override
| Asks the producer to provide output state to the device. More...
Public Member Functions inherited from SurgSim::Input::CommonDevice
| CommonDevice (const std::string &name)
| Constructor. More...
| CommonDevice (const std::string &name, const DataStructures::DataGroup &inputData)
| Constructor. More...
| CommonDevice (const std::string &name, DataStructures::DataGroup &&inputData)
| Constructor. More...
virtual | ~CommonDevice ()
| Destructor. More...
std::string | getName () const override
| Return a (hopefully unique) device name. More...
std::string | getClassName () const override
| The class name for this class. 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...
bool | addInputConsumer (std::shared_ptr< InputConsumerInterface > inputConsumer) override
| Adds an input consumer that will be notified when the application input state is updated. More...
bool | removeInputConsumer (std::shared_ptr< InputConsumerInterface > inputConsumer) override
| Removes an input consumer previously added via addInputConsumer. More...
void | clearInputConsumers () override
| Removes all InputConsumers. More...
bool | setOutputProducer (std::shared_ptr< OutputProducerInterface > outputProducer) override
| Sets an output producer that will be asked for application output state when the device needs it. More...
bool | removeOutputProducer (std::shared_ptr< OutputProducerInterface > outputProducer) override
| Removes an output producer previously added via setOutputProducer. More...
bool | hasOutputProducer () override
| Query if this object has output producer. More...
void | clearOutputProducer () override
| Removes any OutputProducer. More...
Public Member Functions inherited from SurgSim::Input::DeviceInterface
virtual | ~DeviceInterface ()
| Virtual destructor (empty). More...
Public Member Functions inherited from SurgSim::Framework::Accessible
| Accessible ()
| Default Constructor. More...
| ~Accessible ()
| Destructor. More...
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...
template<>
boost::any | getValue (const std::string &name) const
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

void | filterInput (const std::string &device, const DataStructures::DataGroup &dataToFilter, DataStructures::DataGroup *result) override
| Filter the input data. More...
void | filterOutput (const std::string &device, const DataStructures::DataGroup &dataToFilter, DataStructures::DataGroup *result) override
| Filter the output data. More...

## Private Attributes

boost::mutex | m_mutex
| The mutex that protects the transform and scaling factor. More...
Math::RigidTransform3d | m_transform
| The constant pre-transform. More...
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...

## 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< DeviceInterface, std::string >
typedef ObjectFactory1< DeviceInterface, std::string > | FactoryType
Static Public Member Functions inherited from SurgSim::Framework::FactoryBase1< DeviceInterface, std::string >
static FactoryType & | getFactory ()
Protected Member Functions inherited from SurgSim::Devices::DeviceFilter
bool | finalize () override
| Finalize (de-initialize) the device. More...
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...
DataStructures::DataGroup & | getInputData ()
| Getter for the input data DataGroup. More...
const DataStructures::DataGroup & | getOutputData () const
| Getter for the output data DataGroup. More...
Protected Attributes inherited from SurgSim::Devices::DeviceFilter
bool | m_initialized
| true if initialized and not finalized. 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

## PoseTransform()

SurgSim::Devices::PoseTransform::PoseTransform | ( | const std::string & | name | ) |

explicit

Constructor.

Parameters

  name | Name of this device filter.

## Member Function Documentation

## filterInput()

void SurgSim::Devices::PoseTransform::filterInput | ( | const std::string & | device,
|  | const DataStructures::DataGroup & | dataToFilter,
|  | DataStructures::DataGroup * | result
| ) |  |

override private virtual

Filter the input data.

Parameters

  | device | The name of the device pushing the input data.
  | dataToFilter | The data that will be filtered.
  [in,out] | result | A pointer to a DataGroup object that must be assignable to by the dataToFilter object. Will contain the filtered data.

Reimplemented from SurgSim::Devices::DeviceFilter.

## filterOutput()

void SurgSim::Devices::PoseTransform::filterOutput | ( | const std::string & | device,
|  | const DataStructures::DataGroup & | dataToFilter,
|  | DataStructures::DataGroup * | result
| ) |  |

override private virtual

Filter the output data.

Parameters

  | device | The name of the device pulling the output data.
  | dataToFilter | The data that will be filtered.
  [in,out] | result | A pointer to a DataGroup object that must be assignable to by the dataToFilter object. Will contain the filtered data.

Reimplemented from SurgSim::Devices::DeviceFilter.

## getTransform()

const RigidTransform3d & SurgSim::Devices::PoseTransform::getTransform | ( |  | ) | const

Returns
  The current transform.

## getTranslationScale()

double SurgSim::Devices::PoseTransform::getTranslationScale | ( |  | ) | const

Returns
  Get the translation scale factor.

## setTransform()

void SurgSim::Devices::PoseTransform::setTransform | ( | const Math::RigidTransform3d & | transform | ) |

Set the constant transform.

The transform is pre-applied to the input pose.

Parameters

  transform | The 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.

## setTranslationScale()

void SurgSim::Devices::PoseTransform::setTranslationScale | ( | double | translationScale | ) |

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

Parameters

  translationScale | The 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.

## SURGSIM_CLASSNAME()

SurgSim::Devices::PoseTransform::SURGSIM_CLASSNAME | ( | SurgSim::Devices::PoseTransform |  | ) |

## Member Data Documentation

## m_mutex

boost::mutex SurgSim::Devices::PoseTransform::m_mutex

private

The mutex that protects the transform and scaling factor.

## m_transform

Math::RigidTransform3d SurgSim::Devices::PoseTransform::m_transform

private

The constant pre-transform.

## m_transformInverse

Math::RigidTransform3d SurgSim::Devices::PoseTransform::m_transformInverse

private

The inverse of the pre-transform.

## m_translationScale

double SurgSim::Devices::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:

- SurgSim/Devices/DeviceFilters/PoseTransform.h
- SurgSim/Devices/DeviceFilters/PoseTransform.cpp