Commands
bs
bs [OPTIONS] COMMAND [ARGS]...
Make dense 3D segmentations of microscopy volumes from sparse 2D labels.
Write a round with bs prepare, then run it with bs run.
-
--versionShow the version and exit.
bs prepare
bs prepare [OPTIONS] PATH
Write the round PATH from the facts of your data.
Answer a short dialogue, or give the facts as flags. A PATH ending in .toml stores the round in one file. On an existing round, bs prepare rewrites each file's run tail from your edits; with --raw and the other volume flags, it first adds a volume to a round folder.
Example: bs prepare round_01 --raw data.zarr/raw/s0 --labels labels/s0 --labelled sparsely
Options (all text):
-
--rawThe image to segment: a Zarr array or container, a tif, or a folder of 2D images. A glob makes one volume per match. Example:
--raw data.zarr/raw/s0 -
--voxel-sizeThe raw's voxel size in nm, z y x, when its metadata has none. Example:
--voxel-size 50,4,4 -
--labelsThe traced objects to train on, as a path relative to the raw's container or an absolute path. Without labels, training does not use the volume. Example:
--labels labels/s0 -
--labelledHow the labels cover the raw: sparsely, densely, or a mask path (densely labelled within it). Example:
--labelled sparsely -
--untracedWith sparse labels, what fills the untraced space next to a traced object: other (objects) or background. Example:
--untraced background -
--target-maskSegment, refine and evaluate only inside this mask; predict covers the mask array's extent. Example:
--target-mask mask/s0 -
--gtThe ground truth for the evaluate step; 'labels' reuses the labels. bs prepare adds an evaluate step if any volume has ground truth. Example:
--gt labels -
--nameThe volume's name, used in its table names, such as [segment.apical]. The default is the container's file name, such as data-zarr. Example:
--name apical -
--modelsThe models in run order, by name or short form; the default fits the labels. Example:
--models 2M,3Af2L
bs run
bs run [OPTIONS] PATH
Run the steps of a config file in file order, or the numbered files of a directory.
Each run writes a receipt into runs/ with the keys each step read. Run bs run on a receipt to repeat its steps. Without --only or --from, bs run starts a directory round at its first unfinished or changed step. Use --from 01 to run all steps. For a single-file round, bs run repeats every selected step.
-
--onlyRun only these steps: a kind, kind.name, or a file prefix in a directory
-
--fromRun from this step to the end
-
--dry-runCheck the input paths and print what each selected step reads and writes, without running anything
bs view
bs view [OPTIONS] [PATH]...
View a round, one of its steps, a training snapshot or arrays in Neuroglancer.
bs view round_01 shows a round; bs view round_01 04 shows one step. Use -s for a training snapshot; bs view opens any other path as an array. It prints each layer, then the URL.
-
--snapshot/-sPath to the Zarr container of a snapshot
-
--bind/-bThe address to serve the viewer on
bs train
bs train [OPTIONS] CONFIG_FILE
Train the model of the [train.*] step of CONFIG_FILE.
The options override the values in the config file. A file with several train steps needs --step.
-
--step/-sThe train step to run when the file has several
-
--max-iterations/-nNumber of training iterations
-
--save-checkpoints-every/-ceSave checkpoints every n iterations
-
--save-snapshots-everySave snapshots every n iterations
-
--voxel-size/-vVoxel size in nm, z y x (space-separated integers)
bs predict
bs predict [OPTIONS] CONFIG_FILE
Run the [predict.*] steps of CONFIG_FILE in file order, or select one with --step.
-
--step/-sThe predict step to run when the file has several
-
--roi-offset/-roROI offset in world units, z y x (space-separated integers)
-
--roi-shape/-rsROI shape in world units, z y x (space-separated integers)
-
--num-workers/-wNumber of workers
-
--num-gpus/-ngNumber of GPUs to use
bs segment
bs segment [OPTIONS] CONFIG_FILE
Segment affinities using the [segment] settings in CONFIG_FILE.
Set the method key to ws, mws or cc, or override it with -ws, -mws or -cc.
-
--stepThe segment step to run when the file has several
-
--ws/-wsWatershed segmentation (waterz)
-
--mws/-mwsMutex watershed segmentation
-
--cc/-ccConnected components segmentation
-
--roi-offset/-roROI offset in world units, z y x (space-separated integers)
-
--roi-shape/-rsROI shape in world units, z y x (space-separated integers)
-
--blockwise/-bRun ws or mws over many daisy blocks. Without this flag, the blockwise key of the config applies, and an unset key means one block. cc cannot run blockwise.
-
--num-workers/-wNumber of workers, for blockwise segmentation
-
--block-shape/-bsBlock shape in voxels, z y x (space-separated integers). Use 'roi' for one block.
-
--block-context/-bcBlock context in voxels, z y x, for blockwise segmentation (space-separated integers)
-
--param/-pA method parameter that overrides the config, as key=value. Example:
-p 'thresholds=[0.2,0.3]'
bs refine
bs refine [OPTIONS] COMMAND [ARGS]...
Refine a segmentation: filter objects, remove or merge ids, mask, or apply morphology.
Each command reads one label array and writes another, block by block.
bs refine mask
bs refine mask [OPTIONS]
Zero every label outside a mask, blockwise.
-
--in-array/-iThe label array to read.
-
--mask/-mThe mask array, at the labels' voxel size. Labels become 0 where the mask is 0.
-
--out-array/-oThe label array to write. Default: the input path with the suffix _masked.
-
--num-workers/-wThe number of daisy workers that process the blocks.
bs refine morph
bs refine morph [OPTIONS]
Apply a morphological operation to a labelled volume, blockwise.
Each operation keeps the label ids (multilabel). With --xy, the operation runs on each z-section by itself; otherwise it runs in 3D over the block.
The halo (--context) adds the data around each block, up to the volume edge. Labels agree across block faces when the halo is at least the minimum in the --context help.
-
--in-array/-iThe label array to read.
-
--out-array/-oThe label array to write. Default: append the operation to the input path, such as labels_fill_holes.
-
--opThe morphological operation. fill-holes gives each region that one object encloses that object's id. It always fills background; it absorbs enclosed objects when the region has at most --max-area voxels.
-
--iterations/-nThe number of iterations for dilate, erode, opening and closing.
-
--max-areaThe largest enclosed region in which fill-holes absorbs objects, in voxels (pixels with --xy), such as 84000. A value of 0 keeps every object.
-
--exclude-idsLabel ids that dilate never grows and fill-holes never absorbs, such as 1,4,8. In config files, use exclude_ids = [1, 4, 8].
-
--xyApply the operation to each z-section in 2D instead of in 3D.
-
--context/-cThe halo in voxels, in xy with --xy and otherwise in xy and z. The minimum is the iteration count for dilate and erode, twice the iteration count for opening and closing, and the width of the largest hole plus its wall for fill-holes.
-
--block-size/-bThe write-block size in xy, in voxels, rounded to a multiple of the chunk size. In z, each block is one chunk deep.
-
--num-workers/-wThe number of daisy workers that process the blocks.
bs refine outlier-filter
bs refine outlier-filter [OPTIONS]
Remove objects whose size is an outlier, large or small, blockwise.
The command removes an object when its voxel count differs from the mean by more than num_std standard deviations. The mean and the standard deviation include only the objects of at least min_size voxels.
-
--in-array/-iThe label array to read.
-
--out-array/-oThe label array to write. Default: the input path with the suffix _outlier_filtered.
-
--num-std/-nRemove objects whose size differs from the mean by more than this many standard deviations.
-
--min-sizeCompute the mean and standard deviation from the objects with at least this many voxels.
-
--num-workers/-wThe number of daisy workers that process the blocks.
-
--dry-runPrint the size cutoffs and the number of objects to remove without writing.
bs refine remap
bs refine remap [OPTIONS]
Remove label ids, merge groups of ids, or both, blockwise.
-
--in-array/-iThe label array to read.
-
--out-array/-oThe label array to write. Default: the input path with the suffix _remapped.
-
--remove-ids/-rComma-separated label ids to remove (set to 0)
-
--merge-ids/-mComma-separated label ids to merge into the first id of the group. Repeat the option for more groups.
-
--num-workers/-wThe number of daisy workers that process the blocks.
bs refine size-filter
bs refine size-filter [OPTIONS]
Remove objects outside a [min_size, max_size] voxel-count range, blockwise.
An object is one label id, and its size is its voxel count over the whole volume, even when the object spans blocks. A first pass counts the sizes, and a second pass removes the out-of-range ids block by block.
-
--in-array/-iThe label array to read.
-
--out-array/-oThe label array to write. Default: the input path with the suffix _size_filtered.
-
--min-sizeRemove objects smaller than this many voxels (dust)
-
--max-sizeRemove objects larger than this many voxels. With 0 or no value, the command keeps large objects.
-
--num-workers/-wThe number of daisy workers that process the blocks.
-
--dry-runPrint size statistics and the number of objects to remove without writing.
bs refine z-filter
bs refine z-filter [OPTIONS]
Remove thin objects that span few z-slices, blockwise.
A read-only pass finds the z-extent of each label over the whole volume (max z - min z + 1). A second pass removes the ids whose extent is min_z or less.
-
--in-array/-iThe label array to read.
-
--out-array/-oThe label array to write. Default: the input path with the suffix _z_filtered.
-
--min-z/-zRemove objects whose z-extent is this many slices or fewer
-
--num-workers/-wThe number of daisy workers that process the blocks.
-
--dry-runPrint the total object count and the number of objects to remove without writing.
bs evaluate
bs evaluate [OPTIONS] CONFIG_FILE
Evaluate segmentations using the [evaluate] settings in CONFIG_FILE.
-
--stepThe evaluate step to run when the file has several
-
--gt/-gtEvaluate only against ground truth
-
--pred/-pEvaluate only against predictions
-
--out-result/-oResult JSON path. Each volume gets its own file, and with several checks each file name also gets the check name.
bs utils
bs utils [OPTIONS] COMMAND [ARGS]...
Utility commands for arrays and segmentations.
bs utils bbox
bs utils bbox [OPTIONS]
Crop an array to the bounding box of its positive voxels.
Add padding with --padding. The default output is the input path with the suffix _bbox.
-
--in-array/-iPath to the input Zarr array.
-
--out-array/-oPath to the output array
-
--padding/-pPadding in voxels on each side of the bounding box, clipped to the input array.
bs utils convert
bs utils convert [OPTIONS]
Convert a 3D image or a directory of 2D images to a Zarr array.
-
--in-path/-iPath to the input 3D image, or to a directory of 2D images
-
--out-array/-oPath to the output Zarr array
-
--dtype/-dOutput data type
-
--voxel-size/-vsSize of each voxel in physical units (space-separated integers)
-
--voxel-offset/-voOffset in voxels (space-separated integers)
-
--axis-names/-axNames of the axes (space-separated strings)
-
--units/-uPhysical units of the axes (space-separated strings)
-
--crop/-cCrop to the bounding box of positive voxels
bs utils download-ckpts
bs utils download-ckpts [OPTIONS]
Download the checkpoints of the shipped models.
Use --model-name to select models and --setup-dir to select their destination. Without these options, the command downloads each shipped model's checkpoint to its folder in bootstrapper/models.
Options (all text):
-
--model-name/-mThe models to download, by name or short form, separated by commas. Example:
-m 3Af2M -
--setup-dir/-sThe directory to download the checkpoints to
bs utils mask
bs utils mask [OPTIONS]
Write a mask of a Zarr image or labels array, blockwise.
With --mode raw, the mask is the nonzero voxels of the image, closed in xy. With --mode labels, it is labels > 0. The default output of raw/s0 is raw_mask/s0.
-
--in-array/-iThe path of the input Zarr array
-
--out-array/-oThe path of the output mask Zarr array
-
--mode/-mraw masks an image, and labels masks objects
bs utils merge
bs utils merge [OPTIONS]
Apply the merges of a LUTs file to a segmentation, blockwise.
The LUTs file is JSON. Its "merges" maps each new id to the list of ids that merge into it.
-
--in-seg/-iThe path of the input segmentation Zarr array
-
--out-seg/-oThe path of the output segmentation Zarr array
-
--luts/-lPath to the LUTs file
bs utils scale-pyramid
bs utils scale-pyramid [OPTIONS]
Create a scale pyramid of a Zarr array, in place.
An array that is not a scale level moves into a group of the same name. It becomes s0 for --mode down, or sN for N upscaling levels. A scale-level input such as raw/s1 keeps its level, unless upscaling needs levels below s0. Downscaling writes higher levels and upscaling writes lower levels, so a lower level is always finer.
-
--in-array/-iThe path of the input Zarr array, which may already end in a scale level
-
--scales/-sSpatial scale factors for one level. Repeat -s for each level. Example:
-s 2,2,2 -
--chunk-shape/-cSpatial chunk shape in voxels. The default is the input's. Example:
-c 64,64,64 -
--mode/-m -
--labels/--image--labels samples ids. --image averages intensities to downscale and interpolates them to upscale. The default is --labels for uint32, uint64, or a name with label, lbl, ids, mask or seg
bs utils tissue-mask
bs utils tissue-mask [OPTIONS] RAW OUT
Write a tissue mask of a raw array, with no holes.
On each section the mask is raw > 0, closed with a disk of --radius, with its holes filled. A section below half the median tissue coverage takes the OR of its nearest valid sections above and below. Folds and black sections thus stay inside the mask, so bs refine mask keeps their labels.
Example: bs utils tissue-mask vol.zarr/raw/s1 vol.zarr/masks/tissue/s1
-
--radius/-rDisk radius in voxels: 24 at 4 nm (about 100 nm), 12 at 8 nm
-
--num-workers/-wThe number of worker processes. Allow about 80 bytes per voxel of one section (3.8 GB at 4926 x 9750).