Untitled

📰Getting Started | ⭐**Updates |** 📝 Guides | 🔢 API | ❓FAQ

Guides Overview

The Hand API preview provides hand tracking data for supported platforms.

const hands = require('hands-preview');

Data

Get the position and rotation of a specific joint on a specific hand. Use hands.None if the handedness doesn't matter.

var pos = hands.getPosition(hands.hands.Right, hands.joints.Palm);
var rot = hands.getRotation(hands.hands.Right, hands.joints.Palm);

var pos = hands.getPosition(hands.hands.None);

Events

Events are dispatched for hands entering and leaving detection. These can be useful for starting and stopping behaviors. Subscribe and unsubscribe to events with on and off.

hands.on('handdetected',function(handedness) {
    //
});

hands.off('handupdated', onHandUpdated);

Attaching Elements to Hands

The API below enables you to attach scene elements to common locations on the hand. Simply provide an element reference to the relevant method.

With this API, you will need to set a specific element for each hand, but it enables two-handed interactions and ensures that handedness detection will not get in the way of showing elements.

Set your hand element using the function below. When called, the element will snap to the position on your hand. For the first parameter, choose a name for this hand element which you can use to detach it later. The name must be uinique.

// gives a reference to the element this script is attached to
const self = this;

// available hands: "left", "right"
// available joints: "hover", "thumb", "index", "middle", "ring", "pinky", "palm", "wrist"
// - "hover" simply causes an element to hover above your palm like a ball of magic.

// Attaches an element by a specific name to a particular hand's joint.
hands.setHandElement("leftHandMagic", "left", "palm", self);

To remove an element from a hand, use the function below. Provide the name you used to set the hand element as above. The last parameter accepts a boolean that determines visibility of the element upon detach. You don’t need to specify the exact joint.

// available hands: "left", "right"
// the last parameter determines element visibility after detach

// Removes an element by a specific name from a particular hand.
hands.removeHandElement("rightHandMagic", "left", false);

Hand Up/Down

This is an alternative way to make things happen when you raise / lower your hands. While it’s less dynamic, this is helpful when you need full control over the left and right hand separately.

const hands = require('hands-preview');
const gestures = hands.gestures;

// --- Set Callbacks ---
// Left Hand
gestures.addLeftHandUpCallback(onLeftHandUp);
gestures.addLeftHandDownCallback(onLeftHandDown);

// Right Hand
gestures.addRightHandUpCallback(onRightHandUp)
gestures.addRightHandDownCallback(onRightHandDown)

// --- Callback Format ---
function onLeftHandUp()
{
  log.info("left hand was raised");
}

function onLeftHandDown()
{
  log.info("right hand was lowered");
}

function onRightHandUp()
{
  log.info("right hand was raised");
}

function onRightHandDown()
{
  log.info("right hand was lowered");
}

// --- Clearing Callbacks ---
// remove individual callbacks
hands.gestures.removeLeftHandUpCallback(callback);
hands.gestures.removeLeftHandDownCallback(callback);
hands.gestures.removeRightHandUpCallback(callback);
hands.gestures.removeRightHandDownCallback(callback);

// remove all callbacks
gestures.clearLeftHandUpCallbacks();
gestures.clearRightHandUpCallbacks();
gestures.clearLeftHandDownCallbacks();
gestures.clearRightHandDownCallbacks();

Hand Open Gesture

You can make use of a premade hand gesture in experience interactions. The hand gesture involves making a fist and then opening your hand.

If you access the gestures API within hands, you can access a new set of functions to invoke JavaScript callbacks when this gesture is made.

You can set separate callbacks for when the gesture is done with both the left and right hands. In addition, when the gesture is completed, you will get the position and rotation of the hand which are accessible as parameters in the callback.

const hands = require('hands-preview');
const gestures = hands.gestures;

// --- Config ---
gestures.handOpenSize = 0.09;

// --- Set Callbacks ---
// Left Hand
gestures.addLeftHandOpenCallback(onOpened);
gestures.addLeftHandClosedCallback(onClosed);

// Right Hand
gestures.addRightHandOpenCallback(onOpened)
gestures.addRightHandClosedCallback(onClosed)

// --- Callback Format ---
function onOpened(pos, rot)
{
  log.info("hand was opened at this position: " + pos);
	log.info("with this rotation: " + rot);
}

function onClosed(pos, rot)
{
  log.info("hand was closed at this position: " + pos);
	log.info("with this rotation: " + rot);
}

// --- Clearing Callbacks ---
// remove individual callbacks
hands.gestures.removeLeftHandOpenCallback(onOpened);
hands.gestures.removeLeftHandClosedCallback(onClosed);
hands.gestures.removeRightHandOpenCallback(onOpened);
hands.gestures.removeRightHandClosedCallback(onClosed);

// remove all callbacks
gestures.clearLeftHandOpenCallbacks();
gestures.clearRightHandOpenCallbacks();
gestures.clearLeftHandClosedCallbacks();
gestures.clearRightHandClosedCallbacks();

Query Hand States

At any time, you can get the current state of each hand, whether it’s up or down, or it’s open or closed. These lines return either true or false depending on the state.

// query for hand open closed / up down states
hands.gestures.isLeftHandOpen;
hands.gestures.isRightHandOpen;
hands.gestures.isLeftHandUp;
hands.gestures.isRightHandUp;

Module Events

"handdetected"

"handupdated"

"handlost"

Module Properties

All possible hands values [Read Only]

All tracked joints [Read Only]

Module Methods

on(event, callback)

on(event, hand, callback)

Subscribes to a hand event.

off(event, callback)

off(event, hand, callback)

Unsubscribes from a hand event.

getPosition(handedness, joint)

Gets the position of a specfic joint of a hand.

getRotation(handedness, joint)

Gets the rotation of a specific joint of a hand.

setHandElement(name, handedness, joint, element)

Attaches an element to a specified hand and joint.

removeHandElement(name, handedness, joint, visible)

Untitled