Leap_JSON.rst

Leap Motion WebSocket server

The Leap Motion service/daemon provides a WebSocket server listening to port 6347 on the localhost domain. The server provides tracking data in the form of JSON formated messages.

Connecting to the WebSocket server

// Support both the WebSocket and MozWebSocket objects
if ((typeof(WebSocket) == 'undefined') &&
    (typeof(MozWebSocket) != 'undefined')) {
  WebSocket = MozWebSocket;
}

// Create the socket with event handlers
function init() {
  // Create and open the socket
  ws = new WebSocket("ws://localhost:6437/");

  // On successful connection
  ws.onopen = function(event) {
    var enableMessage = JSON.stringify({enableGestures: true});
    ws.send(enableMessage); // Enable gestures
  };

  // On message received
  ws.onmessage = function(event) {
      var trackingdata = JSON.parse(event.data);
      // ...do something with the data
    }
  };

  // On socket close
  ws.onclose = function(event) {
    ws = null;
  }

  // On socket error
  ws.onerror = function(event) {
    alert("Received error");
  };
}

Leap Motion JSON format

Each frame of data from the WebSocket server contains JSON defining a frame. The attributes of a frame in the JSON message are similar, but not identical to those of a Frame object obtained through the native library. They include:

"id": float
"r": array of floats (Matrix)
"s": float
"t":  array of floats (Vector)
"timestamp": integer

"hands": array of Hand objects
   "direction": array of floats (Vector)
   "id": integer
   "palmNormal": array of floats (Vector)
   "palmPosition": array of floats (Vector)
   "palmVelocity": array of floats (Vector)
   "r": array of floats (Matrix)
   "s": float
   "sphereCenter": array of floats (Vector)
   "sphereRadius": float
   "t": array of floats (Vector)

"interactionBox": object
   "center": array of floats (Vector)
   "size": array of floats  (Vector)

"pointables": array of Pointable objects
   "direction": array of floats (Vector)
   "handId": integer
   "id": integer
   "length": float
   "stabilizedTipPosition": array of floats (Vector)
   "tipPosition":  array of floats (Vector)
   "tipVelocity":  array of floats (Vector)
   "tool": boolean (true or false)
   "touchDistance": float
   "touchZone": string - one of "none", "hovering", "touching"

"gestures": array of Gesture objects
    "center": array of floats (Vector)
    "duration": integer microseconds
    "handIds": array of integers
    "id": integer
    "normal": array of floats
    "pointableIds": array
    "progress": float,
    "radius": float,
    "state": string - one of "start", "update", "stop"
    "type": string - one of "circle", "swipe", "keyTap", "screenTap"

Protocol versions

The current version of the protocol is v2.json. The format is the same as the previous version (v1.json), but the WebSocket server now accepts a heartbeat message to suppress plug-ins.

Motion factors

The motion factors, r, s, t, attached to Hand and Frame objects are snapshots of the motion occuring across frames. These factors must be combined with those of a previous frame to derive the relative motion.

• r -- a 3x3 rotation matrix
• s -- a scale factor
• t -- a 3-element translation vector

Rotation factor

The matrix expressing the relative rotation between two frames can be calculated by multiplying the r matrix from the current frame by the inverse of the r matrix of the starting frame.

\mathbf{rotation} = \mathbf{r_{current frame}} * \mathbf{r_{since frame}^{-1}}

Scale factor

The relative scale factor between two frames can be calculated by subtracting the s value from the starting frame from the current s value and taking the natural logarithm of the result.

scalefactor = s_{current frame} - s_{sinceframe}

Translation factor

The relative translation factor between two frames can be calculated by subtracting the t vector from the starting frame from the current t factor.

\mathbf{\overrightarrow{translation}} = \mathbf{\vec{t}}_{current frame} - \mathbf{\vec{t}}_{since frame}

Heartbeat messages

A user interacting with your Leap-enabled application can cause unintended interactions with background Leap-enabled applications, such as the Leap Motion OS Interaction touch emulation feature.