LeapPointable

class LeapPointable

The LeapPointable class reports the physical characteristics of a detected finger or tool.

Both fingers and tools are classified as LeapPointable objects. Use the [LeapPointable isFinger] function to determine whether a pointable object represents a finger. Use the [LeapPointable isTool] function to determine whether a pointable object represents a tool. The Leap classifies a detected entity as a tool when it is thinner, straighter, and longer than a typical finger.

To provide touch emulation, the Leap Motion software associates a floating touch plane that adapts to the user’s finger movement and hand posture. The Leap Motion interprets purposeful movements toward this plane as potential touch points. The logic used by the LeapPointable class is the same as that used by the Leap Motion software for OS-level touch and mouse input emulation. The LeapPointable class reports touch state with the touchZone and touchDistance properties.

Note that LeapPointable objects can be invalid, which means that they do not contain valid tracking data and do not correspond to a physical entity. Invalid LeapPointable objects can be the result of asking for a pointable object using an ID from an earlier frame when no pointable objects with that ID exist in the current frame. A pointable object created from the LeapPointable constructor is also invalid. Test for validity with the [LeapPointable isValid] function.

Since 1.0

Property


- (LeapVector *) direction
direction

The direction in which this finger or tool is pointing.

LeapVector *direction = pointable.direction;

The direction is expressed as a unit vector pointing in the same direction as the tip.

api/../../../images/Leap_Finger_Model.png

Return
The LeapVector pointing in the same direction as the tip of this LeapPointable object.
Since 1.0


- (LeapFrame *) frame
frame

The LeapFrame associated with this LeapPointable object.

LeapFrame *owningFrame = pointable.frame;

This property is a weak reference to the LeapFrame object so it is only valid during the lifetime of the LeapFrame object while the LeapFrame object is in the history buffer or while your application maintains its own reference.

Return
The associated LeapFrame object, if available; otherwise, an invalid LeapFrame object is returned.
Since 1.0


- (LeapHand *) hand
hand

The LeapHand associated with a finger.

LeapHand *owningHand = pointable.hand;

This property is a weak reference to the LeapHand object so it is only valid during the lifetime of that LeapHand object in other words, while the parent LeapFrame object is valid or while your application maintains its own reference.

As of version 2, tools are not associated with hands, so this property always returns an invalid LeapHand object for tools.

Return
The associated LeapHand object, if available; otherwise, an invalid LeapHand object is returned.
Since 1.0


- (int32_t) id
id

A unique ID assigned to this LeapPointable object, whose value remains the same across consecutive frames while the tracked finger or tool remains visible.

If tracking is lost, the Leap may assign a new ID when it detects the entity in a future frame.

int id = pointable.id;

Use the ID value with the [LeapFrame pointable:] function to find this LeapPointable object in future frames.

int idOfInterest = 201;
LeapPointable *pointableOfInterest = [frame pointable:idOfInterest];

Return
The ID assigned to this LeapPointable object.
Since 1.0


- (BOOL) isExtended
isExtended

Whether or not this Pointable is in an extended posture.

int extendedCount = 0;
for (LeapPointable *pointable in frame.pointables) {
  if (pointable.isExtended) {
    extendedCount++;
  }
}

A finger is considered extended if it is extended straight from the hand as if pointing. A finger is not extended when it is bent down and curled towards the palm. Tools are always extended.

Return
True, if the pointable is extended.
Since 2.0


- (BOOL) isFinger
isFinger

Whether or not the LeapPointable is classified a finger.

if (pointable.isFinger) {
  LeapFinger *finger = (LeapFinger *)pointable;
}

Return
YES, if this LeapPointable is classified as a LeapFinger.
Since 1.0


- (BOOL) isTool
isTool

Whether or not the LeapPointable is classified to be a tool.

if (pointable.isTool) {
  LeapTool *tool = (LeapTool *)pointable;
}

Return
YES, if this LeapPointable is classified as a LeapTool.
Since 1.0


- (BOOL) isValid
isValid

Reports whether this is a valid LeapPointable object.

if(pointable.isValid){
    //Use the data
}

