Haply::Inverse::Unity::Inverse3

Represents the Inverse3 device controller, managing device data and state updates. More...

Inherits from Haply.Inverse.Unity.DeviceBehaviour, MonoBehaviour

Public Events

	Name
DeviceDelegate	DeviceStateChanged() Event triggered on each haptic frame.
Action< Inverse3 >	OrientationChangedAsync() Triggered whenever the body orientation of the Inverse3 device changes.

Public Functions

	Name
delegate void	DeviceDelegate(Inverse3 inverse3) Represents a method that will handle the Inverse3.DeviceStateChanged event of an Inverse3 device.
void	RequestPowerSupplyStatus() Requests an update to the current power supply status (Powered) and triggers the PowerSupplyStatusChanged event upon completion.
void	RequestOrientation() Requests an update to the Inverse3 body Orientation and triggers the OrientationChangedAsync event upon completion.
void	CursorSetLocalForce(in Vector3 force) Sets the force applied to the cursor in newtons (N) along the x, y, and z axes in the device's local space.
void	CursorSetLocalForce(float x, float y, float z)
void	CursorSetForce(in Vector3 force) Sets the force applied to the cursor in newtons (N) in world space.
void	CursorSetForce(float x, float y, float z)
void	CursorSetLocalPosition(in Vector3 position) Sets the cursor's position set-point in meters (m) along the x, y, and z axes in the device's local space.
void	CursorSetLocalPosition(float x, float y, float z)
void	CursorSetPosition(in Vector3 position) Sets the cursor's position set-point in meters (m) in world space.
void	CursorSetPosition(float x, float y, float z)
void	JointsSetTorques(Joint3 torques) Sets the desired torque in newton millimeters (Nmm) for each joint of the Inverse3 device.
void	JointsSetTorques(float t0, float t1, float t2)
void	JointsSetTorque(Vector3 angles)
void	JointsSetTorque(float x, float y, float z)
void	JointsSetAngles(Joint3 angles) Sets the desired joint angles in degrees (°) for each joint of the Inverse3 device.
void	JointsSetAngles(float alpha0, float alpha1, float alpha2)
void	JointsSetAngles(Vector3 angles)
bool	Release() Attempts to reset all force and position control for the cursor.
bool	TryResetForce()
Vector3	TransformPoint(Vector3 position) Transforms a position from the local space of the device or cursor to world space using the cached LocalToWorldMatrix.
Vector3	TransformVector(Vector3 vector) Transforms a vector from the local space of the device or cursor to world space using the cached LocalToWorldMatrix.
Vector3	InverseTransformPoint(Vector3 position) Transforms a position from world space back to the local space of the device or cursor using the cached WorldToLocalMatrix.
Vector3	InverseTransformVector(Vector3 vector) Transforms a vector from world space back to the local space of the device or cursor using the cached WorldToLocalMatrix.
override string	ToString() Returns a string representation of the object, providing a human-readable description that includes the object's name, class type, device ID, and selected handedness.

Protected Functions

	Name
virtual override void	Setup() This method is automatically called once the _performSetup flag is set to handle consuming calculations too heavy to be called on each frame. This method can be override with taking care to keep base call. Use SetSetupToPerform to trigger Setup call.
virtual override void	FixedUpdate()

Public Properties

	Name
override DeviceType	DeviceType Gets the type of device, always returning DeviceType.Inverse3 for this controller.
override CursorBehaviour	Cursor
Inverse3Body	Body GameObject automatically rotating with the Inverse3 body Orientation.
Vector3	CursorLocalPosition Gets the position of the Inverse3 cursor in meters (m) in the device local space.
Vector3	LocalPosition
Vector3	CursorPosition Gets the Inverse3 cursor world space position from CursorLocalPosition and LocalToWorldMatrix
Vector3	Position
Vector3	CursorLocalVelocity Gets the velocity of the Inverse3 cursor in meters per second (m/s) in the device local space.
Vector3	LocalVelocity
Vector3	CursorVelocity Gets the Inverse3 cursor world space velocity from CursorLocalVelocity and LocalToWorldMatrix
Vector3	Velocity
Joint3	JointsAngles Gets the current joint angles of the Inverse3 device in degrees.
Joint3	JointsAngularVelocity Gets the current angular velocities of the Inverse3 device's joints in degrees per second.
HandednessType	SelectedHandedness Gets or sets the desired handedness type of the Inverse3 device.
HandednessType	Handedness Gets the handedness type of the device at runtime.
bool	Powered Indicates whether the device is currently powered.
Quaternion	Orientation Gets the current orientation of the Inverse3 device based on the last received orientation data.
Vector3	WorkspaceCenterLeft Workspace center local coordinates for a HandednessType.Left-handed device.
Vector3	WorkspaceCenterRight Workspace center local coordinates for a HandednessType.Right-handed device.
Vector3	WorkspaceCenter Workspace center local coordinates depending on the Handedness value.
ControlMode	ControlMode Gets the current control mode of the device.
Vector3	ForceOutput Last force sent to the device by the CursorSetForce or CursorSetLocalForce methods.
Vector3	PositionOutput Last position sent to the device by the CursorSetPosition or CursorSetLocalPosition methods.
Joint3	JointsTorqueOutput Last torque sent to the device by the JointsSetTorque method.
Joint3	JointsAnglesOutput Last angles sent to the device by the JointsSetAngles method.
Matrix4x4	LocalToWorldMatrix Matrix that transforms the device or Cursor space into world space.
Matrix4x4	WorldToLocalMatrix Matrix that transforms back from the world space into device or Cursor space.

Protected Properties

	Name
override BaseCoordinateConverter	CoordinateConverter
Transform	SpaceTransformationReference Reference transform used for setup LocalToWorldMatrix and WorldToLocalMatrix.

Public Attributes

	Name
UnityEvent< Inverse3, bool >	PowerSupplyStatusChanged Triggered whenever there is a change in the power supply status of the Inverse3 device.
UnityEvent< Inverse3, ControlMode >	ControlModeChanged Event triggered when the control mode of the device changes.

Additional inherited members

Public Events inherited from Haply.Inverse.Unity.DeviceBehaviour

	Name
Action< DeviceBehaviour, Ret >	ErrorEvent()
ConnectionStateDelegate	ConnectionStateChanged() Event triggered when the device connection state changes.
Action< DeviceBehaviour, DeviceConnectionState, DeviceConnectionState >	ConnectionStateChangedAsync() Event triggered shortly after the device connection state changes.

Public Functions inherited from Haply.Inverse.Unity.DeviceBehaviour

	Name
delegate void	ConnectionStateDelegate(DeviceBehaviour device, DeviceConnectionState state, DeviceConnectionState prevState) Delegate for handling connection state changes of the device.
void	SetSetupToPerform() Indicate to perform setup on next frame.

Protected Functions inherited from Haply.Inverse.Unity.DeviceBehaviour

	Name
virtual void	Awake()
void	OnEnable()
void	OnDisable()
void	OnDestroy()

Public Properties inherited from Haply.Inverse.Unity.DeviceBehaviour

	Name
int	SelectedDeviceId
uint	DeviceId Gets the device ID.
DeviceConnectionState	ConnectionState Gets or sets the current connection state of the device.
bool	IsConnected Gets whether the device is connected.
bool	IsOpened Gets whether the device is opened.
bool	IsReady

Protected Properties inherited from Haply.Inverse.Unity.DeviceBehaviour

	Name
bool	IsCursorSet Indicates whether the Cursor has been set.

Public Attributes inherited from Haply.Inverse.Unity.DeviceBehaviour

	Name
const int	ANY_ID
UnityEvent< DeviceBehaviour >	DeviceOpened Event triggered when the ConnectionState transitions to the DeviceConnectionState.Opened state.
UnityEvent< DeviceBehaviour >	DeviceClosed Event triggered when the ConnectionState transitions to the DeviceConnectionState.Connected state.

Protected Attributes inherited from Haply.Inverse.Unity.DeviceBehaviour

	Name
string	_objectName

Detailed Description

class Haply::Inverse::Unity::Inverse3;

Represents the Inverse3 device controller, managing device data and state updates.

This component should be attached to a GameObject that represents the physical Inverse3 device in a Unity scene.

Public Events Documentation

event DeviceStateChanged

DeviceDelegate DeviceStateChanged()

