Frame

Attributes:

Functions:

class Frame()

The Frame class represents a set of hand and finger tracking data detected in a single frame.

The Leap detects hands, fingers and tools within the tracking area, reporting their positions, orientations and motions in frames at the Leap frame rate.

<p>Framerate: <span id="leapFPS">FPS</span></p>
<p>Number of hands: <span id="handCount">Hands</span></p>
<p>Number of pointables: <span id="pointableCount">Pointables</span></p>
<p>Number of tools: <span id="toolCount">Tools</span></p>
<p>Number of fingers: <span id="fingerCount">Fingers</span></p>
<p>Number of gestures: <span id="gestureCount">Gestures</span></p>

<script>
var controller = new Leap.Controller({
                         enableGestures: true,
                         frameEventName: 'animationFrame'
                         });

var fpsDisplay = document.getElementById('leapFPS');
var handCountDisplay = document.getElementById('handCount');
var pointableCountDisplay = document.getElementById('pointableCount');
var fingerCountDisplay = document.getElementById('fingerCount');
var toolCountDisplay = document.getElementById('toolCount');
var gestureCountDisplay = document.getElementById('gestureCount');

controller.on('frame', function(frame){
  fpsDisplay.innerText = frame.currentFrameRate;
  handCountDisplay.innerText = frame.hands.length;
  pointableCountDisplay.innerText = frame.pointables.length;
  fingerCountDisplay.innerText = frame.fingers.length;
  toolCountDisplay.innerText = frame.tools.length;
  gestureCountDisplay.innerText = frame.gestures.length;
  
  });
controller.connect();
</script>

Frame instances created with a constructor are invalid. Get valid Frame objects by calling the Controller.frame() function.

Frame.currentFrameRate
Type:float – frames per second

The instantaneous rate at which the Leap Motion controller is producing frames.

var fps = frame.currentFrameRate;

Note that this is not the rate at which your application is receiving or processing frames, which can vary depending on the type of animation or update loop you are using as well as whether the execution environment in which your application is running is overburdened or not.

Leap Motion 1.0.8 and LeapJS 0.3.0

Frame.fingers[]
Type:array of Pointable() objects representing fingers

The list of Finger objects detected in this frame, given in arbitrary order. The list can be empty if no fingers are detected.

for(var f = 0; f < frame.fingers.length; f++){
    var finger = frame.fingers[f];
}

Leap Motion 1.0 and LeapJS 0.3.0

Frame.gestures[]
Type:array of Gesture() objects

The list of Gesture objects detected in this frame, given in arbitrary order. The list can be empty if no gestures are detected.

for(var g = 0; g < frame.gestures.length; g++){
    var gesture = frame.gestures[g];
}

Circle and swipe gestures are updated every frame. Tap gestures only appear in the list for a single frame.

Leap Motion 1.0 and LeapJS 0.3.0

Frame.hands[]
Type:array of Hand() objects

The list of Hand objects detected in this frame, given in arbitrary order. The list can be empty if no hands are detected.

for(var h = 0; h < frame.hands.length; h++){
    var hand = frame.hands[h];
}

Leap Motion 1.0 and LeapJS 0.3.0

Frame.id
Type:string

A unique ID for this Frame. Consecutive frames processed by the Leap have consecutive increasing values.

var lastFrameProcessed = 0;
var frame = controller.frame();
if(lastFrameProcessed != frame.id){
    processFrame(frame);
    lastFrameProcessed = frame.id;
}

Leap Motion 1.0 and LeapJS 0.3.0

Frame.interactionBox
Type:InteractionBox()

The current InteractionBox() for the frame.

var interactionBox = frame.interactionBox;

Use the interaction box to normalize Leap Motion position coordinates from physical millimeters to dimensionless coordinates. These normalized, dimensionless coordinates range from 0 at one side of the interaction box to 1 at the opposite side.

The following example illustrates how to get take a point, normalize it, and then scale it so that the interaction area maps to the inner dimensions of an HTML window:

<p id="lmCoordinates">...</p>
<p id="normalizedCoordinates">...</p>
<p id="windowCoordinates">...</p>

<script>
var leapCoordinates = document.getElementById('lmCoordinates');
var normalizedCoordinates = document.getElementById('normalizedCoordinates');
var windowCoordinates = document.getElementById('windowCoordinates');

Leap.loop(function(frame){
    var interactionBox = frame.interactionBox;
    
    if(frame.pointables.length > 0){
        //Leap coordinates
        var tipPosition = frame.pointables[0].tipPosition;
        leapCoordinates.innerText = vectorToString(tipPosition,1);
        
        //Normalized coordinates
        var normalizedPosition = interactionBox.normalizePoint(tipPosition, true);
        normalizedCoordinates.innerText = vectorToString(normalizedPosition,4);

        //Pixel coordinates in current window
        var windowPosition = [normalizedPosition[0] * window.innerWidth, 
                              window.innerHeight - (normalizedPosition[1] * window.innerHeight), 
                              0];
        windowCoordinates.innerText = vectorToString(windowPosition, 0);        
    }
});

