Hand

Attributes:

Methods:

class Leap.Hand

The Hand 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.

The following example gets the rightmost hand from a HandList object and accesses some basic hand attributes:

hand = frame.hands.rightmost
position = hand.palm_position
velocity = hand.palm_velocity
direction = hand.direction

Note that Hand objects can be invalid, which means that they do not contain valid tracking data and do not correspond to a physical entity. Invalid Hand 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 Hand constructor is also invalid. Test for validity with the Hand.is_valid property.

New in version 1.0.

classmethod Hand()

Constructs a Hand object.

An uninitialized hand is considered invalid. Get valid Hand objects from a Frame object.

New in version 1.0.

arm
type:Arm

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.

New in version 2.0.3.

basis
Type:Matrix

The basis vectors of the hand, stored in a matrix.

The basis specifies the orientation of the hand and is defined as follows:

  • x_axis: Perpendicular to both the palm normal and hand direction vectors; positive in the direction of the pinky
  • y_axis: Aligned with the palm normal; positive above the hand
  • z_axis: Aligned with the hand direction vector; positive in the direction of the wrist

Note: Since the left hand is a mirror of the right hand, the basis matrix is left-handed for left hands. Thus, the positive direction of the x-basis is to the right for the right hand and to the left for the left hand. You can change from right-hand to left-hand rule by multiplying the basis vectors by -1.

basis = hand.basis
x_basis = basis.x_basis
y_basis = basis.y_basis
z_basis = basis.z_basis

New in version 2.0.

confidence
type:float

How well the internal hand model fits the observed data.

A low value indicates that there are significant discrepancies; finger positions, even hand identification could be incorrect. The significance of the confidence value to your application can vary with context. For example, gestures and motions can be valid even without a high confidence in the hand data.

confidence = hand.confidence

New in version 2.0.

direction
Type:Vector

The direction from the palm position toward the fingers.

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

hand_direction = hand.direction

New in version 1.0.

fingers
Type:FingerList

The list of Finger objects detected in this frame that are attached to this hand, given in arbitrary order. The list can be empty if no fingers attached to this hand are detected.

# hand is a Leap.Hand object
pointables = hand.pointables
fingers = hand.fingers

New in version 1.0.

frame
Type:Frame

The associated Frame object, if available; otherwise, an invalid Frame object.

frame_for_hand = hand.frame

New in version 1.0.

grab_strength
type:float

The strength of a grab hand pose as a value in the range [0..1].

An open hand has a grab strength of zero. As a hand closes into a fist, its grab strength increases to one.

strength = hand.grab_strength

New in version 2.0.

id
Type:integer

A unique ID assigned to this Hand 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 Motion Controller field of view), the Leap Motion software may assign a new ID when it detects the hand in a future frame.

Use the ID value with the Frame.hand() function to find this Hand object in future frames.

hand_identifier = hand.id

New in version 1.0.

is_left
Type:boolean

Identifies whether this Hand is a left hand.

hand_name = "Left hand" if hand.is_left else "Right hand"

New in version 2.0.

is_right
Type:boolean

Identifies whether this Hand is a right hand.

if hand.is_right:
    # .. Do right handed stuff

New in version 2.0.

is_valid
Type:boolean

Reports whether this is a valid Hand object.

if hand.is_valid:
    #Process hand data...

New in version 1.0.

palm_normal
Type:Vector

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.

https://di4564baj7skl.cloudfront.net/documentation/v2/images/Leap_Palm_Vectors.png

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

normal = hand.palm_normal

New in version 1.0.

palm_position
Type:Vector

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

hand_center = hand.palm_position

New in version 1.0.

palm_velocity
Type:Vector

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

hand_speed = hand.palm_velocity

New in version 1.0.

palm_width
Type:float

The average width of the hand (not including fingers or thumb).

hand_width = hand.palm_width

New in version 2.0.

pinch_strength
type:float

The strength of a pinch pose between the thumb and the closest finger tip as a value in the range [0..1].

