HandΒΆ

The Hand class reports the physical characteristics of a detected hand. More...

Inherits Interface.

Public Member Functions

Arm arm () const
 The arm to which this hand is attached. More...
 
Matrix basis () const
 The orientation of the hand as a basis matrix. More...
 
float confidence () const
 How confident we are with a given hand pose. More...
 
Vector direction () const
 The direction from the palm position toward the fingers. More...
 
Finger finger (int32_t id) const
 The Finger object with the specified ID attached to this hand. More...
 
FingerList fingers () const
 The list of Finger objects detected in this frame that are attached to this hand, given in order from thumb to pinky. More...
 
Frame frame () const
 The Frame associated with this Hand. More...
 
float grabAngle () const
 The angle between the fingers and the hand of a grab hand pose. More...
 
float grabStrength () const
 Deprecated. More...
 
 Hand (HandImplementation *)
 
 Hand ()
 Constructs a Hand object. More...
 
int32_t id () const
 A unique ID assigned to this Hand object, whose value remains the same across consecutive frames while the tracked hand remains visible. More...
 
bool isLeft () const
 Identifies whether this Hand is a left hand. More...
 
bool isRight () const
 Identifies whether this Hand is a right hand. More...
 
bool isValid () const
 Reports whether this is a valid Hand object. More...
 
bool operator!= (const Hand &) const
 Compare Hand object inequality. More...
 
bool operator== (const Hand &) const
 Compare Hand object equality. More...
 
Vector palmNormal () const
 The normal vector to the palm. More...
 
Vector palmPosition () const
 The center position of the palm in millimeters from the Leap Motion Controller origin. More...
 
Vector palmVelocity () const
 The rate of change of the palm position in millimeters/second. More...
 
float palmWidth () const
 The estimated width of the palm when the hand is in a flat position. More...
 
float pinchDistance () const
 The distance between the thumb and index finger of a pinch hand pose. More...
 
float pinchStrength () const
 Deprecated. More...
 
Pointable pointable (int32_t id) const
 The Pointable object with the specified ID associated with this hand. More...
 
PointableList pointables () const
 The list of Pointable objects detected in this frame that are associated with this hand, given in arbitrary order. More...
 
float rotationAngle (const Frame &sinceFrame) const
 The angle of rotation around the rotation axis derived from the change in orientation of this hand, and any associated fingers, 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 change in orientation of this hand, and any associated fingers, between the current frame and the specified frame. More...
 
Vector rotationAxis (const Frame &sinceFrame) const
 The axis of rotation derived from the change in orientation of this hand, and any associated fingers, between the current frame and the specified frame. More...
 
Matrix rotationMatrix (const Frame &sinceFrame) const
 The transform matrix expressing the rotation derived from the change in orientation of this hand, and any associated fingers, between the current frame and the specified frame. More...
 
float rotationProbability (const Frame &sinceFrame) const
 The estimated probability that the hand 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 this hand's motion between the current frame and the specified frame. More...
 
float scaleProbability (const Frame &sinceFrame) const
 The estimated probability that the hand motion between the current frame and the specified frame is intended to be a scaling motion. More...
 
Vector sphereCenter () const
 The center of a sphere fit to the curvature of this hand. More...
 
float sphereRadius () const
 The radius of a sphere fit to the curvature of this hand. More...
 
Vector stabilizedPalmPosition () const
 The stabilized palm position of this Hand. More...
 
float timeVisible () const
 The duration of time this Hand has been visible to the Leap Motion Controller. More...
 
std::string toString () const
 A string containing a brief, human readable description of the Hand object. More...
 
Vector translation (const Frame &sinceFrame) const
 The change of position of this hand between the current frame and the specified frame. More...
 
float translationProbability (const Frame &sinceFrame) const
 The estimated probability that the hand motion between the current frame and the specified frame is intended to be a translating motion. More...
 
Vector wristPosition () const
 The position of the wrist of this hand. More...
 

Static Public Member Functions

static const Handinvalid ()
 Returns an invalid Hand object. More...
 

Friends

std::ostream & operator<< (std::ostream &, const Hand &)
 Writes a brief, human readable description of the Hand object to an output stream. More...
 

Detailed Description

The Hand class reports the physical characteristics of a detected hand.

Hand tracking data includes a palm position and velocity; vectors for the palm normal and direction to the fingers; properties of a sphere fit to the hand; and lists of the attached fingers.

Get Hand objects from a Frame object:

Leap::HandList hands = frame.hands();
Leap::Hand firstHand = hands[0];

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

Since
1.0

Constructor & Destructor Documentation

Hand ( HandImplementation *  )
Hand ( )

Constructs a Hand object.

