LeapFrameΒΆ

LeapFrame Class Reference

The LeapFrame class represents a set of hand and finger tracking data detected in a single frame. More...

Inherits NSObject.

Instance Methods

(LeapFinger *) - finger:
 The LeapFinger object with the specified ID in this frame. More...
 
(LeapGesture *) - gesture:
 The LeapGesture object with the specified ID in this frame. More...
 
(NSArray *) - gestures:
 The gestures recognized or continuing since the specified frame. More...
 
(LeapHand *) - hand:
 The LeapHand object with the specified ID in this frame. More...
 
(LeapInteractionBox *) - interactionBox
 The current LeapInteractionBox for the frame. More...
 
(LeapPointable *) - pointable:
 The LeapPointable object with the specified ID in this frame. More...
 
(float) - rotationAngle:
 The angle of rotation around the rotation axis derived from the overall rotational motion between the current frame and the specified frame. More...
 
(float) - rotationAngle:axis:
 The angle of rotation around the specified axis derived from the overall rotational motion between the current frame and the specified frame. More...
 
(LeapVector *) - rotationAxis:
 The axis of rotation derived from the overall rotational motion between the current frame and the specified frame. More...
 
(LeapMatrix *) - rotationMatrix:
 The transform matrix expressing the rotation derived from the overall rotational motion between the current frame and the specified frame. More...
 
(float) - rotationProbability:
 The estimated probability that the overall motion between the current frame and the specified frame is intended to be a rotating motion. More...
 
(float) - scaleFactor:
 The scale factor derived from the overall motion between the current frame and the specified frame. More...
 
(float) - scaleProbability:
 The estimated probability that the overall motion between the current frame and the specified frame is intended to be a scaling motion. More...
 
(NSData *) - serialize
 Encodes this Frame object as NSData object. More...
 
(LeapTool *) - tool:
 The LeapTool object with the specified ID in this frame. More...
 
(LeapVector *) - translation:
 The change of position derived from the overall linear motion between the current frame and the specified frame. More...
 
(float) - translationProbability:
 The estimated probability that the overall motion between the current frame and the specified frame is intended to be a translating motion. More...
 

Class Methods

(LeapFrame *) + deserialize:
 Decodes an NSData object representing frame data into a LeapFrame object. More...
 
(LeapFrame *) + invalid
 Returns an invalid LeapFrame object. More...
 

Properties

float currentFramesPerSecond
 The instantaneous framerate. More...
 
NSArray * fingers
 The list of LeapFinger objects detected in this frame, given in arbitrary order. More...
 
NSArray * hands
 The list of LeapHand objects detected in this frame, given in arbitrary order. More...
 
int64_t id
 A unique ID for this LeapFrame. More...
 
NSArray * images
 The list of images from the Leap Motion cameras. More...
 
BOOL isValid
 Reports whether this LeapFrame instance is valid. More...
 
NSArray * pointables
 The list of LeapPointable objects (fingers and tools) detected in this frame, given in arbitrary order. More...
 
int64_t timestamp
 The frame capture time in microseconds elapsed since an arbitrary point in time in the past. More...
 
NSArray * tools
 The list of LeapTool objects detected in this frame, given in arbitrary order. More...
 

Detailed Description

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.

LeapFrame *frame = [controller frame:0];

Implement a LeapListener subclass to receive a callback event when a new LeapFrame is available.

A LeapFrame object maintains strong references to its child objects (hands, fingers, tools, etc). However, the child objects only maintain weak references to their parent objects. Thus, you can access the full hierarchy of objects while the LeapFrame object exists, but you can only access child objects once the LeapFrame object has been deleted.

Since 1.0

Method Documentation

+ (LeapFrame *) deserialize: (NSData *)  serializedFrame

Decodes an NSData object representing frame data into a LeapFrame object.

A LeapController object must be instantiated for this function to succeed, but it does not need to be connected.

NSData *serializedData = [NSData dataWithContentsOfFile:@"frame.data"];
LeapFrame *newFrame = [LeapFrame deserialize:serializedData];

Note: The behavior when calling functions which take another LeapFrame object as a parameter is undefined when either frame has been deserialized.

Parameters
serializedFrameAn NSData object containing the serialized bytes of a frame.
Since
2.2.1
- (LeapFinger *) finger: (int32_t)  fingerId

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.

