api.data¶

All binary data / layer related API methods.

Example:

window.webknossos.apiReady(3).then(api => {
  api.data.getLayerNames();
  api.data.reloadBuckets(...);
  ...
}

Methods

`activateMapping` ¶

activateMapping(
  mappingName?: string,
  mappingType: MappingType = "JSON",
  layerName?: string,
): void

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

`captureScreenshots` ¶

captureScreenshots(prefix?: string): Promise<ScreenshotBlob[]>

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.

Parameters:

prefix: Optional string prepended to each filename (e.g. a zero-padded frame index). Resulting names follow the pattern <prefix>__<dataset>__<x>_<y>_<z>__<plane>.png, which makes the files sort correctly when passed to downloadScreenshotsAsZip.

`computeMeshOnDemand` ¶

computeMeshOnDemand(
  segmentIdLike: NumberLike,
  seedPosition: Vector3,
  seedAdditionalCoordinates?: AdditionalCoordinate[],
): void

Load a mesh for a given segment id and a seed position by computing it ad-hoc. The segment id can be a number or a bigint. Pass ids above Number.MAX_SAFE_INTEGER as bigint.

Example:

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

`downloadRawDataCuboid` ¶

downloadRawDataCuboid(
  layerName: string,
  topLeft: Vector3,
  bottomRight: Vector3,
): Promise<void>

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.

Example:

// 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]);

`downloadScreenshot` ¶

downloadScreenshot(): Promise<void>

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.

`downloadScreenshotsAsZip` ¶

downloadScreenshotsAsZip(
  screenshots: ScreenshotBlob[],
  zipName?: string,
): Promise<void>

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

Parameters:

screenshots: The collected screenshot blobs to include.
zipName: Base name for the downloaded file (without .zip). Defaults to "screenshots".

`getActiveMapping` ¶

getActiveMapping(layerName?: string): string | null | undefined

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

`getActiveMeshFile` ¶

getActiveMeshFile(layerName?: string): string | null | undefined

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

Example:

const activeMeshFile = api.data.getActiveMeshFile();

`getAvailableMeshFiles` ¶

getAvailableMeshFiles(layerName?: string): Promise<string[]>

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

Example:

const availableMeshFileNames = api.data.getAvailableMeshFiles();

`getBoundingBox` ¶

getBoundingBox(layerName: string): [Vector3, Vector3]

Returns the bounding box for a given layer name.

`getChannelCount` ¶

getChannelCount(layerName: string): number

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

Example:

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

`getConfiguration` ¶

getConfiguration(
  key: (keyof DatasetConfiguration) | OutdatedDatasetConfigurationKeys,
): any

Returns the dataset's setting for the tracing view.

Parameters:

key: One of the following keys:
segmentationOpacity
fourBit
interpolation
layers
quality
segmentationPatternOpacity
renderMissingDataBlack

Example:

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

`getDataFor2DBoundingBox` ¶

getDataFor2DBoundingBox(
  layerName: string,
  bbox: BoundingBoxMinMaxType,
  _zoomStep: number | null | undefined = null,
): Promise<TypedArray>

Deprecated:

Use DataApi.getDataForBoundingBox instead, whose name describes its interface correctly.

`getDataForBoundingBox` ¶

getDataForBoundingBox(
  layerName: string,
  mag1Bbox: BoundingBoxMinMaxType,
  _zoomStep: number | null | undefined = null,
  additionalCoordinates: AdditionalCoordinate[] | null = null,
  signal?: AbortSignal,
): Promise<TypedArray>

For the provided layer name and bounding box, an array is constructed with the actual data. By default, the finest existent quality is chosen, but the quality can be adapted via the zoomStep parameter.

`getDataValue` ¶

getDataValue(
  layerName: string,
  position: Vector3,
  _zoomStep: number | null | undefined = null,
  additionalCoordinates: AdditionalCoordinate[] | null = null,
  respectMapping: boolean = false,
  channelIndex: number = 0,
): Promise<NumberLike>

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.

Example:

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

Example:

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

Example:

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

`getLayerNames` ¶

getLayerNames(): string[]

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

`getMappedDataValue` ¶

getMappedDataValue(
  layerName: string,
  position: Vector3,
  zoomStep: number | null | undefined = null,
  additionalCoordinates: AdditionalCoordinate[] | null = null,
): Promise<bigint>

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.

`getMappingNames` ¶

getMappingNames(layerName?: string): Promise<string[]>

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

`getRenderedZoomStepAtPosition` ¶

getRenderedZoomStepAtPosition(
  layerName: string,
  positionInLayerSpace: Vector3 | null | undefined,
): number

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

`getSegmentationLayerNames` ¶

getSegmentationLayerNames(): string[]

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).

`getSegmentColor` ¶

getSegmentColor(segmentIdLike: NumberLike, layerName?: string): Vector3

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

Example:

api.data.getSegmentColor(3);

`getUltimatelyRenderedZoomStepAtPosition` ¶

getUltimatelyRenderedZoomStepAtPosition(
  layerName: string,
  positionInLayerSpace: Vector3,
): Promise<number>

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

`getVisibleSegmentationLayerName` ¶

getVisibleSegmentationLayerName(): string | null | undefined

Returns the name of the visible segmentation layer (if it exists). Note that if the visible layer is a volume tracing layer, the name will be an ID (and not the name which the user can specify in the UI).

`getVolumeTracingLayerIds` ¶

getVolumeTracingLayerIds(): string[]

Returns the ids of the existing volume tracing layers.

