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

Inherits Interface.

Public Member Functions
float	currentFramesPerSecond () const
	The instantaneous frame rate. More...

void	deserialize (const std::string &str)
	Decodes a byte string to replace the properties of this Frame. More...

void	deserialize (const unsigned char *ptr, int length)

Finger	finger (int32_t id) const
	The Finger object with the specified ID in this frame. More...

FingerList	fingers () const
	The list of Finger objects detected in this frame, given in arbitrary order. More...

	Frame (FrameImplementation *)

	Frame ()
	Constructs a Frame object. More...

Gesture	gesture (int32_t id) const
	The Gesture object with the specified ID in this frame. More...

GestureList	gestures () const
	The gestures recognized or continuing in this frame. More...

GestureList	gestures (const Frame &sinceFrame) const
	Returns a GestureList containing all gestures that have occurred since the specified frame. More...

Hand	hand (int32_t id) const
	The Hand object with the specified ID in this frame. More...

HandList	hands () const
	The list of Hand objects detected in this frame, given in arbitrary order. More...

int64_t	id () const
	A unique ID for this Frame. More...

ImageList	images () const
	The list of IR images from the Leap Motion cameras. More...

InteractionBox	interactionBox () const
	The current InteractionBox for the frame. More...

bool	isValid () const
	Reports whether this Frame instance is valid. More...

bool	operator!= (const Frame &) const
	Compare Frame object inequality. More...

bool	operator== (const Frame &) const
	Compare Frame object equality. More...

Pointable	pointable (int32_t id) const
	The Pointable object with the specified ID in this frame. More...

PointableList	pointables () const
	The list of Pointable objects (fingers and tools) detected in this frame, given in arbitrary order. More...

ImageList	rawImages () const
	The list of Raw images from the Leap Motion cameras. More...

float	rotationAngle (const Frame &sinceFrame) const
	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 (const Frame &sinceFrame, const Vector &axis) const
	The angle of rotation around the specified axis derived from the overall rotational motion between the current frame and the specified frame. More...

Vector	rotationAxis (const Frame &sinceFrame) const
	The axis of rotation derived from the overall rotational motion between the current frame and the specified frame. More...

Matrix	rotationMatrix (const Frame &sinceFrame) const
	The transform matrix expressing the rotation derived from the overall rotational motion between the current frame and the specified frame. More...

float	rotationProbability (const Frame &sinceFrame) const
	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 (const Frame &sinceFrame) const
	The scale factor derived from the overall motion between the current frame and the specified frame. More...

float	scaleProbability (const Frame &sinceFrame) const
	The estimated probability that the overall motion between the current frame and the specified frame is intended to be a scaling motion. More...

std::string	serialize () const
	Encodes this Frame object as a byte string. More...

void	serialize (unsigned char *ptr) const

int	serializeLength () const

int64_t	timestamp () const
	The frame capture time in microseconds elapsed since an arbitrary point in time in the past. More...

Tool	tool (int32_t id) const
	The Tool object with the specified ID in this frame. More...

ToolList	tools () const
	The list of Tool objects detected in this frame, given in arbitrary order. More...

std::string	toString () const
	A string containing a brief, human readable description of the Frame object. More...

Vector	translation (const Frame &sinceFrame) const
	The change of position derived from the overall linear motion between the current frame and the specified frame. More...

float	translationProbability (const Frame &sinceFrame) const
	The estimated probability that the overall motion between the current frame and the specified frame is intended to be a translating motion. More...

Static Public Member Functions
static const Frame &	invalid ()
	Returns an invalid Frame object. More...