An uninitialized hand is considered invalid. Get valid Hand objects from a Frame object.

Leap::Hand leftmostHand = frame.hands().leftmost();
Since
1.0

Member Function Documentation

Arm arm ( ) const

The arm to which this hand is attached.

If the arm is not completely in view, Arm attributes are estimated based on the attributes of entities that are in view combined with typical human anatomy.

Leap::Hand hand = frame.hands().frontmost();
Leap::Arm arm = hand.arm();
Returns
The Arm object for this hand.
Since
2.0.3
Matrix basis ( ) const

The orientation of the hand as a basis matrix.

The basis is defined as follows:

xAxis Positive in the direction of the pinky

yAxis Positive above the hand

zAxis Positive in the direction of the wrist

Note: Since the left hand is a mirror of the right hand, the basis matrix will be left-handed for left hands.

Leap::Matrix basis = hand.basis();
Leap::Vector xBasis = basis.xBasis;
Leap::Vector yBasis = basis.yBasis;
Leap::Vector zBasis = basis.zBasis;
Returns
The basis of the hand as a matrix.
Since
2.0
float confidence ( ) const

How confident we are with a given hand pose.

The confidence level ranges between 0.0 and 1.0 inclusive.

float confidence = hand.confidence();
Since
2.0
Vector direction ( ) const

The direction from the palm position toward the fingers.

The direction is expressed as a unit vector pointing in the same direction as the directed line from the palm position to the fingers.

You can use the palm direction vector to compute the pitch and yaw angles of the palm with respect to the horizontal plane:

float pitch = hand.direction().pitch();
float yaw = hand.direction().yaw();
float roll = hand.palmNormal().roll();
Returns
The Vector pointing from the palm position toward the fingers.
Since
1.0
Finger finger ( int32_t  id) const

The Finger object with the specified ID attached to this hand.

Use the Hand::finger() function to retrieve a Finger object attached to this hand 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.

Leap::Finger fingerOnHandByID = hand.finger(fingerID);

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 finger may have a different ID than that representing the finger in an earlier frame.

Parameters
idThe ID value of a Finger object from a previous frame.
Returns
The Finger object with the matching ID if one exists for this hand in this frame; otherwise, an invalid Finger object is returned.
Since
1.0
FingerList fingers ( ) const

The list of Finger objects detected in this frame that are attached to this hand, given in order from thumb to pinky.

The list cannot be empty.

Use PointableList::extended() to remove non-extended fingers from the list.

// hand is a Leap::Hand object
Leap::PointableList pointables = hand.pointables(); // Both fingers and tools
Leap::FingerList fingers = hand.fingers();
Returns
The FingerList containing all Finger objects attached to this hand.
Since
1.0
Frame frame ( ) const

The Frame associated with this Hand.

Leap::Frame frameForHand = hand.frame();
Returns
The associated Frame object, if available; otherwise, an invalid Frame object is returned.
Since
1.0
float grabAngle ( ) const

The angle between the fingers and the hand of a grab hand pose.

The angle is computed by looking at the angle between the direction of the 4 fingers and the direction of the hand. Thumb is not considered when computing the angle. The angle is 0 radian for an open hand, and reaches pi radians when the pose is a tight fist.

Returns
The angle of a grab hand pose between 0 and pi radians (0 and 180 degrees).
Since
3.0
float grabStrength ( ) const

Deprecated.

Use grabAngle() instead.

Since
2.0
Deprecated:
3.0
int32_t id ( ) const

A unique ID assigned to this Hand object, whose value remains the same across consecutive frames while the tracked hand remains visible.

If tracking is lost (for example, when a hand is occluded by another hand or when it is withdrawn from or reaches the edge of the Leap Motion Controller field of view), the Leap Motion software may assign a new ID when it detects the hand in a future frame.

Use the ID value with the Frame::hand() function to find this Hand object in future frames:

Leap::Hand knownHand = frame.hand(handID);
Returns
The ID of this hand.
Since
1.0
static const Hand& invalid ( )
static

Returns an invalid Hand object.

if (hand != Leap::Hand::invalid()) {
//Process hand data...
}

You can use the instance returned by this function in comparisons testing whether a given Hand instance is valid or invalid. (You can also use the Hand::isValid() function.)

Returns
The invalid Hand instance.
Since
1.0
bool isLeft ( ) const

Identifies whether this Hand is a left hand.

std::string handName = hand.isLeft() ? "Left hand" : "Right hand";
Returns
True if the hand is identified as a left hand.
Since
2.0
bool isRight ( ) const

Identifies whether this Hand is a right hand.

if(hand.isRight()){
// .. Do right handed stuff
}
Returns
True if the hand is identified as a right hand.
Since
2.0
bool isValid ( ) const

Reports whether this is a valid Hand object.

if (hand.isValid()) {
//Process hand data...
}
Returns
True, if this Hand object contains valid tracking data.
Since
1.0
bool operator!= ( const Hand ) const

Compare Hand object inequality.

thisHand != thatHand;

Two Hand objects are equal if and only if both Hand objects represent the exact same physical hand in the same frame and both Hand objects are valid.

Since
1.0
bool operator== ( const Hand ) const

Compare Hand object equality.

thisHand == thatHand;

Two Hand objects are equal if and only if both Hand objects represent the exact same physical hand in the same frame and both Hand objects are valid.

Since
1.0
Vector palmNormal ( ) const

The normal vector to the palm.

If your hand is flat, this vector will point downward, or "out" of the front surface of your palm.

Leap_Palm_Vectors.png

The direction is expressed as a unit vector pointing in the same direction as the palm normal (that is, a vector orthogonal to the palm).

You can use the palm normal vector to compute the roll angle of the palm with respect to the horizontal plane:

float pitch = hand.direction().pitch();
float yaw = hand.direction().yaw();
float roll = hand.palmNormal().roll();
Returns
The Vector normal to the plane formed by the palm.
Since
1.0
Vector palmPosition ( ) const

The center position of the palm in millimeters from the Leap Motion Controller origin.

Leap::Vector handCenter = hand.palmPosition();
Returns
The Vector representing the coordinates of the palm position.
Since
1.0
Vector palmVelocity ( ) const

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

Leap::Vector handSpeed = hand.palmVelocity();
Returns
The Vector representing the coordinates of the palm velocity.
Since
1.0
float palmWidth ( ) const

The estimated width of the palm when the hand is in a flat position.

float handWidth = hand.palmWidth();
Returns
The width of the palm in millimeters
Since
2.0
float pinchDistance ( ) const

The distance between the thumb and index finger of a pinch hand pose.

The distance is computed by looking at the shortest distance between the last 2 phalanges of the thumb and those of the index finger. This pinch measurement only takes thumb and index finger into account.

Returns
The distance between the thumb and index finger of a pinch hand pose in millimeters.
Since
3.0
float pinchStrength ( ) const

Deprecated.

Use pinchDistance() instead.

Since
2.0
Deprecated:
3.0
Pointable pointable ( int32_t  id) const

The Pointable object with the specified ID associated with this hand.

Use the Hand::pointable() function to retrieve a Pointable object associated with this hand using an ID value obtained from a previous frame. This function always returns a Pointable object, but if no finger with the specified ID is present, an invalid Pointable object is returned.

Leap::Pointable knownPointable = hand.pointable(pointableID);

Note that the ID values assigned to fingers are based on the hand ID. Hand IDs persist across frames, but only until tracking of that hand is lost. If tracking of the hand is lost and subsequently regained, the new Hand object and its child Finger objects will have a different ID than in an earlier frame.

Parameters
idThe ID value of a Pointable object from a previous frame.
Returns
The Pointable object with the matching ID if one exists for this hand in this frame; otherwise, an invalid Pointable object is returned.
Since
1.0
PointableList pointables ( ) const

The list of Pointable objects detected in this frame that are associated with this hand, given in arbitrary order.

The list will always contain 5 fingers.

Use PointableList::extended() to remove non-extended fingers from the list.

// hand is a Leap::Hand object
Leap::PointableList pointables = hand.pointables(); // Both fingers and tools
Leap::FingerList fingers = hand.fingers();
Returns
The PointableList containing all Pointable objects associated with this hand.
Since
1.0
float rotationAngle ( const Frame sinceFrame) const

The angle of rotation around the rotation axis derived from the change in orientation of this hand, and any associated fingers, between the current frame and the specified frame.

float rotationOfHand = hand.rotationAngle(startFrame);
Parameters
sinceFrameThe starting frame for computing the relative rotation.
Returns
A positive value representing the heuristically determined rotational change of the hand between the current frame and that specified in the sinceFrame parameter.
Deprecated:
3.0
float rotationAngle ( const Frame sinceFrame,
const Vector axis 
) const

The angle of rotation around the specified axis derived from the change in orientation of this hand, and any associated fingers, between the current frame and the specified frame.

float rotationAroundYAxis = hand.rotationAngle(startFrame, Leap::Vector::yAxis());
Parameters
sinceFrameThe starting frame for computing the relative rotation.
axisThe axis to measure rotation around.
Returns
A value representing the heuristically determined rotational change of the hand between the current frame and that specified in the sinceFrame parameter around the specified axis.
Deprecated:
3.0
Vector rotationAxis ( const Frame sinceFrame) const

