Realistic Hand Interaction API

API Description

HandGrabInteractor

Inherited Class: MonoBehaviour, IHandGrabber

Public Properties

Name Type Description
grabDistance float Get/Set the grabbing distance for HandGrabInteractable objects.
enableCollider bool Get/Set true it means enable collider for the Wave Hand.
isLeft bool Return true if the handedness is left-handed.

Public Methods

Name Description
Pose GetCurrentJointPose(int jointId) Get the current joint pose of the grabber.
bool GetGrabPoseJointRotation(int jointId, out Quaternion rotation) Get the rotation of the joint in the grab pose.

HandGrabInteractable

Inherited Class: MonoBehaviour, IHandGrabbable

Public Properties

Name Type Description
grabPoses List<GrabPose> Get the list of GrabPose.
bestGrabPose GrabPose Get the best grabPose base on the position of grabber.

Public Methods

Name Description
void ShowIndicator(bool enable, HandGrabInteractor grabber) Enable/Disable indicators. If enabled, display the closest indicator based on grabber position.
float CalculateDistanceScore(Vector3 grabberPos, float grabDistance = 0.03f) Calculate the shortest distance between the grabber and the grabbable and convert it into a score based on grabDistance

IHandGrabber

Inherited Interface: IGrabber

Public Properties

Name Type Description
handedness Handedness Get/Set the handedness of hand.
handGrabState HandGrabState Get the HandGrabState with handedness.

IHandGrabbable

Inherited Interface: IGrabbable

Public Properties

Name Type Description
fingerRequirement FingerRequirement The requirement states which fingers are required when the grabber want to grab it.

IGrabber

Public Properties

Name Type Description
grabbable IGrabbable. Return IGrabbable.
isGrabbing bool Return true if grabbing a grabbable object.

Public Methods

Name Description
AddBeginGrabbedListener(OnBeginGrabbed handler) Adds a listener for the event when the grabber begins grabbing.
RemoveBeginGrabbedListener(OnBeginGrabbed handler) Removes a listener for the event when the grabber begins grabbing.
AddEndGrabbedListener(OnEndGrabbed handler) Adds a listener for the event when the grabber ends grabbing.
RemoveEndGrabbedListener(OnEndGrabbed handler) Removes a listener for the event when the grabber ends grabbing.

IGrabbable

Public Properties

Name Type Description
grabber IGrabber Return IGrabber.
isGrabbed bool Return true if currently being grabbed.
isGrabbable bool Get/Set true if IGrabbable could be grabbable.
isMovable bool Get/Set true if IGrabber could be able to push it.

Public Methods

Name Description
void SetGrabber(IGrabber grabber) Set the grabber for the hand grabbable object.
void AddBeginGrabbedListener(OnBeginGrabbed handler) Add a listener for the event triggered when the grabbable object is grabbed.
void RemoveBeginGrabbedListener(OnBeginGrabbed handler) Remove a listener for the event triggered when the grabbable object is grabbed.
void AddEndGrabbedListener(OnEndGrabbed handler) Add a listener for the event triggered when the grabbable object is released.
void RemoveEndGrabbedListener(OnEndGrabbed handler) Remove a listener for the event triggered when the grabbable object is released.

GrabManager

Public Static Properties

Name Type Description
handGrabbers IReadOnlyList<HandGrabInteractor> Get the readonly list of HandGrabInteractor.
handGrabbables IReadOnlyList<HandGrabInteractable> Get the readonly list of HandGrabInteractable.

Public Static Methods

Name Description
bool RegisterGrabber(IGrabber grabber) Register the grabber in the grabber registry.
bool UnregisterGrabber(IGrabber grabber) Remove the grabber from the grabber registry.
bool RegisterGrabbable(IGrabbable grabbable) Register the grabbable in the grabbable registry.
bool UnregisterGrabbable(IGrabbable grabbable) Remove the grabbable from the grabbable registry. 
using UnityEngine;
using Wave.Essence.Hand.Interaction;

public class GrabTest : MonoBehaviour
{
    public void SwitchGrabbableMovable()
    {
        foreach (var grabber in GrabManager.handGrabbers)
        {
            if (grabber.isGrabbing)
            {
                HandGrabInteractable handGrabbable = (HandGrabInteractable)grabber.grabbable;
                if (handGrabbable != null)
                {
                    handGrabbable.forceMovable = !handGrabbable.forceMovable;
                    Debug.Log($"{grabber.name} is grabbing at {handGrabbable.name}");
                    Debug.Log($"Is Grabbable : {handGrabbable.isGrabbable}\n" +
                              $"Force Movable : {handGrabbable.forceMovable}\n" +
                              $"Finger Requirement : {handGrabbable.fingerRequirement}");
                }
            }
        }
    }

