LeapGesture

class 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];

Since 1.0

Public Functions


- (BOOL) equals:(const LeapGesture *) other

Compare 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

Property


- (int64_t) duration
duration

The 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


- (float) durationSeconds
durationSeconds

The elapsed duration in seconds.

float seconds = gesture.duration;

See
duration
Return
float the elapsed duration in seconds.
Since 1.0


- (LeapFrame *) frame
frame

The LeapFrame containing this LeapGesture instance.

LeapFrame *owningFrame = gesture.frame;

Return
The parent LeapFrame object.
Since 1.0


- (NSArray *) hands
hands

The 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


- (int32_t) id
id

The 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


- (BOOL) isValid
isValid

Reports 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


- (NSArray *) pointables
pointables

The 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


- (LeapGestureState) 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 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


- (LeapGestureType) type
type

The 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

Public Static Functions


+ (LeapGesture *) invalid

Returns 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.