Skip to content

Frontend Scripting API

WEBKNOSSOS exposes a JavaScript API in the browser for user scripts, e.g. to add custom keyboard shortcuts or to automate repetitive annotation steps. Scripts can be run from the annotation viewer or attached to tasks, see Scripts.

The API is available as window.webknossos once an annotation or dataset is opened. Request the API with apiReady, which resolves as soon as WEBKNOSSOS is fully initialized. This example comments on the active node, so it requires an opened skeleton annotation:

window.webknossos.apiReady(3).then((api) => {
  const nodeId = api.tracing.getActiveNodeId();
  if (nodeId != null) {
    api.tracing.setCommentForNode("my comment", nodeId);
  }
});

The resolved api object is split into the following namespaces:

Namespace Description
api.tracing Skeleton and volume annotation: nodes, trees, segments, groups, camera and tools.
api.data Layers, mappings, meshes, bounding boxes, data and screenshots.
api.user User configuration.
api.utils Utilities such as keyboard shortcuts, toasts and event listeners.

window.webknossos

Entry point of the WEBKNOSSOS frontend API, available as window.webknossos. Use ApiLoader.apiReady to obtain the API object.

Methods

apiReady 

apiReady(version: number = latestVersion): Promise<ApiInterface>

Waits for the WEBKNOSSOS API to become ready and returns the API object.

Parameters:

  • version: The requested API version. Only the latest version (3) is supported.

Example:

window.webknossos.apiReady(3).then((api) => {
  // Your cool user script / wK plugin
  const nodes = api.tracing.getAllNodes();
  ...
});