LeapFinger *knownFinger = [frame 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 physical finger may have a different ID than that representing the finger in an earlier frame.

Parameters
fingerIdThe ID value of a LeapFinger object from a previous frame.
Returns
The LeapFinger object with the matching ID if one exists in this frame; otherwise, an invalid LeapFinger object is returned.
Since 1.0
- (LeapGesture *) gesture: (int32_t)  gestureId

The LeapGesture object with the specified ID in this frame.

LeapFrame *frame = [controller frame:0];
LeapGesture *trackedGesture = [frame gesture:trackedGestureID];
if(trackedGesture.isValid)
{
//Use the data...
}
Parameters
gestureIdThe ID of a LeapGesture object from a previous frame.
Returns
The LeapGesture object in the frame with the specified ID if one exists; Otherwise, an Invalid LeapGesture object.
- (NSArray *) gestures: (const LeapFrame *)  sinceFrame

The gestures recognized or continuing since the specified frame.

//In an init function
LeapFrame *lastProcessedFrame = LeapFrame.invalid;
// Later in your code...
NSArray *gestureList = [frame gestures:lastProcessedFrame];
for (LeapGesture *gesture in gestureList) {
//Use data...
lastProcessedFrame = frame;
}
Parameters
sinceFrameAn earlier LeapFrame. Set to nil to get the gestures for the current LeapFrame only.
Returns
NSArray containing the list of gestures.
- (LeapHand *) hand: (int32_t)  handId

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.

LeapHand *knownHand = [frame hand:handID];

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.

Parameters
handIdThe ID value of a LeapHand object from a previous frame.
Returns
The LeapHand object with the matching ID if one exists in this frame; otherwise, an invalid LeapHand object is returned.
Since 1.0
- (LeapInteractionBox *) interactionBox

The current LeapInteractionBox for the frame.

See the LeapInteractionBox class documentation for more details on how this class should be used.

Returns
The current LeapInteractionBox object.
Since 1.0
+ (LeapFrame *) invalid

Returns an invalid LeapFrame object.

Returns
The invalid LeapFrame instance.
Since 1.0
- (LeapPointable *) pointable: (int32_t)  pointableId

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.

LeapPointable *knownPointable = [frame pointable:pointableID];

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.

Parameters
pointableIdThe ID value of a LeapPointable object from a previous frame.
Returns
The LeapPointable object with the matching ID if one exists 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 overall rotational motion between the current frame and the specified frame.

LeapFrame *lastFrame = [controller frame:1];
float angleOfRotationSinceLastFrame =
[frame rotationAngle:lastFrame];
Parameters
sinceFrameThe starting frame for computing the relative rotation.
Returns
A positive value containing the heuristically determined rotational change 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 overall rotational motion between the current frame and the specified frame.

LeapFrame *lastFrame = [controller frame:1];
float angleOfRotationAroundYSinceLastFrame =
[frame rotationAngle:lastFrame axis:LeapVector.yAxis];
Parameters
sinceFrameThe starting frame for computing the relative rotation.
axisThe LeapVector representing the direction of the axis to measure rotation around.
Returns
A value containing the heuristically determined rotational change between the current frame and that specified in the sinceFrame parameter around the given axis.
- (LeapVector *) rotationAxis: (const LeapFrame *)  sinceFrame

The axis of rotation derived from the overall rotational motion between the current frame and the specified frame.

LeapFrame *lastFrame = [controller frame:1];
LeapVector *axisOfRotationSinceLastFrame =
[frame rotationAxis:lastFrame];
Parameters
sinceFrameThe starting frame for computing the relative rotation.
Returns
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.
- (LeapMatrix *) rotationMatrix: (const LeapFrame *)  sinceFrame

The transform matrix expressing the rotation derived from the overall rotational motion between the current frame and the specified frame.

LeapFrame *lastFrame = [controller frame:1];
LeapMatrix *rotationSinceLastFrame =
[frame rotationMatrix:lastFrame];
Parameters
sinceFrameThe starting frame for computing the relative rotation.
Returns
A LeapMatrix containing the heuristically determined rotational change between the current frame and that specified in the sinceFrame parameter.
- (float) rotationProbability: (const LeapFrame *)  sinceFrame

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

LeapFrame *lastFrame = [controller frame:1];
float rotationIntent =
[frame rotationProbability:lastFrame];
Parameters
sinceFrameThe starting frame for computing the relative rotation.
Returns
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.
- (float) scaleFactor: (const LeapFrame *)  sinceFrame

The scale factor derived from the overall motion between the current frame and the specified frame.

LeapFrame *lastFrame = [controller frame:1];
float scaleChangeSinceLastFrame =
[frame scaleFactor:lastFrame];
Parameters
sinceFrameThe starting frame for computing the relative scaling.
Returns
A positive value representing the heuristically determined scaling change ratio between the current frame and that specified in the sinceFrame parameter.
- (float) scaleProbability: (const LeapFrame *)  sinceFrame

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

LeapFrame *lastFrame = [controller frame:1];
float scaleIntent = [frame scaleProbability:lastFrame];
Parameters
sinceFrameThe starting frame for computing the relative scaling.
Returns
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.
- (NSData *) serialize

Encodes this Frame object as NSData object.

NSData *serializedFrame = [frameToSave serialize];
BOOL success = [serializedFrame writeToFile:@"frame.data" atomically:YES];
Returns
The NSData encoding the data for this frame.
Since
2.2.1
- (LeapTool *) tool: (int32_t)  toolId

The LeapTool object with the specified ID in this frame.

LeapTool *knownTool = [frame tool:toolID];
Parameters
toolIdThe ID value of a LeapTool object from a previous frame.
Returns
The LeapTool object with the matching ID if one exists in this frame; otherwise, an invalid LeapTool object is returned.
- (LeapVector *) translation: (const LeapFrame *)  sinceFrame

The change of position derived from the overall linear motion between the current frame and the specified frame.

LeapFrame *lastFrame = [controller frame:1];
LeapVector *translationSinceLastFrame =
[frame translation:lastFrame];
Parameters
sinceFrameThe starting frame for computing the relative translation.
Returns
A LeapVector representing the heuristically determined change in position of all objects between the current frame and that specified in the sinceFrame parameter.
- (float) translationProbability: (const LeapFrame *)  sinceFrame

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

LeapFrame *lastFrame = [controller frame:1];
float translationIntent =
[frame translationProbability:lastFrame];
Parameters
sinceFrameThe starting frame for computing the translation.
Returns
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.

Property Documentation

- (float) currentFramesPerSecond
readnonatomicassign

The instantaneous framerate.

The rate at which the Leap Motion software is providing frames of data (in frames per second). The framerate can fluctuate depending on available computing resources, activity within the device field of view, software tracking settings, and other factors.

float fps = frame.currentFramesPerSecond;
Returns
An estimate of frames per second of the Leap Motion Controller.
Since 1.0
- (NSArray*) fingers
readnonatomicstrong

The list of LeapFinger objects detected in this frame, given in arbitrary order.

The list can be empty if no fingers are detected.

NSArray *fingerList = frame.fingers;
Returns
NSArray containing all LeapFinger objects detected in this frame.
Since 1.0
- (NSArray*) hands
readnonatomicstrong

The list of LeapHand objects detected in this frame, given in arbitrary order.

The list can be empty if no hands are detected.

NSArray *handList = frame.hands;
Returns
NSArray containing all LeapHand objects detected in this frame.
Since 1.0
- (int64_t) id
readnonatomicassign

A unique ID for this LeapFrame.

Consecutive frames processed by the Leap have consecutive increasing values.

int64_t frameId = frame.id;
Returns
The frame ID.
Since 1.0
- (NSArray*) images
readnonatomicstrong

The list of images from the Leap Motion cameras.

Returns
An NSArray object containing the camera images analyzed to create this Frame.
Since 2.1.5
- (BOOL) isValid
readnonatomicassign

Reports whether this LeapFrame instance is valid.

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

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

Returns
YES, if this is a valid LeapFrame object; false otherwise.
Since 1.0
- (NSArray*) pointables
readnonatomicstrong

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.

NSArray *pointableList = frame.pointables;
Returns
NSArray containing all LeapPointable objects detected in this frame.
Since 1.0
- (int64_t) timestamp
readnonatomicassign

The frame capture time in microseconds elapsed since an arbitrary point in time in the past.

Use [LeapController now] to calculate the age of the frame.

int64_t microseconds = frame.timestamp;
Returns
The timestamp in microseconds.
Since 1.0
- (NSArray*) tools
readnonatomicstrong

The list of LeapTool objects detected in this frame, given in arbitrary order.

The list can be empty if no tools are detected.

NSArray *toolList = frame.tools;
Returns
NSArray containing all LeapTool objects detected in this frame.