CREMI A tutorial

In this tutorial, you train Bootstrapper on 151 objects that a person traced on one section of CREMI A. CREMI A is an electron microscopy volume with voxels of 40 x 8 x 8 nm. Bootstrapper then segments the whole volume in 3D, and a second volume that it did not train on.

You need a Linux machine with a CUDA GPU and about 4 GB of free disk for the data and round 1. Allow about 30 minutes after installation and downloads. The outputs below come from a test run on 2026-10-14 with one NVIDIA GeForce RTX 4090. A line ... marks lines that this tutorial cuts from an output.

Install

Installation gives the requirements and the optional extras. In short:

git clone --branch v1.0.0 https://github.com/ucsdmanorlab/bootstrapper.git
cd bootstrapper
uv sync --locked
source .venv/bin/activate

Activate the environment again in each new shell. Then check the install:

$ bs --version
bs, version 1.0.0

Get the data

Make an empty tutorial folder, and go into it. Run every command below in this folder. This command downloads the 3.9 GB archive and keeps only CREMI A (60 MB):

curl -L "https://zenodo.org/records/21223591/files/data.tar?download=1" | tar xf - --strip-components=1 data/cremi_a

The folder cremi_a contains two volumes, volume_1.zarr and volume_2.zarr. Each volume has a raw image (raw) and dense ground-truth labels (labels). volume_1 also contains sparse_labels, the 151 traced objects on section 31. Round 1 trains only on sparse_labels, and evaluation uses only the dense labels.

Look at the data

$ bs view cremi_a/volume_1.zarr/raw cremi_a/volume_1.zarr/sparse_labels
raw            cremi_a/volume_1.zarr/raw  image
sparse_labels  cremi_a/volume_1.zarr/sparse_labels  segmentation
http://<host>:41229/v/5548329eba2f56c52c1748ebb9e7c07a26599b7f/
Press any key to exit...

Open the URL in a browser. The viewer is Neuroglancer, and it stays open until you press a key in the terminal. To serve it on this machine only, add --bind 127.0.0.1.

Section 31 of volume_1, a gray EM image with about 150 colored traced objects over its center

Section 31 of volume_1, with the 151 sparse labels.

volume_1 in xz, a gray EM image with one thin colored line across its middle

volume_1 in xz. Only section 31 of the 63 sections has labels.

Prepare round 1

A round is a folder of commented step files. bs prepare writes it for your data. Give volume_1 as the training volume:

bs prepare round_01 --raw cremi_a/volume_1.zarr/raw --labels sparse_labels --labelled sparsely

--labelled sparsely tells Bootstrapper that only some objects have labels, so training learns only from the traced objects. In a terminal, bs prepare asks each question that has no flag. Press Enter at each question to take the default. bs prepare round_01 alone asks every question in a short dialogue.

Then add volume_2 as an evaluation volume. Its labels are ground truth only, so round 1 does not train on them:

$ bs prepare round_01 --raw cremi_a/volume_2.zarr/raw --gt labels
  volume_2-zarr: raw, ground truth labels
added volume_2-zarr to round_01/volumes.toml
wrote round_01/06_evaluate.toml
...
round_01 is current.
Next: bs run round_01

The round now has six steps. Step 01 trains a 2D model on the sparse labels. Steps 02 and 03 predict affinities, which give for each voxel the chance that it is in the same object as its neighbors. Step 03 uses a 3D model that ships with Bootstrapper, and the first bs prepare on a new install downloads it (41 MB). Step 04 segments the affinities into objects, step 05 fills holes, and step 06 evaluates.

Run round 1

A dry run checks every path and runs nothing:

bs run round_01 --dry-run

Make sure that the GPU is free, for example with nvidia-smi. On a machine with more than one GPU, CUDA_VISIBLE_DEVICES=0 bs run round_01 uses GPU 0 only. Run all steps:

$ bs run round_01
Running train.2d_mtlsd from round_01/01_train_2d_mtlsd.toml
...
Running segment from round_01/04_segment.toml
...
Running evaluate from round_01/06_evaluate.toml
...
volume_2-zarr  mws/fill_holes  NVI split 0.121 merge 0.154  VOI split 1.05 merge 1.34  (round_01/06_evaluate_volume_2-zarr_gt.json)
...
View: bs view round_01 06

In the test run, training took 23 minutes, and the whole run took 27 minutes. If you stop the run, bs run round_01 starts again at the first step that is not done.

If the segment step fails with database is locked, set num_workers = 4 in round_01/04_segment.toml. Then run bs run round_01 again.

Look at the result

bs view round_01 04

This command shows the raw and the step 04 layers of each volume, and the viewer opens on volume_2 with its segmentation visible. Click a layer name in the top bar to show or hide that layer. bs view round_01 shows the layers of every step.

The round 1 segmentation of section 31 of volume_2, where each object has one color over the gray raw

The round 1 segmentation of volume_2, which round 1 did not train on. Each color is one object.

The same segmentation in xz, where many colored objects run from the top to the bottom of the volume

The same segmentation in xz. Labels on one section gave objects that run through many sections.

Some objects change color at a straight line. These lines are the faces of the blocks that the segment step works in.

The evaluate step compares the segmentation with the ground truth of volume_2 and gives the normalized variation of information (NVI). NVI split rises when the segmentation cuts one true object into pieces. NVI merge rises when one object covers more than one true object. Both go from 0 to 1, and lower is better. Your numbers can be a little different, because the segment step adds random noise to the affinities to break ties.

Next steps

Round 2 trains a 3D model on this segmentation.
To change a step, edit a key at the top of its file. Then run bs run round_01 again. If bs run asks for it, run bs prepare round_01 first. The configuration reference explains each key.
The command reference explains --from, --only and the other options of bs run.
Your data shows how to give bs prepare your own image and labels.