Import semantic sementation into webKnossos

Hi there,

this might be a strange question, given the scope of webKnossos but: Is there a possibility to import semantic segmentation masks into webKnossos such that they are visible in the annotation view?

My institute has a running webKnossos instance to annotate the skeleton as well as the volume of 3D EM data. Since I really like the webKnossos interface (and the idea to store all annotations in the same location/ format), I would like to use the instance to annotate 2D EM data for a machine learning (pre-processing) pipeline.

This works nicely for data I annotate from scratch (I just stack the 2D slices and load it as if it is a 3D volume). For the first 100 stacks, however, I already created annotations in CVAT. Is there an option that I can import existing annotations (i.e. stacked labelimages) into webKnossos?

Best wishes,


Hi Eric,

this is should be possible. Depending on your use case, you can either add the segmentation as layer to your dataset (example) or create a volume annotation from your images.

I have a few questions before recommending the best way to import the data:

  • Do you have access to the file system where webKnossos stores its data or do you use the GUI upload for datasets?
  • Does the segmentation span the whole dataset? How big is the data and/or the segmentation?
  • Do you want to edit the segmentation with webKnossos?
  • Are you familiar with writing Python scripts?

Hi Norman,

the moment I have access to a sftp ‘gateway’ where I can upload data to a file to a data folder. The folder structure in my (intensity) dataset currently looks like this:

  • color
    • 16-16-1
    • 8-8-1
    • 2-2-1
    • 1
  • core
  • datasource-properties.json

As far as I know, this is the default wkw structure. I have to check whether these are actually the “production” files which is displayed in webknossos, but for the sake of simplicity we can assume that this is the dataset I would like to enhance with an existing segementation and display in webknossos (otherwise I ask my colleague which has superuser rights …).

For a start, I only annotated 100 of the around 2700 images in CVAT. I do not plan to create a “dense” annotation but rather annotate up to 500 (random) slices and see how it goes. The (intensity) only takes approx 6.6GB disk space (so tiny compared to full resolution data). Due to the file size it is absolutely fine to create a numpy array with zeros (for background) and convert it into a format you suggest.

Editing with webKnossos would be optimal. The segmentation in the webinterface has to be stored somewhere as well, right? So a head start with an existing segmentation would be nice (and also cool if I can correct results of an automatic segmentation pipeline in 3D in the future).

Python scripts are not a problem.

Best wishes,


Hi Eric,

thanks for providing more context. I would recommend to add the segmentation as an additional layer to the dataset. For this you need to place a segmentation folder adjacent to color and add a section to the datasource-properties.json. This can be done easily with our Python library:

  1. Make sure to have a recent verion of the wkcuber installed: pip install -U wkcuber

from wkcuber.api.Dataset import WKDataset
import numpy as np
import os

buf = np.zeros((1000, 1000, 2700), np.uint8)

# Add data from CVAT to buf
# You may need to transpose the slices
# buf[:, :, z] = cvat_slice.T

ds = WKDataset(os.path.join("path", "to", "dataset"))
seg = ds.add_layer("segmentation", "segmentation", np.uint8)
mag = seg.get_or_add_mag(1)
mag.write(buf, offset=(0,0,0))
  1. (optional) Compress the segmentation layer python -m wkcuber.compress -l segmentation path/to/dataset and remove the *.bak folder afterwards

  2. Press “Refresh” in the wk dataset dashboard.

This approach assumes that you have the dataset (or at least the datasource-properties.json) locally, so that the metadata can be properly merged. Once imported, you can create a volume annotation on top of the segmentation to edit the data. Please let me know if you encounter any errors or need help with converting the label images into the numpy array.

Best, Norman