Leap Motion C++ API Reference  0.8.0
Leap::Frame Class Reference

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

Inherits Leap::Interface.

Public Member Functions

Finger finger (int32_t id) const
 The Finger object with the specified ID in this frame.
 
FingerList fingers () const
 The list of Finger objects detected in this frame, given in arbitrary order.
 
 Frame ()
 Constructs a Frame object.
 
Gesture gesture (int32_t id) const
 The Gesture object with the specified ID in this frame.
 
GestureList gestures () const
 The gestures recognized or continuing in this frame.
 
GestureList gestures (const Frame &sinceFrame) const
 Returns a GestureList containing all gestures that have occured since the specified frame.
 
Hand hand (int32_t id) const
 The Hand object with the specified ID in this frame.
 
HandList hands () const
 The list of Hand objects detected in this frame, given in arbitrary order.
 
int64_t id () const
 A unique ID for this Frame.
 
InteractionBox interactionBox () const
 The current InteractionBox for the frame.
 
bool isValid () const
 Reports whether this Frame instance is valid.
 
bool operator!= (const Frame &) const
 Compare Frame object inequality.
 
bool operator== (const Frame &) const
 Compare Frame object equality.
 
Pointable pointable (int32_t id) const
 The Pointable object with the specified ID in this frame.
 
PointableList pointables () const
 The list of Pointable objects (fingers and tools) detected in this frame, given in arbitrary order.
 
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 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.
 
Vector rotationAxis (const Frame &sinceFrame) const
 The axis of rotation derived from the overall rotational motion between the current frame and the specified frame.
 
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.
 
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 scaleFactor (const Frame &sinceFrame) const
 The scale factor derived from the overall motion between the current frame and the specified frame.
 
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.
 
int64_t timestamp () const
 The frame capture time in microseconds elapsed since the Leap started.
 
Tool tool (int32_t id) const
 The Tool object with the specified ID in this frame.
 
ToolList tools () const
 The list of Tool objects detected in this frame, given in arbitrary order.
 
std::string toString () const
 A string containing a brief, human readable description of the Frame object.
 
Vector translation (const Frame &sinceFrame) const
 The change of position derived from the overall linear motion between the current frame and the specified frame.
 
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.
 

Static Public Member Functions

static const Frameinvalid ()
 Returns an invalid Frame object.
 

Friends

std::ostream & operator<< (std::ostream &, const Frame &)
 Writes a brief, human readable description of the Frame object to an output stream.
 

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 and motions in frames at the Leap Motion frame rate.

Access Frame objects through an instance of the Controller class. Implement a Listener subclass to receive a callback event when a new Frame is available.

Constructor & Destructor Documentation

Leap::Frame::Frame ( )

Constructs a Frame object.

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

Member Function Documentation

Finger Leap::Frame::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.

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
idThe 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.
FingerList Leap::Frame::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.

Returns
The FingerList containing all Finger objects detected in this frame.
Gesture Leap::Frame::gesture ( int32_t  id) const

The Gesture object with the specified ID in this frame.

Use the Frame::gesture() function to return a Gesture object in this frame using an ID obtained in an earlier frame. The function always returns a Gesture object, but if there was no update for the gesture in this frame, then an invalid Gesture object is returned.

All Gesture objects representing the same recognized movement share the same ID.

Parameters
idThe 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.
GestureList Leap::Frame::gestures ( ) const

The gestures recognized or continuing in this frame.

Circle and swipe gestures are updated every frame. Tap gestures only appear in the list for a single frame.

Returns
GestureList the list of gestures.
GestureList Leap::Frame::gestures ( const Frame sinceFrame) const

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

Parameters
sinceFrameAn 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 occured since the specified frame.
Hand Leap::Frame::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.

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.
HandList Leap::Frame::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.

Returns
The HandList containing all Hand objects detected in this frame.
int64_t Leap::Frame::id ( ) const

A unique ID for this Frame.

Consecutive frames processed by the Leap Motion software have consecutive increasing values.

