api.tracing¶

All tracing related API methods. This is the newest version of the API (version 3).

Example:

window.webknossos.apiReady(3).then(api => {
  api.tracing.getActiveNodeId();
  api.tracing.getActiveTreeId();
  ...
}

Methods

`centerActiveNode` ¶

centerActiveNode(): void

Centers the active node.

`centerNode` ¶

centerNode(nodeId?: number): void

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

Example:

api.tracing.centerNode()

`centerPositionAnimated` ¶

centerPositionAnimated(
  position: Vector3,
  skipCenteringAnimationInThirdDimension: boolean = true,
  rotation?: Vector3,
  useVoxelCenter: boolean = false,
): void

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

Parameters:

position: Vector3
skipCenteringAnimationInThirdDimension: 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).
rotation: Vector3 (optional) - Will only be noticeable in flight mode.

Example:

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

`centerTDView` ¶

centerTDView(): void

Centers the 3D view.

Example:

api.tracing.centerTDView()

`createNode` ¶

createNode(
  position: Vector3,
  options?: { activate?: boolean; additionalCoordinates?: AdditionalCoordinate[]; branchpoint?: boolean; center?: boolean; rotation?: Vector3; skipCenteringAnimationInThirdDimension?: boolean },
): void

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.

`createSegmentGroup` ¶

createSegmentGroup(
  name: string | null = null,
  parentGroupId: number | null = MISSING_GROUP_ID,
  volumeLayerName?: string,
): Promise<number>

Creates a new segment group and returns its id.

Example:

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

`createTree` ¶

createTree(): never

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

`deleteCommentForNode` ¶

deleteCommentForNode(nodeId: number, treeId?: number): void

Deletes the comment of a node.

Example:

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

`deleteNode` ¶

deleteNode(nodeId: number, treeId: number): void

Deletes the node with nodeId in the tree with treeId

`deleteSegmentGroup` ¶

deleteSegmentGroup(
  groupId: number,
  deleteChildren: boolean = false,
  volumeLayerName?: string,
): void

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

Example:

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

`deleteTree` ¶

deleteTree(treeId: number): void

Deletes the tree with the given treeId.

`disableSaving` ¶

disableSaving(): void

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

`findShortestPathBetweenNodes` ¶

findShortestPathBetweenNodes(
  sourceNodeId: number,
  targetNodeId: number,
): { lengthInUnit: number; lengthInVx: number; shortestPath: number[] }

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

`finishAndGetNextTask` ¶

finishAndGetNextTask(): Promise<void>

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.

Example:

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

Example:

await api.tracing.finishAndGetNextTask();

`getActiveCellId` ¶

getActiveCellId(): bigint | null | undefined

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

`getActiveGroupId` ¶

getActiveGroupId(): number | null | undefined

Deprecated! Use getActiveTreeGroupId instead.

`getActiveNodeId` ¶

getActiveNodeId(): number | null | undefined

Returns the id of the current active node.

`getActiveTreeGroupId` ¶

getActiveTreeGroupId(): number | null | undefined

Returns the id of the current active group.

`getActiveTreeId` ¶

getActiveTreeId(): number | null | undefined

Returns the id of the current active tree.

`getAllNodes` ¶

getAllNodes(): Readonly<MutableNode>[]

Returns all nodes belonging to a tracing.

`getAllTrees` ¶

getAllTrees(): Record<number, Tree>

Returns all trees belonging to a tracing.

`getAnnotationTool` ¶

getAnnotationTool(
  ,
): "MOVE" | "SKELETON" | "BRUSH" | "ERASE_BRUSH" | "TRACE" | "ERASE_TRACE" | "FILL_CELL" | "VOXEL_PIPETTE" | "QUICK_SELECT" | "BOUNDING_BOX" | "PROOFREAD" | "LINE_MEASUREMENT" | "AREA_MEASUREMENT"

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

`getCameraPosition` ¶

getCameraPosition(): Vector3

Returns the current camera position.

Example:

const currentPosition = api.tracing.getCameraPosition()

`getCommentForNode` ¶

getCommentForNode(nodeId: number, treeId?: number): string | null | undefined

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

