Haply::Inverse::Unity::Inverse3

Inherits from DeviceBehaviour

Public Events

	Name
DeviceDelegate	DeviceStateChanged() Event triggered on each haptic frame.

Public Functions

	Name
delegate void	DeviceDelegate(Inverse3 device) Represents a method that will handle the Inverse3.DeviceStateChanged event of an Inverse3 device.
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	JointsSetTorque(in Vector3 torque) Sets the desired torque in newton millimeters (Nmm) for each joint of the Inverse3 device.
void	JointsSetTorque(float x, float y, float z)
void	JointsSetAngles(in Vector3 angles) Sets the desired joint angles in degrees (°) for each joint of the Inverse3 device.
void	JointsSetAngles(float x, float y, float z)
bool	TryResetForce() Attempts to reset all force and position control for the cursor.
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()

Protected Functions

	Name
override void	Setup()
override void	FixedUpdate()
override void	AddClientListeners(Internal.ClientConnection clientConnection)
override void	RemoveClientListeners(Internal.ClientConnection clientConnection)

Public Properties

	Name
override DeviceType	DeviceType
override CursorBehaviour	Cursor
Vector3	LocalPosition Gets the position of the Inverse3 cursor in meters (m) in the device local space.
Vector3	Position Gets the Inverse3 cursor world space position from LocalPosition and LocalToWorldMatrix
Vector3	LocalVelocity Gets the velocity of the Inverse3 cursor in meters per second (m/s) in the device local space.
Vector3	Velocity Gets the Inverse3 cursor world space velocity from LocalVelocity and LocalToWorldMatrix
HandednessType	SelectedHandedness Gets or sets the desired handedness type of the Inverse3 device.
HandednessType	Handedness Gets the handedness type of the device at runtime.
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.
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
Transform	SpaceTransformationReference Reference transform used for setup LocalToWorldMatrix and WorldToLocalMatrix.

Public Events Documentation

event DeviceStateChanged

DeviceDelegate DeviceStateChanged()

Event triggered on each haptic frame.

See: ClientConfiguration.HapticFrequencyHz

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 Position, Velocity, LocalPosition, or LocalVelocity.

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.HapticFrequencyHz.

Public Functions Documentation

function DeviceDelegate

delegate void DeviceDelegate(
    Inverse3 device
)

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

Parameters:

• device The Inverse3 device instance raising the event.

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 LocalPosition and LocalVelocity. If the force calculation is based on world space coordinates (Position and Velocity) 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.

See: WorkspaceCenterLeft, WorkspaceCenterRight

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 (Position, Velocity) 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 JointsSetTorque

void JointsSetTorque(
    in Vector3 torque
)

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

Parameters:

• torque The desired torque vector in newton millimeters (Nmm).

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.

• Joint 1 controls the head of the device.
• Joint 2 controls the inner joint of the arms.
• Joint 3 controls the outer joint of the arms.

function JointsSetTorque

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

function JointsSetAngles

void JointsSetAngles(
    in Vector3 angles
)

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

Parameters:

• angles The desired joint angles vector in degrees (°).

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.

• Joint 1 controls the head of the device.
• Joint 2 controls the inner joint of the arms.
• Joint 3 controls the outer joint of the arms.

function JointsSetAngles

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

function TryResetForce

bool TryResetForce()

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 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()

Protected Functions Documentation

function Setup

override void Setup()

function FixedUpdate

override void FixedUpdate()

function AddClientListeners

override void AddClientListeners(
    Internal.ClientConnection clientConnection
)

function RemoveClientListeners

override void RemoveClientListeners(
    Internal.ClientConnection clientConnection
)

Public Property Documentation

property DeviceType

override DeviceType DeviceType;

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 LocalPosition

Vector3 LocalPosition;

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 Position

Vector3 Position;

Gets the Inverse3 cursor world space position from LocalPosition and LocalToWorldMatrix

See: Transform.position, TransformPoint

property LocalVelocity

Vector3 LocalVelocity;

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 Velocity

Vector3 Velocity;

Gets the Inverse3 cursor world space velocity from LocalVelocity and LocalToWorldMatrix

TransformVector

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 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 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 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 position will move the device where the head is parallel and the arms are perpendicular to the body.

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 SpaceTransformationReference

Transform SpaceTransformationReference;

Reference transform used for setup LocalToWorldMatrix and WorldToLocalMatrix.

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

---