LeapGesture¶
The LeapGesture class represents a recognized movement by the user.
The Leap 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 recognizes a gesture, it assigns an ID and adds a LeapGesture object to the frame gesture list. For continuous gestures, which occur over many frames, the Leap updates the gesture by adding a LeapGesture object having the same ID and updated properties in each subsequent frame.
Important: Recognition for each type of gesture must be enabled using the [LeapController enableGesture:enable:] function; otherwise no gestures are recognized or reported.
[controller enableGesture:LEAP_GESTURE_TYPE_CIRCLE enable:YES]; [controller enableGesture:LEAP_GESTURE_TYPE_KEY_TAP enable:YES]; [controller enableGesture:LEAP_GESTURE_TYPE_SCREEN_TAP enable:YES]; [controller enableGesture:LEAP_GESTURE_TYPE_SWIPE enable:YES];Subclasses of LeapGesture define the properties for the specific movement patterns recognized by the Leap.
The LeapGesture subclasses for include:
LeapCircleGesture A circular movement by a finger.
LeapSwipeGesture A straight line movement by the hand with fingers extended.
LeapScreenTapGesture A forward tapping movement by a finger.
LeapKeyTapGesture 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 tap gestures are discrete. The Leap only creates a single LeapScreenTapGesture or LeapKeyTapGesture object appears for each tap and that object is always assigned the stop state.
Get valid LeapGesture instances from a LeapFrame object. You can get a list of gestures with the [LeapFrame gestures:] method. You can also use the [LeapFrame gesture:] method to find a gesture in the current frame using an ID value obtained in a previous frame.
LeapGesture objects can be invalid. For example, when you get a gesture by ID using [LeapFrame gesture:], and there is no gesture with that ID in the current frame, then gesture: returns an Invalid LeapGesture 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 LeapConfig 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 The LeapController object must be connected to the Leap Motion service/daemon before setting the configuration parameters.
[controller.config setFloat:@"Gesture.Circle.MinRadius" value:10.0]; [controller.config setFloat:@"Gesture.Circle.MinArc" value:.5]; [controller.config setFloat:@"Gesture.Swipe.MinLength" value:200.0]; [controller.config setFloat:@"Gesture.Swipe.MinVelocity" value:750]; [controller.config setFloat:@"Gesture.KeyTap.MinDownVelocity" value:40.0]; [controller.config setFloat:@"Gesture.KeyTap.HistorySeconds" value:.2]; [controller.config setFloat:@"Gesture.KeyTap.MinDistance" value:8.0]; [controller.config setFloat:@"Gesture.ScreenTap.MinForwardVelocity" value:30.0]; [controller.config setFloat:@"Gesture.ScreenTap.HistorySeconds" value:.5]; [controller.config setFloat:@"Gesture.ScreenTap.MinDistance" value:1.0]; [controller.config save];Public Functions
- Since 1.0
Property- (BOOL) equals:(const LeapGesture *) otherCompare LeapGesture object equality.
Two LeapGestures are equal if they represent the same snapshot of the same recognized movement.
[thisGesture equals:thatGesture];
- Since 1.0
- Parameters
- other -
The LeapGesture object to compare.
Public Static Functionsduration- (int64_t) durationThe elapsed duration of the recognized movement up to the frame containing this LeapGesture object, in microseconds.
int64_t microseconds = gesture.duration;The duration reported for the first LeapGesture in the sequence (with the LEAP_GESTURE_STATE_START state) will typically be a small positive number since the movement must progress far enough for the Leap to recognize it as an intentional gesture.
- Return
- int64_t the elapsed duration in microseconds.
- Since 1.0
durationSeconds- (float) durationSecondsThe elapsed duration in seconds.
float seconds = gesture.duration;
- See
- duration
- Return
- float the elapsed duration in seconds.
- Since 1.0
frame- (LeapFrame *) frameThe LeapFrame containing this LeapGesture instance.
LeapFrame *owningFrame = gesture.frame;
- Return
- The parent LeapFrame object.
- Since 1.0
hands- (NSArray *) handsThe list of hands associated with this LeapGesture, if any.
NSArray *handList = gesture.hands; //Only one hand for current gestures LeapHand *gesturingHand = [handList objectAtIndex:0];If no hands are related to this gesture, the list is empty.
- Return
- NSArray the list of related LeapHand objects.
- Since 1.0
id- (int32_t) idThe gesture ID.
All LeapGesture objects belonging to the same recognized movement share the same ID value. Use the ID value with the [LeapFrame gesture:] method to find updates related to this LeapGesture object in subsequent frames.
int gestureID = gesture.id;
- Return
- int32_t the ID of this LeapGesture.
- Since 1.0
isValid- (BOOL) isValidReports whether this LeapGesture instance represents a valid gesture.
An invalid LeapGesture object does not represent a snapshot of a recognized movement. Invalid LeapGesture objects are returned when a valid object cannot be provided. For example, when you get an gesture by ID using [LeapFrame gesture:], and there is no gesture with that ID in the current frame, then gesture: returns an Invalid LeapGesture object (rather than a null value). Always check object validity in situations where an gesture might be invalid.
LeapFrame *frame = [controller frame:0]; LeapGesture *trackedGesture = [frame gesture:trackedGestureID]; if(trackedGesture.isValid) { //Use the data... }
- Return
- bool Yes, if this is a valid LeapGesture instance; NO, otherwise.
- Since 1.0
pointables- (NSArray *) pointablesThe list of fingers and tools associated with this LeapGesture, if any.
NSArray *pointableList = gesture.pointables; //Only one pointable for current gestures LeapHand *gesturingPointable = [pointableList objectAtIndex:0];If no LeapPointable objects are related to this gesture, the list is empty.
- Return
- NSArray the list of related LeapPointable objects.
- Since 1.0
state- (LeapGestureState) stateThe 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 LeapGesture object falls.
LeapGestureState state = gesture.state;The possible gesture states are defined by the LeapGestureState enumeration:
LEAP_GESTURE_STATE_INVALID An invalid state.
LEAP_GESTURE_STATE_START The gesture is starting. Just enough has happened to recognize it.
LEAP_GESTURE_STATE_UPDATE The gesture is in progress. (Note: not all gestures have updates).
LEAP_GESTURE_STATE_STOP The gesture has completed or stopped.
- Return
- LeapGestureState A value from the LeapGestureState enumeration.
- Since 1.0
type- (LeapGestureType) typeThe gesture type.
LeapGestureType type = gesture.type;The supported types of gestures are defined by the LeapGestureType enumeration:
LEAP_GESTURE_TYPE_INVALID An invalid type.
LEAP_GESTURE_TYPE_SWIPE A straight line movement by the hand with fingers extended.
LEAP_GESTURE_TYPE_CIRCLE A circular movement by a finger.
LEAP_GESTURE_TYPE_SCREEN_TAP A forward tapping movement by a finger.
LEAP_GESTURE_TYPE_KEY_TAP A downward tapping movement by a finger.
- Return
- LeapGestureType A value from the LeapGestureType enumeration.
- Since 1.0
+ (LeapGesture *) invalidReturns an invalid LeapGesture object.
LeapGesture *wrongGesture = LeapGesture.invalid;
- Return
- The invalid LeapGesture instance.
- Since 1.0
LeapGestureType¶
LeapGestureType enum
The supported types of gestures.
- Since 1.0
Values:
- LEAP_GESTURE_TYPE_INVALID = = -1 -
An invalid type.
- LEAP_GESTURE_TYPE_SWIPE = = 1 -
A straight line movement by the hand with fingers extended.
- LEAP_GESTURE_TYPE_CIRCLE = = 4 -
A circular movement by a finger.
- LEAP_GESTURE_TYPE_SCREEN_TAP = = 5 -
A forward tapping movement by a finger.
- LEAP_GESTURE_TYPE_KEY_TAP = = 6 -
A downward tapping movement by a finger.
LeapGestureState¶
LeapGestureState enum
The possible gesture states.
Values:
- LEAP_GESTURE_STATE_INVALID = = -1 -
An invalid state.
- LEAP_GESTURE_STATE_START = = 1 -
The gesture is starting.
Just enough has happened to recognize it.
- LEAP_GESTURE_STATE_UPDATE = = 2 -
The gesture is in progress.
(Note: not all gestures have updates).
- LEAP_GESTURE_STATE_STOP = = 3 -
The gesture has completed or stopped.