Skip to content

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

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

PaulHax wants to merge 2 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. This PR 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 masks are now addressed by their segment, and slice views stop creating one actor per mask. Copying segments between images is an explicit action.

Replaces #1005 and #1015.

Per-image segment sets

  • Keep images independent. Editing one image's segments does not change another image's set.
  • Start from the configuration. An image's set is created when the image is first shown or edited: the configured segments, or none without a configuration. It never depends on which image was shown before.
  • Copy on request. "Copy segments from..." under "New segment" lists the other images that have segments. Choosing one adds the segment names and appearance the current image lacks. Masks and shapes are not copied, and a same-named segment on the current image is left as it is.
  • Merge by name. Anything that arrives later for an image that has a set merges into it by name; nothing replaces it.
  • Unique names. Segment names are unique within an image. Adding or renaming to a taken name gives a numbered name such as Tumor (2).
Situation Result
Image shown or edited for the first time The configured segments, or an empty list without a configuration.
Return to an image Keep its own set.
Image loaded with matched segmentation files Start from the configured segments, then bind incoming labels by name.
Saved session Each image restores its saved set, including an empty one. An image the session saved no set for starts from the current configuration when it is first shown or edited. A session that targets an image which already has a set merges into it by name.
Configuration, loaded alone or with images On every image that has a set, stated fields are written onto same-named segments and missing names are added; other images take the configured segments when first shown or edited. If a configuration 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.

A configuration is a template, not a layer that can be taken off again. It never removes or resets a segment: fields it omits keep their current value, {} or null only makes new images start empty, and a configured name that was renamed on an image is added again as a new row. See configuration behavior.

Matching names does not merge or overwrite existing voxels. One rule covers labelmap import and session restore: an incoming segment that brings a mask joins the same-named segment only if that segment has no mask. Otherwise it gets a numbered name. See segment matching.

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 no longer carries a parallel mask model beside the segment set.

  • 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.
  • One way in. Labelmap import, session restore, configuration and processing results seat incoming segments by name through one registry function, seatSegment. Labelmap conversion, decoding and splitting live in src/segmentation/io/labelmapImport.ts, outside the mask store.
  • One kind of empty. A segment with no voxels has no mask. A label that a file or a processing result declares but that holds no voxels becomes a segment without a mask, so readers ask whether a mask exists.
  • Rendering that follows overlap, not segment count. Each slice view writes the 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, so a view draws one actor per overlap plane. 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. Only voxel writes that reach the shown slice recompose it, and appearance and visibility changes update the lookup tables without recomposing. En face uses the same lookup path.

Commits

  1. 91a5912 isolate segments by image and address masks by segment. Everything above except the copy action, with manifest 8.0.0 and the migration from shared catalogs.
  2. 2fabb86 copy segments from another image. The "Copy segments from..." row and menu.

Manifest 8.0.0

The segment data is one tree per image:

imageSegments: [{
  imageId, selectedSegmentId?, display?,
  segments: [{ id, name, color, visible, locked, fillOpacity?, outlineOpacity?,
               strokeWidth?, labelmap?: { path, extent, source? } }]
}]
  • The top-level segments[] and segmentations[] are gone. Array order is segment order, and a segment's mask is its labelmap.
  • Saved segment ids are scoped to their image. Tools and en face views resolve a saved id together with the image they belong to.
  • Each mask's archive entry is named at save from its image and segment names, so the path can change when a segment is renamed. The default export file name is the image name.
  • No starting segments are saved. An image without a saved set follows the configuration in use when the session is opened.
  • segmentationArtifacts is unchanged.
  • 7.0.0 manifests migrate by copying the shared catalog under every image with its original ids, moving each mask onto its segment and each segmentation's display onto its image, without duplicating voxels. A 7.0.0 segmentation's own name is dropped. Masks a 7.0.0 segmentation left out of its order are reported as skipped, and a 7.0.0 catalog saved without any image is dropped.

Other behavior changes

  • New images. On main every image shows the one shared catalog. Now an image starts from the configured segments or empty; "Copy segments from..." brings another image's segments over.
  • 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.
  • Empty labels. A declared label without voxels, a saved mask with an empty extent and a mask whose archive entry is missing all restore as a segment with no mask; a missing entry is still reported. Such a segment is not written into an exported labelmap or a processing input, and a later import or restore may reuse it by name.
  • Annotations on a foreign segment. A saved annotation whose segment id is not on its own image restores as a shape with no segment.
  • Fill color. Colors are exact per label. The previous tables left a blend toward black of at most one 8-bit level.

@netlify

netlify Bot commented Nov 15, 2026 •

Copy link
Copy Markdown

✅ Deploy Preview for volview-dev ready!

Name Link
🔨 Latest commit 2fabb86
🔍 Latest deploy log https://app.netlify.com/projects/volview-dev/deploys/6afbfd12ec4129a3517ed9d8
😎 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
@PaulHax
PaulHax force-pushed the segment-model-fold branch 4 times, most recently from e6a22d1 to 162dcb7 Compare November 17, 2026 02:31
…ment

Every image shared one segment catalog, so renaming or deleting a
segment while viewing one image changed every other image. Each image
now owns its segment set: definitions, order, selection, display
settings and at most one mask per segment, keyed by segment id. Paint,
rectangles, polygons and rulers on an image share its set.

- an image's set starts from the current config's segments, or empty
  without a config, on its first view or edit, whatever was shown before
- a config is a template: it writes its stated fields onto same-named
  segments of every set, adds missing names and seeds new sets. It
  never removes or resets a segment
- segment names are unique per image; a taken name gets a numbered one
- labelmap import, session restore, config and processing results seat
  incoming segments by name through one registry function. A segment
  that brings a mask joins a same-named segment only if that one has no
  mask
- a label a file or result declares without voxels is a segment with no
  mask, so a mask always holds at least one voxel outside an edit
- labelmap conversion lives in src/segmentation/io/labelmapImport.ts,
  outside the mask store
- mask ids and Segmentation records are gone: editing, voxel access,
  rendering, export, processing, en face and the state file address a
  mask by its segment
- slice views compose the masks on the shown slice into shared Uint8
  label planes, one actor per overlap plane instead of one per mask;
  only writes that reach the shown slice recompose it, and hiding a
  segment only changes its plane's lookup table
- manifest 8.0.0 saves one imageSegments entry per image: selection,
  display and its segments in order, each with its mask. Saved segment
  ids are scoped to their image. Mask archive entries are named at save
  from the image and segment names. 7.0.0 manifests migrate by copying
  the shared catalog under each image with its original ids, without
  duplicating voxels
A "Copy segments from..." row under "New segment" lists the other
images that have segments. Choosing one adds the segment names and
appearance the current image lacks. Masks and shapes are not copied,
and a same-named segment on the current image is left as it is.

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