The LeapHand class reports the physical characteristics of a detected hand. More...

Inherits NSObject.

Instance Methods
(LeapFinger *)	- finger:
	The LeapFinger object with the specified ID attached to this hand. More...

(LeapPointable *)	- pointable:
	The LeapPointable object with the specified ID associated with this hand. More...

(float)	- rotationAngle:
	The angle of rotation around the rotation axis derived from the change in orientation of this hand, and associated fingers, between the current LeapFrame and the specified LeapFrame. More...

(float)	- rotationAngle:axis:
	The angle of rotation around the specified axis derived from the change in orientation of this hand, and associated fingers, between the current LeapFrame and the specified LeapFrame. More...

(LeapVector *)	- rotationAxis:
	The axis of rotation derived from the change in orientation of this hand, and associated fingers, between the current LeapFrame and the specified LeapFrame. More...

(LeapMatrix *)	- rotationMatrix:
	The transform matrix expressing the rotation derived from the change in orientation of this hand, and associated fingers, between the current LeapFrame and the specified LeapFrame. More...

(float)	- rotationProbability:
	The estimated probability that the hand motion between the current LeapFrame and the specified LeapFrame is intended to be a rotating motion. More...

(float)	- scaleFactor:
	The scale factor derived from this hand's motion between the current LeapFrame and the specified LeapFrame. More...

(float)	- scaleProbability:
	The estimated probability that the hand motion between the current LeapFrame and the specified LeapFrame is intended to be a scaling motion. More...

(LeapVector *)	- translation:
	The change of position of this hand between the current LeapFrame and the specified LeapFrame. More...

(float)	- translationProbability:
	The estimated probability that the hand motion between the current frame and the specified LeapFrame is intended to be a translating motion. More...

Class Methods
(LeapHand *)	+ invalid
	Returns an invalid LeapHand object. More...

Properties
LeapArm *	arm
	The arm to which this hand is attached. More...

LeapMatrix *	basis
	The orientation of the hand as a basis matrix. More...

float	confidence
	Rates how well the internal hand model fits the observed data. More...

LeapVector *	direction
	The direction from the palm position toward the fingers. More...

NSArray *	fingers
	The list of LeapFinger objects detected in this frame that are attached to this hand, given in arbitrary order. More...

LeapFrame *	frame
	The LeapFrame associated with this Hand. More...

float	grabAngle
	The angle between the fingers and the hand of a grab hand pose. More...

float	grabStrength
	Deprecated. More...

int32_t	id
	A unique ID assigned to this LeapHand object, whose value remains the same across consecutive frames while the tracked hand remains visible. More...

BOOL	isLeft
	Identifies whether this Hand is a left hand. More...

BOOL	isRight
	Identifies whether this Hand is a right hand. More...

BOOL	isValid
	Reports whether this is a valid LeapHand object. More...

LeapVector *	palmNormal
	The normal vector to the palm. More...

LeapVector *	palmPosition
	The center position of the palm in millimeters from the Leap origin. More...

LeapVector *	palmVelocity
	The rate of change of the palm position in millimeters/second. More...

float	palmWidth
	The estimated width of the palm when the hand is in a flat position. More...

float	pinchDistance
	The distance between the thumb and index finger of a pinch hand pose. More...

float	pinchStrength
	Deprecated. More...

NSArray *	pointables
	The list of LeapPointable objects (fingers) detected in this frame that are associated with this hand, given in arbitrary order. More...

LeapVector *	sphereCenter
	The center of a sphere fit to the curvature of this hand. More...

float	sphereRadius
	The radius of a sphere fit to the curvature of this hand. More...

LeapVector *	stabilizedPalmPosition
	The stabilized tip position of this Pointable. More...

float	timeVisible
	The duration of time this Hand has been visible to the Leap Motion Controller. More...

Detailed Description

The LeapHand class reports the physical characteristics of a detected hand.

Hand tracking data includes a palm position and velocity; vectors for the palm normal and direction to the fingers; properties of a sphere fit to the hand; and lists of the attached fingers.

Note that LeapHand objects can be invalid, which means that they do not contain valid tracking data and do not correspond to a physical entity. Invalid LeapHand objects can be the result of asking for a Hand object using an ID from an earlier frame when no hand objects with that ID exist in the current frame. A hand object created from the LeapHand constructor is also invalid. Test for validity with the LeapHand isValid function.

Since 1.0

Method Documentation

- (LeapFinger *) finger: (int32_t) fingerId

The LeapFinger object with the specified ID attached to this hand.

Use this [LeapHand finger:] function to retrieve a LeapFinger object attached to this hand using an ID value obtained from a previous frame. This function always returns a LeapFinger object, but if no finger with the specified ID is present, an invalid LeapFinger object is returned.

LeapFinger *knownFinger = [hand finger:fingerID];

Note that ID values persist across frames, but only until tracking of a particular object is lost. If tracking of a finger is lost and subsequently regained, the new LeapFinger object representing that finger may have a different ID than that representing the finger in an earlier frame.

Parameters

fingerId The ID value of a LeapFinger object from a previous frame.

Returns: The LeapFinger object with the matching ID if one exists for this hand in this frame; otherwise, an invalid LeapFinger object is returned.

Since 1.0

+ (LeapHand *) invalid

Returns an invalid LeapHand object.

LeapHand *badHand = LeapHand.invalid;

Returns: The invalid LeapHand instance.

Since 1.0

- (LeapPointable *) pointable: (int32_t) pointableId

The LeapPointable object with the specified ID associated with this hand.

Use this [LeapHand pointable:] function to retrieve a LeapPointable object associated with this hand using an ID value obtained from a previous frame. This function always returns a LeapPointable object, but if no finger with the specified ID is present, an invalid LeapPointable object is returned.

LeapPointable *knownPointable = [hand pointable:pointableID];

Note that ID values of fingers are based on the hand ID. Hand IDs persist across frames, but only until tracking of that hand is lost. If tracking of a hand is lost and subsequently regained, the new LeapHand object representing that hand will have a different ID than that representing the hand in an earlier frame. Thus the IDs for the fingers on the hand will also change.

Parameters

pointableId The ID value of a LeapPointable object from a previous frame.

Returns: The LeapPointable object with the matching ID if one exists for this hand in this frame; otherwise, an invalid LeapPointable object is returned.

Since 1.0

- (float) rotationAngle: (const LeapFrame *) sinceFrame

The angle of rotation around the rotation axis derived from the change in orientation of this hand, and associated fingers, between the current LeapFrame and the specified LeapFrame.

LeapFrame *lastFrame = [controller frame:1];
float angleOfRotationSinceLastFrame =
    [hand rotationAngle:lastFrame];

Parameters

sinceFrame The starting LeapFrame for computing the relative rotation.

Returns: A positive value representing the heuristically determined rotational change of the hand between the current frame and that specified in the sinceFrame parameter.

- (float) rotationAngle:	(const LeapFrame *)	sinceFrame
axis:	(const LeapVector *)	axis

The angle of rotation around the specified axis derived from the change in orientation of this hand, and associated fingers, between the current LeapFrame and the specified LeapFrame.

LeapFrame *lastFrame = [controller frame:1];
float angleOfRotationAroundYSinceLastFrame =
    [hand rotationAngle:lastFrame axis:LeapVector.yAxis];

Parameters

sinceFrame	The starting LeapFrame for computing the relative rotation.
axis	A LeapVector representing the axis to measure rotation around.

Returns: A value representing the heuristically determined rotational change of the hand between the current frame and that specified in the sinceFrame parameter around the specified axis.

- (LeapVector *) rotationAxis: (const LeapFrame *) sinceFrame

The axis of rotation derived from the change in orientation of this hand, and associated fingers, between the current LeapFrame and the specified LeapFrame.

LeapFrame *lastFrame = [controller frame:1];
LeapVector *axisOfRotationSinceLastFrame =
    [hand rotationAxis:lastFrame];

Parameters

sinceFrame The starting LeapFrame for computing the relative rotation.

Returns: A LeapVector containing the normalized direction vector representing the heuristically determined axis of rotational change of the hand between the current frame and that specified in the sinceFrame parameter.

- (LeapMatrix *) rotationMatrix: (const LeapFrame *) sinceFrame

The transform matrix expressing the rotation derived from the change in orientation of this hand, and associated fingers, between the current LeapFrame and the specified LeapFrame.

LeapFrame *lastFrame = [controller frame:1];
LeapMatrix *rotationSinceLastFrame =
    [hand rotationMatrix:lastFrame];

Parameters

sinceFrame The starting LeapFrame for computing the relative rotation.

Returns: A transformation LeapMatrix representing the heuristically determined rotational change of the hand between the current frame and that specified in the sinceFrame parameter.

- (float) rotationProbability: (const LeapFrame *) sinceFrame

The estimated probability that the hand motion between the current LeapFrame and the specified LeapFrame is intended to be a rotating motion.

LeapFrame *lastFrame = [controller frame:1];
float rotationIntent =
    [hand rotationProbability:lastFrame];

Parameters

sinceFrame The starting LeapFrame for computing the relative rotation.

Returns: A value between 0 and 1 representing the estimated probability that the hand motion between the current frame and the specified frame is intended to be a rotating motion.

- (float) scaleFactor: (const LeapFrame *) sinceFrame

The scale factor derived from this hand's motion between the current LeapFrame and the specified LeapFrame.

LeapFrame *lastFrame = [controller frame:1];
float scaleChangeSinceLastFrame =
    [hand scaleFactor:lastFrame];

Parameters

sinceFrame The starting LeapFrame for computing the relative scaling.

Returns: A positive value representing the heuristically determined scaling change ratio of the hand between the current frame and that specified in the sinceFrame parameter.

- (float) scaleProbability: (const LeapFrame *) sinceFrame

The estimated probability that the hand motion between the current LeapFrame and the specified LeapFrame is intended to be a scaling motion.

LeapFrame *lastFrame = [controller frame:1];

float scaleIntent = [hand scaleProbability:lastFrame];

Parameters

sinceFrame The starting LeapFrame for computing the relative scaling.

Returns: A value between 0 and 1 representing the estimated probability that the hand motion between the current frame and the specified frame is intended to be a scaling motion.

- (LeapVector *) translation: (const LeapFrame *) sinceFrame

The change of position of this hand between the current LeapFrame and the specified LeapFrame.

LeapFrame *lastFrame = [controller frame:1];
LeapVector *translationSinceLastFrame =
    [hand translation:lastFrame];

Parameters

sinceFrame The starting LeapFrame for computing the translation.

Returns: A LeapVector representing the heuristically determined change in hand position between the current frame and that specified in the sinceFrame parameter.

- (float) translationProbability: (const LeapFrame *) sinceFrame

The estimated probability that the hand motion between the current frame and the specified LeapFrame is intended to be a translating motion.

Parameters

sinceFrame The starting LeapFrame for computing the translation.

Returns: A value between 0 and 1 representing the estimated probability that the hand motion between the current frame and the specified frame is intended to be a translating motion.

Property Documentation

- (LeapArm*) arm

readnonatomicassign

The arm to which this hand is attached.

If the arm is not completely in view, Arm attributes are estimated based on the attributes of entities that are in view combined with typical human anatomy.

Returns: The Arm object for this hand.

Since: 2.0.3

- (LeapMatrix*) basis

readnonatomicassign

The orientation of the hand as a basis matrix.

The basis is defined as follows:

xAxis Positive in the direction of the pinky

yAxis Positive above the hand

zAxis Positive in the direction of the wrist

Note: Since the left hand is a mirror of the right hand, the basis matrix uses the left-hand rule for left hands.

LeapFrame *frame = [leap frame:0];
for (LeapHand *hand in [frame hands]) {
    LeapMatrix *handTransform = [[LeapMatrix alloc] initWithXBasis:hand.basis.xBasis
                                                            yBasis:hand.basis.yBasis
                                                            zBasis:hand.basis.zBasis
                                                            origin:hand.basis.origin];
    handTransform = [handTransform rigidInverse];
    LeapInteractionBox *iBox = frame.interactionBox;
    for (LeapFinger *finger in hand.fingers)
    {
        LeapVector *transformedPosition = [handTransform transformPoint:finger.tipPosition];
        LeapVector *transformedDirection = [handTransform transformDirection:finger.direction];
    }

Returns: The basis of the hand as a matrix.

Since: 2.0

- (float) confidence

readnonatomicassign

Rates how well the internal hand model fits the observed data.

The confidence level ranges between 0.0 and 1.0 inclusive, with 1.0 representing high confidence.

float modelToDataFitQuality = hand.confidence;

Returns: A confidence rating between 0 and 1.

Since 2.0

- (LeapVector*) direction

readnonatomicassign

The direction from the palm position toward the fingers.

LeapVector *direction = hand.direction;

The direction is expressed as a unit vector pointing in the same direction as the directed line from the palm position to the fingers.

Returns: The LeapVector pointing from the palm position toward the fingers.

Since 1.0

- (NSArray*) fingers

readnonatomicassign

The list of LeapFinger objects detected in this frame that are attached to this hand, given in arbitrary order.

NSArray *fingerList = hand.fingers;

The list can be empty if no fingers attached to this hand are detected.

Returns: An NSArray containing all LeapFinger objects attached to this hand.

Since 1.0

- (LeapFrame*) frame

readnonatomicweak

The LeapFrame associated with this Hand.

LeapFrame *owningFrame = hand.frame;

This property is a weak reference to the LeapFrame object so it is only valid during the lifetime of the LeapFrame object – while the LeapFrame object is in the history buffer or while your application maintains its own reference.

Returns: The associated LeapFrame object, if available; otherwise, an invalid LeapFrame object is returned.

Since 1.0

- (float) grabAngle

readnonatomicassign

The angle between the fingers and the hand of a grab hand pose.

The angle is computed by looking at the angle between the direction of the 4 fingers and the direction of the hand. Thumb is not considered when computing the angle. The angle is 0 radian for an open hand, and reaches pi radians when the pose is a tight fist.

Returns: The angle of a grab hand pose between 0 and pi radians (0 and 180 degrees).

Since 3.0

- (float) grabStrength

readnonatomicassign

Deprecated.

Use grabAngle() instead.

Since: 2.0

- (int32_t) id

readnonatomicassign

A unique ID assigned to this LeapHand object, whose value remains the same across consecutive frames while the tracked hand remains visible.

If tracking is lost (for example, when a hand is occluded by another hand or when it is withdrawn from or reaches the edge of the Leap field of view), the Leap may assign a new ID when it detects the hand in a future frame.

int handId = hand.id;

Use the ID value with the [LeapFrame hand:] function to find this LeapHand object in future frames.

LeapHand *knownHand = [frame hand:handID];

Returns: The ID of this hand.

Since 1.0

- (BOOL) isLeft

readnonatomicassign

Identifies whether this Hand is a left hand.

if(hand.isLeft)
{
    //Do left handed things...
}

Returns: True if the hand is a left hand.

Since 2.0

- (BOOL) isRight

readnonatomicassign

Identifies whether this Hand is a right hand.

if(hand.isRight)
{
    //Do right handed things...
}

Returns: True if the hand is a right hand.

Since 2.0

- (BOOL) isValid

readnonatomicassign

Reports whether this is a valid LeapHand object.

if(hand.isValid){
    //Use the data...
}

Returns: YES, if this LeapHand object contains valid tracking data.

Since 1.0

- (LeapVector*) palmNormal

readnonatomicassign

The normal vector to the palm.

If your hand is flat, this vector will point downward, or "out" of the front surface of your palm.

The direction is expressed as a unit vector pointing in the same direction as the palm normal (that is, a vector orthogonal to the palm).

LeapVector *normal = hand.palmNormal;

Returns: The LeapVector normal to the plane formed by the palm.

Since 1.0

- (LeapVector*) palmPosition

readnonatomicassign

The center position of the palm in millimeters from the Leap origin.

LeapVector *position = hand.palmPosition;

Returns: The LeapVector representing the coordinates of the palm position.

Since 1.0

- (LeapVector*) palmVelocity

readnonatomicassign

The rate of change of the palm position in millimeters/second.

LeapVector *speed = hand.palmVelocity;

Returns: The LeapVector representing the coordinates of the palm velocity.

Since 1.0

- (float) palmWidth

readnonatomicassign

The estimated width of the palm when the hand is in a flat position.

float averageWidth = hand.palmWidth;

Returns: The width of the palm in millimeters

Since: 2.0

- (float) pinchDistance

readnonatomicassign

The distance between the thumb and index finger of a pinch hand pose.

The distance is computed by looking at the shortest distance between the last 2 phalanges of the thumb and those of the index finger. This pinch measurement only takes thumb and index finger into account.

Returns: The distance between the thumb and index finger of a pinch hand pose in millimeters.

Since 3.0

- (float) pinchStrength

readnonatomicassign

Deprecated.

Use pinchDistance() instead.

Since: 2.0

- (NSArray*) pointables

readnonatomicassign

The list of LeapPointable objects (fingers) detected in this frame that are associated with this hand, given in arbitrary order.

NSArray *pointableList = hand.pointables;

The list will always contain 5 fingers even when some fingers are blocked from view and when the user is missing digits.

Returns: An NSArray containing all LeapPointable objects associated with this hand.

Since 1.0

- (LeapVector*) sphereCenter

readnonatomicassign

The center of a sphere fit to the curvature of this hand.

LeapVector *spherePosition = hand.sphereCenter;

This sphere is placed roughly as if the hand were holding a ball.

Returns: The LeapVector representing the center position of the sphere.

Since 1.0

- (float) sphereRadius

readnonatomicassign

The radius of a sphere fit to the curvature of this hand.

float diameter = 2 * hand.sphereRadius;

This sphere is placed roughly as if the hand were holding a ball. Thus the size of the sphere decreases as the fingers are curled into a fist.

Returns: The radius of the sphere in millimeters.

Since 1.0

- (LeapVector*) stabilizedPalmPosition

readnonatomicassign

The stabilized tip position of this Pointable.

LeapVector *stabilizedPosition = hand.stabilizedPalmPosition;

Smoothing and stabilization is performed in order to make this value more suitable for interaction with 2D content.

Returns: A modified tip position of this Pointable object with some additional smoothing and stabilization applied.

Since 1.0

- (float) timeVisible

readnonatomicassign

The duration of time this Hand has been visible to the Leap Motion Controller.

float handPersistence = hand.timeVisible;

Returns: The duration (in seconds) that this Hand has been tracked.

Since 1.0

LeapHand¶

Instance Methods

Class Methods

Properties

Detailed Description

Method Documentation

Property Documentation