Event triggered on each haptic frame.

See: ClientConfiguration.HapticPollFrequency

It provides real-time updates of the cursor's position and velocity.

This event is useful for applications that require continuous tracking of the cursor's state or for applying real-time control commands. During this event, you can use properties such as CursorPosition, CursorVelocity, CursorLocalPosition, or CursorLocalVelocity.

And control methods such as:

• CursorSetForce to apply a force to the cursor,
• CursorSetPosition to set the cursor's position,
• JointsSetTorque to apply torque to the device's joints, or
• JointsSetAngles to set the angles of the device's joints.

The frequency at which this event is triggered is determined by the haptic loop frequency, which can be configured via ClientConfiguration.HapticPollFrequency.

event OrientationChangedAsync

Action< Inverse3 > OrientationChangedAsync()

Triggered whenever the body orientation of the Inverse3 device changes.

Public Functions Documentation

function DeviceDelegate

delegate void DeviceDelegate(
    Inverse3 inverse3
)

Represents a method that will handle the Inverse3.DeviceStateChanged event of an Inverse3 device.

Parameters:

• inverse3 The Inverse3 device instance raising the event.

function RequestPowerSupplyStatus

void RequestPowerSupplyStatus()

Requests an update to the current power supply status (Powered) and triggers the PowerSupplyStatusChanged event upon completion.

Note: Frequent calls to this method (e.g., within an Update loop) may lead to performance degradation and haptic jitters. It is recommended to use this method judiciously, based on specific user actions or events, or use the DeviceMapperDeviceMapper.DeviceInfoPollingMode.Continuous mode.

function RequestOrientation

void RequestOrientation()

Requests an update to the Inverse3 body Orientation and triggers the OrientationChangedAsync event upon completion.

Use this method to manually refresh the device's orientation data. If a body is set, its transform will be updated automatically with the new orientation. Note: Frequent calls to this method (e.g., within an Update loop) may lead to performance degradation and haptic jitters. It is recommended to use this method judiciously, based on specific user actions or events, or use the DeviceMapperDeviceMapper.DeviceInfoPollingMode.Continuous mode.

function CursorSetLocalForce

void CursorSetLocalForce(
    in Vector3 force
)

Sets the force applied to the cursor in newtons (N) along the x, y, and z axes in the device's local space.

Parameters:

• force The desired force vector in newtons (N) in the device's local space.

Exceptions:

• InvalidOperationException Thrown when the client connection is not established.
• Exception Thrown if an unexpected error is received from the service.

This method sends a non-processed force vector directly to the device in its local space and should be used only in conjunction with CursorLocalPosition and CursorLocalVelocity. If the force calculation is based on world space coordinates (CursorPosition and CursorVelocity) and/or involves a transformed (position, rotation, or scale) controller, CursorSetForce should be used instead.

When generating forces, the device's LED turns green. The Inverse3 device can generate up to 10 N total, though the maximum achievable force varies across the workspace. If the requested force exceeds the device's capability, it will either generate the maximum possible force in the same direction or, if force scaling is enabled, adjust to provide the highest achievable force while maintaining a similar direction. Setting the force along all axes to zero generates no net force on the cursor, but the cursor will remain gravity compensated if enabled.

function CursorSetLocalForce

void CursorSetLocalForce(
    float x,
    float y,
    float z
)

function CursorSetForce

void CursorSetForce(
    in Vector3 force
)

Sets the force applied to the cursor in newtons (N) in world space.

Parameters:

• force The desired force vector in newtons (N) in world space.

See: CursorSetLocalForce, InverseTransformVector

This method converts the provided force vector from world space to the device's local space before sending it to the device. It should be used when the force calculation is based on world space coordinates. For direct local space control, use CursorSetLocalForce instead.

function CursorSetForce

void CursorSetForce(
    float x,
    float y,
    float z
)

function CursorSetLocalPosition

void CursorSetLocalPosition(
    in Vector3 position
)

Sets the cursor's position set-point in meters (m) along the x, y, and z axes in the device's local space.

Parameters:

• position The desired position vector in meters (m) in the device's local space.

Exceptions:

• InvalidOperationException Thrown when the client connection is not established.
• Exception Thrown if an unexpected error is received from the service.

This method sets a position set-point that moves the cursor to the specified position. It sends a non-processed position directly to the device in its local space. If the position calculation is based on world space coordinates (CursorPosition, CursorVelocity) and/or involves a transformed (position, rotation, or scale) controller, CursorSetPosition should be considered.

The device's LED turns blue when in position control mode. Setting an unobtainable position causes the Inverse3 device arms to slowly drop down or remain in their current location. To exit position control mode, apply a force (which can be zero), use TryResetForce or disconnect from the device.

function CursorSetLocalPosition

void CursorSetLocalPosition(
    float x,
    float y,
    float z
)

function CursorSetPosition

void CursorSetPosition(
    in Vector3 position
)

Sets the cursor's position set-point in meters (m) in world space.

Parameters:

• position The desired position vector in meters (m) in world space.

See: CursorSetLocalPosition, InverseTransformPoint

This method converts the provided position from world space to the device's local space before setting the position set-point. It should be used when the position calculation is based on world space coordinates. For direct local space control, use CursorSetLocalPosition instead.

function CursorSetPosition

void CursorSetPosition(
    float x,
    float y,
    float z
)

function JointsSetTorques

void JointsSetTorques(
    Joint3 torques
)

Sets the desired torque in newton millimeters (Nmm) for each joint of the Inverse3 device.

Parameters:

• torques Desired torques on each device joints.

Exceptions:

• InvalidOperationException Thrown when throwException is true and the client connection is not established.
• Exception Thrown if an unexpected error is received from the service.

When generating torque, the device's LED turns green.

The Inverse3 device can generate up to 1000 Nmm of torque at each joint. If the desired torque exceeds this limit, the device will generate the maximum torque instead.

function JointsSetTorques

void JointsSetTorques(
    float t0,
    float t1,
    float t2
)

function JointsSetTorque

void JointsSetTorque(
    Vector3 angles
)

function JointsSetTorque

void JointsSetTorque(
    float x,
    float y,
    float z
)

function JointsSetAngles

void JointsSetAngles(
    Joint3 angles
)

Sets the desired joint angles in degrees (°) for each joint of the Inverse3 device.

Parameters:

• angles Desired angles on each device joints.

Exceptions:

• InvalidOperationException Thrown when throwException is true and the client connection is not established.
• Exception Thrown if an unexpected error is received from the service.

Sets a desired joint angles for the device. Setting an unobtainable angle will move the device to the closest physically obtainable configuration. For example, setting (-90, 180, 0) will move the device to a position where the head is parallel and the arms are perpendicular to the body.

function JointsSetAngles

void JointsSetAngles(
    float alpha0,
    float alpha1,
    float alpha2
)

function JointsSetAngles

void JointsSetAngles(
    Vector3 angles
)

function Release

bool Release()

Attempts to reset all force and position control for the cursor.

Return: True if the force reset was successful; false if the client connection is not established or an unexpected error occurred.

This method does not throw an exception if the ClientConnection is already closed, making it suitable for use during program termination or in OnDisable events. It returns false if the client connection is not established or if an unexpected error is received from the service while resetting the force and position control.

function TryResetForce

bool TryResetForce()

function TransformPoint

Vector3 TransformPoint(
    Vector3 position
)

Transforms a position from the local space of the device or cursor to world space using the cached LocalToWorldMatrix.

Parameters:

• position Local position.

See: LocalToWorldMatrix

Return: World position.

You can perform the opposite conversion, from world to local space using InverseTransformPoint.

function TransformVector

Vector3 TransformVector(
    Vector3 vector
)

Transforms a vector from the local space of the device or cursor to world space using the cached LocalToWorldMatrix.

Parameters:

• vector Local vector.

See: LocalToWorldMatrix

Return: World vector.

You can perform the opposite conversion, from world to local space using InverseTransformVector.

function InverseTransformPoint

Vector3 InverseTransformPoint(
    Vector3 position
)

Transforms a position from world space back to the local space of the device or cursor using the cached WorldToLocalMatrix.

Parameters:

• position World position.

See: WorldToLocalMatrix

Return: Local position.

The opposite of TransformPoint.

function InverseTransformVector

