Skip to content

fix(segmentation): isolate segments by image and address masks by segment - #1035

Open
PaulHax wants to merge 6 commits into
Kitware:mainfrom
PaulHax:segment-model-fold
Open

PaulHax wants to merge 6 commits into
Kitware:mainfrom
PaulHax:segment-model-fold

Conversation

@PaulHax

@PaulHax PaulHax commented Nov 15, 2026 •

Copy link
Copy Markdown
Collaborator

Deleting or renaming a segment while viewing one base image also changed every other image, because all images shared one segment catalog. The first commit gives each image its own segment definitions, order and selection, shared by Paint, rectangles, polygons and rulers on that image. With segments per image, mask ids and the Segmentation record repeat what the segment id and the image's segment set already say, so the remaining commits remove that duplication and stop the slice views from creating one actor per mask.

Replaces #1005 and #1015. #1015's commit is the first commit here, unchanged.

Per-image segment sets

  • Keep images independent. Editing one image's segments does not change another image's set.
  • Carry setup forward. A new image copies the last active image's definitions, order and selection, with fresh identities and no masks or shapes. With no previous set, it uses configured defaults.
  • Decide a set once. An image's set is created when the image arrives. Anything that arrives later for that image merges into the set by name; nothing replaces it.
Situation Result
Image loaded with nothing else On first view or edit, copy the previous image's setup, or use configured defaults.
Return to an initialized image Keep its own set; do not copy again.
Image loaded with matched segmentation files Start from configured defaults before the image is shown, then bind incoming labels by name.
Saved session Each restored image gets its saved set before views are assigned. A session that targets an image which already has a set merges into it by name.
Config, loaded alone or with images Apply to every loaded image by name and update starting defaults. A loaded image without a set takes the configured segments as its set. If a config is loaded alongside a session, it applies after restore.

"Matched segmentation files" means labelmaps associated with the primary image chosen for the initial load: filename matches such as scan.seg.nii.gz or scan.seg.nrrd for scan.nrrd (the seg marker is configurable), or DICOM SEG volumes from the same study. File format alone does not establish the association. See the matching path.

Matching names does not merge or overwrite existing voxels. Labelmap import reuses an exact-name segment only if it has no mask; session restore requires no mask or shape. Otherwise the incoming segment gets a numbered name such as Tumor (2). Configs deliberately reapply names and appearance; removing a config entry only deletes a row that the config created and that has no mask or shape. See segment matching and configuration behavior.

One consequence of merging: a session loaded onto an image that is already open keeps that image's existing empty segments beside the restored ones.

Processing results and image removal are scoped to their destination images. Unlike #1005, there is no deferred initialization or loading state.

One segment model

A segment belongs to exactly one image, a segment has at most one mask, and an image has exactly one segmentation. The code carried both the segment set and a parallel mask model: two per-image containers, two orders, two id spaces, and lookups and guards that exist only to keep them in step.

  • One container per image. An image's segment set holds its definitions, order, selection, display settings and masks. Masks are keyed by segment id.
  • One id space. Editing, voxel access, rendering, export, processing, en face, import and the state file all address a mask by its segment.
  • Rendering that follows overlap, not segment count. A slice view draws one actor per overlap plane.

Commits

Each commit builds and can be reviewed on its own.

  1. 32da1d9 isolate segment definitions by image. The per-image segment sets described above, with manifest 8.0.0 and the migration from shared catalogs.
  2. cfaf4c5 seat incoming segments through one registry function. Labelmap import, session restore, config and processing results each chose a segment by exact name with their own code. They now call seatSegment with a reuse policy. The rules themselves are unchanged.
  3. 2b01fad move labelmap conversion out of the mask store. Conversion, decoding and splitting move to src/segmentation/io/labelmapImport.ts.
  4. f80cc01 compose slice masks into shared label planes. Each slice view writes the visible masks on its slice into shared Uint8 label planes, one label per mask. A mask moves to the next plane only where it overlaps a claimed pixel, the same first-fit rule export uses. A plane holds at most 255 labels because the vtk.js label outline shader reads labels as 8-bit. Label lookup tables use a fixed range with a flat plateau per label: the mapper samples a 1024-texel table, and tables with a point per integer label blend in the neighboring label. Appearance changes update tables without recomposing. En face uses the same lookup path.
  5. 7eb7b45 fold masks into each image's segment set. Introduces ImageSegments and removes SegmentMask, Segmentation, mask order, the mask-id render projection and the mask reference hook between the two stores. The state-file wire becomes two module functions, which also removes an import cycle between the store and the wire. The saved manifest shape is unchanged in this commit.
  6. 921840f key saved masks by segment in manifest 8.0.0. See below.