Parameters:

treeId: Supplying the tree id will provide a performance boost for looking up a comment.

Example:

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

Example:

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

`getSegment` ¶

getSegment(segmentIdLike: NumberLike, layerName: string): Segment

Gets a segment object within the referenced volume layer. Note that this object does not support any modifications made to it. The segment id can be a number or a bigint. Pass ids above Number.MAX_SAFE_INTEGER as bigint.

Example:

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

`getTreeGroups` ¶

getTreeGroups(): TreeGroupTypeFlat[]

Gets a list of tree groups

Example:

api.tracing.getTreeGroups();

`getTreeName` ¶

getTreeName(treeId?: number): string

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

Example:

api.tracing.getTreeName();

`getVolumeTool` ¶

getVolumeTool(
  ,
): "MOVE" | "SKELETON" | "BRUSH" | "ERASE_BRUSH" | "TRACE" | "ERASE_TRACE" | "FILL_CELL" | "VOXEL_PIPETTE" | "QUICK_SELECT" | "BOUNDING_BOX" | "PROOFREAD" | "LINE_MEASUREMENT" | "AREA_MEASUREMENT"

Deprecated! Use getAnnotationTool instead.

`hardReload` ¶

hardReload(): Promise<void>

Reload tracing by reloading the entire page.

Example:

api.tracing.hardReload()

`loadAgglomerateSkeletonForSegmentId` ¶

loadAgglomerateSkeletonForSegmentId(segmentIdLike: NumberLike): void

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. The segment id can be a number or a bigint. Pass ids above Number.MAX_SAFE_INTEGER as bigint.

Example:

api.tracing.loadAgglomerateSkeletonForSegmentId(3);

`loadAgglomerateTreeAtPosition` ¶

loadAgglomerateTreeAtPosition(position: Vector3): void

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.

Example:

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

`measureAllTrees` ¶

measureAllTrees(): [number, number]

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

`measurePathLengthBetweenNodes` ¶

measurePathLengthBetweenNodes(
  sourceNodeId: number,
  targetNodeId: number,
): [number, number]

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

`measureTreeLength` ¶

measureTreeLength(treeId: number): [number, number]

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

`moveSegmentGroup` ¶

moveSegmentGroup(
  groupId: number,
  targetGroupId: number | null | undefined,
  layerName: string,
): void

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

Example:

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

`moveSkeletonGroup` ¶

moveSkeletonGroup(groupId: number, targetGroupId: number | null): void

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

Example:

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

`registerSegment` ¶

registerSegment(
  segmentIdLike: NumberLike,
  anchorPosition: Vector3,
  additionalCoordinates: AdditionalCoordinate[] | undefined = undefined,
  layerName?: string,
): void

Adds a segment to the segment list. The segment id can be a number or a bigint. Pass ids above Number.MAX_SAFE_INTEGER as bigint.

Example:

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

`registerSegmentsForBoundingBox` ¶

registerSegmentsForBoundingBox(
  min: Vector3,
  max: Vector3,
  bbName: string,
  options?: { maximumSegmentCount?: number; maximumVolume?: number },
): Promise<void>

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

Example:

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

`removeSegment` ¶

removeSegment(segmentIdLike: NumberLike, layerName: string): void

Removes a segment from the segment list. This does not mutate the actual voxel data. The segment id can be a number or a bigint. Pass ids above Number.MAX_SAFE_INTEGER as bigint.

Example:

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

`renameGroup` ¶

renameGroup(groupId: number, newName: string): void

Deprecated! Use renameSkeletonGroup instead.

`renameSegmentGroup` ¶

renameSegmentGroup(
  groupId: number,
  newName: string,
  volumeLayerName?: string,
): void

Renames the segment group referenced by the provided id.

Example:

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

`renameSkeletonGroup` ¶

renameSkeletonGroup(groupId: number, newName: string): void

Renames the group referenced by the provided id.

Example:

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

`resetSkeletonTracing` ¶

resetSkeletonTracing(): void

Completely resets the skeleton tracing.

`restart` ¶

