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... | |
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:
Implement a Listener subclass to receive a callback event when a new Frame is available.
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.
The only time you should use this constructor is before deserializing serialized frame data. Call Frame::deserialize(string)
to recreate a saved Frame.
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.
|
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.
Note: The behavior when calling functions which take another Frame object as a parameter is undefined when either frame has been deserialized.
str | A std:string object containing the serialized bytes of a frame. |
|
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.
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.
id | The ID value of a Finger object from a previous frame. |
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.
Gesture gesture | ( | int32_t | id | ) | const |
The Gesture object with the specified ID in this frame.
id | The ID of an Gesture object from a previous 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 occurred since the specified frame.
sinceFrame | An earlier Frame object. The starting frame must still be in the frame history cache, which has a default length of 60 frames. |
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.
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.
id | The ID value of a Hand object from a previous frame. |
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.
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:
As well as to make sure that your application processes every frame:
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
InteractionBox interactionBox | ( | ) | const |
The current InteractionBox for the frame.
See the InteractionBox class documentation for more details on how this class should be used.
|
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.)
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:
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.)
bool operator!= | ( | const Frame & | ) | const |
bool operator== | ( | const Frame & | ) | const |
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.
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.
id | The ID value of a Pointable object from a previous frame. |
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.
ImageList rawImages | ( | ) | const |
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.
sinceFrame | The starting frame for computing the relative rotation. |
The angle of rotation around the specified axis derived from the overall rotational motion between the current frame and the specified frame.
sinceFrame | The starting frame for computing the relative rotation. |
axis | The axis to measure rotation around. |
The axis of rotation derived from the overall rotational motion between the current frame and the specified frame.
sinceFrame | The starting frame for computing the relative rotation. |
The transform matrix expressing the rotation derived from the overall rotational motion between the current frame and the specified frame.
sinceFrame | The starting frame for computing the relative rotation. |
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.
sinceFrame | The starting frame for computing the relative rotation. |
float scaleFactor | ( | const Frame & | sinceFrame | ) | const |
The scale factor derived from the overall motion between the current frame and the specified frame.
sinceFrame | The starting frame for computing the relative scaling. |
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.
sinceFrame | The starting frame for computing the relative scaling. |
|
inline |
|
inline |
|
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.
Tool tool | ( | int32_t | id | ) | const |
The Tool object with the specified ID in this frame.
id | The ID value of a Tool object from a previous frame. |
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.
|
inline |
The change of position derived from the overall linear motion between the current frame and the specified frame.
sinceFrame | The starting frame for computing the relative translation. |
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.
sinceFrame | The starting frame for computing the translation. |