LeapFrameΒΆ

Properties:

Methods:

class LeapFrame

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

Public Functions


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

Return
The LeapFinger object with the matching ID if one exists in this frame; otherwise, an invalid LeapFinger object is returned.
Since 1.0
Parameters
  • fingerId -

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


- (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...
}

Return
The LeapGesture object in the frame with the specified ID if one exists; Otherwise, an Invalid LeapGesture object.
Parameters
  • gestureId -

    The ID of a LeapGesture object from a previous frame.


- (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;
}

Return
NSArray containing the list of gestures.
Parameters
  • sinceFrame -

    An earlier LeapFrame. Set to nil to get the gestures for the current LeapFrame only.


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

Return
The LeapHand object with the matching ID if one exists in this frame; otherwise, an invalid LeapHand object is returned.
Since 1.0
Parameters
  • handId -

    The ID value of a LeapHand object from a previous frame.


- (LeapInteractionBox *) interactionBox

The current LeapInteractionBox for the frame.

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

LeapInteractionBox *interactionBox = frame.interactionBox;

Return
The current LeapInteractionBox object.
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.

Return
The LeapPointable object with the matching ID if one exists in this frame; otherwise, an invalid LeapPointable object is returned.
Since 1.0
Parameters
  • pointableId -

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


- (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];

Return
A positive value containing the heuristically determined rotational change between the current frame and that specified in the sinceFrame parameter.
Parameters
  • sinceFrame -

    The starting frame for computing the relative rotation.


- (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];

Return
A value containing the heuristically determined rotational change between the current frame and that specified in the sinceFrame parameter around the given axis.
Parameters
  • sinceFrame -

    The starting frame for computing the relative rotation.

  • axis -

    The LeapVector representing the direction of the axis to measure rotation around.


- (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];

Return
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.
Parameters
  • sinceFrame -

    The starting frame for computing the relative rotation.


- (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];

Return
A LeapMatrix containing the heuristically determined rotational change between the current frame and that specified in the sinceFrame parameter.
Parameters
  • sinceFrame -

    The starting frame for computing the relative rotation.


- (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];

Return
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.
Parameters
  • sinceFrame -

    The starting frame for computing the relative rotation.


- (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];

Return
A positive value representing the heuristically determined scaling change ratio between the current frame and that specified in the sinceFrame parameter.
Parameters
  • sinceFrame -

    The starting frame for computing the relative scaling.


- (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];

Return
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.
Parameters
  • sinceFrame -

    The starting frame for computing the relative scaling.


- (NSData *) serialize

Encodes this Frame object as NSData object.

NSData *serializedFrame = [frameToSave serialize];
BOOL success = [serializedFrame writeToFile:@"frame.data" atomically:YES];

Return
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];

Return
The LeapTool object with the matching ID if one exists in this frame; otherwise, an invalid LeapTool object is returned.
Parameters
  • toolId -

    The ID value of a LeapTool object from a previous frame.


- (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];

Return
A LeapVector representing the heuristically determined change in position of all objects between the current frame and that specified in the sinceFrame parameter.
Parameters
  • sinceFrame -

    The starting frame for computing the relative translation.


- (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];

Return
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.
Parameters
  • sinceFrame -

    The starting frame for computing the translation.

Property


- (float) currentFramesPerSecond
currentFramesPerSecond

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;

Return
An estimate of frames per second of the Leap Motion Controller.
Since 1.0


- (NSArray *) fingers
fingers

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;

Return
NSArray containing all LeapFinger objects detected in this frame.
Since 1.0


- (NSArray *) hands
hands

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;

Return
NSArray containing all LeapHand objects detected in this frame.
Since 1.0


- (int64_t) id
id

A unique ID for this LeapFrame.

Consecutive frames processed by the Leap have consecutive increasing values.

int64_t frameId = frame.id;

Return
The frame ID.
Since 1.0


- (NSArray *) images
images

The list of images from the Leap Motion cameras.

Return
An NSArray object containing the camera images analyzed to create this Frame.
Since 2.1.5


- (BOOL) isValid
isValid

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

Return
YES, if this is a valid LeapFrame object; false otherwise.
Since 1.0


- (NSArray *) pointables
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.

NSArray *pointableList = frame.pointables;

Return
NSArray containing all LeapPointable objects detected in this frame.
Since 1.0


- (int64_t) timestamp
timestamp

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;

Return
The timestamp in microseconds.
Since 1.0


- (NSArray *) tools
tools

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;

Return
NSArray containing all LeapTool objects detected in this frame.

Public Static Functions


+ (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.

Since
2.2.1
Parameters
  • serializedFrame -

    An NSData object containing the serialized bytes of a frame.


+ (LeapFrame *) invalid

Returns an invalid LeapFrame object.

LeapFrame *badFrame = LeapFrame.invalid;

Return
The invalid LeapFrame instance.
Since 1.0