Skip to content

refactor(dicom): unify loading and extract core and vtk modules - #994

Draft
PaulHax wants to merge 10 commits into
Kitware:mainfrom
PaulHax:dicom-loading
Draft

PaulHax wants to merge 10 commits into
Kitware:mainfrom
PaulHax:dicom-loading

Conversation

@PaulHax

@PaulHax PaulHax commented Oct 25, 2026 •

Copy link
Copy Markdown
Collaborator

DICOM files and URLs share one metadata-first pipeline that loads volumes frame by frame. Collections are planned the same way for batch and incremental imports, splitting incompatible acquisitions and pixel geometries while keeping stable identities, reconstruction details and session provenance.

The loader lives in packages/dicom. It is a directory of VolView source, not a separate package, and has no build of its own. Its public surface is two entry points, core/index.ts and vtk/index.ts, and lint lets src and tests import the module only through them. packages/dicom/README.md describes the API.

  • Core reads instances from byte sources (files, blobs, URLs with Range requests) using an AbortSignal, plans collections with a pure registry reducer, and allocates and fills a Volume buffer it owns. A runtime owns the request pool, metadata workers and GDCM decoder, and dispose() stops everything it started. Core imports no Vue, Pinia, vtk.js or application code.
  • vtk wraps the volume buffer in vtkImageData without copying and widens the scalar range as slices arrive.
  • VolView keeps its stores and UI. Each registry update says whether its collection is an image or a segmentation and whether it is new, unchanged or changed. An import plans and commits synchronously, so a series that fails changes nothing, and other series in the same import still land.

Loading order and decoding:

  • The slice in view loads first, then the rest coarse to fine. Scrolling re-prioritizes what is still queued.
  • Every unit of pixels loads one way. A pixel decoder plans, from the header alone, the units it would read and decode, and a decoder table lists candidates per transfer syntax in preference order. Uncompressed pixel data is planned as one ranged read per frame and decoded without GDCM, including multiframe files. Everything else is one unit per instance on a pool of GDCM workers. A caller adds a decoder by placing it in the table.
  • A frame of a local file is one Blob read. Decodes on the calling thread run back to back for a few milliseconds and then yield, so a server that ignores Range, which hands over every frame of a file at once, does not freeze the page while they decode.
  • Volumes use Float32 buffers where integer or fractional rescale allows. vtk.js renders Float32 without converting the whole volume on each 3D render, which Int32 and Float64 buffers required. Values for fractional rescale (for example PET and DSC) can differ from Float64 by Float32 rounding, and a few test expectations change by that rounding only.

Cine:

  • Whether a multiframe ultrasound instance plays as a clip is decided from its header, so no pixel bytes are read at import. The clip reads its header from the shared dataset and its pixel bytes when loading starts.
  • Encapsulated frames are cut by splitEncapsulatedFrames (Basic Offset Table, then one fragment per frame, then JPEG End Of Image markers). dicom-parser is no longer a dependency.

Behavior changes for reviewers:

  • A volume removed while a later import brings more files of its series comes back holding only the new files, the same as removing it before that import started.
  • A failed load raises one error notification per load attempt, titled with the series name, instead of one per slice or frame. Its message names the file, and the frame when one frame was lost, and says whether it could not be read or decoded.
  • Thumbnail failures no longer raise their own error notification, except when encoding the thumbnail image itself fails.
  • A clip whose pixel data cannot be read fails as a clip when it loads. It used to fall back to a volume import.
  • A malformed encapsulated Pixel Data stream is an error instead of a best-effort split.
  • An uncompressed file cut short loads the frames it still holds and reports the rest. From a local file the missing part used to be shown as zeros with no error.
  • An instance whose frames carry differing modality rescale fails from its header, before any pixel bytes are downloaded.
  • The modality rescale comes from a Pixel Value Transformation functional group only for the IODs that define it there (Enhanced and Legacy Converted CT, MR and PET, X-Ray 3D, breast tomosynthesis and projection, Segmentation), as GDCM reads it. Other SOP classes, such as multi-frame secondary capture and ophthalmic tomography, use the top-level Rescale.
  • An uncompressed file that declares more frames than its Pixel Data holds fails to load. It used to load with blank extra frames.
  • A series is planned within its study, so a Series Instance UID reused in another study or patient loads as its own volume.
  • When a restored session's files now load two saved images as one volume, neither image's annotations, layers or view settings are restored, and the restore notice names them.
  • An image with no Image Position (a radiograph, a secondary capture, a positionless multiframe) is named "(position unknown)" and warned about only when its series also holds a positioned volume.
  • A volume whose label or warnings change because a sibling arrived is renamed in place. It is no longer reallocated, and a warning that only becomes true later is raised then.
  • Patient, study and series text is trimmed of DICOM padding, so a study that holds a clip and a still image no longer shows a second, empty patient.
  • A series with no description, number or Series Instance UID is named "Unnamed series".
  • An HTTP failure reports its status. It used to say the resource could not be found for every status.
  • Files with unreadable content inside a defined-length sequence import, since the header scan steps over such sequences. Private elements are dropped in the metadata worker and never copied to the page.

