Returns the id of the current active node.

Returns the id of the current active tree.

Returns the id of the current active group.

Deprecated! Use getActiveTreeGroupId instead.

Sets the active node given a node id.

Returns all nodes belonging to a tracing.

Returns all trees belonging to a tracing.

Deletes the node with nodeId in the tree with treeId

Centers the active node.

Creates a new and empty tree. Returns the id of that tree.

Deletes the tree with the given treeId.

Creates a new node in the current tree. If the active tree already contains nodes, the new node will be connected to the currently active one via an edge.

When the camera is rotated and centering animation is enabled, using unrounded (floating-point) coordinates [x, y, z] helps maintain a consistent viewing slice. This prevents the viewports from jumping between slices due to the animation.

In scenarios without rotation or centering animation, rounded integer coordinates are sufficient.

Completely resets the skeleton tracing.

Sets the comment for a node. Passing an empty string deletes the comment.

const activeNodeId = api.tracing.getActiveNodeId();
api.tracing.setCommentForNode("This is a branch point", activeNodeId);

Deletes the comment of a node.

const activeNodeId = api.tracing.getActiveNodeId();
api.tracing.deleteCommentForNode(activeNodeId);

Returns the comment for a given node and tree (optional).

const comment = api.tracing.getCommentForNode(23);

// Provide a tree for lookup speed boost
const comment = api.tracing.getCommentForNode(23, api.getActiveTreeid());

Sets the name for a tree. If no tree id is given, the active tree is used.

api.tracing.setTreeName("Special tree", 1);

Sets the visibility of the edges for a tree. If no tree id is given, the active tree is used.

api.tracing.setTreeEdgeVisibility(false, 1);

Makes the specified tree active. Within the tree, the node with the highest ID will be activated.

api.tracing.setActiveTree(3);

Makes the tree specified by name active. Within the tree, the node with the highest ID will be activated.

api.tracing.setActiveTree("tree_1");

Makes the specified group active. Nodes cannot be added through the UI when a group is active.

api.tracing.setActiveTreeGroup(3);

Deprecated! Use renameSkeletonGroup instead.

Changes the color of the referenced tree. Internally, a pre-defined array of colors is used which is why this function uses a colorIndex (between 0 and 500) instead of a proper color.

api.tracing.setTreeColorIndex(3, 10);

Changes the visibility of the referenced tree.

api.tracing.setTreeVisibility(3, false);

Gets a list of tree groups

api.tracing.getTreeGroups();

Sets the parent group of the referenced tree.

api.tracing.setTreeGroup(
  3,
  api.tracing.getTreeGroups.find(({ name }) => name === "My Tree Group").id,
);

Renames the group referenced by the provided id.

api.tracing.renameSkeletonGroup(
  3,
  "New group name",
);

Moves one skeleton group to another one (or to the root node when providing null as the second parameter).

api.tracing.moveSkeletonGroup(
  3,
  null, // moves group with id 0 to the root node
);

Adds a segment to the segment list.

api.tracing.registerSegment(
  3,
  [1, 2, 3],
  null,             // optional
  "volume-layer-id" // optional
);

Registers all segments that exist at least partially in the given bounding box.

api.tracing.registerSegmentsForBoundingBox(
  [0, 0, 0],
  [10, 10, 10],
  "My Bounding Box"
);

Gets a segment object within the referenced volume layer. Note that this object does not support any modifications made to it.

const segment = api.tracing.getSegment(
  3,
  "volume-layer-id"
);
console.log(segment.groupId)

Updates a segment. The segment parameter can contain all properties of a Segment (except for the id) or less.

api.tracing.updateSegment(
  3,
  {
    name: "A name",
    anchorPosition: [1, 2, 3],
    additionalCoordinates: [],
    color: [1, 2, 3],
    groupId: 1,
  },
  "volume-layer-id"
);

Removes a segment from the segment list. This does not mutate the actual voxel data.

api.tracing.removeSegment(
  3,
  "volume-layer-id"
);

Moves one segment group to another one (or to the root node when providing null as the second parameter).

api.tracing.moveSegmentGroup(
  3,
  null, // moves group with id 0 to the root node
  "volume-layer-id"
);

Creates a new segment group and returns its id.

await api.tracing.createSegmentGroup(
  "Group name",    // optional
  parentGroupId,   // optional. use -1 for the root group
  volumeLayerName, // see getSegmentationLayerNames
);

Renames the segment group referenced by the provided id.

api.tracing.renameSegmentGroup(
  3,
  "New group name",
  volumeLayerName, // see getSegmentationLayerNames
);

Deletes the segment group referenced by the provided id. If deleteChildren is true, the deletion is recursive.

api.tracing.deleteSegmentGroup(
  3,
  true,
  volumeLayerName, // see getSegmentationLayerNames
);

Deprecated! Use renameSkeletonGroup instead.

Returns the name for a given tree id. If none is given, the name of the active tree is returned.

api.tracing.getTreeName();

Loads the agglomerate tree for the agglomerate at the given position. Only possible if a segmentation layer is visible for which an agglomerate mapping is enabled. Should be preferred over using api.tracing.loadAgglomerateSkeletonForSegmentId as this version yields more reliable results in live collaborative context. A conflicting merge can result in the agglomerate id at the give position to change. That's why passing the position is safer than passing the agglomerate id via api.tracing.loadAgglomerateSkeletonForSegmentId as the agglomerate id lookup is done after applying such an interfering merge.

api.tracing.loadAgglomerateTreeAtPosition([3, 3, 3]);

Loads the agglomerate tree for the given segment id. Only possible if a segmentation layer is visible for which an agglomerate mapping is enabled. Please consider using api.tracing.loadAgglomerateTreeAtPosition as it yields more reliable results in a live collaborative context. A conflicting merge of another user can make the passed agglomerate id invalid just before loading the agglomerate tree from the backend. By passing any position of the agglomerate instead its id via using api.tracing.loadAgglomerateTreeAtPosition WEBKNOSSOS can ensure to use the up-to-date agglomerate id to request the correct agglomerate tree.

api.tracing.loadAgglomerateSkeletonForSegmentId(3);

Saves the tracing and returns a promise (which you can call then on or use await with).

api.tracing.save().then(() => ... );

await api.tracing.save();

Finishes the task and gets the next one. It returns a promise (which you can call then on or use await with). Don't assume that code after the finishAndGetNextTask call will be executed. It can happen that there is no further task, in which case the user will be redirected to the dashboard. Or the the page can be reloaded (e.g., if the dataset changed), which also means that no further JS code will be executed in this site context.

api.tracing.finishAndGetNextTask().then(() => ... );

await api.tracing.finishAndGetNextTask();

Restart webKnossos without refreshing the page. Please prefer finishAndGetNextTask for user scripts since it does extra validation of the requested change and makes sure everything is saved etc.

api.tracing.restart("Explorational", "5909b5aa3e0000d4009d4d15", "TRACE")

Reload tracing by reloading the entire page.

api.tracing.hardReload()

Increases the node radius of the given node by multiplying it with 1.05^delta. If no nodeId and/or treeId are provided, it defaults to the current tree and current node.

api.tracing.setNodeRadius(1)

Centers the given node. If no node is provided, the active node is centered.

api.tracing.centerNode()

Centers the 3D view.

api.tracing.centerTDView()

Measures the length of the given tree and returns the length in dataset unit and in voxels.

Measures the length of all trees and returns the length in dataset unit and in voxels.

Returns the shortest path between two nodes in nanometer and voxels as well as an array of the node IDs in the shortest path.

Returns the length of the shortest path between two nodes in nanometer and in voxels.

Starts an animation to center the given position. See setCameraPosition for a non-animated version of this function.

   Boolean which decides whether the third dimension shall also be animated (defaults to true)
   When true, this lets the user still manipulate the "third dimension"
   during the animation (important because otherwise the user cannot continue to trace until
   the animation is over).

api.tracing.centerPositionAnimated([0, 0, 0])

Returns the current camera position.

const currentPosition = api.tracing.getCameraPosition()

Sets the current camera position. See centerPositionAnimated for an animated version of this function.

api.tracing.setCameraPosition([100, 100, 100])

Sets the current camera rotation.

api.tracing.setCameraRotation([180, 0, 90])

Returns the id of the current active segment. Volume tracing only!

Sets the active segment given a segment id. If a segment with the given id doesn't exist, it is created. Volume tracing only!

Returns the active tool which is either "MOVE", "SKELETON", "TRACE", "BRUSH", "FILL_CELL" or "VOXEL_PIPETTE"

Sets the active tool which should be either "MOVE", "SKELETON", "TRACE", "BRUSH", "FILL_CELL" or "VOXEL_PIPETTE" Volume tracing only!

Deprecated! Use getAnnotationTool instead.

Deprecated! Use setAnnotationTool instead.

Disables the saving for the current annotation. WARNING: Cannot be undone. Only do this if you know what you are doing.

Returns the names of all available layers of the current tracing.

DEPRECATED! Use getSegmentationLayerNames, getVisibleSegmentationLayer or getVolumeTracingLayerIds instead.

Returns the name of the volume tracing layer (only exists for a volume annotation) or the visible segmentation layer.

Return a list of segmentation layer names. Note for volume tracing layers, the name will be an ID (and not the name which the user can specify in the UI).

Invalidates all downloaded buckets of the given layer so that they are reloaded. If an additional predicate is passed, each bucket is checked to see whether it should be reloaded. Note that buckets that are in a REQUESTED state (i.e., currently being queued or downloaded) will always be reloaded by cancelling and rescheduling the request.

Invalidates all downloaded buckets so that they are reloaded.

Sets a mapping for a given layer.

const position = [123, 123, 123];
const segmentationLayerName = "segmentation";
const segmentId = await api.data.getDataValue(segmentationLayerName, position);
const treeId = api.tracing.getActiveTreeId();
const mapping = {[segmentId]: treeId}

api.data.setMapping(segmentationLayerName, mapping);

Enables/Disables the active mapping. If layerName is not passed, the currently visible segmentation layer will be used.

Gets all available mapping names for a given layer. If the layerName is not passed, the currently visible segmentation layer will be used.

Gets the active mapping for a given layer. If layerName is not passed, the currently visible segmentation layer will be used.

Sets the active mapping for a given layer. If layerName is not passed, the currently visible segmentation layer will be used.

Returns whether a mapping is currently enabled. If layerName is not passed, the currently visible segmentation layer will be used.

Returns the bounding box for a given layer name.

Returns raw binary data for a given layer, position and zoom level. If the zoom level is not provided, the first magnification will be used. If this mag does not exist, the next existing mag will be used. If the zoom level is provided and points to a not existent mag, 0 will be returned.

// Return the greyscale value for a bucket
const position = [123, 123, 123];
api.data.getDataValue("binary", position).then((greyscaleColor) => ...);

// Using the await keyword instead of the promise syntax
const greyscaleColor = await api.data.getDataValue("binary", position);

// Get the segmentation id for the first volume tracing layer
const segmentId = await api.data.getDataValue(api.data.getVolumeTracingLayerIds()[0], position);

Returns the mapped (agglomerate) id for the segment at the given position, respecting the active HDF5 mapping. For layers without a local HDF5 mapping, delegates to getDataValue with respectMapping enabled. For layers with a local HDF5 mapping (proofread mode or editable mapping), looks up the id in the local mapping and fetches from the server if the id is not cached yet.

Returns the channel count of a layer. Except for RGB layers (which have three channels), layers always have one channel.

api.data.getChannelCount("color") === 1; // true
api.data.getChannelCount("uint32_segmentation") === 1; // true
api.data.getChannelCount("rgb-layer") === 3; // true

Returns the magnification that is currently rendered at the given position.

Returns the maginfication that will ultimately be rendered at the given position, once all respective buckets are loaded.

Downloads a cuboid of raw data from a dataset (not tracing) layer. A new window is opened for the download - if that is not the case, please check your pop-up blocker.

// Download a cuboid (from (0, 0, 0) to (100, 200, 100)) of raw data from the "segmentation" layer.
api.data.downloadRawDataCuboid("segmentation", [0,0,0], [100,200,100]);

Label voxels with the supplied value. This method behaves as if the user had brushed the provided voxels all at once. If the volume data wasn't downloaded completely yet, WEBKNOSSOS will merge the data as soon as it was downloaded.

Volume tracing only!

// Set the segmentation id for some voxels to 1337
api.data.labelVoxels([[1,1,1], [1,2,1], [2,1,1], [2,2,1]], 1337);