function vectorToString(vector, digits) {
  if (typeof digits === "undefined") {
    digits = 1;
  }
  return "(" + vector[0].toFixed(digits) + ", "
             + vector[1].toFixed(digits) + ", "
             + vector[2].toFixed(digits) + ")";
}
</script> 

When interaction box height is set to automatic in the Leap Motion control panel, the position and size of the interaction box can change as the user moves his or her hands within the Leap Motion field of view. Thus a new InteractionBox object is included in each frame.

Leap Motion 1.0 and LeapJS 0.3.0

Frame.pointables[]
Type:array of Pointable() objects

The list of Pointable objects (fingers and tools) detected in this frame, given in arbitrary order. The list can be empty if no fingers or tools are detected.

for(var p = 0; p < frame.pointables.length; p++){
    var pointable = frame.pointables[p];
}

Leap Motion 1.0 and LeapJS 0.3.0

Frame.timestamp
Type:number

The frame capture time in microseconds elapsed since an arbitrary point in time guaranteed to be before your application started.

var elapsed = frame.timestamp - controller.frame(1).timestamp;

Leap Motion 1.0 and LeapJS 0.3.0

Frame.tools[]
Type:array of Pointable() objects representing tools

The list of Tool objects detected in this frame, given in arbitrary order. The list can be empty if no tools are detected.

for(var t = 0; t < frame.tools.length; t++){
    var tool = frame.tools[t];
}

Leap Motion 1.0 and LeapJS 0.3.0

Frame.valid
Type:boolean

Reports whether this Frame instance is valid.

A valid Frame is one generated by the Controller object that contains tracking data for all detected entities. An invalid Frame contains no actual tracking data, but you can call its functions without risk of a undefined object exception. The invalid Frame mechanism makes it more convenient to track individual data across the frame history. For example, you can invoke:

var finger = controller.frame(n).finger(fingerID);

for an arbitrary Frame history value, “n”, without first checking whether frame(n) returned a null object. (You should still check that the returned Finger instance is valid.)

Leap Motion 1.0 and LeapJS 0.3.0

Frame.dump()

Returns a JSON-formatted string containing the hands, pointables and gestures in this frame.

console.log(frame.dump());
Returns:String – A JSON-formatted string.

Leap Motion 1.0 and LeapJS 0.3.0

Frame.finger(id)

The finger with the specified ID in this frame.

Use the Frame finger() function to retrieve the finger from this frame 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 Pointable object is returned.

var lastFrameProcessed = 0;
var frame = controller.frame();
if(lastFrameProcessed != frame.id){
    processFrame(frame);
    lastFrameProcessed = frame.id;
}

Note that ID values persist across frames, but only until tracking of a hand is lost. If tracking of a hand is lost and subsequently regained, the new Pointable objects representing the physical fingers of that hand may have different IDs than those representing the fingers in an earlier frame.

Arguments:
  • id (string) – The ID value of a finger from a previous frame.
Returns:

Pointable() – The finger with the matching ID if one exists in this frame; otherwise, an invalid Pointable object is returned.

Leap Motion 1.0 and LeapJS 0.3.0

Frame.hand(id)

The Hand object with the specified ID in this frame.

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

var hand = frame.hand(handID);

Note that ID values persist across frames, but only until tracking of a particular hand is lost. If tracking of a hand is lost and subsequently regained, the new Hand object representing that physical hand may have a different ID than that representing the physical hand in an earlier frame.

Arguments:
  • id (string) – The ID value of a Hand object from a previous frame.
Returns:

Hand() – The Hand object with the matching ID if one exists in this frame; otherwise, an invalid Hand object is returned.

Leap Motion 1.0 and LeapJS 0.3.0

Frame.pointable(id)

The Pointable object with the specified ID in this frame.

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

var pointable = frame.pointable(pointableID);

Note that ID values persist across frames, but only until tracking of a particular hand is lost. If tracking of a hand is lost and subsequently regained, the new Pointable objects representing the fingers of that hand may have different IDs than those representing the fingers in an earlier frame.

Arguments:
  • id (string) – The ID value of a Pointable object from a previous frame.
Returns:

Pointable() – The Pointable object with the matching ID if one exists in this frame; otherwise, an invalid Pointable object is returned.

Leap Motion 1.0 and LeapJS 0.3.0

Frame.rotationAngle(sinceFrame[, axis])

The angle of rotation around the rotation axis derived from the overall rotational motion between the current frame and the specified frame.