`getVolumeTracingLayerName` ¶

getVolumeTracingLayerName(): string

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.

`isMappingEnabled` ¶

isMappingEnabled(layerName?: string): boolean

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

`labelVoxels` ¶

labelVoxels(
  globalPositionsMag1: Vector3[],
  segmentIdLike: NumberLike,
  optAdditionalCoordinates?: AdditionalCoordinate[] | null,
): void

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

Volume tracing only!

Example:

// 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);

`loadPrecomputedMesh` ¶

loadPrecomputedMesh(
  segmentIdLike: NumberLike,
  seedPosition: Vector3,
  layerName: string | null | undefined,
  seedAdditionalCoordinates?: AdditionalCoordinate[],
): void

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

Example:

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);

`reloadAllBuckets` ¶

reloadAllBuckets(): Promise<void>

Invalidates all downloaded buckets so that they are reloaded.

`reloadBuckets` ¶

reloadBuckets(
  layerName: string,
  predicateFn?: (bucket: DataBucket) => boolean,
  ctx?: OperationContext,
): Promise<void>

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.

`removeMesh` ¶

removeMesh(segmentIdLike: NumberLike, layerName?: string): void

Remove the mesh for a given segment and segmentation layer. If layerName is not passed, the currently visible segmentation layer will be used. The segment id can be a number or a bigint. Pass ids above Number.MAX_SAFE_INTEGER as bigint.

Example:

api.data.removeMesh(3, layerName);

`resetMeshes` ¶

resetMeshes(layerName?: string): void

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

Example:

api.data.resetMeshes();

`setActiveMeshFile` ¶

setActiveMeshFile(
  meshFileName: string | null | undefined,
  layerName?: string,
): void

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

Example:

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

`setConfiguration` ¶

setConfiguration(
  key: (keyof DatasetConfiguration) | OutdatedDatasetConfigurationKeys,
  value: any,
): void

Set the dataset's setting for the tracing view.

Parameters:

key: Same keys as for getConfiguration()

Example:

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

`setMapping` ¶

setMapping(
  layerName: string,
  mapping: Mapping | Record<number, number>,
  options: { colors?: number[]; hideUnmappedIds?: boolean; isMergerModeMapping?: boolean; showLoadingIndicator?: boolean } = {},
): void

Sets a mapping for a given layer.

Example:

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);

`setMappingEnabled` ¶

setMappingEnabled(isEnabled: boolean, layerName?: string): void

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

`setMeshVisibility` ¶

setMeshVisibility(
  segmentIdLike: NumberLike,
  isVisible: boolean,
  layerName?: string,
): void

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

Example:

api.data.setMeshVisibility(3, false);

`setSegmentColor` ¶

setSegmentColor(
  segmentIdLike: NumberLike,
  rgbColor: Vector3,
  layerName?: string,
  meshOpacity?: number,
): void

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

Example:

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

api.data¶

activateMapping ¶

captureScreenshots ¶

computeMeshOnDemand ¶

downloadRawDataCuboid ¶

downloadScreenshot ¶

downloadScreenshotsAsZip ¶

getActiveMapping ¶

getActiveMeshFile ¶

getAvailableMeshFiles ¶

getBoundingBox ¶

getChannelCount ¶

getConfiguration ¶

getDataFor2DBoundingBox ¶

getDataForBoundingBox ¶

getDataValue ¶

getLayerNames ¶

getMappedDataValue ¶

getMappingNames ¶

getRenderedZoomStepAtPosition ¶

getSegmentationLayerNames ¶

getSegmentColor ¶

getUltimatelyRenderedZoomStepAtPosition ¶

getVisibleSegmentationLayerName ¶

getVolumeTracingLayerIds ¶

getVolumeTracingLayerName ¶

isMappingEnabled ¶

labelVoxels ¶

loadPrecomputedMesh ¶

reloadAllBuckets ¶

reloadBuckets ¶

removeMesh ¶

resetMeshes ¶

setActiveMeshFile ¶

setConfiguration ¶

setMapping ¶

setMappingEnabled ¶

setMeshVisibility ¶

setSegmentColor ¶

`activateMapping` ¶

`captureScreenshots` ¶

`computeMeshOnDemand` ¶

`downloadRawDataCuboid` ¶

`downloadScreenshot` ¶

`downloadScreenshotsAsZip` ¶

`getActiveMapping` ¶

`getActiveMeshFile` ¶

`getAvailableMeshFiles` ¶

`getBoundingBox` ¶

`getChannelCount` ¶

`getConfiguration` ¶

`getDataFor2DBoundingBox` ¶

`getDataForBoundingBox` ¶

`getDataValue` ¶

`getLayerNames` ¶

`getMappedDataValue` ¶

`getMappingNames` ¶

`getRenderedZoomStepAtPosition` ¶

`getSegmentationLayerNames` ¶

`getSegmentColor` ¶

`getUltimatelyRenderedZoomStepAtPosition` ¶

`getVisibleSegmentationLayerName` ¶

`getVolumeTracingLayerIds` ¶

`getVolumeTracingLayerName` ¶

`isMappingEnabled` ¶

`labelVoxels` ¶

`loadPrecomputedMesh` ¶

`reloadAllBuckets` ¶

`reloadBuckets` ¶

`removeMesh` ¶

`resetMeshes` ¶

`setActiveMeshFile` ¶

`setConfiguration` ¶

`setMapping` ¶

`setMappingEnabled` ¶

`setMeshVisibility` ¶

`setSegmentColor` ¶