copick convert seg2fil
utils
Trace filaments in segmentations.
Plugin command — copick-utils
This command is provided by the copick-utils plugin, not copick core. Install it to make this command available:
See the plugin system guide for details.
Trace filaments in segmentations.
Usage
Description
Traces the centreline of every filament (e.g. microtubules or actin) in a segmentation and
stores it as a copick Filaments entry: an editable Catmull-Rom curve through the filament's
fitted spline (--curve bspline stores the fit itself) and the centreline points copick
regenerates from it. Filaments are numbered 1, 2, ... by length, longest first.
Each connected component is skeletonized and split into branches between ends and junctions.
Holes up to --fill-lumen are filled first, so a tube labelled by its wall alone traces as one
filament. Side branches shorter than --prune-length are pruned, and at each junction the branches
that continue most nearly straight (within --max-bend) are joined, so two crossing
filaments stay two filaments. Free ends are extended to the edge of the segmentation, and
filaments shorter than --min-length, shorter than --min-aspect label diameters (blobs),
or thinner than --min-radius (slivers of segmentation noise) are rejected. Options left
unset are derived from the segmentation's own thickness or the object's radius.
The input can be a binary, multilabel (--label), panoptic or instance segmentation. An
instance segmentation, for example one edited by hand or written by --instances, is traced
one instance at a time and keeps its IDs. Sample picks from the filaments with
copick convert fil2picks.
URI Format
Segmentations: name:user_id/session_id@voxel_spacing
Instance or panoptic input: append ?instance=true or ?panoptic=true
Filaments: object_name:user_id/session_id
Options
| Option | Type | Default | Description |
|---|---|---|---|
-c, --config |
path | — | Path to the configuration file. |
--run-names, -r |
text · multiple | — | Specific run names to process (default: all runs). Repeatable; pass -r once per run. |
--debug / --no-debug |
boolean flag | False |
Enable debug logging. |
Input Options
| Option | Type | Default | Description |
|---|---|---|---|
--input, -i |
COPICK_URI | required | Input segmentation URI (format: name:user_id/session_id@voxel_spacing). Supports glob patterns. Append ?instance=true or ?panoptic=true to read those segmentation types. |
Tool Options
| Option | Type | Default | Description |
|---|---|---|---|
--min-length |
float | — | Reject filaments shorter than this (unit: --length-unit). Unset: no length filter. |
--min-aspect |
float | 3.0 |
Reject filaments shorter than this many label diameters (compact blobs and specks). The default rejects only microtubule-thick stubs under ~44 nm on dataset 10521. |
--min-radius |
float | — | Reject filaments whose median label radius is below this (unit: --length-unit): thin slivers of segmentation noise. Unset: a third of the object's (tube) radius. |
--fill-lumen |
float | — | Before tracing, fill holes up to this radius (unit: --length-unit) in every slice of the label, so a tube whose wall alone is labelled traces as one filament. Unset: the object's (tube) radius; 0: no filling. |
--min-volume |
float | — | Drop connected components smaller than this before tracing (unit: --volume-unit). Unset: no volume filter. |
--prune-length |
float | — | Prune skeleton side branches shorter than this (unit: --length-unit). Unset: one label diameter. |
--junction-merge |
float | — | Merge junctions joined by a bridge up to this long, as two crossing filaments often skeletonize (unit: --length-unit). Unset: one label diameter. |
--max-bend |
float | 45.0 |
Largest deviation from a straight line, in degrees, for a filament to continue through a junction. |
--smoothing |
float | — | RMS deviation of the fitted spline from the skeleton (unit: --length-unit). Unset: half a voxel. |
--extend-ends / --no-extend-ends |
boolean flag | True |
Extend free filament ends along their direction to the edge of the segmentation (thinning shortens each end by about one radius). |
--label |
integer | — | Label to trace in a multilabel or panoptic segmentation (default: the output object's label). |
--length-unit |
choice (angstrom | voxel) | angstrom |
Unit of --min-length, --min-radius, --fill-lumen, --prune-length, --junction-merge and --smoothing. |
--volume-unit |
choice (angstrom | voxel) | angstrom |
Unit of --min-volume: 'angstrom' for ų, 'voxel' for cubic voxels. |
--workers, -w |
integer | 8 |
Number of worker processes. |
Output Options
| Option | Type | Default | Description |
|---|---|---|---|
--output, -o |
COPICK_URI | required | Output filaments URI. Supports smart defaults (e.g., "microtubule", "microtubule/my-session", or "/my-session"). Full format: object_name:user_id/session_id. |
--instances, -oi |
COPICK_URI | — | Also write the instance segmentation of the traced filaments (each voxel holds the ID of its filament, the same IDs as the filaments). Smart defaults as for -o; ?instance=true is implied. |
--curve |
choice (catmull-rom | bspline) | catmull-rom |
Curve stored for each filament: 'catmull-rom' control points through the fitted spline (within half a voxel of it), which ChimeraX-copick and napari-copick edit freely; 'bspline' the exact fit, whose control points can be moved but not added or removed. |
Examples
# Trace microtubules and keep the instance segmentation of the traced filaments
copick convert seg2fil -i "microtubule:easymode/job006@10.0" \
-o "microtubule:trace/1" --instances "microtubule:trace/1@10.0?instance=true"
# Reject filaments shorter than 100 nm
copick convert seg2fil -i "microtubule:easymode/job006@10.0" -o "microtubule:trace/1" --min-length 1000
# Re-trace an edited instance segmentation, keeping its IDs
copick convert seg2fil -i "microtubule:curated/1@10.0?instance=true" -o "microtubule:trace/curated"
See also
copick convert fil2picks— sample picks along the traced filamentscopick convert fil2seg— paint tubes around filaments into an instance segmentationcopick process fit-spline— segmentation to picks in one step (older, voxel units)copick process seg-stats— component and skeleton statistics to choose thresholds
Filament workflow
Filaments are traced once and sampled as often as needed. Three commands share one set of IDs:
copick convert seg2filtraces a segmentation into a Filaments entry: one editable Catmull-Rom curve per filament, through its fitted spline and within half a voxel of it (--curve bsplinestores the fit itself), and the centreline copick evaluates from it. With--instancesit also writes the instance segmentation of the traced filaments, whose voxel values are the filament IDs.copick convert fil2picks --spacingsamples picks along each curve, ordered along the filament and grouped by its ID, with each pick's +Z along the filament. Sampling at another spacing needs no new trace.copick convert fil2segpaints a tube around each filament into an instance segmentation, for filaments traced or edited by hand.
Picks of an object declared a filament carry RELION's filament columns (rlnHelicalTubeID, track length, priors)
through copick export picks --filament-columns.
Microtubules in a tomogram of CZ cryoET Data Portal dataset 10521: the segmentation (left), and the filaments traced from it with picks every 82 Å, coloured by ID (right). Three microtubules cross near one point; each keeps its own ID.
Choosing thresholds
- Thin slivers of segmentation noise are removed by
--min-radius, which defaults to a third of the object's radius.copick process seg-stats --skeletonreports each component's skeleton length and label radius, to check where a dataset's filaments and its noise fall. - A label that covers only a tube's wall is filled before tracing (
--fill-lumen, the object's radius by default), so it traces as one filament rather than as fragments of the wall. - Short pieces that pass every other filter can be removed with
--min-length, which has no default.