Vector3 InverseTransformVector(
    Vector3 vector
)

Transforms a vector from world space back to the local space of the device or cursor using the cached WorldToLocalMatrix.

Parameters:

• vector World vector.

See: WorldToLocalMatrix

Return: Local vector.

The opposite of TransformVector.

function ToString

override string ToString()

Returns a string representation of the object, providing a human-readable description that includes the object's name, class type, device ID, and selected handedness.

Return: A string that represents the current object, including its name, class type, device ID, and selected handedness.

The returned string follows the format: "name <Class>(#id.handedness)", where:

• "name" is the value of the object's _objectName field.
• "Class" is the name of the object's class type.
• "id" is the device ID, formatted as a 4-character hexadecimal string, or "*" if the device ID is ANY_ID. If DeviceId is ANY_ID, the value of SelectedDeviceId is used.
• "handedness" is the selected handedness, represented as ".left", ".right", or omitted if SelectedHandedness is Nil.

This method helps in debugging and logging by providing a concise and informative description of the object.

Protected Functions Documentation

function Setup

virtual override void Setup()

This method is automatically called once the _performSetup flag is set to handle consuming calculations too heavy to be called on each frame. This method can be override with taking care to keep base call. Use SetSetupToPerform to trigger Setup call.

Reimplements: Haply::Inverse::Unity::DeviceBehaviour::Setup

function FixedUpdate

virtual override void FixedUpdate()

Reimplements: Haply::Inverse::Unity::DeviceBehaviour::FixedUpdate

Public Property Documentation

property DeviceType

override DeviceType DeviceType;

Gets the type of device, always returning DeviceType.Inverse3 for this controller.

property Cursor

override CursorBehaviour Cursor;

This property overrides the base DeviceBehaviour.Cursor property and can be safely cast to Inverse3Cursor. Setting this property also updates the DeviceBehaviour._performSetup flag.

property Body

Inverse3Body Body;

GameObject automatically rotating with the Inverse3 body Orientation.

property CursorLocalPosition

Vector3 CursorLocalPosition;

Gets the position of the Inverse3 cursor in meters (m) in the device local space.

The device DeviceBehaviour.ConnectionState must be DeviceConnectionState.Opened first to get a consistent value.

property LocalPosition

Vector3 LocalPosition;

property CursorPosition

Vector3 CursorPosition;

Gets the Inverse3 cursor world space position from CursorLocalPosition and LocalToWorldMatrix

See: Transform.position, TransformPoint

property Position

Vector3 Position;

property CursorLocalVelocity

Vector3 CursorLocalVelocity;

Gets the velocity of the Inverse3 cursor in meters per second (m/s) in the device local space.

The provided velocity is calculated using velocity estimation algorithms and does not require further filtering or processing.

The device DeviceBehaviour.ConnectionState must be DeviceConnectionState.Opened first to get a consistent value.

property LocalVelocity

Vector3 LocalVelocity;

property CursorVelocity

Vector3 CursorVelocity;

Gets the Inverse3 cursor world space velocity from CursorLocalVelocity and LocalToWorldMatrix

TransformVector

property Velocity

Vector3 Velocity;

property JointsAngles

Joint3 JointsAngles;

Gets the current joint angles of the Inverse3 device in degrees.

Each component of the Vector3 represents the angle of one of the device's joints:

• x: Angle of Joint 1, which controls the head of the device.
• y: Angle of Joint 2, which controls the inner joint of the arms.
• z: Angle of Joint 3, which controls the outer joint of the arms.

These angles are essential for understanding and controlling the spatial orientation of the device's moving parts.

property JointsAngularVelocity

Joint3 JointsAngularVelocity;

Gets the current angular velocities of the Inverse3 device's joints in degrees per second.

Each component of the Vector3 represents the angular velocity of one of the device's joints:

• x: Angular velocity of Joint 1, which controls the head of the device.
• y: Angular velocity of Joint 2, which controls the inner joint of the arms.
• z: Angular velocity of Joint 3, which controls the outer joint of the arms.

Angular velocities help in monitoring the speed at which the joints are moving, which is crucial for dynamic control and feedback applications.

property SelectedHandedness

HandednessType SelectedHandedness;

