FrameΒΆ

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

Inherits IEquatable< Frame >.

Public Member Functions

void Deserialize (byte[] arg)
 Decodes a byte string to replace the properties of this Frame. More...
 
bool Equals (Frame other)
 Compare Frame object equality. More...
 
 Frame ()
 Constructs a Frame object. More...
 
 Frame (long id, long timestamp, float fps, InteractionBox interactionBox, List< Hand > hands)
 Constructs a new Frame. More...
 
Hand Hand (int id)
 The Hand object with the specified ID in this frame. More...
 
override string ToString ()
 A string containing a brief, human readable description of the Frame object. More...
 

Public Attributes

float CurrentFramesPerSecond
 The instantaneous framerate. More...
 
List< HandHands
 The list of Hand objects detected in this frame, given in arbitrary order. More...
 
Vector HeadPosition
 The position and orientation of the user's head. More...
 
long Id
 A unique ID for this Frame. More...
 
InteractionBox InteractionBox
 The current InteractionBox for the frame. More...
 
long Timestamp
 The frame capture time in microseconds elapsed since an arbitrary point in time in the past. More...
 

Properties

byte[] Serialize [get]
 Encodes this Frame object as a byte string. More...
 

Detailed Description

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

The Leap Motion software detects hands, fingers and tools within the tracking area, reporting their positions, orientations, gestures, and motions in frames at the Leap Motion frame rate.

Access Frame objects through an instance of the Controller class:

if (controller.IsConnected) { //controller is a Controller object
Frame frame = controller.Frame (); //The latest frame
Frame previous = controller.Frame (1); //The previous frame
}

Implement a Listener subclass to receive a callback event when a new Frame is available.

Since
1.0

Constructor & Destructor Documentation

Frame ( )

Constructs a Frame object.

Frame instances created with this constructor are invalid. Get valid Frame objects by calling the Controller::frame() function.

Frame current = controller.Frame ();
Frame previous = controller.Frame (1);

The only time you should use this constructor is before deserializing serialized frame data. Call Frame::deserialize(string) to recreate a saved Frame.

Since
1.0
Frame ( long  id,
long  timestamp,
float  fps,
InteractionBox  interactionBox,
List< Hand hands 
)

Constructs a new Frame.

Parameters
idThe id of this frame.
timestampThe creation time of this frame in microseconds.
fpsThe current data frame rate of the service when this frame was created.
interactionBoxThe InteractionBox object for this frame.
Since
3.0

Member Function Documentation

void Deserialize ( byte[]  arg)

Decodes a byte string to replace the properties of this Frame.

A Controller object must be instantiated for this function to succeed, but it does not need to be connected. To extract gestures from the deserialized frame, you must enable the appropriate gestures first.

Any existing data in the frame is destroyed. If you have references to child objects (hands, fingers, etc.), these are preserved as long as the references remain in scope.

Controller controller = new Controller (); //An instance must exist
byte[] frameData = System.IO.File.ReadAllBytes ("frame.data");
Frame reconstructedFrame = new Frame ();
reconstructedFrame.Deserialize (frameData);

Note: The behavior when calling functions which take another Frame object as a parameter is undefined when either frame has been deserialized. For example, calling Gestures(sinceFrame) on a deserialized frame or with a deserialized frame as parameter (or both) does not necessarily return all gestures that occurred between the two frames. Motion functions, like ScaleFactor(startFrame), are more likely to return reasonable results, but could return anomalous values in some cases.

Parameters
argA byte array containing the bytes of a serialized frame.
Since
2.1.0
bool Equals ( Frame  other)

Compare Frame object equality.

Boolean isFrameEqual = thisFrame.Equals(thatFrame);

Two Frame objects are equal if and only if both Frame objects represent the exact same frame of tracking data and both Frame objects are valid.

Since
1.0
Hand Hand ( int  id)

The Hand object with the specified ID in this frame.

Use the Frame::hand() function to retrieve the Hand object from this frame using an ID value obtained from a previous frame. This function always returns a Hand object, but if no hand with the specified ID is present, an invalid Hand object is returned.

Hand handOfInterest = 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 Hand object representing that physical hand may have a different ID than that representing the physical hand in an earlier frame.

Parameters
idThe ID value of a Hand object from a previous frame.
Returns
The Hand object with the matching ID if one exists in this frame; otherwise, an invalid Hand object is returned.
Since
1.0
override string ToString ( )

A string containing a brief, human readable description of the Frame object.

Returns
A description of the Frame as a string.
Since
1.0

Member Data Documentation

float 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 instantaneousFrameRate = frame.CurrentFramesPerSecond;
Returns
An estimate of frames per second of the Leap Motion Controller.
Since
1.0
List<Hand> Hands

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

The list can be empty if no hands are detected.

List<Hand> handsInFrame = frame.Hands;
Returns
The List<Hand> containing all Hand objects detected in this frame.
Since
1.0
Vector HeadPosition

The position and orientation of the user's head.

Positional tracking must be enabled.

Since
3.2.1
long Id

A unique ID for this Frame.

Consecutive frames processed by the Leap Motion software have consecutive increasing values. You can use the frame ID to avoid processing the same Frame object twice:

Int64 lastFrameID = 0;
void processFrame (Frame frame)
{
if (frame.Id == lastFrameID)
return;
//...
lastFrameID = frame.Id;
}

As well as to make sure that your application processes every frame:

Int64 lastProcessedFrameID = 0;
void nextFrame (Controller controller)
{
Int64 currentID = controller.Frame ().Id;
for (int history = 0; history < currentID - lastProcessedFrameID; history++) {
processFrame (controller.Frame (history));
}
lastProcessedFrameID = currentID;
}
void processNextFrame (Frame frame)
{
if (frame.Id > 0) {
//...
}
}
Returns
The frame ID.
Since
1.0

The current InteractionBox for the frame.

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

Returns
The current InteractionBox object.
Since
1.0
long Timestamp

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

Use Controller::now() to calculate the age of the frame.

float framePeriod = controller.Frame (0).Timestamp - controller.Frame (1).Timestamp;
Returns
The timestamp in microseconds.
Since
1.0

Property Documentation

byte [] Serialize
get

Encodes this Frame object as a byte string.

byte[] serializedFrame = frame.Serialize;
System.IO.File.WriteAllBytes ("frame.data", serializedFrame);
Since
2.1.0