The axis of rotation derived from the change in orientation of this hand, and any associated fingers, between the current frame and the specified frame.

Leap::Vector axisOfHandRotation = hand.rotationAxis(startFrame);
Parameters
sinceFrameThe starting frame for computing the relative rotation.
Returns
A normalized direction Vector representing the heuristically determined axis of rotational change of the hand between the current frame and that specified in the sinceFrame parameter.
Deprecated:
3.0
Matrix rotationMatrix ( const Frame sinceFrame) const

The transform matrix expressing the rotation derived from the change in orientation of this hand, and any associated fingers, between the current frame and the specified frame.

Leap::Matrix handRotationTransform = hand.rotationMatrix(startFrame);
Parameters
sinceFrameThe starting frame for computing the relative rotation.
Returns
A transformation Matrix representing the heuristically determined rotational change of the hand between the current frame and that specified in the sinceFrame parameter.
Deprecated:
3.0
float rotationProbability ( const Frame sinceFrame) const

The estimated probability that the hand motion between the current frame and the specified frame is intended to be a rotating motion.

float rotationIntentFactor = hand.rotationProbability(startFrame);
Parameters
sinceFrameThe starting frame for computing the relative rotation.
Returns
A value between 0 and 1 representing the estimated probability that the hand motion between the current frame and the specified frame is intended to be a rotating motion.
Deprecated:
3.0
float scaleFactor ( const Frame sinceFrame) const

The scale factor derived from this hand's motion between the current frame and the specified frame.

float handScaleMotion = hand.scaleFactor(startFrame);
Parameters
sinceFrameThe starting frame for computing the relative scaling.
Returns
A positive value representing the heuristically determined scaling change ratio of the hand between the current frame and that specified in the sinceFrame parameter.
Deprecated:
3.0
float scaleProbability ( const Frame sinceFrame) const

The estimated probability that the hand motion between the current frame and the specified frame is intended to be a scaling motion.

float scaleIntentFactor = hand.scaleProbability(startFrame);
Parameters
sinceFrameThe starting frame for computing the relative scaling.
Returns
A value between 0 and 1 representing the estimated probability that the hand motion between the current frame and the specified frame is intended to be a scaling motion.
Deprecated:
3.0
Vector sphereCenter ( ) const

The center of a sphere fit to the curvature of this hand.

This sphere is placed roughly as if the hand were holding a ball.

Leap_Hand_Ball.png
Returns
The Vector representing the center position of the sphere.
Since
1.0
float sphereRadius ( ) const

The radius of a sphere fit to the curvature of this hand.

This sphere is placed roughly as if the hand were holding a ball. Thus the size of the sphere decreases as the fingers are curled into a fist.

float sphereDiameter = 2 * hand.sphereRadius();
Returns
The radius of the sphere in millimeters.
Since
1.0
Vector stabilizedPalmPosition ( ) const

The stabilized palm position of this Hand.

Smoothing and stabilization is performed in order to make this value more suitable for interaction with 2D content. The stabilized position lags behind the palm position by a variable amount, depending primarily on the speed of movement.

Leap::Vector filteredHandPosition = hand.stabilizedPalmPosition();
Returns
A modified palm position of this Hand object with some additional smoothing and stabilization applied.
Since
1.0
float timeVisible ( ) const

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

float lifetimeOfThisHandObject = hand.timeVisible();
Returns
The duration (in seconds) that this Hand has been tracked.
Since
1.0
std::string toString ( ) const
inline

A string containing a brief, human readable description of the Hand object.

Returns
A description of the Hand as a string.
Since
1.0
Vector translation ( const Frame sinceFrame) const

The change of position of this hand between the current frame and the specified frame.

Leap::Vector linearHandMovement = hand.translation(startFrame);
Parameters
sinceFrameThe starting frame for computing the translation.
Returns
A Vector representing the heuristically determined change in hand position between the current frame and that specified in the sinceFrame parameter.
Deprecated:
3.0
float translationProbability ( const Frame sinceFrame) const

The estimated probability that the hand motion between the current frame and the specified frame is intended to be a translating motion.

float translationIntentFactor = hand.translationProbability(startFrame);
Parameters
sinceFrameThe starting frame for computing the translation.
Returns
A value between 0 and 1 representing the estimated probability that the hand motion between the current frame and the specified frame is intended to be a translating motion.
Deprecated:
3.0
Vector wristPosition ( ) const

The position of the wrist of this hand.

Returns
A vector containing the coordinates of the wrist position in millimeters.
Since
2.0.3

Friends And Related Function Documentation

std::ostream& operator<< ( std::ostream &  ,
const Hand  
)
friend

Writes a brief, human readable description of the Hand object to an output stream.

std::cout << hand << std::endl;
Since
1.0