    public void SetGrabberGrabDistance(bool isLeft, float grabDistance)
    {
        foreach (var grabbable in GrabManager.handGrabbables)
        {
            if (grabbable.isGrabbed)
            {
                HandGrabInteractor handGrabber = (HandGrabInteractor)grabbable.grabber;
                if (handGrabber != null && handGrabber.isLeft == isLeft)
                {
                    handGrabber.grabDistance = grabDistance;
                    Debug.Log($"{grabbable.name} is being grabbed by {handGrabber.name}");
                    Debug.Log($"Is Grabbing : {handGrabber.isGrabbing}\n" +
                              $"Enable Collider : {handGrabber.enableCollider}\n" +
                              $"Grab Distance : {handGrabber.grabDistance}");
                }
            }
        }
    }
}

Grab

Public Static Methods

Name Description
bool HandBeginGrab(IHandGrabber grabber, IHandGrabbable grabbable) Checks if the hand grabber is beginning to grab grabbable object.
bool HandIsGrabbing(IHandGrabber grabber, IHandGrabbable grabbable) Check if the hand grabber is grabbing the grabbable object.
bool HandDoneGrab(IHandGrabber grabber, IHandGrabbable grabbable) Check if the hand grabber has just finished grabbing the grabbable.
float CalculateHandGrabScore(IHandGrabber grabber, IHandGrabbable grabbable) Calculate the grab score between the grabber and the grabbable object.

HandGrabState

Inherited Interface: GrabState

Public Properties

Name Type Description
isLeft bool Return true if the handedness is left.

Public Methods

Name Description
bool HandGrabStateIsChanged(FingerRequirement fingerRequirement, bool expectState) Checks if the state of the FingerPinchState for each finger has changed as expected.
bool HandKeepGrabbing(FingerRequirement fingerRequirement) Determine whether the hand is keeping grabbing based on finger requirements.
float HandGrabNearStrength(FingerRequirement fingerRequirement) Calculates the score of the current hand grab state based on FingerRequirement.
Pose GetJointPose(JointType jointType) Get the pose of the specified joint.
Pose GetJointPose(int jointId) Get the pose of the specified joint.
Quaternion GetDefaultJointRotationInGesture(HandGrabGesture handGrabGesture, int jointId) Get the default joint rotation for a specific HandGrabGesture and joint type.

GrabState

Public Methods

Name Description
UpdateState Should update grab state each frame.

CachedHand

Public Methods

Name Description
HandData Get(bool isLeft) Get the complete data for the left or right hand.

HandData

Public Properties

Name Type Description
valid bool Return true if the hand is valid.
isTracked bool Return true if the hand tracking is working.
normal Vector3 Get the normal of hand.
direction Vector3 Get the direction of hand.
palm JointData Get the jointdata of palm of hand.
wrist JointData Get the jointdata of wrist of hand.
thumb FingerData Get the FingerData of thumb of hand.
index FingerData Get the FingerData of index of hand.
middle FingerData Get the FingerData of middle of hand.
ring FingerData Get the FingerData of ring of hand.
pinky FingerData Get the FingerData of pinky of hand.

Public Methods

Name Description
GetJointPosition(JointType joint, ref Vector3 position) Get the position of a specific joint.
GetJointRotation(JointType joint, ref Quaternion rotation) Get the rotation of a specific joint.
GetDefaultJointRotationInGesture(bool isLeft, HandGrabGesture handGrabGesture, JointType joint, ref Quaternion rotation) Get the default joint rotation for a specific HandGrabGesture and joint type.

FingerData

Public Properties

Name Type Description
direction Vector3 Get the direction of finger.
joints Array of JointData Get the all joints of finger.
joint0 JointData Get the JointData of JointId.Joint0 in joints.
joint1 JointData Get the JointData of JointId.Joint1 in joints.
joint2 JointData Get the JointData of JointId.Joint2 in joints.
joint3 JointData Get the JointData of JointId.Joint3 in joints.
tip JointData Get the JointData of JointId.tip in joints.

Struct Description

JointData

Public Properties

Name Type Description
position Vector3 The position of joint.
rotation Quaternion The rotation of joint.
velocity Vector3 The velocity of joint.

FingerRequirement

Public Properties

Name Type Description
thumb GrabRequirement The grabbing requirement of the thumb finger.
index GrabRequirement The grabbing requirement of the index finger.
middle GrabRequirement The grabbing requirement of the middle finger.
ring GrabRequirement The grabbing requirement of the ring finger.
pinky GrabRequirement The grabbing requirement of the pinky finger.

GrabPose

Public Properties

Name Type Description
grabPoseName string The name of the grab pose.
handGrabGesture HandGrabGesture The hand gesture while grabbing.
recordedGrabRotations Array of Quaternion The preserved joint rotation of a hand during recording.
isLeft bool True if the hand is left; otherwise, false.
indicator Indicator The indicator of the grab pose.
grabOffSet GrabOffset The grab offset between grabber and grabbable objects.

HandGrabGesture

Public Properties

