Skip to content

feat: instance and panoptic segmentations in copick-utils (v2.0) - #109

Merged
uermel merged 1 commit into
uermel/pick-identity-v2from
uermel/instance-tools-v2
Oct 6, 2026
Merged

feat: instance and panoptic segmentations in copick-utils (v2.0)#109
uermel merged 1 commit into
uermel/pick-identity-v2from
uermel/instance-tools-v2

Conversation

@uermel

@uermel uermel commented Oct 6, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Summary

Part 2 of 3 of filament support in copick-utils, v2.0 line (cherry-picked twin of the main PR). Stack (v2.0): #108 → #109 → #110; main twins #105 → #106 → #107. CLI docs: copick/copick#496.

copick now has instance segmentations (voxel value = instance ID) and panoptic segmentations (a label channel plus an instance channel), selected with ?instance=true / ?panoptic=true in a URI (copick/copick#481 → #482 → #493 → #495). This PR teaches copick-utils to read and write them:

  • Framework. Segmentation inputs and outputs take their type from the URI; a command writes the type its -o names or refuses one it cannot write. filaments joins picks, meshes and segmentations as a worker input type. io.readers.segmentation and io.writers.segmentation take the instance/panoptic flags. Untyped selections stay binary and multilabel.
  • separate-components with -o ...?instance=true writes one instance segmentation (IDs 1..K by size) instead of K binary ones; panoptic output from a multilabel or binary input. The per-component loops are vectorised.
  • filter-components drops whole instances by volume or by the new --min-skeleton-length, keeping the surviving IDs; multilabel input keeps its labels.
  • seg-stats reports per-instance rows; --skeleton adds skeleton length and label radius per component, for choosing thresholds.
  • combine -o ...?panoptic=true builds a panoptic segmentation from stuff labels plus per-object instance segmentations (--instances); split takes a panoptic input apart again.
  • process/skeleton_graph.py: a sparse 26-neighbour skeleton graph (branches, junctions, spur pruning, junction merging), shared with the filament tracer in part 3.

Tests

tests/test_instance_tools.py (separate, filter and stats keep IDs; a panoptic combine/split round trip; an untyped selection ignores a same-key instance store) and tests/test_skeleton_graph.py. The suite passes locally (78 tests).

🤖 Generated with Claude Code

This was referenced Oct 6, 2026
Merged
Merged
Merged
Merged
Merged
@uermel
uermel added this pull request to stack #114 October 6, 2026 09:07
@uermel
uermel marked this pull request as ready for review October 6, 2026 09:07
@uermel @claude
feat: instance and panoptic segmentations in copick-utils
1f650b1 
copick now has instance segmentations (voxel value = instance ID, the same IDs
as picks and filaments of the same user and session) and panoptic ones (a label
channel plus a per-object instance channel). copick-utils learns both:

Selecting types
- A segmentation URI selects its type with ?multilabel=true, ?instance=true or
  ?panoptic=true. Without one, inputs, references (--ref-seg), seg-stats and
  readers.segmentation() match binary and multilabel segmentations only, so a
  tool never reads an instance or 4D panoptic store that shares a name, user and
  session with a binary one.
- The output URI's type reaches converters that ask for it
  (output_segmentation_type), so a command can write the type its -o names.
- "filaments" is a selector input and output type, for the tracing commands.
- readers.segmentation(is_instance=, is_panoptic=) and
  writers.segmentation(instance=) read and write the new types.

Tools
- separate-components: -o ...?instance=true writes all components of a binary
  segmentation as one instance segmentation (IDs 1..K by size), and
  ?panoptic=true keeps every label of a multilabel input. The per-component
  output is unchanged, but no longer holds every component volume at once, and
  the size filter is one lookup table instead of a pass per component.
- filter-components: an instance input drops whole instances and keeps the IDs
  of the rest. A multilabel input is filtered label by label and keeps its
  labels (it was flattened to 1 while still flagged multilabel). New
  --min-skeleton-length drops specks and short blobs. Vectorised.
- seg-stats: one row per instance (instance_id column) or per panoptic
  segment; --skeleton adds skeleton length, label radius and branch, junction
  and endpoint counts.
- combine -o ...?panoptic=true takes regions from -i plus instance
  segmentations from --instances; split takes a panoptic input apart into an
  instance segmentation (things) and a binary segmentation (regions) per object.

process/skeleton_graph.py is the skeleton graph these share with the filament
tracer: a sparse 26-neighbour graph without staircase shortcuts, branches
between endpoints and junction clusters, spur pruning, and merging of junctions
joined by a short bridge.

Tests: tests/test_instance_tools.py, tests/test_skeleton_graph.py.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@uermel
uermel force-pushed the uermel/instance-tools-v2 branch from b2ec23b to 1f650b1 Compare October 6, 2026 09:14
uermel added a commit that referenced this pull request Oct 6, 2026
@uermel @claude
fix: pick tools keep identity and place particles at their centre (#105)
8a944f0 
## Summary

Part 1 of 3 of filament support in copick-utils. Stack (`main`): #105 →
#106 → #107; `v2.0` twins #108 → #109 → #110. CLI docs:
copick/copick#496.

Requires copick 1.28.0, which ships the filament stack
(copick/copick#479, #480, #492, #494). The first commit built against
the unreleased stack and the last one sets the floor, so squashed, the
dependency change is `copick>=1.28.0`.

The pick tools now treat a pick as the particle it describes:

- `picksin`, `picksout` and `clippicks` test each particle's centre
(`location` plus the transform's translation) and write the surviving
points unchanged: transform, instance ID, score and order. An empty
result writes an empty pick set instead of failing and leaving stale
output behind.
- `clippicks --ref-seg` indexed a (Z, Y, X) volume with (X, Y, Z)
indices; it now indexes it correctly, also for non-cubic volumes.
- `picks2seg` and the pick-to-mesh converters (`picks2sphere`,
`picks2ellipsoid`, `picks2plane`, `picks2surface`, `picks2mesh`) place
each particle at its centre.
- Shared helpers in `util/picks.py`.

## Tests

`tests/test_pick_tools.py`: identity and order survive the filters, a
shifted particle is filtered and painted at its centre, a non-cubic
`--ref-seg`, an empty result. Each fails on `main`. The suite passes
locally (45 tests); `main` has no pytest CI.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
uermel added a commit that referenced this pull request Oct 6, 2026
@uermel @claude
feat: instance and panoptic segmentations in copick-utils (#106)
100d838 
## Summary

Part 2 of 3 of filament support in copick-utils. Stack (`main`): #105 →
#106 → #107; `v2.0` twins #108 → #109 → #110. CLI docs:
copick/copick#496.

copick now has instance segmentations (voxel value = instance ID) and
panoptic segmentations (a label channel plus an instance channel),
selected with `?instance=true` / `?panoptic=true` in a URI (copick
1.28.0: copick/copick#479, #480, #492, #494). This PR teaches
copick-utils to read and write them:

- **Framework.** Segmentation inputs and outputs take their type from
the URI; a command writes the type its `-o` names or refuses one it
cannot write. `filaments` joins picks, meshes and segmentations as a
worker input type. `io.readers.segmentation` and
`io.writers.segmentation` take the instance/panoptic flags. Untyped
selections stay binary and multilabel.
- **`separate-components`** with `-o ...?instance=true` writes one
instance segmentation (IDs 1..K by size) instead of K binary ones;
panoptic output from a multilabel or binary input. The per-component
loops are vectorised.
- **`filter-components`** drops whole instances by volume or by the new
`--min-skeleton-length`, keeping the surviving IDs; multilabel input
keeps its labels.
- **`seg-stats`** reports per-instance rows; `--skeleton` adds skeleton
length and label radius per component, for choosing thresholds.
- **`combine -o ...?panoptic=true`** builds a panoptic segmentation from
stuff labels plus per-object instance segmentations (`--instances`);
**`split`** takes a panoptic input apart again.
- `process/skeleton_graph.py`: a sparse 26-neighbour skeleton graph
(branches, junctions, spur pruning, junction merging), shared with the
filament tracer in part 3.

## Tests

`tests/test_instance_tools.py` (separate, filter and stats keep IDs; a
panoptic combine/split round trip; an untyped selection ignores a
same-key instance store) and `tests/test_skeleton_graph.py`. The suite
passes locally (55 tests).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
uermel added a commit that referenced this pull request Oct 6, 2026
@uermel @claude
feat: filament tracing (seg2fil, fil2picks, fil2seg) (#107)
314885e 
## Summary

Part 3 of 3 of filament support in copick-utils. Stack (`main`): #105 →
#106 → #107; `v2.0` twins #108 → #109 → #110. CLI docs:
copick/copick#496.

Filaments such as microtubules had no real path to picks: `fit-spline`
kept one path per volume, and `seg2picks` treats every object as a
sphere. Three new `copick convert` commands trace, sample and paint
filaments, sharing one set of IDs between copick's Filaments entity,
instance segmentations and picks (copick 1.28.0: copick/copick#479,
#480, #492, #494):

- **`seg2fil`** traces every filament in a binary, multilabel, panoptic
or instance segmentation. Lumen-sized holes are filled first
(`--fill-lumen`), so a tube labelled by its wall traces as one filament.
Components are skeletonized and split into branches; spurs are pruned,
nearby junctions merged, and branches continue through a junction where
they run most nearly straight (`--max-bend`), so crossing filaments stay
separate. Ends are extended to the label's edge. Short (`--min-length`),
blob-like (`--min-aspect`) and thin (`--min-radius`) pieces are
rejected. Each filament's smoothing spline is stored exactly as an
editable `bspline` curve; `--instances` also writes the instance
segmentation of the traced filaments. Tracing an instance segmentation
keeps its IDs.
- **`fil2picks`** samples each filament's curve (any curve kind, or one
derived from its points) at a required `--spacing`, with +Z along the
filament and rotation-minimising frames, grouped by filament ID and
ordered along it.
- **`fil2seg`** paints tubes around filaments into an instance
segmentation.

The old commands are kept and fixed, each pointing to the new ones:

- `process fit-spline` fits every filament instead of the longest
hop-count path, with no O(N³) fallback; spacing is exact (in voxels, now
documented); orientations come from the spline's derivative with
rotation-minimising frames; sharp fits are smoothed further instead of
deleting skeleton points; picks carry filament IDs. New `--label` and
`--filaments`. `--connectivity-radius` is hidden and has no effect.
- `process skeletonize`: new `--prune-length` prunes spurs
(`--remove-short-branches` only ever removed whole small pieces, as its
help now says); the `-o` name is honoured.

The tracer (`process/filament_tracing.py`, numpy/scipy) is public for
copick-pipeliner.

## Acceptance

On the 58 easymode microtubule segmentations of CZ cryoET Data Portal
dataset 10521, run through the CLI:

- 102 filaments (34.5 µm) give 4,255 picks at 82 Å, none on specks.
Consecutive picks are 79.9–82 Å apart, frames turn at most 29° between
neighbours, and the median distance to the label's medial axis is 5.6 Å
(octopi's watershed picks: 6.1 Å; `fit-spline` 1.8.1: 7.1 Å, covering
42% of the traced length).
- IDs agree across the instance segmentation, Filaments and picks;
re-tracing the instance segmentation returns the same IDs.
- Every stored curve is current; resampling at 41 Å needs no re-trace.
- `copick export picks --filament-columns on` writes valid RELION
filament columns, and re-importing them keeps IDs, order and poses
exactly.

## Tests

`tests/test_filaments.py` on synthetic tubes (straight, along Y, arc,
crossing, ring, thick end, hollow tube, speck, blob, sliver), plus the
converter-signature, run-names and legacy-flag pinning tests. The suite
passes locally (84 tests).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
@uermel
uermel merged commit 1c1d8d9 into v2.0 Oct 6, 2026
7 of 12 checks passed
uermel added a commit that referenced this pull request Oct 6, 2026
@uermel @claude
fix: pick tools keep identity and place particles at their centre (v2…
d764eb7 
….0) (#108)

## Summary

Part 1 of 3 of filament support in copick-utils, `v2.0` line
(cherry-picked twin of the `main` PR). Stack (`v2.0`): #108 → #109 →
#110; `main` twins #105 → #106 → #107. CLI docs: copick/copick#496.

Requires copick 2.0.0a3, which ships the v2.0 filament stack
(copick/copick#481, #482, #493, #495). The first commit built against
the unreleased stack and the last one sets the floor, so squashed, the
dependency change is `copick>=2.0.0a3,<3`, with `uv.lock` resolving it
from PyPI.

The pick tools now treat a pick as the particle it describes:

- `picksin`, `picksout` and `clippicks` test each particle's centre
(`location` plus the transform's translation) and write the surviving
points unchanged: transform, instance ID, score and order. An empty
result writes an empty pick set instead of failing and leaving stale
output behind.
- `clippicks --ref-seg` indexed a (Z, Y, X) volume with (X, Y, Z)
indices; it now indexes it correctly, also for non-cubic volumes.
- `picks2seg` and the pick-to-mesh converters (`picks2sphere`,
`picks2ellipsoid`, `picks2plane`, `picks2surface`, `picks2mesh`) place
each particle at its centre.
- Shared helpers in `util/picks.py`.

## Tests

`tests/test_pick_tools.py`: identity and order survive the filters, a
shifted particle is filtered and painted at its centre, a non-cubic
`--ref-seg`, an empty result. Each fails on `v2.0`. The suite passes
locally (68 tests).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
uermel added a commit that referenced this pull request Oct 6, 2026
@uermel @claude
feat: filament tracing (seg2fil, fil2picks, fil2seg) (v2.0) (#110)
76c3236 
## Summary

Part 3 of 3 of filament support in copick-utils, `v2.0` line
(cherry-picked twin of the `main` PR; `fil2seg` reads the tomogram shape
through `get_level_array`, and the package smoke test counts 35 entry
points). Stack (`v2.0`): #108 → #109 → #110; `main` twins #105 → #106 →
#107. CLI docs: copick/copick#496.

Filaments such as microtubules had no real path to picks: `fit-spline`
kept one path per volume, and `seg2picks` treats every object as a
sphere. Three new `copick convert` commands trace, sample and paint
filaments, sharing one set of IDs between copick's Filaments entity,
instance segmentations and picks (copick/copick#481 → #482 → #493 →
#495):

- **`seg2fil`** traces every filament in a binary, multilabel, panoptic
or instance segmentation. Lumen-sized holes are filled first
(`--fill-lumen`), so a tube labelled by its wall traces as one filament.
Components are skeletonized and split into branches; spurs are pruned,
nearby junctions merged, and branches continue through a junction where
they run most nearly straight (`--max-bend`), so crossing filaments stay
separate. Ends are extended to the label's edge. Short (`--min-length`),
blob-like (`--min-aspect`) and thin (`--min-radius`) pieces are
rejected. Each filament's smoothing spline is stored exactly as an
editable `bspline` curve; `--instances` also writes the instance
segmentation of the traced filaments. Tracing an instance segmentation
keeps its IDs.
- **`fil2picks`** samples each filament's curve (any curve kind, or one
derived from its points) at a required `--spacing`, with +Z along the
filament and rotation-minimising frames, grouped by filament ID and
ordered along it.
- **`fil2seg`** paints tubes around filaments into an instance
segmentation.

The old commands are kept and fixed, each pointing to the new ones:

- `process fit-spline` fits every filament instead of the longest
hop-count path, with no O(N³) fallback; spacing is exact (in voxels, now
documented); orientations come from the spline's derivative with
rotation-minimising frames; sharp fits are smoothed further instead of
deleting skeleton points; picks carry filament IDs. New `--label` and
`--filaments`. `--connectivity-radius` is hidden and has no effect.
- `process skeletonize`: new `--prune-length` prunes spurs
(`--remove-short-branches` only ever removed whole small pieces, as its
help now says); the `-o` name is honoured.

The tracer (`process/filament_tracing.py`, numpy/scipy) is public for
copick-pipeliner.

## Acceptance

On the 58 easymode microtubule segmentations of CZ cryoET Data Portal
dataset 10521, run through the CLI:

- 102 filaments (34.5 µm) give 4,255 picks at 82 Å, none on specks.
Consecutive picks are 79.9–82 Å apart, frames turn at most 29° between
neighbours, and the median distance to the label's medial axis is 5.6 Å
(octopi's watershed picks: 6.1 Å; `fit-spline` 1.8.1: 7.1 Å, covering
42% of the traced length).
- IDs agree across the instance segmentation, Filaments and picks;
re-tracing the instance segmentation returns the same IDs.
- Every stored curve is current; resampling at 41 Å needs no re-trace.
- `copick export picks --filament-columns on` writes valid RELION
filament columns, and re-importing them keeps IDs, order and poses
exactly.

## Tests

`tests/test_filaments.py` on synthetic tubes (straight, along Y, arc,
crossing, ring, thick end, hollow tube, speck, blob, sliver), plus the
converter-signature, run-names and legacy-flag pinning tests. The suite
passes locally (107 tests).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
@github-actions github-actions Bot mentioned this pull request Oct 6, 2026
Merged
uermel pushed a commit that referenced this pull request Oct 6, 2026
@github-actions
chore(v2.0): release copick-utils 2.0.0-alpha.3 (#115)
456b4e8 
🤖 I have created a release *beep* *boop*
---


##
[2.0.0-alpha.3](copick-utils-v2.0.0-alpha.2...copick-utils-v2.0.0-alpha.3)
(2026-10-06)


### ✨ Features

* filament tracing (seg2fil, fil2picks, fil2seg) (v2.0)
([#110](#110))
([76c3236](76c3236))
* instance and panoptic segmentations in copick-utils (v2.0)
([#109](#109))
([1c1d8d9](1c1d8d9))


### 🐞 Bug Fixes

* pick tools keep identity and place particles at their centre (v2.0)
([#108](#108))
([d764eb7](d764eb7))

---
Merging this PR will publish a copick-utils alpha prerelease to PyPI.

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@uermel