An open, flat hand has a grab strength of zero. As the tip of the thumb approaches the tip of a finger, the pinch strength increases to one.

pinch = hand.pinch_strength

New in version 2.0.

pointables
Type:PointableList

The list of Pointable objects (fingers) detected in this frame that are associated with this hand, given in arbitrary order. The list always has five fingers, even if the user is missing digits.

pointables_for_hand = hand.pointables

New in version 1.0.

sphere_center
Type:Vector

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

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

https://di4564baj7skl.cloudfront.net/documentation/v2/images/Leap_Hand_Ball.png
sphere_center = hand.sphere_center

New in version 1.0.

sphere_radius
Type:float

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

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.

sphere_diameter = 2 * hand.sphere_radius

New in version 1.0.

stabilized_palm_position
Type:Vector

The stabilized palm position of this Hand.

Smoothing and stabilization is performed in order to make this value more suitable for interaction with 2D content. The stabilized position lags behind the palm position by a variable amount, depending primarily on the speed of movement.

filtered_hand_position = hand.stabilized_palm_position

New in version 1.0.

time_visible
Type:float

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

lifetime_of_this_hand_object = hand.time_visible

New in version 1.0.

tools
Type:ToolList

In version 2+, tools are not associated with hands. This list is always empty.

The list of Tool objects detected in this frame that are held by this hand, given in arbitrary order. The list can be empty if no tools held by this hand are detected.

New in version 1.0.

wrist_position
Type:Vector

The position of the wrist of this hand.

New in version 2.0.3.

finger(id)

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

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

finger_on_hand_by_ID = hand.finger(finger_ID)

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 Finger object representing that finger may have a different ID than that representing the finger in an earlier frame.

Parameters:id (integer) – The ID value of a Finger object from a previous frame.
Returns:Finger – The finger with the matching ID if one exists for this hand in this frame; otherwise, an invalid Finger object is returned.

New in version 1.0.

pointable(id)

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

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

pointable_of_interest = hand.pointable(pointable_ID)

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

Parameters:id (integer) – The ID value of a Pointable object from a previous frame.
Returns:Pointable – The Pointable object with the matching ID if one exists for this hand in this frame; otherwise, an invalid Pointable object is returned.

New in version 1.0.

rotation_angle(sinceFrame[, axis])

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

If no axis parameter is specified, then the returned angle is expressed in radians measured clockwise around the computed rotation_axis() vector (using the right-hand rule) between the start and end frames. The value is always between 0 and pi radians (0 and 180 degrees).

If an axis parameter is specified, then the returned angle is expressed in radians measured clockwise around the supplied rotation axis (using the right-hand rule). In this case, the value is always between -pi and pi radians (-180 and 180 degrees).

rotation_around_y_axis = hand.rotation_angle(start_frame, Vector.y_axis)

If a corresponding Hand object is not found in sinceFrame, or if either this frame or sinceFrame are invalid Frame objects, then the angle of rotation is zero.

Parameters:
  • sinceFrame (Frame) – The starting frame for computing the relative rotation.
  • axis (Vector) – The axis to measure rotation around.
Return type:

float – A positive value containing the heuristically determined rotational change between the current frame and that specified in the sinceFrame parameter, in radians.

New in version 1.0.

rotation_axis(sinceFrame)

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

The returned direction vector is normalized.

axis_of_hand_rotation = hand.rotation_axis(start_frame)

If a corresponding Hand object is not found in sinceFrame, or if either this frame or sinceFrame are invalid Frame objects, then this method returns a zero vector.

Parameters:sinceFrame (Frame) – The starting frame for computing the relative rotation.
Return type:Vector – A 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.

New in version 1.0.

rotation_matrix(sinceFrame)

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

hand_rotation_transform = hand.rotation_matrix(start_frame)

If a corresponding Hand object is not found in sinceFrame, or if either this frame or sinceFrame are invalid Frame objects, then this method returns an identity matrix.

