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

serializedFrame An 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

fingerId The 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

gestureId The 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

sinceFrame An 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

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

LeapInteractionBox *interactionBox = frame.interactionBox;

Returns: The current LeapInteractionBox object.

Since 1.0

+ (LeapFrame *) invalid

Returns an invalid LeapFrame object.

LeapFrame *badFrame = LeapFrame.invalid;

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

pointableId The 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

sinceFrame The 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

sinceFrame	The starting frame for computing the relative rotation.
axis	The 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

sinceFrame The 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

sinceFrame The 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

sinceFrame The 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

sinceFrame The 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

sinceFrame The 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

toolId The 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

sinceFrame The 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

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

LeapFrame¶

Instance Methods

Class Methods

Properties

Detailed Description

Method Documentation

Property Documentation