restart(
  newMaybeCompoundType: "CompoundTask" | "CompoundProject" | "CompoundTaskType" | null,
  newAnnotationId: string,
  newControlMode: "TRACE" | "SANDBOX" | "VIEW",
  version?: number | null,
  keepUrlState: boolean = false,
  keepUrlSearch: boolean = true,
): Promise<void>

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.

Example:

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

`save` ¶

save(): Promise<void>

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

Example:

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

Example:

await api.tracing.save();

`setActiveCell` ¶

setActiveCell(idLike: NumberLike): void

Sets the active segment given a segment id. If a segment with the given id doesn't exist, it is created. The segment id can be a number or a bigint. Pass ids above Number.MAX_SAFE_INTEGER as bigint. Volume tracing only!

`setActiveGroup` ¶

setActiveGroup(groupId: number): void

Deprecated! Use renameSkeletonGroup instead.

`setActiveNode` ¶

setActiveNode(
  id: number,
  suppressAnimation?: boolean,
  suppressCentering?: boolean,
  suppressRotation?: boolean,
): void

Sets the active node given a node id.

`setActiveTree` ¶

setActiveTree(treeId: number): void

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

Example:

api.tracing.setActiveTree(3);

`setActiveTreeByName` ¶

setActiveTreeByName(treeName: string): void

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

Example:

api.tracing.setActiveTree("tree_1");

`setActiveTreeGroup` ¶

setActiveTreeGroup(groupId: number): void

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

Example:

api.tracing.setActiveTreeGroup(3);

`setAnnotationTool` ¶

setAnnotationTool(
  toolId: "MOVE" | "SKELETON" | "BRUSH" | "ERASE_BRUSH" | "TRACE" | "ERASE_TRACE" | "FILL_CELL" | "VOXEL_PIPETTE" | "QUICK_SELECT" | "BOUNDING_BOX" | "PROOFREAD" | "LINE_MEASUREMENT" | "AREA_MEASUREMENT",
): void

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

`setCameraPosition` ¶

setCameraPosition(position: Vector3): void

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

Example:

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

`setCameraRotation` ¶

setCameraRotation(rotation: Vector3): void

Sets the current camera rotation.

Example:

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

`setCommentForNode` ¶

setCommentForNode(commentText: string, nodeId: number, treeId?: number): void

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

Example:

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

`setNodeRadius` ¶

setNodeRadius(delta: number, nodeId?: number, treeId?: number): void

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.

Example:

api.tracing.setNodeRadius(1)

`setTreeColorIndex` ¶

setTreeColorIndex(treeId: number | null | undefined, colorIndex: number): void

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.

Example:

api.tracing.setTreeColorIndex(3, 10);

`setTreeEdgeVisibility` ¶

setTreeEdgeVisibility(
  edgesAreVisible: boolean,
  treeId: number | null | undefined,
): void

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

Example:

api.tracing.setTreeEdgeVisibility(false, 1);

`setTreeGroup` ¶

setTreeGroup(treeId?: number, groupId?: number): void

Sets the parent group of the referenced tree.

Example:

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

`setTreeName` ¶

setTreeName(name: string, treeId?: number | null): void

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

Example:

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

`setTreeVisibility` ¶

setTreeVisibility(treeId: number | null | undefined, isVisible: boolean): void

Changes the visibility of the referenced tree.

Example:

api.tracing.setTreeVisibility(3, false);

`setVolumeTool` ¶

setVolumeTool(
  tool: "MOVE" | "SKELETON" | "BRUSH" | "ERASE_BRUSH" | "TRACE" | "ERASE_TRACE" | "FILL_CELL" | "VOXEL_PIPETTE" | "QUICK_SELECT" | "BOUNDING_BOX" | "PROOFREAD" | "LINE_MEASUREMENT" | "AREA_MEASUREMENT",
): void

Deprecated! Use setAnnotationTool instead.

`updateSegment` ¶

updateSegment(
  segmentIdLike: NumberLike,
  segment: Partial<Segment>,
  layerName: string,
): void

Updates a segment. The segment parameter can contain all properties of a Segment (except for the id) or less. The segment id can be a number or a bigint. Pass ids above Number.MAX_SAFE_INTEGER as bigint.

