LeapHand Class Reference
Inherits from | NSObject |
Declared in | LeapObjectiveC.h |
Overview
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 and tools.
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.
Tasks
-
– id
A unique ID assigned to this LeapHand object, whose value remains the same
across consecutive frames while the tracked hand remains visible. -
– pointables
The list of LeapPointable objects (fingers and tools) detected in this frame
that are associated with this hand, given in arbitrary order. -
– fingers
The list of LeapFinger objects detected in this frame that are attached to
this hand, given in arbitrary order. -
– tools
The list of LeapTool 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. -
– pointable:
The LeapPointable object with the specified ID associated with this hand.
-
– finger:
The LeapFinger object with the specified ID attached to this hand.
-
– tool:
The LeapTool object with the specified ID held by this hand.
-
– palmPosition
The center position of the palm in millimeters from the Leap origin.
-
– palmVelocity
The rate of change of the palm position in millimeters/second.
-
– palmNormal
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. -
– direction
The direction from the palm position toward the fingers.
-
– sphereCenter
The center of a sphere fit to the curvature of this hand.
-
– sphereRadius
The radius of a sphere fit to the curvature of this hand.
-
– isValid
Reports whether this is a valid LeapHand object.
-
– frame
The LeapFrame associated with this Hand.
-
– translation:
The change of position of this hand between the current LeapFrame and
the specified LeapFrame. -
– translationProbability:
The estimated probability that the hand motion between the current
frame and the specified LeapFrame is intended to be a translating motion. -
– rotationAxis:
The axis of rotation derived from the change in orientation of this
hand, and any associated fingers and tools, between the current LeapFrame
and the specified LeapFrame. -
– rotationAngle:
The angle of rotation around the rotation axis derived from the change
in orientation of this hand, and any associated fingers and tools,
between the current LeapFrame and the specified LeapFrame. -
– rotationAngle:axis:
The angle of rotation around the specified axis derived from the change
in orientation of this hand, and any associated fingers and tools,
between the current LeapFrame and the specified LeapFrame. -
– rotationMatrix:
The transform matrix expressing the rotation derived from the change
in orientation of this hand, and any associated fingers and tools,
between the current LeapFrame and the specified LeapFrame. -
– rotationProbability:
The estimated probability that the hand motion between the current
LeapFrame and the specified LeapFrame is intended to be a rotating motion. -
– scaleFactor:
The scale factor derived from this hand’s motion between the current
LeapFrame and the specified LeapFrame. -
– scaleProbability:
The estimated probability that the hand motion between the current
LeapFrame and the specified LeapFrame is intended to be a scaling motion. -
+ invalid
Returns an invalid LeapHand object.
Class Methods
invalid
Returns an invalid LeapHand object.
+ (LeapHand *)invalid
Return Value
The invalid LeapHand instance.
Discussion
Returns an invalid LeapHand object.
You can use the instance returned by this function in comparisons testing
whether a given LeapHand instance is valid or invalid. (You can also use the
LeapHand isValid: function.)
Declared In
LeapObjectiveC.h
Instance Methods
direction
The direction from the palm position toward the fingers.
- (LeapVector *)direction
Return Value
The LeapVector pointing from the palm position toward the fingers.
Discussion
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.
Declared In
LeapObjectiveC.h
finger:
The LeapFinger object with the specified ID attached to this hand.
- (LeapFinger *)finger:(int32_t)fingerId
Parameters
- fingerId
The ID value of a LeapFinger object from a previous frame.
Return Value
The LeapFinger object with the matching ID if one exists for this
hand in this frame; otherwise, an invalid LeapFinger object is returned.
Discussion
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.
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.
Declared In
LeapObjectiveC.h
fingers
The list of LeapFinger objects detected in this frame that are attached to
this hand, given in arbitrary order.
- (NSArray *)fingers
Return Value
An NSArray containing all LeapFinger objects attached to this hand.
Discussion
The list of LeapFinger 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.
Declared In
LeapObjectiveC.h
frame
The LeapFrame associated with this Hand.
- (LeapFrame *)frame
Return Value
The associated LeapFrame object, if available; otherwise,
an invalid LeapFrame object is returned.
Discussion
The LeapFrame associated with this Hand.
Declared In
LeapObjectiveC.h
id
A unique ID assigned to this LeapHand object, whose value remains the same
across consecutive frames while the tracked hand remains visible.
- (int32_t)id
Return Value
The ID of this hand.
Discussion
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.
Use the ID value with the [LeapFrame hand:] function to find this LeapHand object
in future frames.
Declared In
LeapObjectiveC.h
isValid
Reports whether this is a valid LeapHand object.
- (BOOL)isValid
Return Value
YES, if this LeapHand object contains valid tracking data.
Discussion
Reports whether this is a valid LeapHand object.
Declared In
LeapObjectiveC.h
palmNormal
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.
- (LeapVector *)palmNormal
Return Value
The LeapVector normal to the plane formed by the palm.
Discussion
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).
Declared In
LeapObjectiveC.h
palmPosition
The center position of the palm in millimeters from the Leap origin.
- (LeapVector *)palmPosition
Return Value
The LeapVector representing the coordinates of the palm position.
Discussion
The center position of the palm in millimeters from the Leap origin.
Declared In
LeapObjectiveC.h
palmVelocity
The rate of change of the palm position in millimeters/second.
- (LeapVector *)palmVelocity
Return Value
The LeapVector representing the coordinates of the palm velocity.
Discussion
The rate of change of the palm position in millimeters/second.
Declared In
LeapObjectiveC.h
pointable:
The LeapPointable object with the specified ID associated with this hand.
- (LeapPointable *)pointable:(int32_t)pointableId
Parameters
- pointableId
The ID value of a LeapPointable object from a previous frame.
Return Value
The LeapPointable object with the matching ID if one exists for this
hand in this frame; otherwise, an invalid LeapPointable object is returned.
Discussion
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 or tool
with the specified ID is present, an invalid LeapPointable object is returned.
Note that ID values persist across frames, but only until tracking of a
particular object is lost. If tracking of a finger or tool is lost and subsequently
regained, the new LeapPointable object representing that finger or tool may have a
different ID than that representing the finger or tool in an earlier frame.
Declared In
LeapObjectiveC.h
pointables
The list of LeapPointable objects (fingers and tools) detected in this frame
that are associated with this hand, given in arbitrary order.
- (NSArray *)pointables
Return Value
An NSArray containing all LeapPointable objects associated with this hand.
Discussion
The list of LeapPointable objects (fingers and tools) detected in this frame
that are associated with this hand, given in arbitrary order.
The list can be empty if no fingers or tools associated with this hand
are detected.
Use the [LeapPointable isFinger] function to determine whether or not an
item in the list represents a finger. Use the [LeapPointable isTool] function
to determine whether or not an item in the list represents a tool.
You can also get only fingers using the [LeapHand fingers] function or
only tools using the [LeapHand tools] function.
Declared In
LeapObjectiveC.h
rotationAngle:
The angle of rotation around the rotation axis derived from the change
in orientation of this hand, and any associated fingers and tools,
between the current LeapFrame and the specified LeapFrame.
- (float)rotationAngle:(const LeapFrame *)sinceFrame
Parameters
- sinceFrame
The starting LeapFrame for computing the relative rotation.
Return Value
A positive value representing the heuristically determined
rotational change of the hand between the current frame and that
specified in the sinceFrame parameter.
Discussion
The angle of rotation around the rotation axis derived from the change
in orientation of this hand, and any associated fingers and tools,
between the current LeapFrame and the specified LeapFrame.
The returned angle is expressed in radians measured clockwise around the
rotation axis (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 a corresponding LeapHand object is not found in sinceFrame, or if either
this frame or sinceFrame are invalid LeapFrame objects, then the angle of
rotation is zero.
Declared In
LeapObjectiveC.h
rotationAngle:axis:
The angle of rotation around the specified axis derived from the change
in orientation of this hand, and any associated fingers and tools,
between the current LeapFrame and the specified LeapFrame.
- (float)rotationAngle:(const LeapFrame *)sinceFrame axis:(const LeapVector *)axis
Parameters
- sinceFrame
The starting LeapFrame for computing the relative rotation.
- axis
A LeapVector representing the axis to measure rotation around.
Return Value
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.
Discussion
The angle of rotation around the specified axis derived from the change
in orientation of this hand, and any associated fingers and tools,
between the current LeapFrame and the specified LeapFrame.
The returned angle is expressed in radians measured clockwise around the
rotation axis (using the right-hand rule) between the start and end frames.
The value is always between -pi and pi radians (-180 and 180 degrees).
If a corresponding LeapHand object is not found in sinceFrame, or if either
this frame or sinceFrame are invalid LeapFrame objects, then the angle of
rotation is zero.
Declared In
LeapObjectiveC.h
rotationAxis:
The axis of rotation derived from the change in orientation of this
hand, and any associated fingers and tools, between the current LeapFrame
and the specified LeapFrame.
- (LeapVector *)rotationAxis:(const LeapFrame *)sinceFrame
Parameters
- sinceFrame
The starting LeapFrame for computing the relative rotation.
Return Value
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.
Discussion
The axis of rotation derived from the change in orientation of this
hand, and any associated fingers and tools, between the current LeapFrame
and the specified LeapFrame.
The returned direction vector is normalized.
If a corresponding LeapHand object is not found in sinceFrame, or if either
this frame or sinceFrame are invalid LeapFrame objects, then this method
returns a zero vector.
Declared In
LeapObjectiveC.h
rotationMatrix:
The transform matrix expressing the rotation derived from the change
in orientation of this hand, and any associated fingers and tools,
between the current LeapFrame and the specified LeapFrame.
- (LeapMatrix *)rotationMatrix:(const LeapFrame *)sinceFrame
Parameters
- sinceFrame
The starting LeapFrame for computing the relative rotation.
Return Value
A transformation LeapMatrix representing the heuristically determined
rotational change of the hand between the current frame and that specified
in the sinceFrame parameter.
Discussion
The transform matrix expressing the rotation derived from the change
in orientation of this hand, and any associated fingers and tools,
between the current LeapFrame and the specified LeapFrame.
If a corresponding LeapHand object is not found in sinceFrame, or if either
this frame or sinceFrame are invalid LeapFrame objects, then this method
returns an identity matrix.
Declared In
LeapObjectiveC.h
rotationProbability:
The estimated probability that the hand motion between the current
LeapFrame and the specified LeapFrame is intended to be a rotating motion.
- (float)rotationProbability:(const LeapFrame *)sinceFrame
Parameters
- sinceFrame
The starting LeapFrame for computing the relative rotation.
Return Value
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.
Discussion
The estimated probability that the hand motion between the current
LeapFrame and the specified LeapFrame is intended to be a rotating motion.
If a corresponding LeapHand object is not found in sinceFrame, or if either
this frame or sinceFrame are invalid LeapFrame objects, then this method
returns zero.
Declared In
LeapObjectiveC.h
scaleFactor:
The scale factor derived from this hand’s motion between the current
LeapFrame and the specified LeapFrame.
- (float)scaleFactor:(const LeapFrame *)sinceFrame
Parameters
- sinceFrame
The starting LeapFrame for computing the relative scaling.
Return Value
A positive value representing the heuristically determined
scaling change ratio of the hand between the current frame and that
specified in the sinceFrame parameter.
Discussion
The scale factor derived from this hand’s motion between the current
LeapFrame and the specified LeapFrame.
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 derives scaling from the relative inward or outward motion of
a hand and its associated fingers and tools (independent of translation
and rotation).
If a corresponding LeapHand object is not found in sinceFrame, or if either
this frame or sinceFrame are invalid LeapFrame objects, then this method
returns 1.0.
Declared In
LeapObjectiveC.h
scaleProbability:
The estimated probability that the hand motion between the current
LeapFrame and the specified LeapFrame is intended to be a scaling motion.
- (float)scaleProbability:(const LeapFrame *)sinceFrame
Parameters
- sinceFrame
The starting LeapFrame for computing the relative scaling.
Return Value
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.
Discussion
The estimated probability that the hand motion between the current
LeapFrame and the specified LeapFrame is intended to be a scaling motion.
If a corresponding LeapHand object is not found in sinceFrame, or if either
this frame or sinceFrame are invalid LeapFrame objects, then this method
returns zero.
Declared In
LeapObjectiveC.h
sphereCenter
The center of a sphere fit to the curvature of this hand.
- (LeapVector *)sphereCenter
Return Value
The LeapVector representing the center position of the sphere.
Discussion
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.
Declared In
LeapObjectiveC.h
sphereRadius
The radius of a sphere fit to the curvature of this hand.
- (float)sphereRadius
Return Value
The radius of the sphere in millimeters.
Discussion
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.
Declared In
LeapObjectiveC.h
tool:
The LeapTool object with the specified ID held by this hand.
- (LeapTool *)tool:(int32_t)toolId
Parameters
- toolId
The ID value of a LeapTool object from a previous frame.
Return Value
The LeapTool object with the matching ID if one exists for this
hand in this frame; otherwise, an invalid LeapTool object is returned.
Discussion
The LeapTool object with the specified ID held by this hand.
Use this [LeapHand tool:] function to retrieve a LeapTool object held by
this hand using an ID value obtained from a previous frame.
This function always returns a LeapTool object, but if no tool
with the specified ID is present, an invalid LeapTool 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 LeapTool object representing that tool may have a
different ID than that representing the tool in an earlier frame.
Declared In
LeapObjectiveC.h
tools
The list of LeapTool 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.
- (NSArray *)tools
Return Value
An NSArray containing all LeapTool objects held by this hand.
Discussion
The list of LeapTool 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.
Declared In
LeapObjectiveC.h
translation:
The change of position of this hand between the current LeapFrame and
the specified LeapFrame.
- (LeapVector *)translation:(const LeapFrame *)sinceFrame
Parameters
- sinceFrame
The starting LeapFrame for computing the translation.
Return Value
A LeapVector representing the heuristically determined change in
hand position between the current frame and that specified in the
sinceFrame parameter.
Discussion
The change of position of this hand between the current LeapFrame and
the specified LeapFrame.
The returned translation vector provides the magnitude and direction of
the movement in millimeters.
If a corresponding LeapHand object is not found in sinceFrame, or if either
this frame or sinceFrame are invalid LeapFrame objects, then this method
returns a zero vector.
Declared In
LeapObjectiveC.h
translationProbability:
The estimated probability that the hand motion between the current
frame and the specified LeapFrame is intended to be a translating motion.
- (float)translationProbability:(const LeapFrame *)sinceFrame
Parameters
- sinceFrame
The starting LeapFrame for computing the translation.
Return Value
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.
Discussion
The estimated probability that the hand motion between the current
frame and the specified LeapFrame is intended to be a translating motion.
If a corresponding LeapHand object is not found in sinceFrame, or if either
this frame or sinceFrame are invalid LeapFrame objects, then this method
returns zero.
Declared In
LeapObjectiveC.h