Skip to content

Proofreading Tool

The proofreading tool lets you fix merge and split errors in segmentations generated by automated workflows (outside WEBKNOSSOS), for example with Voxelytics. Split and merge operations are executed directly on the underlying supervoxel graph structure.

Watch this video to get started with the proofreading tools:

To use the proofreading tool, enable an ID mapping for your segmentation so WEBKNOSSOS can load the supervoxel graph. Once detected, you can activate the proofreading tool from the toolbar (clipboard icon), or with the keyboard shortcut Ctrl+K then O:

  1. Select an ID mapping for a segmentation layer from the left-hand side panel
  2. From the toolbar, switch to the proofreading tool (clipboard icon)
  3. [Optional] Press Shift + middle-click on any segment to load and display its supervoxel graph as an agglomerate tree
  4. Proceed to fix split and merge errors:

Fixing Split Errors

  1. Left-click on any part of the source segment. It will be marked with a white crosshair
  2. Right-click on the target segment to bring up the context menu. Select Merge with active segment
  3. WEBKNOSSOS will merge both segments and reload the updated segmentation and 3D meshes

Fixing Merge Errors

  1. Left-click on any part of the source segment. It will be marked with a white crosshair
  2. Right-click the part of the segment you want to split off to open the context menu. Select Split from active segment
  3. WEBKNOSSOS will perform a min-cut operation to delete all supervoxel graph edges between the source and target segments, effectively splitting the two into individual segments
  4. WEBKNOSSOS will reload the split agglomerate, updated segmentation, and 3D meshes

Proofreading operations rely on the quality of the initial over-segmentation. If cells are already connected incorrectly in that base graph, WEBKNOSSOS cannot separate them with proofreading alone.

If you want to reload, hide, or remove a 3D mesh during proofreading, use the mesh context menu in the 3D viewport.

Fixing Merge Errors with Multi-Split Mode

The standard min-cut determines the cut location based solely on two clicked positions, which can sometimes produce an inaccurate result. Multi-split mode lets you guide the cut by labeling representative segments on each side of the intended boundary before it is computed. This additional context improves accuracy and saves time when dealing with complex merge errors.

When to use multi-split mode

Use multi-split mode when:

  • A standard min-cut keeps producing incorrect results.
  • You already have a clear idea of which segments belong on each side of the cut and want to encode that knowledge directly.

Step-by-step

  1. Activate multi-split mode by clicking the scissor icon in the proofreading toolbar, or press M.
  2. Assign segments to Partition 1 by Ctrl / Cmd + Left Click on a segment in any orthogonal viewport or the 3D viewport. Partition 1 segments are highlighted in dark gray, but only in the 3D Viewport.
  3. Assign segments to Partition 2 by Ctrl / Cmd + Shift + Left Click. Partition 2 segments are highlighted in light gray, but only in the 3D Viewport.
  4. Continue clicking to build up representative samples on both sides. Sampling close to the intended boundary is usually sufficient for an accurate result.
  5. Once both partitions contain at least one segment, trigger the split by pressing Enter or by right-clicking any segment and choosing Split partitions from the context menu.
  6. WEBKNOSSOS computes a min-cut that separates the agglomerate into two parts and reloads the updated segmentation and 3D meshes.

The right-click context menu (Add/Remove to Partition 1 / Add/Remove to Partition 2) also lets you add or remove individual segments and serves as a shortcut reminder.

Clearing the selection

Press Esc at any time to clear all partition selections without performing a split. Toggling multi-split mode off (scissor icon or M) also clears the current selections.

Splitting a Segment from All Its Neighbors

When a segment is incorrectly merged with multiple neighbors simultaneously, you can cut it free from all of them in a single operation instead of performing individual min-cuts. Right-click the segment and select Split from all neighboring segments. WEBKNOSSOS identifies all adjacent segments in the agglomerate graph and severs all connecting edges at once, leaving the segment as its own agglomerate.

This option is available from any viewport and from agglomerate tree node context menus.

Working with Agglomerate Trees

Agglomerate trees represent the supervoxel graph of an agglomerate as a tree of connected nodes in the skeleton layer. Load one by pressing Shift + middle-click on a segment, or via right-click → Import Agglomerate Tree. Trees are automatically updated after proofreading operations.

In addition to the context-menu interactions described above, agglomerate trees support fine-grained control:

  • Min-cut via nodes: Right-click a node while a second node is selected and choose Perform Min-Cut between these Nodes to split the agglomerate along the minimum-cut path between them.
  • Split from neighbors via nodes: Right-click a node and choose Split from all neighboring segments to isolate it from all neighboring segments in the agglomerate.
  • Merge via edge creation: Drawing an edge between a node in one agglomerate tree and a node in another (while the proofreading tool is active) merges the two agglomerates.
  • Split via edge deletion: Deleting an edge between two nodes splits the agglomerate at that point.