The browser test pages under tests/fixtures/dicom-pages build straight from the module source and check calibrated voxel hashes, native and GDCM parity, and collection composition without VolView startup.

@netlify

netlify Bot commented Oct 25, 2026 •

Copy link
Copy Markdown

✅ Deploy Preview for volview-dev ready!

Name Link
🔨 Latest commit 09b01eb
🔍 Latest deploy log https://app.netlify.com/projects/volview-dev/deploys/6af9f738d19a175a3c3fb16c
😎 Deploy Preview https://deploy-preview-994--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 force-pushed the dicom-loading branch 6 times, most recently from e26844b to a23c9b3 Compare October 31, 2026 23:32
@PaulHax
PaulHax force-pushed the dicom-loading branch 3 times, most recently from b341c94 to 240e9de Compare November 13, 2026 02:15
DICOM files and URLs share one metadata-first pipeline that loads
volumes frame by frame. Collections are planned the same way for batch
and incremental imports, splitting incompatible acquisitions and pixel
geometries while keeping stable identities, reconstruction details and
session provenance.

The loader lives in packages/dicom. Core reads instances from byte
sources with an AbortSignal, plans collections with a pure registry
reducer, and fills a Volume buffer it owns. The vtk entry point wraps
that buffer in vtkImageData and widens its scalar range as slices
arrive. VolView keeps its stores and UI; each series commits in one
synchronous step, so a failed series changes nothing.

The viewed slice loads first, then the rest coarse to fine, on a pool
of GDCM decode workers. Uncompressed pixel data is decoded per frame
without GDCM. Volumes use Float32 buffers where integer or fractional
rescale allows, which vtk.js renders without conversion.
Remove the standalone package build. packages/dicom is a plain directory
whose public surface is core/index.ts and vtk/index.ts, enforced by lint.
The browser test pages build straight from source.

Load every unit of pixels one way. Native frames and GDCM are both pixel
decoders that plan units from a header, the decoder table lists candidates
per transfer syntax in preference order, and loadVolume has one read,
decode and write path. A decoder's units must cover every frame exactly
once. Pixels are written when a decode completes and a slice is marked
loaded when its update is yielded.

Let the plan say what a collection is. Registry updates carry whether a
collection is an image or a segmentation and whether it is new, unchanged
or changed, so allocateVolume returns a Volume and importInstances plans
and commits synchronously.

Decide cine from the header. A clip is built from its instance, reads its
pixel bytes when loading starts, and cuts encapsulated frames with
splitEncapsulatedFrames, so dicom-parser is no longer a dependency. A clip
whose pixel data cannot be read now fails as a clip at load instead of
falling back to a volume import, and malformed encapsulated streams throw.