The returned angle is expressed in radians measured clockwise around the rotation axis (using the right-hand rule) between the start and end frames. The value is always between 0 and pi radians (0 and 180 degrees).

The Leap derives frame rotation from the relative change in position and orientation of all objects detected in the field of view.

var previousFrame = controller.frame(30);
var angle = frame.rotationAngle(previousFrame);

If either this frame or sinceFrame is an invalid Frame object, then the angle of rotation is zero.

Arguments:
  • sinceFrame (Frame) – The starting frame for computing the relative rotation.
  • axis (number[]) – The axis to measure rotation around expressed as a direction vector stored in a 3-element array of numbers.
Returns:

number – A positive value containing the heuristically determined rotational change between the current frame and that specified in the sinceFrame parameter.

Leap Motion 1.0 and LeapJS 0.3.0

Frame.rotationAxis(sinceFrame)

The axis of rotation derived from the overall rotational motion between the current frame and the specified frame.

The returned direction vector is normalized.

The Leap derives frame rotation from the relative change in position and orientation of all objects detected in the field of view.

var previousFrame = controller.frame(30);
var axisVector = frame.rotationAxis(previousFrame);

If either this frame or sinceFrame is an invalid Frame object, or if no rotation is detected between the two frames, a zero vector is returned.

Arguments:
  • sinceFrame (Frame) – The starting frame for computing the relative rotation.
Returns:

number[] – A normalized direction vector (as a 3-element array) representing the axis of the heuristically determined rotational change between the current frame and that specified in the sinceFrame parameter.

Leap Motion 1.0 and LeapJS 0.3.0

Frame.rotationMatrix(sinceFrame)

The transform matrix expressing the rotation derived from the overall rotational motion between the current frame and the specified frame.

The Leap derives frame rotation from the relative change in position and orientation of all objects detected in the field of view.

var previousFrame = controller.frame(30);
var matrix = frame.rotationMatrix(previousFrame);

If either this frame or sinceFrame is an invalid Frame object, then this method returns an identity matrix.

Arguments:
  • sinceFrame (Frame) – The starting frame for computing the relative rotation.
Returns:

number[] – A transformation matrix (as a 9-element array in row-major order) containing the heuristically determined rotational change between the current frame and that specified in the sinceFrame parameter.

Leap Motion 1.0 and LeapJS 0.3.0

Frame.scaleFactor(sinceFrame)

The scale factor derived from the overall motion between the current frame and the specified frame.

The scale factor is always positive. A value of 1.0 indicates no scaling took place. Values between 0.0 and 1.0 indicate contraction and values greater than 1.0 indicate expansion.

The Leap derives scaling from the relative inward or outward motion of all objects detected in the field of view (independent of translation and rotation).

var previousFrame = controller.frame(30);
var scale = frame.scaleFactor(previousFrame);

If either this frame or sinceFrame is an invalid Frame object, then this method returns 1.0.

Arguments:
  • sinceFrame (Frame) – The starting frame for computing the relative scaling.
Returns:

number – A positive value representing the heuristically determined scaling change ratio between the current frame and that specified in the sinceFrame parameter.

Leap Motion 1.0 and LeapJS 0.3.0

Frame.tool(id)

The tool with the specified ID in this frame.

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

var tool = frame.tool(toolID);

Note that ID values persist across frames, but only until tracking of a particular tool is lost. If tracking of a tool is lost and subsequently regained, the new Pointable object representing the tool may have a different ID than that representing the tool in an earlier frame.

Arguments:
  • id (String) – The ID value of a Tool object from a previous frame.
Returns:

Pointable() – The tool with the matching ID if one exists in this frame; otherwise, an invalid Pointable object is returned.

Leap Motion 1.0 and LeapJS 0.3.0

Frame.toString()

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

console.log(frame.toString());
Returns:String – A brief description of this frame.

Leap Motion 1.0 and LeapJS 0.3.0

Frame.translation(sinceFrame)

The change of position derived from the overall linear motion between the current frame and the specified frame.

The returned translation vector provides the magnitude and direction of the movement in millimeters.

The Leap derives frame translation from the linear motion of all objects detected in the field of view.

var previousFrame = controller.frame(30);
var translationVector = frame.translation(previousFrame);

If either this frame or sinceFrame is an invalid Frame object, then this method returns a zero vector.

Arguments:
  • sinceFrame (Frame) – The starting frame for computing the relative translation.
Returns:

number[] – A vector, expressed as a 3-element array, representing the heuristically determined change in position of all objects between the current frame and that specified in the sinceFrame parameter.

Leap Motion 1.0 and LeapJS 0.3.0

Invalid
Type:Frame()

An invalid Frame object.

You can use this invalid Frame in comparisons testing whether a given Frame instance is valid or invalid. (You can also check the js:attr:valid property.)

Leap Motion 1.0 and LeapJS 0.3.0