Hands¶

Getting Hands¶

Get Hand objects from a Frame:

Frame frame = controller.Frame (); // controller is a Controller object
HandList hands = frame.Hands;
Hand firstHand = hands [0];

Or, if you know the ID from a previous frame:

Hand knownHand = frame.Hand (handID);

You can also get hands by their relative positions in the frame:

Frame frame = controller.Frame (); // controller is a Controller object
HandList hands = frame.Hands;

Hand leftmost = hands.Leftmost;
Hand rightmost = hands.Rightmost;
Hand frontmost = hands.Frontmost;

Note that the the leftmost() and rightmost() functions only identify which hand is farthest to the left or right. Use the Hand isLeft or isRight attribute to tell if a hand object represents a left or a right hand.

Getting the Hand Characteristics¶

A hand is described by its handedness, position, orientation, posture, and motion:

• isRight, isLeft — Whether the hand is a left or a right hand.
• Palm Position — The center of the palm measured in millimeters from the Leap Motion origin.
• Palm Velocity — The speed and movement direction of the palm in millimeters per second.
• Palm Normal — A vector perpendicular to the plane formed by the palm of the hand. The vector points downward out of the palm.
• Direction — A vector pointing from the center of the palm toward the fingers.
• grabStrength, pinchStrength — Describe the posture of the hand.
• Motion factors — Provide relative scale, rotation, and translation factors for movement between two frames.

The hand’s position is given by its palm position attribute, which provides a vector containing the 3-dimensional coordinates of the palm center point in millimeters from the Leap Motion origin. The hand’s orientation is given by two vectors: the direction, which points from the palm center towards the fingers, and the palm normal, which points out of the palm, perpendicular to the plane of the hand.

The movement of the hand is given by the velocity attribute, which is a vector providing the instantaneous motion of the hand in mm/s. You can also get motion factors that translate how a hand has moved between two given frames into translation, rotation, and scaling values.

The following code snippet illustrates how to get a Hand object from a frame and access its basic attributes:

Hand hand = frame.Hands.Rightmost;
Vector position = hand.PalmPosition;
Vector velocity = hand.PalmVelocity;
Vector direction = hand.Direction;

Getting the Fingers¶

You can get the fingers associated with a hand as a list or individually using an ID obtained in a previous frame.

By list:

// hand is a Hand object
PointableList pointables = hand.Pointables;
FingerList fingers = hand.Fingers;

By ID from a previous frame:

Pointable knownPointable = hand.Pointable (pointableID);

To get a finger by relative position within the Leap field of view, use the right-, left- and frontmost functions of the matching list class:

// hand is a Hand object
Pointable leftPointable = hand.Pointables.Leftmost;
Finger rightFinger = hand.Fingers.Rightmost;
Finger frontFinger = hand.Fingers.Frontmost;

Note that these functions are relative to the Leap Motion origin, not to the hand itself. To get the fingers relative to the hand, you can use the Leap Matrix class to transform the finger positions into the hands frame of reference.

Computing the Hand Orientation¶

You can compute the hand orientation angles using the Hand direction and normal vectors.

The normal vector points perpendicularly out of the hand; the direction vector points forward.

The Vector class defines functions for getting the pitch (angle around the x-axis), yaw (angle around the y-axis), and roll (angle around the z-axis):

float pitch = hand.Direction.Pitch;
float yaw = hand.Direction.Yaw;
float roll = hand.PalmNormal.Roll;

Note that the roll function only provides the expected angle when used with a normal vector.

Transforming Finger Coordinates into the Hand’s Frame of Reference¶

Sometimes it is useful to obtain the coordinates of the fingers of a hand with respect to the hand’s frame of reference. This lets you sort the fingers spatially and can simplify analysis of finger positions. You can create a transform matrix using the Leap Matrix class to transform the finger position and direction coordinates. The hand frame of reference can be usefully defined by the hand’s Basis and PalmPosition. The Basis orients the x-axis sideways across the hand, the z-axis pointing forward, and the y-axis parallel with the palm normal. The origin of the transform is the PalmPosition.

Frame frame = controller.Frame ();
for (int h = 0; h < frame.Hands.Count; h++) {
    Hand leapHand = frame.Hands [h];
    
    Vector handXBasis = leapHand.PalmNormal.Cross (leapHand.Direction).Normalized;
    Vector handYBasis = -leapHand.PalmNormal;
    Vector handZBasis = -leapHand.Direction;
    Vector handOrigin = leapHand.PalmPosition;
    Matrix handTransform = new Matrix (handXBasis, handYBasis, handZBasis, handOrigin);
    handTransform = handTransform.RigidInverse ();
    
    for (int f = 0; f < leapHand.Fingers.Count; f++) {
        Finger leapFinger = leapHand.Fingers [f];
        Vector transformedPosition = handTransform.TransformPoint (leapFinger.TipPosition);
        Vector transformedDirection = handTransform.TransformDirection (leapFinger.Direction);
        // Do something with the transformed fingers
    }
}

foreach (Hand hand in handList) {
    Console.WriteLine (hand.ToString ());
}

Hand furthestRight = frame.Hands.Rightmost;