Gets or sets the desired handedness type of the Inverse3 device.

If set to HandednessType.Nil, the first device found will be selected at runtime by the DeviceMapper.

Use Handedness to know the real device handedness at runtime.

property Handedness

HandednessType Handedness;

Gets the handedness type of the device at runtime.

property Powered

bool Powered;

Indicates whether the device is currently powered.

See: DeviceMapper.devicesInfoPollingMode

This property isn't refreshed in real-time. It can be updated manually with RequestPowerSupplyStatus, or automatically using the DeviceMapper.

property Orientation

Quaternion Orientation;

Gets the current orientation of the Inverse3 device based on the last received orientation data.

See: DeviceMapper.devicesInfoPollingMode

This property isn't refreshed in real-time. It can be updated manually with RequestOrientation, or automatically by the DeviceMapper.

property WorkspaceCenterLeft

static Vector3 WorkspaceCenterLeft = new(-0.05f, 0.15f, -0.12f);

Workspace center local coordinates for a HandednessType.Left-handed device.

See: CursorSetLocalPosition, SelectedHandedness

Setting the cursor at this local position will move the device where the head is parallel and the arms are perpendicular to the body.

property WorkspaceCenterRight

static Vector3 WorkspaceCenterRight = new(0.05f, 0.15f, -0.12f);

Workspace center local coordinates for a HandednessType.Right-handed device.

See: CursorSetLocalPosition, SelectedHandedness

Setting the cursor at this local position will move the device where the head is parallel and the arms are perpendicular to the body.

property WorkspaceCenter

Vector3 WorkspaceCenter;

Workspace center local coordinates depending on the Handedness value.

See: CursorSetLocalPosition, SelectedHandedness

Returns WorkspaceCenterRight if Handedness is HandednessType.Nil.

Setting the cursor at this local position will move the device where the head is parallel and the arms are perpendicular to the body.

property ControlMode

ControlMode ControlMode;

Gets the current control mode of the device.

Control modes dictate how the device responds to input commands and manages its outputs, such as cursor position or joint torques.

property ForceOutput

Vector3 ForceOutput;

Last force sent to the device by the CursorSetForce or CursorSetLocalForce methods.

property PositionOutput

Vector3 PositionOutput;

Last position sent to the device by the CursorSetPosition or CursorSetLocalPosition methods.

property JointsTorqueOutput

Joint3 JointsTorqueOutput;

Last torque sent to the device by the JointsSetTorque method.

property JointsAnglesOutput

Joint3 JointsAnglesOutput;

Last angles sent to the device by the JointsSetAngles method.

property LocalToWorldMatrix

Matrix4x4 LocalToWorldMatrix;

Matrix that transforms the device or Cursor space into world space.

See: SpaceTransformationReference, TransformPoint, TransformVector

The matrix depends on the SpaceTransformationReference.

This matrix can be used for converting positions and velocities from the local space of the device or cursor to the world space. It allows haptic-related calculations to be done accurately in environments where the Transform component's data is not directly accessible.

property WorldToLocalMatrix

Matrix4x4 WorldToLocalMatrix;

Matrix that transforms back from the world space into device or Cursor space.

See: SpaceTransformationReference, InverseTransformPoint, InverseTransformVector

The matrix depends on the SpaceTransformationReference.

This matrix can be used for converting calculated forces from the world space to the local space of the device or cursor. It allows haptic-related calculations to be done accurately in environments where the Transform component's data is not directly accessible.

Protected Property Documentation

property CoordinateConverter

override BaseCoordinateConverter CoordinateConverter;

property SpaceTransformationReference

Transform SpaceTransformationReference;

Reference transform used for setup LocalToWorldMatrix and WorldToLocalMatrix.

If Cursor is set, its parent is used. Else the current device transform.

Public Attributes Documentation

variable PowerSupplyStatusChanged

UnityEvent< Inverse3, bool > PowerSupplyStatusChanged;

Triggered whenever there is a change in the power supply status of the Inverse3 device.

See: Powered

variable ControlModeChanged

UnityEvent< Inverse3, ControlMode > ControlModeChanged;

Event triggered when the control mode of the device changes.

This allows for reactive programming patterns where changes in control mode can trigger specific behaviors or configurations.

---