Frame¶

Properties:

Methods:

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

Public Functions

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.

Since

2.1.0

Parameters

• arg -

  A byte array containing the bytes of a serialized frame.

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

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.

Since

3.0

Parameters

• id -

  The id of this frame.

• timestamp -

  The creation time of this frame in microseconds.

• fps -

  The current data frame rate of the service when this frame was created.

• interactionBox -

  The InteractionBox object for this frame.

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.

Return

The Hand object with the matching ID if one exists in this frame; otherwise, an invalid Hand object is returned.

Since

1.0

Parameters

• id -

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

override string ToString()

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

Return

A description of the Frame as a string.

Since

1.0

Public Members

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;

Return

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;

Return

The List<Hand> containing all Hand objects detected in this frame.

Since

1.0

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) {
        //...
    }
}

Return

The frame ID.

Since

1.0

InteractionBox InteractionBox

The current InteractionBox for the frame.

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

InteractionBox box = frame.InteractionBox;

Return

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;

Return

The timestamp in microseconds.

Since

1.0

Property

byte[] Serialize

Encodes this Frame object as a byte string.

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

Since

2.1.0