Return
YES, if this LeapPointable object contains valid tracking data.
Since 1.0


- (float) length
length

The estimated length of the finger or tool in millimeters.

The reported length is the visible length of the finger or tool. If the length isn’t known, then a value of 0 is returned.

float length = pointable.length;

Return
The estimated length of this LeapPointable object.
Since 1.0


- (LeapVector *) stabilizedTipPosition
stabilizedTipPosition

The stabilized tip position of this LeapPointable.

LeapVector *stabilizedPosition = pointable.stabilizedTipPosition;

Smoothing and stabilization is performed in order to make this value more suitable for interaction with 2D content.

Since 1.0


- (float) timeVisible
timeVisible

The duration of time this Pointable has been visible to the Leap Motion Controller.

float lifetime = pointable.timeVisible;

Return
The duration (in seconds) that this Pointable has been tracked.
Since 1.0


- (LeapVector *) tipPosition
tipPosition

The tip position in millimeters from the Leap origin.

LeapVector *position = pointable.tipPosition;

Return
The LeapVector containing the coordinates of the tip position.
Since 1.0


- (LeapVector *) tipVelocity
tipVelocity

The rate of change of the tip position in millimeters/second.

LeapVector *speed = pointable.tipVelocity;

Return
The LeapVector containing the coordinates of the tip velocity.
Since 1.0


- (float) touchDistance
touchDistance

A value proportional to the distance between this LeapPointable object and the adaptive touch plane.

float touchDistance = pointable.touchDistance;

The touch distance is a value in the range [-1, 1]. The value 1.0 indicates the LeapPointable is at the far edge of the hovering zone. The value 0 indicates the LeapPointable is just entering the touching zone. A value of -1.0 indicates the LeapPointable is firmly within the touching zone. Values in between are proportional to the distance from the plane. Thus, the touchDistance of 0.5 indicates that the LeapPointable is halfway into the hovering zone.

You can use the touchDistance value to modulate visual feedback given to the user as their fingers close in on a touch target, such as a button.

Since 1.0


- (LeapPointableZone) touchZone
touchZone

The current touch zone of this LeapPointable object.

LeapPointableZone zone = pointable.touchZone;

The Leap Motion software computes the touch zone based on a floating touch plane that adapts to the user’s finger movement and hand posture. The Leap Motion interprets purposeful movements toward this plane as potential touch points. When a LeapPointable moves close to the adaptive touch plane, it enters the “hovering” zone. When a LeapPointable reaches or passes through the plane, it enters the “touching” zone.

The possible states are present in the Zone enum:

LEAP_POINTABLE_ZONE_NONE The LeapPointable is outside the hovering zone.

LEAP_POINTABLE_ZONE_HOVERING The LeapPointable is close to, but not touching the touch plane.

LEAP_POINTABLE_ZONE_TOUCHING The LeapPointable has penetrated the touch plane.

api/../../../images/Leap_Touch_Plane.png

The touchDistance property provides a normalized indication of the distance to the touch plane when the LeapPointable is in the hovering or touching zones.

Since 1.0


- (float) width
width

The estimated width of the finger or tool in millimeters.

The reported width is the average width of the visible portion of the finger or tool. If the width isn’t known, then a value of 0 is returned.

float width = pointable.width;

Return
The estimated width of this LeapPointable object.
Since 1.0

Public Static Functions


+ (LeapPointable *) invalid

Returns an invalid LeapPointable object.

LeapPointable *pointer = LeapPointable.invalid;

Return
The invalid LeapPointable instance.
Since 1.0

LeapPointableZone

LeapPointableZone enum

Defines the values for reporting the state of a Pointable object in relation to an adaptive touch plane.

Since 1.0

Values:

  • LEAP_POINTABLE_ZONE_NONE = = 0 -

    The Pointable object is too far from the plane to be considered hovering or touching.

  • LEAP_POINTABLE_ZONE_HOVERING = = 1 -

    The Pointable object is close to, but not touching the plane.

  • LEAP_POINTABLE_ZONE_TOUCHING = = 2 -

    The Pointable has penetrated the plane.