Friends
std::ostream &	operator<< (std::ostream &, const Frame &)
	Writes a brief, human readable description of the Frame object to an output stream. 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
{
    Leap::Frame frame = controller.frame(); //The latest frame
    Leap::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 ( FrameImplementation * )

Frame ( )

Constructs a Frame object.

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

Leap::Frame current = controller.frame();

Leap::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

Member Function Documentation

float currentFramesPerSecond ( ) const

The instantaneous frame rate.

The rate at which the Leap Motion software is providing frames of data (in frames per second). The frame rate 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

void deserialize ( const std::string & str )

inline

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.

Leap::Controller controller; //An instance must exist
std::ifstream inputFile("frame.data");
std::string frameData((std::istreambuf_iterator<char>(inputFile)), std::istreambuf_iterator<char>());
Leap::Frame reconstructedFrame;
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.

Parameters

str	A std:string object containing the serialized bytes of a frame.

Since: 2.1.0

void deserialize	(	const unsigned char *	ptr,
		int	length
	)

inline

Finger finger ( int32_t id ) const

The Finger object with the specified ID in this frame.

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

Leap::Finger fingerOfinterest = 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 Finger object representing that physical finger may have a different ID than that representing the finger in an earlier frame.

Parameters

id	The ID value of a Finger object from a previous frame.

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

Since: 1.0

FingerList fingers ( ) const

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

The list can be empty if no fingers are detected.

Use PointableList::extended() to remove non-extended fingers from the list.

Leap::FingerList fingersInFrame = frame.fingers();

Returns: The FingerList containing all Finger objects detected in this frame.

Since: 1.0

Gesture gesture ( int32_t id ) const

The Gesture object with the specified ID in this frame.

Leap::Gesture gestureOfInterest = frame.gesture(gestureID);

Parameters

id	The ID of an Gesture object from a previous frame.

Returns: The Gesture object in the frame with the specified ID if one exists; Otherwise, an Invalid Gesture object.

Deprecated:: 3.0

GestureList gestures ( ) const

The gestures recognized or continuing in this frame.

Leap::GestureList gesturesInFrame = frame.gestures();

Returns: GestureList the list of gestures.

Deprecated:: 3.0

GestureList gestures ( const Frame & sinceFrame ) const

Returns a GestureList containing all gestures that have occurred since the specified frame.

Leap::GestureList gesturesSinceFrame = frame.gestures(lastProcessedFrame);

Parameters

sinceFrame An earlier Frame object. The starting frame must still be in the frame history cache, which has a default length of 60 frames.

Returns: GestureList The list of the Gesture objects that have occurred since the specified frame.

Deprecated:: 3.0

Hand hand ( int32_t id ) const

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.

Leap::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

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

HandList hands ( ) const

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

The list can be empty if no hands are detected.

Leap::HandList handsInFrame = frame.hands();

Returns: The HandList containing all Hand objects detected in this frame.

Since: 1.0

int64_t id ( ) const

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_t lastFrameID = 0;
void processFrame( Leap::Frame frame )
{
    if( frame.id() == lastFrameID ) return;
    //...
    lastFrameID = frame.id();
}

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

int64_t lastProcessedFrameID = 0;
void nextFrame( Leap::Controller controller )
{
    int64_t currentID = controller.frame().id();
    for( int history = 0; history < currentID - lastProcessedFrameID; history++)
    {
        processNextFrame( controller.frame(history) );
    }
    lastProcessedFrameID = currentID;
}
void processNextFrame( Leap::Frame frame )
{
    if( frame.isValid() )
    {
        //...
    }
}

Returns: The frame ID.

Since: 1.0

ImageList images ( ) const

The list of IR images from the Leap Motion cameras.

If the system is in Robust mode, these will be slightly post processed

Returns: An ImageList object containing the camera images analyzed to create this Frame.

Deprecated:: 3.0

InteractionBox interactionBox ( ) const

The current InteractionBox for the frame.

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

Leap::InteractionBox box = frame.interactionBox();

Returns: The current InteractionBox object.

Since: 1.0

static const Frame& invalid ( )

static

Returns an invalid Frame object.

You can use the instance returned by this function in comparisons testing whether a given Frame instance is valid or invalid. (You can also use the Frame::isValid() function.)

//Average a finger position for the last 10 frames
int count = 0;
Leap::Vector average = Leap::Vector();
Leap::Finger fingerToAverage = frame.fingers()[0];
for( int i = 0; i < 10; i++ )
{
    Leap::Finger fingerFromFrame = controller.frame(i).finger(fingerToAverage.id());
    if( fingerFromFrame.isValid() )
    {
        average += fingerFromFrame.tipPosition();
        count++;
    }
}
average /= count;

Returns: The invalid Frame instance.

Since: 1.0

bool isValid ( ) const

Reports whether this Frame instance is valid.

A valid Frame is one generated by the Leap::Controller object that contains tracking data for all detected entities. An invalid Frame contains no actual tracking data, but you can call its functions without risk of a null pointer exception. The invalid Frame mechanism makes it more convenient to track individual data across the frame history. For example, you can invoke:

Leap::Finger finger = controller.frame(n).finger(fingerID);

for an arbitrary Frame history value, "n", without first checking whether frame(n) returned a null object. (You should still check that the returned Finger instance is valid.)

Returns: True, if this is a valid Frame object; false otherwise.

Since: 1.0

bool operator!= ( const Frame & ) const

Compare Frame object inequality.

thisFrame != 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

bool operator== ( const Frame & ) const

Compare Frame object equality.

thisFrame == 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

Pointable pointable ( int32_t id ) const

The Pointable object with the specified ID in this frame.

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

Leap::Pointable pointableOfInterest = 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 Pointable object representing that finger or tool may have a different ID than that representing the finger or tool in an earlier frame.

Parameters

id	The ID value of a Pointable object from a previous frame.

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

Since: 1.0

PointableList pointables ( ) const

The list of Pointable objects (fingers and tools) detected in this frame, given in arbitrary order.

The list can be empty if no fingers or tools are detected.

Use PointableList::extended() to remove non-extended fingers from the list.

Leap::PointableList pointablesInFrame = frame.pointables();

Returns: The PointableList containing all Pointable objects detected in this frame.

Since: 1.0

ImageList rawImages ( ) const

The list of Raw images from the Leap Motion cameras.

These will never be postprocessed and closely match the raw sensor output.

Returns: An ImageList object containing the camera images analyzed to create this Frame.

Since: 2.3

float rotationAngle ( const Frame & sinceFrame ) const

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

float rotationInFrame = frame.rotationAngle(startFrame);

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.

Deprecated:: 3.0

float rotationAngle	(	const Frame &	sinceFrame,
		const Vector &	axis
	)		const

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

float rotationAroundXAxis = frame.rotationAngle(startFrame, Leap::Vector::xAxis());

Parameters

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

Deprecated:: 3.0

Vector rotationAxis ( const Frame & sinceFrame ) const

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

Leap::Vector axisOfRotation = frame.rotationAxis(startFrame);

Parameters

sinceFrame The starting frame for computing the relative rotation.

Returns: A normalized direction Vector representing the axis of the heuristically determined rotational change between the current frame and that specified in the sinceFrame parameter.

Deprecated:: 3.0

Matrix rotationMatrix ( const Frame & sinceFrame ) const

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

Leap::Matrix rotationTransform = frame.rotationMatrix(startFrame);

Parameters

sinceFrame The starting frame for computing the relative rotation.

Returns: A transformation Matrix containing the heuristically determined rotational change between the current frame and that specified in the sinceFrame parameter.

Deprecated:: 3.0

float rotationProbability ( const Frame & sinceFrame ) const

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

float rotationDominance = frame.rotationProbability(startFrame);

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.

Deprecated:: 3.0

float scaleFactor ( const Frame & sinceFrame ) const

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

float zoomFactor = frame.scaleFactor(startFrame);

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.

Deprecated:: 3.0

float scaleProbability ( const Frame & sinceFrame ) const

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

float scaleDominance = frame.scaleProbability(startFrame);

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.

Deprecated:: 3.0

std::string serialize ( ) const

inline

Encodes this Frame object as a byte string.

std::ofstream outputFile("frame.data");
const std::string serializedFrame = frame.serialize();
outputFile << serializedFrame;
outputFile.close();

Returns: The serialized string encoding the data for this frame.

Since: 2.1.0

void serialize ( unsigned char * ptr ) const

inline

int serializeLength ( ) const

inline

int64_t timestamp ( ) const

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 = frame.timestamp() - controller.frame(1).timestamp();

Returns: The timestamp in microseconds.

Since: 1.0

Tool tool ( int32_t id ) const

The Tool object with the specified ID in this frame.

Parameters

id	The ID value of a Tool object from a previous frame.

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

Deprecated:: 3.0

ToolList tools ( ) const

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

The list can be empty if no tools are detected.

Leap::ToolList toolsInFrame = frame.tools();

Returns: The ToolList containing all Tool objects detected in this frame.

Deprecated:: 3.0

std::string toString ( ) const

inline

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

Returns: A description of the Frame as a string.

Since: 1.0

Vector translation ( const Frame & sinceFrame ) const

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

Leap::Vector linearMovement = frame.translation(startFrame);

Parameters

sinceFrame The starting frame for computing the relative translation.

Returns: A Vector representing the heuristically determined change in position of all objects between the current frame and that specified in the sinceFrame parameter.

Deprecated:: 3.0

float translationProbability ( const Frame & sinceFrame ) const

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

float translationDominance = frame.translationProbability(startFrame);

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.

Deprecated:: 3.0

Friends And Related Function Documentation

std::ostream& operator<<	(	std::ostream &	,
		const Frame &
	)

friend

Writes a brief, human readable description of the Frame object to an output stream.

std::cout << frame << std::endl;

Since: 1.0

Frame¶

Public Member Functions

Static Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation