GestureΒΆ
The Gesture class represents a recognized movement by the user.
The Leap Motion Controller watches the activity within its field of view for certain movement patterns typical of a user gesture or command. For example, a movement from side to side with the hand can indicate a swipe gesture, while a finger poking forward can indicate a screen tap gesture.
When the Leap Motion software recognizes a gesture, it assigns an ID and adds a Gesture object to the frame gesture list. For continuous gestures, which occur over many frames, the Leap Motion software updates the gesture by adding a Gesture object having the same ID and updated properties in each subsequent frame.
Important: Recognition for each type of gesture must be enabled using the Controller::enableGesture() function; otherwise no gestures are recognized or reported.
controller.enableGesture(Gesture.Type.TYPE_CIRCLE); controller.enableGesture(Gesture.Type.TYPE_KEY_TAP); controller.enableGesture(Gesture.Type.TYPE_SCREEN_TAP); controller.enableGesture(Gesture.Type.TYPE_SWIPE);Subclasses of Gesture define the properties for the specific movement patterns recognized by the Leap Motion software.
The Gesture subclasses include:
CircleGesture A circular movement by a finger.
SwipeGesture A straight line movement by the hand with fingers extended.
ScreenTapGesture A forward tapping movement by a finger.
KeyTapGesture A downward tapping movement by a finger.
Circle and swipe gestures are continuous and these objects can have a state of start, update, and stop.
The screen tap gesture is a discrete gesture. The Leap Motion software only creates a single ScreenTapGesture object for each tap and it always has a stop state.
Get valid Gesture instances from a Frame object. You can get a list of gestures with the Frame::gestures() method. You can get a list of gestures since a specified frame with the Frame::gestures(const Frame&) method. You can also use the Frame::gesture() method to find a gesture in the current frame using an ID value obtained in a previous frame.
Gesture objects can be invalid. For example, when you get a gesture by ID using Frame::gesture(), and there is no gesture with that ID in the current frame, then gesture() returns an Invalid Gesture object (rather than a null value). Always check object validity in situations where a gesture might be invalid.
The following keys can be used with the Config class to configure the gesture recognizer:
Key string Value type Default value Units Gesture.Circle.MinRadius float 5.0 mm Gesture.Circle.MinArc float 1.5 * pi radians Gesture.Swipe.MinLength float 150 mm Gesture.Swipe.MinVelocity float 1000 mm/s Gesture.KeyTap.MinDownVelocity float 50 mm/s Gesture.KeyTap.HistorySeconds float 0.1 s Gesture.KeyTap.MinDistance float 3.0 mm Gesture.ScreenTap.MinForwardVelocity float 50 mm/s Gesture.ScreenTap.HistorySeconds float 0.1 s Gesture.ScreenTap.MinDistance float 5.0 mm Public Functions
- Since
- 1.0
Public Static Functionslong duration()The elapsed duration of the recognized movement up to the frame containing this Gesture object, in microseconds.
float microseconds = gesture.duration();The duration reported for the first Gesture in the sequence (with the STATE_START state) will typically be a small positive number since the movement must progress far enough for the Leap Motion software to recognize it as an intentional gesture.
- Return
- int64_t the elapsed duration in microseconds.
- Since
- 1.0
float durationSeconds()The elapsed duration in seconds.
float seconds = gesture.durationSeconds();
- See
- duration()
- Return
- float the elapsed duration in seconds.
- Since
- 1.0
boolean equals(Gesture rhs)Compare Gesture object equality.
Boolean gestureIsEqual = thisGesture.equals(thatGesture);Two Gestures are equal if they represent the same snapshot of the same recognized movement.
- Since
- 1.0
Frame frame()Gesture()Gesture(Gesture rhs)HandList hands()int id()The gesture ID.
All Gesture objects belonging to the same recognized movement share the same ID value. Use the ID value with the Frame::gesture() method to find updates related to this Gesture object in subsequent frames.
int gestureToFind = gesture.id(); GestureList manyGestures = frame.gestures(olderFrame); for(Gesture gestureObject : manyGestures) { if (gestureObject.id() == gestureToFind) { //Process it... } }
- Return
- int32_t the ID of this Gesture.
- Since
- 1.0
boolean isValid()Reports whether this Gesture instance represents a valid Gesture.
An invalid Gesture object does not represent a snapshot of a recognized movement. Invalid Gesture objects are returned when a valid object cannot be provided. For example, when you get an gesture by ID using Frame::gesture(), and there is no gesture with that ID in the current frame, then gesture() returns an Invalid Gesture object (rather than a null value). Always check object validity in situations where an gesture might be invalid.
if (gesture.isValid()) { // Process it... }
- Return
- bool True, if this is a valid Gesture instance; false, otherwise.
- Since
- 1.0
PointableList pointables()The list of fingers and tools associated with this Gesture, if any.
If no Pointable objects are related to this gesture, the list is empty.
PointableList pointablesForGesture = gesture.pointables();
- Return
- PointableList the list of related Pointable objects.
- Since
- 1.0
Gesture.State state()The gesture state.
Recognized movements occur over time and have a beginning, a middle, and an end. The ‘state()‘ attribute reports where in that sequence this Gesture object falls.
for(Gesture gestureObj : frame.gestures()) { switch (gesture.state()) { case STATE_START: //Handle starting gestures break; case STATE_UPDATE: //Handle continuing gestures break; case STATE_STOP: //Handle ending gestures break; default: //Handle unrecognized states break; } }
- Return
- Gesture::State A value from the Gesture::State enumeration.
- Since
- 1.0
String toString()Gesture.Type type()The gesture type.
for(Gesture gesture : frame.gestures()) { switch (gesture.type()) { case TYPE_CIRCLE: //Handle circle gestures break; case TYPE_KEY_TAP: //Handle key tap gestures break; case TYPE_SCREEN_TAP: //Handle screen tap gestures break; case TYPE_SWIPE: //Handle swipe gestures break; default: //Handle unrecognized gestures break; } }
- Return
- Gesture::Type A value from the Gesture::Type enumeration.
- Since
- 1.0
Gesture invalid()Returns an invalid Gesture object.
You can use the instance returned by this function in comparisons testing whether a given Gesture instance is valid or invalid. (You can also use the Gesture::isValid() function.)
Gesture trackedGesture = frame.gesture(gestureID); if (!trackedGesture.equals(Gesture.invalid())) { //Process it... }
- Return
- The invalid Gesture instance.
- Since
- 1.0
class State
The possible gesture states.
- Since
- 1.0
class Type
The supported types of gestures.
- Since
- 1.0