Parameters:sinceFrame (Frame) – The starting frame for computing the relative rotation.
Return type:Matrix – A transformation Matrix representing the heuristically determined rotational change of the hand between the current frame and that specified in the sinceFrame parameter.

New in version 1.0.

rotation_probability(sinceFrame)

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

rotation_intent_factor = hand.rotation_probability(start_frame)

If a corresponding Hand object is not found in sinceFrame, or if either this frame or sinceFrame are invalid Frame objects, then this method returns zero.

Parameters:sinceFrame (Frame) – The starting frame for computing the relative rotation.
Return type:float – 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.

New in version 1.0.

scale_factor(sinceFrame)

The scale factor derived from this hand’s motion between the current frame and the specified frame.

The scale factor is always positive. A value of 1.0 indicates no scaling took place. Values between 0.0 and 1.0 indicate contraction and values greater than 1.0 indicate expansion.

The Leap Motion software derives scaling from the relative inward or outward motion of a hand and its associated fingers (independent of translation and rotation).

hand_scale_motion = hand.scale_factor(start_frame)

If a corresponding Hand object is not found in sinceFrame, or if either this frame or sinceFrame are invalid Frame objects, then this method returns 1.0.

Parameters:sinceFrame (Frame) – The starting frame for computing the relative scaling.
Return type:float – A positive value representing the heuristically determined scaling change ratio of the hand between the current frame and that specified in the sinceFrame parameter.

New in version 1.0.

scale_probability(sinceFrame)

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

scale_intent_factor = hand.scale_probability(start_frame)

If a corresponding Hand object is not found in sinceFrame, or if either this frame or sinceFrame are invalid Frame objects, then this method returns zero.

Arguments

Parameters:sinceFrame (Frame) – The starting frame for computing the relative scaling.
Return type:float – 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.

New in version 1.0.

tool(id)

The Tool object with the specified ID held by this hand.

As of version 2+, tools are not associated with hands. This attribute always returns an invalid Tool object.

Use this function to retrieve a Tool object held by this hand using an ID value obtained from a previous frame. This function always returns a Tool object, but if no tool with the specified ID is present, an invalid Tool object is returned.

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

Parameters:id (integer) – The ID value of a Tool object from a previous frame.
Returns:Tool – The tool with the matching ID if one exists for this hand in this frame; otherwise, an invalid Tool object is returned.

New in version 1.0.

translation(sinceFrame)

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

The returned translation vector provides the magnitude and direction of the movement in millimeters.

linear_hand_movement = hand.translation(start_frame)

If a corresponding Hand object is not found in sinceFrame, or if either this frame or sinceFrame are invalid Frame objects, then this method returns a zero vector.

Parameters:sinceFrame (Frame) – The starting frame for computing the translation.
Return type:Vector – A Vector representing the heuristically determined change in hand position between the current frame and that specified in the sinceFrame parameter.

New in version 1.0.

translation_probability(sinceFrame)

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

translation_intent_factor = hand.translation_probability(start_frame)

If a corresponding Hand object is not found in sinceFrame, or if either this frame or sinceFrame are invalid Frame objects, then this method returns zero.

Parameters:sinceFrame (Frame) – The starting frame for computing the translation.
Return type:float – 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.

New in version 1.0.

invalid
Type:Hand

An invalid Hand object.

if hand is not Hand.invalid:
    #Process hand data...

You can use the instance returned by this function in comparisons testing whether a given Hand instance is valid or invalid. (You can also use the Hand.is_valid property.)

New in version 1.0.

eq(a, b)

Compare Hand object equality. Two Hand objects are equal if and only if both Hand objects represent the exact same physical hand in the same frame and both Hand objects are valid.

New in version 1.0.

ne(a, b)

Compare Hand object inequality. Two Hand objects are equal if and only if both Hand objects represent the exact same physical hand in the same frame and both Hand objects are valid.

New in version 1.0.