Example:

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

api.tracing¶

centerActiveNode ¶

centerNode ¶

centerPositionAnimated ¶

centerTDView ¶

createNode ¶

createSegmentGroup ¶

createTree ¶

deleteCommentForNode ¶

deleteNode ¶

deleteSegmentGroup ¶

deleteTree ¶

disableSaving ¶

findShortestPathBetweenNodes ¶

finishAndGetNextTask ¶

getActiveCellId ¶

getActiveGroupId ¶

getActiveNodeId ¶

getActiveTreeGroupId ¶

getActiveTreeId ¶

getAllNodes ¶

getAllTrees ¶

getAnnotationTool ¶

getCameraPosition ¶

getCommentForNode ¶

getSegment ¶

getTreeGroups ¶

getTreeName ¶

getVolumeTool ¶

hardReload ¶

loadAgglomerateSkeletonForSegmentId ¶

loadAgglomerateTreeAtPosition ¶

measureAllTrees ¶

measurePathLengthBetweenNodes ¶

measureTreeLength ¶

moveSegmentGroup ¶

moveSkeletonGroup ¶

registerSegment ¶

registerSegmentsForBoundingBox ¶

removeSegment ¶

renameGroup ¶

renameSegmentGroup ¶

renameSkeletonGroup ¶

resetSkeletonTracing ¶

restart ¶

save ¶

setActiveCell ¶

setActiveGroup ¶

setActiveNode ¶

setActiveTree ¶

setActiveTreeByName ¶

setActiveTreeGroup ¶

setAnnotationTool ¶

setCameraPosition ¶

setCameraRotation ¶

setCommentForNode ¶

setNodeRadius ¶

setTreeColorIndex ¶

setTreeEdgeVisibility ¶

setTreeGroup ¶

setTreeName ¶

setTreeVisibility ¶

setVolumeTool ¶

updateSegment ¶

`centerActiveNode` ¶

`centerNode` ¶

`centerPositionAnimated` ¶

`centerTDView` ¶

`createNode` ¶

`createSegmentGroup` ¶

`createTree` ¶

`deleteCommentForNode` ¶

`deleteNode` ¶

`deleteSegmentGroup` ¶

`deleteTree` ¶

`disableSaving` ¶

`findShortestPathBetweenNodes` ¶

`finishAndGetNextTask` ¶

`getActiveCellId` ¶

`getActiveGroupId` ¶

`getActiveNodeId` ¶

`getActiveTreeGroupId` ¶

`getActiveTreeId` ¶

`getAllNodes` ¶

`getAllTrees` ¶

`getAnnotationTool` ¶

`getCameraPosition` ¶

`getCommentForNode` ¶

`getSegment` ¶

`getTreeGroups` ¶

`getTreeName` ¶

`getVolumeTool` ¶

`hardReload` ¶

`loadAgglomerateSkeletonForSegmentId` ¶

`loadAgglomerateTreeAtPosition` ¶

`measureAllTrees` ¶

`measurePathLengthBetweenNodes` ¶

`measureTreeLength` ¶

`moveSegmentGroup` ¶

`moveSkeletonGroup` ¶

`registerSegment` ¶

`registerSegmentsForBoundingBox` ¶

`removeSegment` ¶

`renameGroup` ¶

`renameSegmentGroup` ¶

`renameSkeletonGroup` ¶

`resetSkeletonTracing` ¶

`restart` ¶

`save` ¶

`setActiveCell` ¶

`setActiveGroup` ¶

`setActiveNode` ¶

`setActiveTree` ¶

`setActiveTreeByName` ¶

`setActiveTreeGroup` ¶

`setAnnotationTool` ¶

`setCameraPosition` ¶

`setCameraRotation` ¶

`setCommentForNode` ¶

`setNodeRadius` ¶

`setTreeColorIndex` ¶

`setTreeEdgeVisibility` ¶

`setTreeGroup` ¶

`setTreeName` ¶

`setTreeVisibility` ¶

`setVolumeTool` ¶

`updateSegment` ¶