Returns the dataset's setting for the tracing view.

const segmentationOpacity = api.data.getConfiguration("segmentationOpacity");

Set the dataset's setting for the tracing view.

api.data.setConfiguration("segmentationOpacity", 20);

Retrieve a list of available precomputed mesh files. If layerName is not passed, the currently visible segmentation layer will be used.

const availableMeshFileNames = api.data.getAvailableMeshFiles();

Get currently active mesh file (might be null). If layerName is not passed, the currently visible segmentation layer will be used.

const activeMeshFile = api.data.getActiveMeshFile();

Set currently active mesh file (can be set to null). If layerName is not passed, the currently visible segmentation layer will be used.

const availableMeshFileNames = api.data.getAvailableMeshFiles();
if (availableMeshFileNames.length > 0) {
  api.data.setActiveMeshFile(availableMeshFileNames[0]);
}

If a mesh file is active, loadPrecomputedMesh can be used to load a mesh for a given segment at a given seed position for a specified segmentation layer. If layerName is not passed, the currently visible segmentation layer will be used. If there is no mesh file for the dataset's segmentation layer available, you can use api.data.computeMeshOnDemand instead.

const currentPosition = api.tracing.getCameraPosition();
const segmentId = await api.data.getDataValue("segmentation", currentPosition);
const availableMeshFiles = await api.data.getAvailableMeshFiles();
api.data.setActiveMeshFile(availableMeshFiles[0]);

api.data.loadPrecomputedMesh(segmentId, currentPosition);

Load a mesh for a given segment id and a seed position by computing it ad-hoc.

const currentPosition = api.tracing.getCameraPosition();
const segmentId = await api.data.getDataValue("segmentation", currentPosition);
api.data.computeMeshOnDemand(segmentId, currentPosition);

Set the visibility for a loaded mesh by providing the corresponding segment id. If layerName is not passed, the currently visible segmentation layer will be used.

api.data.setMeshVisibility(segmentId, false);

Remove the mesh for a given segment and segmentation layer. If layerName is not passed, the currently visible segmentation layer will be used.

api.data.removeMesh(segmentId, layerName);

Removes all meshes from the scene for a given segmentation layer. If layerName is not passed, the currently visible segmentation layer will be used.

api.data.resetMeshes();

Get the RGB color of a segment (and its mesh) for a given segmentation layer. If layerName is not passed, the currently visible segmentation layer will be used.

api.data.getSegmentColor(3);

Set the RGB color of a segment (and its mesh) for a given segmentation layer. If layerName is not passed, the currently visible segmentation layer will be used. If the mesh is loaded, optionally update its opacity.

api.data.setSegmentColor(3, [0, 1, 1], "segmentation", 0.5);

Takes a screenshot of the current viewport(s) and immediately downloads each image as a PNG. In plane mode, one file per visible viewport is downloaded. Use captureScreenshots + downloadScreenshotsAsZip instead when calling in a loop to avoid repeated save dialogs.

Renders the current viewport(s) and returns the images as an array of { name, blob } objects without triggering any download. Suitable for collecting frames in a loop.

Packages an array of { name, blob } entries (as returned by captureScreenshots) into a single ZIP archive and downloads it once.

Returns the user's setting for the tracing view.

const keyboardDelay = api.user.getConfiguration("keyboardDelay");

Set the user's setting for the tracing view.

api.user.setConfiguration("keyboardDelay", 20);

Wait for some milliseconds before continuing the control flow.

// Wait for 5 seconds
await api.utils.sleep(5000);

Show a toast to the user. Returns a function which can be used to remove the toast again.

// Show a toast for 5 seconds
const removeToast = api.utils.showToast("info", "You just got toasted", false, 5000);
// ... optionally:
// removeToast();

Overwrite existing wK actions. wK uses Redux actions to trigger any changes to the application state.

api.utils.registerOverwrite("MERGE_TREES", (store, next, originalAction) => {
  // ... do stuff before the original function...
  next(originalAction);
  // ... do something after the original function ...
});

Sets a custom handler function for a keyboard shortcut.

const handler = api.utils.registerKeyHandler("g", () => {
  console.log("g was pressed");
});
// later
handler.unregister();