LeapFrame Class Reference
Inherits from | NSObject |
Declared in | LeapObjectiveC.h |
Overview
The LeapFrame class represents a set of hand and finger tracking data detected
in a single frame.
The Leap detects hands, fingers and tools within the tracking area, reporting
their positions, orientations and motions in frames at the Leap frame rate.
Access LeapFrame objects through an instance of a LeapController. Implement a
LeapListener subclass to receive a callback event when a new LeapFrame is available.
Tasks
-
hands
The list of LeapHand objects detected in this frame, given in arbitrary order.
property
The list can be empty if no hands are detected. -
pointables
The list of LeapPointable objects (fingers and tools) detected in this frame,
property
given in arbitrary order. The list can be empty if no fingers or tools are detected. -
fingers
The list of LeapFinger objects detected in this frame, given in arbitrary order.
property
The list can be empty if no fingers are detected. -
tools
The list of LeapTool objects detected in this frame, given in arbitrary order.
property
The list can be empty if no tools are detected. -
– id
A unique ID for this LeapFrame. Consecutive frames processed by the Leap
have consecutive increasing values. -
– timestamp
The frame capture time in microseconds elapsed since the Leap started.
-
– hand:
The LeapHand object with the specified ID in this frame.
-
– pointable:
The LeapPointable object with the specified ID in this frame.
-
– finger:
The LeapFinger object with the specified ID in this frame.
-
– tool:
The LeapTool object with the specified ID in this frame.
-
– gestures:
The gestures recognized or continuing since the specified frame.
-
– gesture:
The LeapGesture object with the specified ID in this frame.
-
– translation:
The change of position derived from the overall linear motion between
the current frame and the specified frame. -
– translationProbability:
The estimated probability that the overall motion between the current
frame and the specified frame is intended to be a translating motion. -
– rotationAxis:
The axis of rotation derived from the overall rotational motion between
the current frame and the specified frame. -
– rotationAngle:
The angle of rotation around the rotation axis derived from the overall
rotational motion between the current frame and the specified frame. -
– rotationAngle:axis:
The angle of rotation around the specified axis derived from the overall
rotational motion between the current frame and the specified frame. -
– rotationMatrix:
The transform matrix expressing the rotation derived from the overall
rotational motion between the current frame and the specified frame. -
– rotationProbability:
The estimated probability that the overall motion between the current
frame and the specified frame is intended to be a rotating motion. -
– scaleFactor:
The scale factor derived from the overall motion between the current frame
and the specified frame. -
– scaleProbability:
The estimated probability that the overall motion between the current
frame and the specified frame is intended to be a scaling motion. -
– isValid
Reports whether this LeapFrame instance is valid.
-
– interactionBox
The current LeapInteractionBox for the frame. See the LeapInteractionBox class
documentation for more details on how this class should be used. -
+ invalid
Returns an invalid LeapFrame object.
Properties
fingers
The list of LeapFinger objects detected in this frame, given in arbitrary order.
The list can be empty if no fingers are detected.
@property (nonatomic, strong, readonly) NSArray *fingers
Return Value
NSArray containing all LeapFinger objects detected in this frame.
Discussion
The list of LeapFinger objects detected in this frame, given in arbitrary order.
The list can be empty if no fingers are detected.
Declared In
LeapObjectiveC.h
hands
The list of LeapHand objects detected in this frame, given in arbitrary order.
The list can be empty if no hands are detected.
@property (nonatomic, strong, readonly) NSArray *hands
Return Value
NSArray containing all LeapHand objects detected in this frame.
Discussion
The list of LeapHand objects detected in this frame, given in arbitrary order.
The list can be empty if no hands are detected.
Declared In
LeapObjectiveC.h
pointables
The list of LeapPointable objects (fingers and tools) detected in this frame,
given in arbitrary order. The list can be empty if no fingers or tools are detected.
@property (nonatomic, strong, readonly) NSArray *pointables
Return Value
NSArray containing all LeapPointable objects detected in this frame.
Discussion
The list of LeapPointable objects (fingers and tools) detected in this frame,
given in arbitrary order. The list can be empty if no fingers or tools are detected.
Declared In
LeapObjectiveC.h
tools
The list of LeapTool objects detected in this frame, given in arbitrary order.
The list can be empty if no tools are detected.
@property (nonatomic, strong, readonly) NSArray *tools
Return Value
NSArray containing all LeapTool objects detected in this frame.
Discussion
The list of LeapTool objects detected in this frame, given in arbitrary order.
The list can be empty if no tools are detected.
Declared In
LeapObjectiveC.h
Class Methods
invalid
Returns an invalid LeapFrame object.
+ (LeapFrame *)invalid
Return Value
The invalid LeapFrame instance.
Discussion
Returns an invalid LeapFrame object.
You can use the instance returned by this function in comparisons testing
whether a given LeapFrame instance is valid or invalid. (You can also use the
[LeapFrame isValid] function.)
Declared In
LeapObjectiveC.h
Instance Methods
finger:
The LeapFinger object with the specified ID in this frame.
- (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 in this frame;
otherwise, an invalid LeapFinger object is returned.
Discussion
The LeapFinger object with the specified ID in this frame.
Use the [LeapFrame finger:] function to retrieve the LeapFinger object from
this frame 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 physical finger may have
a different ID than that representing the finger in an earlier frame.
Declared In
LeapObjectiveC.h
gesture:
The LeapGesture object with the specified ID in this frame.
- (LeapGesture *)gesture:(int32_t)gestureId
Parameters
- gestureId
The ID of a LeapGesture object from a previous frame.
Return Value
The LeapGesture object in the frame with the specified ID if one
exists; Otherwise, an Invalid LeapGesture object.
Discussion
The LeapGesture object with the specified ID in this frame.
Use the [LeapFrame gesture:] function to return a Gesture object in this
frame using an ID obtained in an earlier frame. The function always
returns a LeapGesture object, but if there was no update for the gesture in
this frame, then an invalid LeapGesture object is returned.
All LeapGesture objects representing the same recognized movement share the
same ID.
Declared In
LeapObjectiveC.h
gestures:
The gestures recognized or continuing since the specified frame.
- (NSArray *)gestures:(const LeapFrame *)sinceFrame
Parameters
- sinceFrame
An earlier LeapFrame. Set to nil to get the gestures for
the current LeapFrame only.
Return Value
NSArray containing the list of gestures.
Discussion
The gestures recognized or continuing since the specified frame.
Circle and swipe gestures are updated every frame. Tap gestures
only appear in the list for a single frame.
Declared In
LeapObjectiveC.h
hand:
The LeapHand object with the specified ID in this frame.
- (LeapHand *)hand:(int32_t)handId
Parameters
- handId
The ID value of a LeapHand object from a previous frame.
Return Value
The LeapHand object with the matching ID if one exists in this frame;
otherwise, an invalid LeapHand object is returned.
Discussion
The LeapHand object with the specified ID in this frame.
Use the [LeapFrame hand:] function to retrieve the LeapHand object from
this frame using an ID value obtained from a previous frame.
This function always returns a LeapHand object, but if no hand
with the specified ID is present, an invalid LeapHand object is returned.
Note that ID values persist across frames, but only until tracking of a
particular object is lost. If tracking of a hand is lost and subsequently
regained, the new LeapHand object representing that physical hand may have
a different ID than that representing the physical hand in an earlier frame.
Declared In
LeapObjectiveC.h
id
A unique ID for this LeapFrame. Consecutive frames processed by the Leap
have consecutive increasing values.
- (int64_t)id
Return Value
The frame ID.
Discussion
A unique ID for this LeapFrame. Consecutive frames processed by the Leap
have consecutive increasing values.
Declared In
LeapObjectiveC.h
interactionBox
The current LeapInteractionBox for the frame. See the LeapInteractionBox class
documentation for more details on how this class should be used.
- (LeapInteractionBox *)interactionBox
Return Value
The current LeapInteractionBox object.
Discussion
The current LeapInteractionBox for the frame. See the LeapInteractionBox class
documentation for more details on how this class should be used.
Declared In
LeapObjectiveC.h
isValid
Reports whether this LeapFrame instance is valid.
- (BOOL)isValid
Return Value
YES, if this is a valid LeapFrame object; false otherwise.
Discussion
Reports whether this LeapFrame instance is valid.
A valid LeapFrame is one generated by the LeapController object that contains
tracking data for all detected entities. An invalid LeapFrame contains no
actual tracking data, but you can call its functions without risk of a
null pointer exception. The invalid LeapFrame mechanism makes it more
convenient to track individual data across the frame history. For example,
you can invoke:
LeapFinger finger = [[controller frame:n] finger:fingerID];
for an arbitrary LeapFrame history value, “n”, without first checking whether
frame: returned a null object. (You should still check that the
returned LeapFinger instance is valid.)
Declared In
LeapObjectiveC.h
pointable:
The LeapPointable object with the specified ID in this frame.
- (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 in this frame;
otherwise, an invalid LeapPointable object is returned.
Discussion
The LeapPointable object with the specified ID in this frame.
Use the [LeapFrame pointable:] function to retrieve the LeapPointable object from
this frame 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
rotationAngle:
The angle of rotation around the rotation axis derived from the overall
rotational motion between the current frame and the specified frame.
- (float)rotationAngle:(const LeapFrame *)sinceFrame
Parameters
- sinceFrame
The starting frame for computing the relative rotation.
Return Value
A positive value containing the heuristically determined
rotational change between the current frame and that specified in the
sinceFrame parameter.
Discussion
The angle of rotation around the rotation axis derived from the overall
rotational motion between the current frame and the specified frame.
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).
The Leap derives frame rotation from the relative change in position and
orientation of all objects detected in the field of view.
If either this frame or sinceFrame is an invalid LeapFrame object, then the
angle of rotation is zero.
Declared In
LeapObjectiveC.h
rotationAngle:axis:
The angle of rotation around the specified axis derived from the overall
rotational motion between the current frame and the specified frame.
- (float)rotationAngle:(const LeapFrame *)sinceFrame axis:(const LeapVector *)axis
Parameters
- sinceFrame
The starting frame for computing the relative rotation.
- axis
The LeapVector representing the direction of the axis to measure rotation around.
Return Value
A value containing the heuristically determined rotational
change between the current frame and that specified in the sinceFrame
parameter around the given axis.
Discussion
The angle of rotation around the specified axis derived from the overall
rotational motion between the current frame and the specified frame.
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).
The Leap derives frame rotation from the relative change in position and
orientation of all objects detected in the field of view.
If either this frame or sinceFrame is an invalid LeapFrame object, then the
angle of rotation is zero.
Declared In
LeapObjectiveC.h
rotationAxis:
The axis of rotation derived from the overall rotational motion between
the current frame and the specified frame.
- (LeapVector *)rotationAxis:(const LeapFrame *)sinceFrame
Parameters
- sinceFrame
The starting frame for computing the relative rotation.
Return Value
A LeapVector containing the normalized direction vector representing the axis of the
heuristically determined rotational change between the current frame
and that specified in the sinceFrame parameter.
Discussion
The axis of rotation derived from the overall rotational motion between
the current frame and the specified frame.
The returned direction vector is normalized.
The Leap derives frame rotation from the relative change in position and
orientation of all objects detected in the field of view.
If either this frame or sinceFrame is an invalid LeapFrame object, or if no
rotation is detected between the two frames, a zero vector is returned.
Declared In
LeapObjectiveC.h
rotationMatrix:
The transform matrix expressing the rotation derived from the overall
rotational motion between the current frame and the specified frame.
- (LeapMatrix *)rotationMatrix:(const LeapFrame *)sinceFrame
Parameters
- sinceFrame
The starting frame for computing the relative rotation.
Return Value
A LeapMatrix containing the heuristically determined
rotational change between the current frame and that specified in the
sinceFrame parameter.
Discussion
The transform matrix expressing the rotation derived from the overall
rotational motion between the current frame and the specified frame.
The Leap derives frame rotation from the relative change in position and
orientation of all objects detected in the field of view.
If either this frame or sinceFrame is an invalid LeapFrame object, then this
method returns an identity matrix.
Declared In
LeapObjectiveC.h
rotationProbability:
The estimated probability that the overall motion between the current
frame and the specified frame is intended to be a rotating motion.
- (float)rotationProbability:(const LeapFrame *)sinceFrame
Parameters
- sinceFrame
The starting frame for computing the relative rotation.
Return Value
A value between 0 and 1 representing the estimated probability
that the overall motion between the current frame and the specified frame
is intended to be a rotating motion.
Discussion
The estimated probability that the overall motion between the current
frame and the specified frame is intended to be a rotating motion.
If either this frame or sinceFrame is an invalid LeapFrame object, then this
method returns zero.
Declared In
LeapObjectiveC.h
scaleFactor:
The scale factor derived from the overall motion between the current frame
and the specified frame.
- (float)scaleFactor:(const LeapFrame *)sinceFrame
Parameters
- sinceFrame
The starting frame for computing the relative scaling.
Return Value
A positive value representing the heuristically determined
scaling change ratio between the current frame and that specified in the
sinceFrame parameter.
Discussion
The scale factor derived from the overall 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 derives scaling from the relative inward or outward motion of
all objects detected in the field of view (independent of translation
and rotation).
If either this frame or sinceFrame is an invalid LeapFrame object, then this
method returns 1.0.
Declared In
LeapObjectiveC.h
scaleProbability:
The estimated probability that the overall motion between the current
frame and the specified frame is intended to be a scaling motion.
- (float)scaleProbability:(const LeapFrame *)sinceFrame
Parameters
- sinceFrame
The starting frame for computing the relative scaling.
Return Value
A value between 0 and 1 representing the estimated probability
that the overall motion between the current frame and the specified frame
is intended to be a scaling motion.
Discussion
The estimated probability that the overall motion between the current
frame and the specified frame is intended to be a scaling motion.
If either this frame or sinceFrame is an invalid LeapFrame object, then this
method returns zero.
Declared In
LeapObjectiveC.h
timestamp
The frame capture time in microseconds elapsed since the Leap started.
- (int64_t)timestamp
Return Value
The timestamp in microseconds.
Discussion
The frame capture time in microseconds elapsed since the Leap started.
Declared In
LeapObjectiveC.h
tool:
The LeapTool object with the specified ID in this frame.
- (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 in this frame;
otherwise, an invalid LeapTool object is returned.
Discussion
The LeapTool object with the specified ID in this frame.
Use the [LeapFrame tool:] function to retrieve the LeapTool object from
this frame 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
translation:
The change of position derived from the overall linear motion between
the current frame and the specified frame.
- (LeapVector *)translation:(const LeapFrame *)sinceFrame
Parameters
- sinceFrame
The starting frame for computing the relative translation.
Return Value
A LeapVector representing the heuristically determined change in
position of all objects between the current frame and that specified
in the sinceFrame parameter.
Discussion
The change of position derived from the overall linear motion between
the current frame and the specified frame.
The returned translation vector provides the magnitude and direction of
the movement in millimeters.
The Leap derives frame translation from the linear motion of
all objects detected in the field of view.
If either this frame or sinceFrame is an invalid LeapFrame object, then this
method returns a zero vector.
Declared In
LeapObjectiveC.h
translationProbability:
The estimated probability that the overall motion between the current
frame and the specified frame is intended to be a translating motion.
- (float)translationProbability:(const LeapFrame *)sinceFrame
Parameters
- sinceFrame
The starting frame for computing the translation.
Return Value
A value between 0 and 1 representing the estimated probability
that the overall motion between the current frame and the specified frame
is intended to be a translating motion.
Discussion
The estimated probability that the overall motion between the current
frame and the specified frame is intended to be a translating motion.
If either this frame or sinceFrame is an invalid LeapFrame object, then this
method returns zero.
Declared In
LeapObjectiveC.h