Agglomerate trees can be converted to normal skeleton trees via right-click in the Skeleton tab, which removes their link to the agglomerate mapping.

Info

Undo and redo are not supported for proofreading operations. To revert a mistake, use Restore Older Version in the dropdown next to the Save button.

Proofreading Toolbar Controls

When the proofreading tool is active (and an editable mapping is enabled), additional controls are available in the toolbar:

  • Clear proofreading by-products: Removes auxiliary meshes that were loaded during proofreading. Use this once you have finished correcting a segment pair.
  • Automatic mesh loading: When enabled, WEBKNOSSOS automatically loads a 3D mesh for each segment involved in a merge or split operation.
  • Selective segment visibility: When enabled, only the hovered or active segment is shown, reducing visual clutter when working on densely packed regions.
  • Multi split mode: Enables partition-based splitting (can also be toggled with M).

Info

The proofreading tool requires a supervoxel-graph-compatible mapping. These mappings are commonly generated by automated segmentation pipelines (for example, Voxelytics). If you need help preparing compatible files, contact support@webknossos.org.

Exporting Proofreading Results

Proofreading does not change the voxel data of your segmentation. Instead, WEBKNOSSOS records every merge and split as an edit to the supervoxel graph of the underlying ID mapping. You can export these edits as a file, or apply them to the segmentation to create a new dataset.

Downloading and Re-uploading Proofreading Annotations

To download a proofreading annotation, open Menu > Download and select Include volume annotations as Zarr or Include volume annotations as WKW. If you choose the NML-only option, your proofreading edits are not included.

The downloaded ZIP contains:

  • An NML file with the annotation metadata. For each proofread layer, it references the edits file (editedMappingEdgesLocation) and the name of the ID mapping the edits are based on (editedMappingBaseMappingName).
  • An editedMappingEdges_<layer name>.zip file for each proofread layer (editedMappingEdges_<index>_<layer name>.zip if the annotation has multiple volume layers), containing a Zarr v3 group with two arrays:
    • edges: one row per edited edge, holding the two supervoxel IDs (uint64) the edge connects.
    • edgeIsAddition: one boolean per edge. true means the edge was added (a merge), false means it was removed (a split).

The edges are stored in the order the operations were performed. For proofread layers, the ZIP doesn't contain any voxel data, because volume annotation tools are disabled while an editable mapping is active.

To restore a proofreading annotation from such a ZIP, upload it from the dashboard: click Upload Annotation(s) or drag and drop the ZIP onto your annotation list. WEBKNOSSOS creates a new annotation and replays the recorded edits on top of the original ID mapping.

Keep these limitations in mind when re-uploading:

  • The dataset must still contain the ID mapping that is referenced in the NML. The edits are stored as supervoxel IDs, so they only make sense for the same over-segmentation.
  • You can only upload one proofreading annotation at a time. WEBKNOSSOS can't merge several proofreading annotations into one.
  • The version history of the original annotation isn't transferred. In the new annotation, you can't restore versions from before the upload.
  • Dropping the ZIP into an open annotation doesn't import the proofreading edits. Upload it from the dashboard instead.

Materializing a Proofread Segmentation into a New Dataset

To get a standalone segmentation layer with all your merges and splits applied, materialize the proofreading annotation into a new dataset:

  1. In the Layers tab of the left sidebar, hover over the three-dot menu next to the name of the proofread volume layer.
  2. Select Merge this volume annotation with its fallback layer.
  3. In the dialog, enter a New Dataset Name and select a Bounding Box. For proofreading annotations, only the region inside the selected bounding box is exported. If you don't have one yet, create a bounding box first.
  4. Click Start Materializing this Volume Annotation.

This starts a processing job. When the job finishes, you can open the new dataset from the Processing Jobs page. The size of the bounding box is limited, the same as for TIFF exports.

Info

Materialization is only available to admins and dataset managers. It requires the WEBKNOSSOS worker, so it is available on webknossos.org and on managed instances where the worker is set up. See Merging volume annotation with fallback data for the general materialization workflow.

Simultaneous Multi-User Proofreading (Experimental)

The proofreading tool is currently the only tool that supports WEBKNOSSOS's experimental simultaneous editing / live collaboration mode, which lets several collaborators proofread the same annotation at the same time.