Keep only DICOM in the module. The URI fetcher returns to
src/core/streaming, itk-wasm loads when GDCM first decodes so the core
entry point imports in Node, and core may import only relative paths,
comlink, dcmjs and itk-wasm.
A SEG whose bytes could not be read or parsed left its thumbnail pending,
so the patient browser showed a spinner indefinitely. The thumbnail now
resolves to none once the load fails, and a retry clears the failure.
One unreadable file in a downloaded series marked the whole download as
failed, even though the rest of the series loaded as a volume. The loaded
volume is now shown and each failed file is reported, warning that the
volume may be incomplete. A download that loads no volume still fails.
Report failures where they happen. A read or decode failure names the
file, and the frame when it lost one, and keeps the thrown value as its
cause. A failed load raises one notification per attempt, titled with
the series name. An uncompressed file cut short loads the frames it still
holds and fails the rest instead of showing zeros. GDCM declines an
instance whose frames differ in modality rescale from its header, before
any pixel bytes are read. An HTTP failure reports its status.

Fix what the registry tells the store. A collection's change is decided
from its members, orientation and reconstruction, so a relabel no longer
reallocates its volume, and an update is emitted when a sibling changes
its label or warnings. A positionless image is named and warned about
only beside a positioned volume of its series. Patient, study and series
text is trimmed, a series with no identifying tags is named "Unnamed
series", a thumbnail settles again after a retry, and an import no
longer reports a volume it brought no file for.

Load faster and release what is done. A Blob range is one slice, so a
local frame is one read. Decodes that return at once run for a few
milliseconds and then hand the thread back. A pooled request is released
once its body is read. The header scan steps over defined-length
sequences, and private elements are dropped in the metadata worker.

Remove what nothing needs: the resume path of CachedStreamFetcher, the
GDCM-shaped tag projection in readDicomTags, the archive target handler,
the DICOM series worker pool, the partial import error classes, the
planner's dedupe and self-check, Reconstruction.slots, the irregular
geometry option, and test cases that restated others or pinned internal
structure. The corpus manifests print number arrays on one line, and a
pydicom script checks the volume corpus.
The module carries no complexity debt, so lint now fails on any function
in packages/dicom that exceeds the complexity, depth, parameter or line
limits, where src only warns and relies on the per-commit ratchet. Both
read the limits from scripts/checks/config.mjs.

The duplication ratchet covers the module's source as well as tests, so
a new 60-token clone there fails the commit.
Shorten code that said in many lines what a few say clearly, drop
exports, parameters, casts and annotations nothing needs, and give the
repeated shapes in pixel formats and validation one name each. The HTTP
status constants live where they are used, and the Content-Range parser
no longer models a range the only caller rejects.

The test DICOM writers share one element encoder, one Part 10 assembler
and the sequence, decimal and long helpers; every generated byte is
unchanged. Specs share their repeated setup through helpers, and cases
that restated another case are gone.

restoreState takes the reports it shows the user as one object, which
brings it within the parameter limit.
Read the modality rescale from the Pixel Value Transformation functional
group only for the IODs that define it there, as GDCM does. Other SOP
classes, such as multi-frame secondary capture and ophthalmic tomography,
use the top-level Rescale, so a native and a compressed copy of the same
file now load with the same values and buffer type.

Reject what a header gets wrong before it costs time or memory. A lone
native instance that declares more frames than its Pixel Data holds fails
at allocation, per-frame reads stop at the functional groups present, a
Number of Frames that is not a positive integer counts as one, an element
value cut short ends the header read with an error instead of a clipped
value, and a Transfer Syntax UID padded with a space is still recognised.
Frames split by a Basic Offset Table no longer take quadratic time.

Release a pooled request when its URL read fails, not only when it ends.

Restore no saved state onto a volume that two saved images now share, and
name those images in the restore notice instead of placing their masks on
the merged grid. Plan a series within its study, so a Series Instance UID
reused in another study no longer joins its images.

Export the types the public signatures name, correct two README claims,
and add tests for behaviour no test protected: writes after abort,
values the buffer cannot hold, retrying only failed frames, duplicate
decoder units, disposal of running and idle GDCM workers, and the copy
made before handing bytes to the metadata worker.
Showing image information is a separate feature from the loader.
The loader still reports how each axis spacing was established.

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