copick process expand-labels

utils

Expand labels in segmentations to fill holes and gaps.

Plugin command — copick-utils

This command is provided by the copick-utils plugin, not copick core. Install it to make this command available:

pip install copick-utils

See the plugin system guide for details.

copick process expand-labels input — Input

copick process expand-labels output — Output

Expand labels in segmentations to fill holes and gaps.

Usage

copick process expand-labels [OPTIONS]

Description

Uses scikit-image's expand_labels to grow label regions outward by a specified distance without overlapping into neighboring regions. Useful for filling small holes in segmentations or closing gaps between label boundaries.

When --max-hole-size is specified, expansion is restricted to only fill background holes smaller than the given volume. This prevents labels from expanding beyond their natural borders (e.g., filling internal holes in a cell without expanding outward into the surrounding background). Use seg-stats --include-background to determine appropriate hole size values.

URI Format

Segmentations: name:user_id/session_id@voxel_spacing

Options

Option	Type	Default	Description
`-c, --config`	path	—	Path to the configuration file.
`--debug / --no-debug`	boolean flag	`False`	Enable debug logging.

Input Options

Option	Type	Default	Description
`--run-names, -r`	text · multiple	—	Specific run names to process (default: all runs).
`--input, -i`	COPICK_URI	required	Input segmentation URI (format: name:user_id/session_id@voxel_spacing). Supports glob patterns.

Tool Options

Option	Type	Default	Description
`--distance, -d`	float	required	Distance by which to expand labels. Unit set by --size-unit (default: angstroms).
`--max-hole-size`	float	—	Maximum hole volume to fill. Only background regions smaller than this will be filled by expansion. When omitted, all background can be filled (original behavior). Unit set by --size-unit.
`--size-unit`	choice (angstrom \| voxel)	`angstrom`	Unit for --distance (Å or voxels) and --max-hole-size (Å³ or cubic voxels).
`--connectivity, -cn`	choice (face \| face-edge \| all)	`all`	Connectivity for background hole analysis (face=6-connected, face-edge=18-connected, all=26-connected).
`--workers, -w`	integer	`8`	Number of worker processes.

Output Options

Option	Type	Default	Description
`--output, -o`	COPICK_URI	required	Output segmentation URI. Supports smart defaults (e.g., "membrane", "membrane/my-session", or "/my-session"). Full format: object_name:user_id/session_id@voxel_spacing.

Examples

# Expand labels by 20 angstroms
copick process expand-labels -i "membrane:user1/auto-001@10.0" -o "membrane_filled" --distance 20.0

# Fill only holes smaller than 500000 cubic angstroms
copick process expand-labels -i "membrane:user1/auto-001@10.0" -o "filled" \
    --distance 20.0 --max-hole-size 500000

# Fill holes using voxel units
copick process expand-labels -i "membrane:user1/auto-001@10.0" -o "filled" \
    --distance 20.0 --max-hole-size 500 --size-unit voxel

# Expand labels across specific runs
copick process expand-labels -i "organelle:user1/pred@10.0" -o "organelle_expanded" \
    --distance 15.0 -r run1 -r run2

# Expand with custom output URI
copick process expand-labels -i "membrane:user1/manual@10.0" -o "membrane:expand-labels/0@10.0" --distance 30.0