Returns
The frame ID.
InteractionBox Leap::Frame::interactionBox ( ) const

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.
static const Frame& Leap::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.)

Returns
The invalid Frame instance.
bool Leap::Frame::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:

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.
bool Leap::Frame::operator!= ( const Frame ) const

Compare Frame object inequality.

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.

bool Leap::Frame::operator== ( const Frame ) const

Compare Frame object equality.

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.

Pointable Leap::Frame::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.

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
idThe 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.
PointableList Leap::Frame::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.

Returns
The PointableList containing all Pointable objects detected in this frame.
float Leap::Frame::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.

The returned angle is expressed in radians measured clockwise around the rotation axis (using the right-hand rule) between the start and end frames. The value is always between 0 and pi radians (0 and 180 degrees).

The Leap Motion software derives frame rotation from the relative change in position and orientation of all objects detected in the field of view.

If either this frame or sinceFrame is an invalid Frame object, then the angle of rotation is zero.

Parameters
sinceFrameThe 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 Leap::Frame::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.

The returned angle is expressed in radians measured clockwise around the rotation axis (using the right-hand rule) between the start and end frames. The value is always between -pi and pi radians (-180 and 180 degrees).

The Leap Motion software derives frame rotation from the relative change in position and orientation of all objects detected in the field of view.

If either this frame or sinceFrame is an invalid Frame object, then the angle of rotation is zero.

Parameters
sinceFrameThe starting frame for computing the relative rotation.
axisThe 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.
Vector Leap::Frame::rotationAxis ( const Frame sinceFrame) const

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

The returned direction vector is normalized.

The Leap Motion software derives frame rotation from the relative change in position and orientation of all objects detected in the field of view.

If either this frame or sinceFrame is an invalid Frame object, or if no rotation is detected between the two frames, a zero vector is returned.

Parameters
sinceFrameThe 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.
Matrix Leap::Frame::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.

The Leap Motion software derives frame rotation from the relative change in position and orientation of all objects detected in the field of view.

If either this frame or sinceFrame is an invalid Frame object, then this method returns an identity matrix.

Parameters
sinceFrameThe 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.
float Leap::Frame::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.

If either this frame or sinceFrame is an invalid Frame object, then this method returns zero.

Parameters
sinceFrameThe 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 Leap::Frame::scaleFactor ( const Frame sinceFrame) const

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

The scale factor is always positive. A value of 1.0 indicates no scaling took place. Values between 0.0 and 1.0 indicate contraction and values greater than 1.0 indicate expansion.

The Leap Motion software derives scaling from the relative inward or outward motion of all objects detected in the field of view (independent of translation and rotation).

If either this frame or sinceFrame is an invalid Frame object, then this method returns 1.0.

Parameters
sinceFrameThe 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 Leap::Frame::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.

If either this frame or sinceFrame is an invalid Frame object, then this method returns zero.

Parameters
sinceFrameThe 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.
int64_t Leap::Frame::timestamp ( ) const

The frame capture time in microseconds elapsed since the Leap started.

Returns
The timestamp in microseconds.
Tool Leap::Frame::tool ( int32_t  id) const

The Tool object with the specified ID in this frame.

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

Note that ID values persist across frames, but only until tracking of a particular object is lost. If tracking of a tool is lost and subsequently regained, the new Tool object representing that tool may have a different ID than that representing the tool in an earlier frame.

Parameters
idThe 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.
ToolList Leap::Frame::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.

Returns
The ToolList containing all Tool objects detected in this frame.
std::string Leap::Frame::toString ( ) const

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

Returns
A description of the Frame as a string.
Vector Leap::Frame::translation ( const Frame sinceFrame) const

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

The returned translation vector provides the magnitude and direction of the movement in millimeters.

The Leap Motion software derives frame translation from the linear motion of all objects detected in the field of view.

If either this frame or sinceFrame is an invalid Frame object, then this method returns a zero vector.

Parameters
sinceFrameThe 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.
float Leap::Frame::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.

If either this frame or sinceFrame is an invalid Frame object, then this method returns zero.

Parameters
sinceFrameThe 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.

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.