Manifest 8.0.0

8.0.0 saves per-image membership, order, selection and defaults. The migration splits older shared catalogs into independent per-image sets without duplicating voxels. When an older manifest's per-file datasets resolve to one image, the copies of each legacy definition resolve to one segment on that image.

The first commit introduces 8.0.0 and the last commit reshapes it, so it ships in its final shape:

  • imageSegmentSets[] gains optional name and display (fillOpacity, outlineOpacity, outlineThickness).
  • segmentations[] becomes { parentImage, masks: [{ segmentId, representations: { labelmap } }] }, written only for images that have masks. Mask ids and order are gone, and labelmap is required.
  • segmentationArtifacts is unchanged.
  • 7.0.0 and older manifests migrate as before. Masks a 7.0.0 segmentation left out of its order are still reported as skipped.

Other behavior changes

  • Mask order. Masks are listed and saved in segment order. They were kept in creation order. This affects save order, the en face segment list, and which plane overlapping masks are drawn on.
  • Masks restored without voxels. A saved mask with no labelmap, or whose archive entry is missing, now restores as no mask; it used to restore as an empty record. The segment is kept and a missing entry is still reported. Such a segment is no longer exported as an empty label, and a later import or restore may reuse it by name. A mask that covers nothing but was declared by a file or a processing result is unchanged.
  • Fill color. Colors are exact per label. The previous tables left a blend toward black of at most one 8-bit level.

Not in this PR

Import and restore keep their different reuse rules: import reuses a same-name segment when it has no mask, and restore when it has no mask or shape.

…unction

Labelmap import, session restore, config and processing results now choose a
segment by exact name through seatSegment, each passing its reuse policy,
instead of four separate implementations.
Labelmap conversion, decoding and splitting now live in a labelmapImport
store under io/, which creates masks through the segmentation store's
operations. The mask store keeps records, lookup, lifecycle and voxel access,
and the state-file wire no longer receives the decode and split functions.
Each 2D slice view writes the visible masks on its slice into shared
Uint8 label planes, one label per mask, and moves a mask to the next
plane only where its pixels overlap a claimed pixel. One actor draws
each plane with per-label lookup and outline tables, so the actor count
follows the overlap depth on the slice instead of the segment count.

Label lookup tables use a fixed range with a flat plateau per label so
the mapper's texel sampling never blends in a neighboring label.
Each image now holds one segment set: order, selection, display, the
segment definitions and a mask per segment, keyed by segment id. Mask
ids, Segmentation records and mask order are gone, along with the
lookups that translated between them.

- the registry owns masks and display through imageStorage.ts; deleting
  a segment or an image drops its masks directly
- store.ts keeps the voxel operations, addressed by segment id
- the state file wire is a pair of module functions, which removes the
  store import cycle and the injected store functions
- a segment has a mask, possibly covering nothing, or none: a restored
  mask with no voxels and no artifact restores nothing, and save no
  longer writes masks without a labelmap
- masks are walked and saved in segment order

The 8.0.0 manifest shape is unchanged; a saved mask's id is its
segment id.
Manifest 8.0.0 is unreleased, so its segmentation records take the
shape of the folded model:

- a saved mask names only its segment; mask ids and the mask order are
  gone, and masks restore in segment order
- display settings and the segmentation label sit on the image's
  segment set
- segmentations list only images with masks, and every saved mask has
  a labelmap

The 7.0.0 migration orders masks by their old order and drops their
ids, reports the masks that order left out, and moves display onto the
segment set. An image with no segment set keeps its display through
the migration context, since an empty saved set would stop it from
inheriting one.
@netlify

netlify Bot commented Nov 15, 2026 •

Copy link
Copy Markdown

✅ Deploy Preview for volview-dev ready!

Name Link
🔨 Latest commit 921840f
🔍 Latest deploy log https://app.netlify.com/projects/volview-dev/deploys/6af9d60434ea5ebd681186ab
😎 Deploy Preview https://deploy-preview-1035--volview-dev.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

@PaulHax PaulHax changed the title refactor(segmentation): address masks by segment and compose slice planes fix(segmentation): isolate segments by image and address masks by segment Nov 15, 2026
@PaulHax
PaulHax marked this pull request as ready for review November 15, 2026 18:21

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant