dicom-seg-js 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,72 @@
+# Changelog
+
+## [0.1.0] - 2026-08-29
+
+First release. DICOM Segmentation (SEG) **read and write** — `BINARY` masks and
+`FRACTIONAL` probability/occupancy fields — built on `rt-geometry-js` `^0.1.2` (peer
+dependency). Part of the `dicom-imaging-toolkit-packages` monorepo (roadmap v2, Phase F,
+PRs 2–4).
+
+**Validated voxel-exact against `highdicom`** on real TCIA SEG files (2- and 6-segment
+BINARY, one FRACTIONAL): 728 / 728 per-slice checksums identical. See `VALIDATION.md`.
+
+### Added
+
+- `readSeg(bytes)` / `Segmentation.fromDicom(bytes)` — parse one SEG object:
+  - `BINARY` and `FRACTIONAL` (`LABELMAP` → `UnsupportedSegmentationTypeError`, planned
+    for 0.2.0).
+  - One `GridGeometry` built from the Per-Frame / Shared Functional Groups, spanning every
+    distinct frame position; planes sorted along the normal.
+  - `NotSegmentationError` for a non-SEG SOP class; `MalformedSegmentationError` for an
+    unassemblable object (missing `SegmentSequence` / shared `PixelMeasures` /
+    `PlaneOrientation`, per-frame group count ≠ `NumberOfFrames`, a frame referencing an
+    undeclared `SegmentNumber`, short `PixelData`).
+- `seg.segments()` — number, label, `SegmentAlgorithmType` / `Name`, coded
+  `SegmentedPropertyCategory` / `Type` / `TypeModifier`, `TrackingID` / `TrackingUID`,
+  and the per-segment stored frame count.
+- `seg.mask(n)` — `Mask3D` for a BINARY segment (bit-unpacked; the non-conformant
+  byte-aligned-per-frame variant is detected and handled with a diagnostic).
+- `seg.field(n)` — `ScalarField3D` for a FRACTIONAL segment, rescaled to `[0, 1]` by
+  `MaximumFractionalValue`. `seg.rawField(n)` keeps the stored integers.
+- `seg.fractionalType` — `PROBABILITY` / `OCCUPANCY`, **never defaulted** (absent →
+  `undefined` + a `FRACTIONAL_TYPE_ABSENT` diagnostic; roadmap §7.1).
+- `FRACTIONAL_VALUES_LOOK_BINARY` diagnostic — a FRACTIONAL field with ≥ 98% of its
+  non-zero values pinned at `MaximumFractionalValue` is a binary mask stored as FRACTIONAL,
+  not a graded field (roadmap §7.1). Fires on a real ISPY1 "OCCUPANCY" file.
+- `seg.segmentsOverlap` — `SegmentsOverlap` surfaced; `YES` also raises a diagnostic.
+- `seg.support(n)` — `Mask3D` of a segment's footprint (the mask for BINARY; non-zero
+  voxels for FRACTIONAL), for use as the `mask` argument to the honest metrics.
+- `seg.sampleConfidence(n, point)` — interpolated confidence at a physical point (§7.3),
+  the same call as `dose.sample()` against a different field.
+- `mask()` on FRACTIONAL / `field()` on BINARY throw `SegmentationTypeMismatchError` — no
+  implicit threshold.
+- The full `rt-geometry-js` surface is re-exported, so `meanValue` /
+  `volumeAboveThreshold` / `thresholdSensitivity` (from 0.1.2) are available from a single
+  import. No "accuracy" / "% correct" metric anywhere (§7.2).
+- `writeSeg({ segmentationType, segments, ... })` — a `Mask3D` per BINARY segment or a
+  `ScalarField3D` per FRACTIONAL segment, all on one shared `GridGeometry`:
+  - **`fractionalType` is required** for FRACTIONAL — no default (roadmap §7.1); omitting
+    it is a `TypeError`.
+  - `maximumFractionalValue` (default 255) scales `[0, 1]` field values on write;
+    `fieldScale: "raw"` takes `[0, maximumFractionalValue]` integers instead.
+  - Every segment must share one grid (`GridMismatchError` otherwise). One frame per
+    `(segment, plane)` over the full grid, so `writeSeg` → `readSeg` is an exact round
+    trip. `SegmentsOverlap` defaults to `NO` (one segment) / `UNDEFINED` (more).
+  - Coded category / type / type-modifier, `TrackingID` / `TrackingUID`, algorithm
+    type/name all round-trip.
+
+### Performance
+
+- BINARY continuous-bitstream unpack is memoised per parse (was re-unpacking the whole
+  stream once per frame — O(frames²) on a large SEG). A 546-frame / 6-segment file now
+  reconstructs in ~2 s.
+
+### Known / deferred
+
+- **Sparse writing** (omitting all-zero frames, as most real files do) — 0.2.0. Reading
+  sparse SEGs is fully supported now.
+- **LABELMAP** deferred to 0.2.0 (little real-world test data yet).
+- Validation covers BINARY (2- and 6-segment) and one FRACTIONAL file; no genuinely graded
+  `PROBABILITY` field or `SegmentsOverlap YES` file in the sample yet (`VALIDATION.md`).
+- Per-frame `PlaneOrientationSequence` that varies from the shared one is flagged but not
+  honoured (the shared orientation is used).