Name Type Description
thumbPose FingerBendingLevel The degree of thumb finger bending when grabbing.
indexPose FingerBendingLevel The degree of index finger bending when grabbing.
middlePose FingerBendingLevel The degree of middle finger bending when grabbing.
ringPose FingerBendingLevel The degree of ring finger bending when grabbing.
pinkyPose FingerBendingLevel The degree of pinky finger bending when grabbing.

Indicator

Public Properties

Name Type Description
enableIndicator bool True to enable the indicator, false to disable it.
autoIndicator bool True to automatically generate an indicator if needed; otherwise, false.
target Gameobject The prefab GameObject.
grabOffSet GrabOffset The grab offset between grabbable objects and indicator.

GrabOffset

Public Properties

Name Type Description
position Vector3 The position offset between grabber and grabbable objects.
rotation Quaternion The rotation offset between grabber and grabbable objects.

Enum Description

JointType

enum JointType {
  Palm = HandManager.HandJoint.Palm, // 0
  Wrist = HandManager.HandJoint.Wrist, // 1
  Thumb_Joint0 = HandManager.HandJoint.Thumb_Joint0, // 2
  Thumb_Joint1 = HandManager.HandJoint.Thumb_Joint1, // 3
  Thumb_Joint2 = HandManager.HandJoint.Thumb_Joint2, // 4
  Thumb_Tip = HandManager.HandJoint.Thumb_Tip, // 5
  Index_Joint0 = HandManager.HandJoint.Index_Joint0, // 6
  Index_Joint1 = HandManager.HandJoint.Index_Joint1, // 7
  Index_Joint2 = HandManager.HandJoint.Index_Joint2, // 8
  Index_Joint3 = HandManager.HandJoint.Index_Joint3, // 9
  Index_Tip = HandManager.HandJoint.Index_Tip, // 10
  Middle_Joint0 = HandManager.HandJoint.Middle_Joint0, // 11
  Middle_Joint1 = HandManager.HandJoint.Middle_Joint1, // 12
  Middle_Joint2 = HandManager.HandJoint.Middle_Joint2, // 13
  Middle_Joint3 = HandManager.HandJoint.Middle_Joint3, // 14
  Middle_Tip = HandManager.HandJoint.Middle_Tip, // 15
  Ring_Joint0 = HandManager.HandJoint.Ring_Joint0, // 16
  Ring_Joint1 = HandManager.HandJoint.Ring_Joint1, // 17
  Ring_Joint2 = HandManager.HandJoint.Ring_Joint2, // 18
  Ring_Joint3 = HandManager.HandJoint.Ring_Joint3, // 19
  Ring_Tip = HandManager.HandJoint.Ring_Tip, // 20
  Pinky_Joint0 = HandManager.HandJoint.Pinky_Joint0, // 21
  Pinky_Joint1 = HandManager.HandJoint.Pinky_Joint1, // 22
  Pinky_Joint2 = HandManager.HandJoint.Pinky_Joint2, // 23
  Pinky_Joint3 = HandManager.HandJoint.Pinky_Joint3, // 24
  Pinky_Tip = HandManager.HandJoint.Pinky_Tip, // 25
  Count = Pinky_Tip + 1, // 26
}

JointId

enum JointId {
  Invalid = -1,
  Joint0 = 0,
  Joint1 = 1,
  Joint2 = 2,
  Joint3 = 3,
  Tip = 4,
  Count = 5,
}

FingerId

enum FingerId {
  Invalid = -1,
  Thumb = 0,
  Index = 1,
  Middle = 2,
  Ring = 3,
  Pinky = 4,
  Count = 5,
}

FingerFlags

enum FingerFlags {
  None = 0, // 0
  Thumb = 1 << FingerId.Thumb, // 1
  Index = 1 << FingerId.Index, // 2
  Middle = 1 << FingerId.Middle, // 4
  Ring = 1 << FingerId.Ring, // 8
  Pinky = 1 << FingerId.Pinky, // 16
  All = Thumb | Index | Middle | Ring | Pinky //31
}

HandId

enum HandId {
  Right = 0,
  Left = 1,
  Both = 2,
}

Handedness

enum Handedness {
  Right = HandId.Right, // 0
  Left = HandId.Left, // 1
}

GrabRequirement

enum GrabRequirement {
  Ignored = 0,
  Required = 1,
  Optional = 2,
}

FingerBendingLevel

enum FingerBendingLevel {
  Level0 = 0,
  Level1 = 1,
  Level2 = 2,
  Level3 = 3,
  Level4 = 4,
  Level5 = 5,
}

Delegate Description

OnBeginGrab

void OnBeginGrab(IGrabber grabber)

OnEndGrab

void OnEndGrab(IGrabber grabber)

OnBeginGrabbed

void OnBeginGrabbed(IGrabbable grabbable)

OnEndGrabbed

void OnEndGrabbed(IGrabbable grabbable)