package/README.md

@@ -0,0 +1,119 @@
+# dicom-seg-js
+
+DICOM **Segmentation (SEG)** reading and writing for JavaScript/TypeScript, built on
+[`rt-geometry-js`](https://www.npmjs.com/package/rt-geometry-js). Part of the
+[DICOM imaging toolkit](https://github.com/adeelbarki/dicom-imaging-toolkit-packages).
+
+**Status:** 0.1.0 — first release. Read **and write** `BINARY` masks and `FRACTIONAL`
+probability/occupancy fields. `LABELMAP` (PS3.3 Sup 243) lands in 0.2.0. Requires the peer
+dependency [`rt-geometry-js`](https://www.npmjs.com/package/rt-geometry-js) (`^0.1.2`);
+`npm install dicom-seg-js rt-geometry-js`.
+
+**Validated against real DICOM files**, not just its own fixtures — `dicom-seg-js`'s
+reconstruction is **voxel-exact vs `highdicom`** on real TCIA SEG files (C4KC-KiTS 2-segment
+BINARY, NSCLC-Radiomics 6-segment BINARY, ISPY1 FRACTIONAL): 728 / 728 per-slice checksums
+identical. See
+[VALIDATION.md](https://github.com/adeelbarki/dicom-imaging-toolkit-packages/blob/main/packages/dicom-seg/VALIDATION.md)
+(this link works from both GitHub and the npm page).
+
+**Standard pinned (for doc references):** DICOM PS3.3 **2026c**.
+
+> **FRACTIONAL values are per-voxel model *confidence*, not accuracy.** Averaging them does
+> not give you an accuracy figure, and most model outputs are uncalibrated (a softmax 0.9
+> is not "90% of such voxels are correct"). This library exposes honest quantities only —
+> `meanValue`, `volumeAboveThreshold`, `thresholdSensitivity` (from `rt-geometry-js`) — and
+> no "accuracy" or "% correct" number anywhere. See
+> [`docs/FRACTIONAL-SEG.md`](docs/FRACTIONAL-SEG.md).
+
+## Install
+
+```sh
+npm install dicom-seg-js rt-geometry-js
+```
+
+## Use
+
+```ts
+import { readSeg, meanValue, volumeAboveThreshold } from "dicom-seg-js";
+
+const seg = readSeg(segBytes);          // ArrayBuffer -> parsed Segmentation
+seg.type;                                // "BINARY" | "FRACTIONAL"
+seg.segments();                          // [{ number, label, category, propertyType, algorithmType, ... }]
+seg.geometry;                            // the SEG's own GridGeometry (from the Functional Groups)
+seg.segmentsOverlap;                     // "YES" | "NO" | "UNDEFINED"
+seg.diagnostics;                         // non-fatal issues found while parsing
+
+// BINARY:
+const mask = seg.mask(1);               // Mask3D on seg.geometry
+
+// FRACTIONAL:
+seg.fractionalType;                     // "PROBABILITY" | "OCCUPANCY" | undefined (never assumed)
+const field = seg.field(1);            // ScalarField3D, rescaled to 0..1 by MaximumFractionalValue
+const raw = seg.rawField(1);           // the stored integers, unscaled
+const support = seg.support(1);        // Mask3D of voxels with non-zero confidence
+
+meanValue(field, support);             // mean confidence over the marked region
+volumeAboveThreshold(field, support, 0.7);   // mm³ the model is >= 70% confident about
+seg.sampleConfidence(1, [x, y, z]);   // interpolated confidence at a physical point (§7.3)
+```
+
+`mask()` on a FRACTIONAL SEG and `field()` on a BINARY one both throw
+`SegmentationTypeMismatchError` — there is no safe default threshold to turn a probability
+field into a mask, so the caller must pick one.
+
+## Write
+
+```ts
+import { writeSeg } from "dicom-seg-js";
+
+// BINARY — one Mask3D per segment, all on one GridGeometry
+const bytes = writeSeg({
+  segmentationType: "BINARY",
+  segments: [
+    { number: 1, label: "Liver", mask: liverMask,
+      category: { value: "T-D0050", scheme: "SRT", meaning: "Tissue" },
+      propertyType: { value: "T-62000", scheme: "SRT", meaning: "Liver" } },
+    { number: 2, label: "Tumor", mask: tumorMask },
+  ],
+});
+
+// FRACTIONAL — fractionalType is REQUIRED, there is no default (see FRACTIONAL-SEG.md §1)
+const probBytes = writeSeg({
+  segmentationType: "FRACTIONAL",
+  fractionalType: "PROBABILITY",
+  maximumFractionalValue: 255,        // optional, default 255
+  segments: [{ number: 1, label: "Tumor", field: probField }],  // values in 0..1
+});
+```
+
+`writeSeg` derives the SEG grid from the first segment's mask/field; every other segment
+must be on the same grid (`GridMismatchError` otherwise). One frame is written per
+`(segment, plane)` across the full grid, so `writeSeg` → `readSeg` is an exact round trip
+(sparse writing, which omits all-zero frames, is a 0.2.0 feature). Pass
+`fieldScale: "raw"` when your `field` values are already integers in
+`[0, maximumFractionalValue]` rather than `[0, 1]`.
+
+## What it reads
+
+| Element | Handling |
+|---|---|
+| `SegmentationType` (0062,0001) | `BINARY` → `mask(n)`; `FRACTIONAL` → `field(n)` / `rawField(n)`. `LABELMAP` → `UnsupportedSegmentationTypeError` (0.2.0) |
+| `SegmentSequence` (0062,0002) | number, label, algorithm type/name, coded `SegmentedPropertyCategory` / `Type` / `TypeModifier`, `TrackingID` / `TrackingUID` |
+| `SegmentationFractionalType` (0062,0010) | surfaced on `seg.fractionalType`; **never defaulted** — absent is `undefined` + a diagnostic. A field whose non-zero values are ≥ 98% at the max raises `FRACTIONAL_VALUES_LOOK_BINARY` (a binary mask stored as FRACTIONAL) |
+| `MaximumFractionalValue` (0062,000E) | used to rescale `field(n)` to 0..1; `rawField(n)` keeps the integers. Absent → assumed 255 + a diagnostic |
+| `SegmentsOverlap` (0062,0013) | surfaced on `seg.segmentsOverlap`; `YES` also raises a diagnostic |
+| Per-Frame / Shared Functional Groups | plane positions, orientation, pixel spacing → one `GridGeometry` spanning every frame position |
+| `PixelData` | BINARY bit-unpacked (continuous bitstream; the byte-aligned-per-frame variant is detected and handled with a diagnostic). FRACTIONAL 8-bit |
+
+The SEG's grid is **not** required to match any source image series. To compare a segment
+against a CT or a dose grid, resample it — `resampleMask` / `resampleField` from
+`rt-geometry-js` are re-exported here.
+
+Parsing raises `NotSegmentationError` for a non-SEG SOP class,
+`UnsupportedSegmentationTypeError` for LABELMAP, and `MalformedSegmentationError` when the
+object can't be assembled (missing `SegmentSequence` / shared functional groups, per-frame
+count ≠ `NumberOfFrames`, a frame referencing an undeclared segment, short `PixelData`).
+
+## License
+
+[MIT](../../LICENSE)

package/dist/dicom/port.d.ts

@@ -0,0 +1,117 @@
+import { type Diagnostic, type GridGeometry, type GridTolerance, type Mask3D, type ScalarField3D, type Vec3 } from "rt-geometry-js";
+import type { CodedConcept, FractionalType, SegmentInfo, SegmentationType, SegmentsOverlap } from "../types.js";
+export interface FrameRef {
+    readonly segmentNumber: number;
+    readonly planeIndex: number;
+    /** Position of this frame in the PixelData frame stream. */
+    readonly frameIndex: number;
+}
+export interface ParsedSeg {
+    readonly segmentationType: SegmentationType;
+    readonly fractionalType: FractionalType | undefined;
+    readonly maximumFractionalValue: number | undefined;
+    readonly segmentsOverlap: SegmentsOverlap;
+    readonly geometry: GridGeometry;
+    readonly frameOfReferenceUID: string | undefined;
+    readonly contentLabel: string | undefined;
+    readonly rows: number;
+    readonly columns: number;
+    readonly numberOfFrames: number;
+    readonly segments: readonly SegmentInfo[];
+    readonly frames: readonly FrameRef[];
+    /** Raw PixelData bytes (bit-packed for BINARY, one byte per pixel for FRACTIONAL). */
+    readonly pixelData: Uint8Array;
+    /** True when BINARY frames are individually padded to a byte boundary rather than
+     *  packed as one continuous bitstream (a non-conformant but real variant). */
+    readonly binaryFramesByteAligned: boolean;
+    readonly diagnostics: readonly Diagnostic[];
+}
+/** Parse one SEG object's bytes. Throws NotSegmentationError / MalformedSegmentationError /
+ *  UnsupportedSegmentationTypeError. */
+export declare function readSegDataset(bytes: ArrayBuffer): ParsedSeg;
+/** Unpacked 0/1 bits for BINARY frame `frameIndex` (length rows·columns). */
+export declare function binaryFrame(parsed: ParsedSeg, frameIndex: number): Uint8Array;
+/** Raw 8-bit values for FRACTIONAL frame `frameIndex` (length rows·columns). */
+export declare function fractionalFrame(parsed: ParsedSeg, frameIndex: number): Uint8Array;
+export interface EncodeSegSegment {
+    readonly number: number;
+    readonly label?: string;
+    readonly algorithmType?: string;
+    readonly algorithmName?: string;
+    readonly category?: CodedConcept;
+    readonly propertyType?: CodedConcept;
+    readonly propertyTypeModifier?: CodedConcept;
+    readonly trackingId?: string;
+    readonly trackingUid?: string;
+}
+export interface WriteSegFrame {
+    readonly segmentNumber: number;
+    readonly position: Vec3;
+    /** BINARY: 0/1 per pixel. FRACTIONAL: 0..maximumFractionalValue per pixel. Length rows·columns. */
+    readonly pixels: ArrayLike<number>;
+}
+export interface EncodeSegOptions {
+    readonly rows: number;
+    readonly columns: number;
+    readonly segmentationType: SegmentationType;
+    readonly rowDirection?: Vec3;
+    readonly columnDirection?: Vec3;
+    readonly pixelSpacing?: readonly [number, number];
+    readonly sliceThickness?: number;
+    readonly frameOfReferenceUID?: string;
+    readonly segmentsOverlap?: SegmentsOverlap;
+    readonly fractionalType?: FractionalType;
+    readonly maximumFractionalValue?: number;
+    readonly segments: readonly EncodeSegSegment[];
+    readonly frames: readonly WriteSegFrame[];
+    /** Override to exercise NotSegmentationError. */
+    readonly sopClassUID?: string;
+    readonly modality?: string;
+    /** Test-only: emit LABELMAP as the type. */
+    readonly forceType?: string;
+    /** Test-only: drop SegmentationFractionalType even for FRACTIONAL. */
+    readonly omitFractionalType?: boolean;
+    /** Test-only: drop MaximumFractionalValue even for FRACTIONAL. */
+    readonly omitMaximumFractionalValue?: boolean;
+}
+export declare function encodeSegFrames(options: EncodeSegOptions): ArrayBuffer;
+export interface WriteSegSegment {
+    readonly number: number;
+    readonly label: string;
+    readonly algorithmType?: string;
+    readonly algorithmName?: string;
+    readonly category?: CodedConcept;
+    readonly propertyType?: CodedConcept;
+    readonly propertyTypeModifier?: CodedConcept;
+    readonly trackingId?: string;
+    readonly trackingUid?: string;
+    /** BINARY — the segment mask. */
+    readonly mask?: Mask3D;
+    /** FRACTIONAL — the segment field (0..1 unless `fieldScale: "raw"`). */
+    readonly field?: ScalarField3D;
+}
+export interface WriteSegOptions {
+    readonly segmentationType: SegmentationType;
+    /**
+     * FRACTIONAL only, and **required** — there is no default. PROBABILITY and OCCUPANCY are
+     * different quantities (roadmap §7.1 / FRACTIONAL-SEG.md §1); the writer must be told
+     * which one the values are.
+     */
+    readonly fractionalType?: FractionalType;
+    /** FRACTIONAL only — the stored integer that means 1.0. Default 255 (8-bit ceiling). */
+    readonly maximumFractionalValue?: number;
+    /**
+     * How `segment.field` values are read. `"unit"` (default): they are in `[0, 1]` and get
+     * multiplied by `maximumFractionalValue`. `"raw"`: they are already integers in
+     * `[0, maximumFractionalValue]`.
+     */
+    readonly fieldScale?: "unit" | "raw";
+    readonly segments: readonly WriteSegSegment[];
+    /** Default `"NO"` for one segment, `"UNDEFINED"` for more. */
+    readonly segmentsOverlap?: SegmentsOverlap;
+    /** Default: the shared geometry's `frameOfReferenceUID`, else a fresh UID. */
+    readonly frameOfReferenceUID?: string;
+    readonly contentLabel?: string;
+    readonly tolerance?: GridTolerance;
+}
+export declare function writeSeg(options: WriteSegOptions): ArrayBuffer;