dicom-seg-js 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,87 @@
+/**
+ * dicom-seg-js — DICOM Segmentation (SEG) reading, built on rt-geometry-js.
+ *
+ * 0.1.0: BINARY masks and FRACTIONAL probability/occupancy fields. LABELMAP (PS3.3
+ * Sup 243) is planned for 0.2.0. Writing arrives in a later PR.
+ *
+ * FRACTIONAL values are per-voxel model confidence, not accuracy — see
+ * `docs/FRACTIONAL-SEG.md`. This library exposes honest quantities only
+ * (`meanValue` / `volumeAboveThreshold` / `thresholdSensitivity` from rt-geometry-js) and
+ * never an "accuracy" or "% correct" number.
+ *
+ * The whole rt-geometry-js surface (GridGeometry, Mask3D, ScalarField3D, resampling,
+ * histogram/metrics, geometry errors) is re-exported so a caller can go straight from a
+ * segment to a resample or a histogram from one import.
+ */
+import { type Diagnostic, type GridGeometry, type InterpMethod, type Mask3D, type ScalarField3D, type Vec3 } from "rt-geometry-js";
+import type { FractionalType, SegmentInfo, SegmentationType, SegmentsOverlap } from "./types.js";
+export * from "rt-geometry-js";
+export * from "./types.js";
+export * from "./errors.js";
+export { writeSeg } from "./dicom/port.js";
+export type { WriteSegOptions, WriteSegSegment } from "./dicom/port.js";
+/**
+ * A parsed DICOM Segmentation and the per-segment masks / fields over it.
+ *
+ * BINARY → `mask(n)`; FRACTIONAL → `field(n)` (rescaled to 0..1) and `rawField(n)` (the
+ * stored integers). The two are not interchangeable — calling the wrong one throws
+ * {@link SegmentationTypeMismatchError} rather than guessing a threshold (roadmap §7.1).
+ */
+export declare class Segmentation {
+    readonly type: SegmentationType;
+    /** FRACTIONAL only — PROBABILITY vs OCCUPANCY, or undefined if the SEG didn't declare it. */
+    readonly fractionalType: FractionalType | undefined;
+    /** FRACTIONAL only — the stored value that means 1.0 (usually 255). */
+    readonly maximumFractionalValue: number | undefined;
+    readonly segmentsOverlap: SegmentsOverlap;
+    /** The SEG's own sampling grid, built from the Per-Frame / Shared Functional Groups.
+     *  Not required to match any source image series — resample to cross grids. */
+    readonly geometry: GridGeometry;
+    readonly frameOfReferenceUID: string | undefined;
+    readonly contentLabel: string | undefined;
+    readonly diagnostics: readonly Diagnostic[];
+    private readonly parsed;
+    private readonly maskCache;
+    private readonly fieldCache;
+    private readonly rawFieldCache;
+    private constructor();
+    static fromDicom(bytes: ArrayBuffer): Segmentation;
+    /** Every segment, in `SegmentSequence` order. */
+    segments(): readonly SegmentInfo[];
+    hasSegment(segmentNumber: number): boolean;
+    private assertSegment;
+    private get sliceSize();
+    /**
+     * The boolean mask for a **BINARY** segment. Throws {@link SegmentationTypeMismatchError}
+     * on a FRACTIONAL SEG — threshold `field(n)` yourself, there is no safe default cut.
+     */
+    mask(segmentNumber: number): Mask3D;
+    /**
+     * The confidence/occupancy field for a **FRACTIONAL** segment, rescaled to `[0, 1]` by
+     * `MaximumFractionalValue`. Throws {@link SegmentationTypeMismatchError} on a BINARY SEG
+     * — use `mask(n)`.
+     */
+    field(segmentNumber: number): ScalarField3D;
+    /** The raw stored integers (0..`maximumFractionalValue`) for a FRACTIONAL segment, unscaled. */
+    rawField(segmentNumber: number): ScalarField3D;
+    private fractionalField;
+    /**
+     * The footprint of a segment as a `Mask3D`: for BINARY, the mask itself; for FRACTIONAL,
+     * the voxels with a non-zero stored value. Handy as the `mask` argument to
+     * `meanValue` / `volumeAboveThreshold` / `thresholdSensitivity` — "confidence over the
+     * region the model marked at all".
+     */
+    support(segmentNumber: number): Mask3D;
+    /**
+     * Interpolated confidence at a physical point for a FRACTIONAL segment (0 outside the
+     * grid). The confidence-under-cursor tooltip from §7.3 — the same call as
+     * `dose.sample()` against a different field. Trilinear by default.
+     */
+    sampleConfidence(segmentNumber: number, point: Vec3, opts?: {
+        method?: InterpMethod;
+    }): number;
+}
+/** Parse one DICOM SEG object's bytes. Throws `NotSegmentationError` /
+ *  `MalformedSegmentationError` / `UnsupportedSegmentationTypeError`. */
+export declare function readSeg(bytes: ArrayBuffer): Segmentation;
+export type { ParsedSeg } from "./dicom/port.js";

package/dist/index.js

@@ -0,0 +1,177 @@
+/**
+ * dicom-seg-js — DICOM Segmentation (SEG) reading, built on rt-geometry-js.
+ *
+ * 0.1.0: BINARY masks and FRACTIONAL probability/occupancy fields. LABELMAP (PS3.3
+ * Sup 243) is planned for 0.2.0. Writing arrives in a later PR.
+ *
+ * FRACTIONAL values are per-voxel model confidence, not accuracy — see
+ * `docs/FRACTIONAL-SEG.md`. This library exposes honest quantities only
+ * (`meanValue` / `volumeAboveThreshold` / `thresholdSensitivity` from rt-geometry-js) and
+ * never an "accuracy" or "% correct" number.
+ *
+ * The whole rt-geometry-js surface (GridGeometry, Mask3D, ScalarField3D, resampling,
+ * histogram/metrics, geometry errors) is re-exported so a caller can go straight from a
+ * segment to a resample or a histogram from one import.
+ */
+import { createScalarField, maskFromDense, sampleFieldAt, } from "rt-geometry-js";
+import { binaryFrame, fractionalFrame, readSegDataset } from "./dicom/port.js";
+import { SegmentationTypeMismatchError } from "./errors.js";
+export * from "rt-geometry-js";
+export * from "./types.js";
+export * from "./errors.js";
+// Write a conformant SEG from a Mask3D per BINARY segment / a ScalarField3D per FRACTIONAL
+// segment. The low-level frame encoder (encodeSegFrames) stays internal.
+export { writeSeg } from "./dicom/port.js";
+/**
+ * A parsed DICOM Segmentation and the per-segment masks / fields over it.
+ *
+ * BINARY → `mask(n)`; FRACTIONAL → `field(n)` (rescaled to 0..1) and `rawField(n)` (the
+ * stored integers). The two are not interchangeable — calling the wrong one throws
+ * {@link SegmentationTypeMismatchError} rather than guessing a threshold (roadmap §7.1).
+ */
+export class Segmentation {
+    type;
+    /** FRACTIONAL only — PROBABILITY vs OCCUPANCY, or undefined if the SEG didn't declare it. */
+    fractionalType;
+    /** FRACTIONAL only — the stored value that means 1.0 (usually 255). */
+    maximumFractionalValue;
+    segmentsOverlap;
+    /** The SEG's own sampling grid, built from the Per-Frame / Shared Functional Groups.
+     *  Not required to match any source image series — resample to cross grids. */
+    geometry;
+    frameOfReferenceUID;
+    contentLabel;
+    diagnostics;
+    parsed;
+    maskCache = new Map();
+    fieldCache = new Map();
+    rawFieldCache = new Map();
+    constructor(parsed) {
+        this.parsed = parsed;
+        this.type = parsed.segmentationType;
+        this.fractionalType = parsed.fractionalType;
+        this.maximumFractionalValue = parsed.maximumFractionalValue;
+        this.segmentsOverlap = parsed.segmentsOverlap;
+        this.geometry = parsed.geometry;
+        this.frameOfReferenceUID = parsed.frameOfReferenceUID;
+        this.contentLabel = parsed.contentLabel;
+        this.diagnostics = parsed.diagnostics;
+    }
+    static fromDicom(bytes) {
+        return new Segmentation(readSegDataset(bytes));
+    }
+    /** Every segment, in `SegmentSequence` order. */
+    segments() {
+        return this.parsed.segments;
+    }
+    hasSegment(segmentNumber) {
+        return this.parsed.segments.some((s) => s.number === segmentNumber);
+    }
+    assertSegment(segmentNumber) {
+        if (!this.hasSegment(segmentNumber)) {
+            throw new RangeError(`no segment with SegmentNumber ${segmentNumber} (present: ${this.parsed.segments.map((s) => s.number).join(", ")})`);
+        }
+    }
+    get sliceSize() {
+        return this.parsed.rows * this.parsed.columns;
+    }
+    /**
+     * The boolean mask for a **BINARY** segment. Throws {@link SegmentationTypeMismatchError}
+     * on a FRACTIONAL SEG — threshold `field(n)` yourself, there is no safe default cut.
+     */
+    mask(segmentNumber) {
+        this.assertSegment(segmentNumber);
+        if (this.type !== "BINARY") {
+            throw new SegmentationTypeMismatchError(`mask() is for BINARY segmentations; this is FRACTIONAL — use field(${segmentNumber}) and apply your own threshold`);
+        }
+        const cached = this.maskCache.get(segmentNumber);
+        if (cached)
+            return cached;
+        const rc = this.sliceSize;
+        const data = new Uint8Array(this.parsed.geometry.planes.length * rc);
+        for (const fr of this.parsed.frames) {
+            if (fr.segmentNumber !== segmentNumber)
+                continue;
+            const bits = binaryFrame(this.parsed, fr.frameIndex);
+            const base = fr.planeIndex * rc;
+            for (let i = 0; i < rc; i++)
+                if (bits[i])
+                    data[base + i] = 1;
+        }
+        const mask = maskFromDense(this.parsed.geometry, data);
+        this.maskCache.set(segmentNumber, mask);
+        return mask;
+    }
+    /**
+     * The confidence/occupancy field for a **FRACTIONAL** segment, rescaled to `[0, 1]` by
+     * `MaximumFractionalValue`. Throws {@link SegmentationTypeMismatchError} on a BINARY SEG
+     * — use `mask(n)`.
+     */
+    field(segmentNumber) {
+        return this.fractionalField(segmentNumber, true, this.fieldCache);
+    }
+    /** The raw stored integers (0..`maximumFractionalValue`) for a FRACTIONAL segment, unscaled. */
+    rawField(segmentNumber) {
+        return this.fractionalField(segmentNumber, false, this.rawFieldCache);
+    }
+    fractionalField(segmentNumber, rescale, cache) {
+        this.assertSegment(segmentNumber);
+        if (this.type !== "FRACTIONAL") {
+            throw new SegmentationTypeMismatchError(`field() is for FRACTIONAL segmentations; this is BINARY — use mask(${segmentNumber})`);
+        }
+        const cached = cache.get(segmentNumber);
+        if (cached)
+            return cached;
+        const rc = this.sliceSize;
+        const buffer = new Float32Array(this.parsed.geometry.planes.length * rc);
+        const divisor = rescale ? (this.maximumFractionalValue ?? 255) : 1;
+        for (const fr of this.parsed.frames) {
+            if (fr.segmentNumber !== segmentNumber)
+                continue;
+            const bytes = fractionalFrame(this.parsed, fr.frameIndex);
+            const base = fr.planeIndex * rc;
+            for (let i = 0; i < rc; i++)
+                buffer[base + i] = bytes[i] / divisor;
+        }
+        const field = createScalarField(this.parsed.geometry, buffer);
+        cache.set(segmentNumber, field);
+        return field;
+    }
+    /**
+     * The footprint of a segment as a `Mask3D`: for BINARY, the mask itself; for FRACTIONAL,
+     * the voxels with a non-zero stored value. Handy as the `mask` argument to
+     * `meanValue` / `volumeAboveThreshold` / `thresholdSensitivity` — "confidence over the
+     * region the model marked at all".
+     */
+    support(segmentNumber) {
+        if (this.type === "BINARY")
+            return this.mask(segmentNumber);
+        const raw = this.rawField(segmentNumber);
+        const [columns, rows, planes] = raw.dimensions;
+        const data = new Uint8Array(columns * rows * planes);
+        for (let k = 0; k < planes; k++) {
+            const slice = raw.getSliceBuffer(k);
+            const base = k * columns * rows;
+            for (let i = 0; i < slice.length; i++)
+                if (slice[i] > 0)
+                    data[base + i] = 1;
+        }
+        return maskFromDense(this.geometry, data);
+    }
+    /**
+     * Interpolated confidence at a physical point for a FRACTIONAL segment (0 outside the
+     * grid). The confidence-under-cursor tooltip from §7.3 — the same call as
+     * `dose.sample()` against a different field. Trilinear by default.
+     */
+    sampleConfidence(segmentNumber, point, opts = {}) {
+        return sampleFieldAt(this.field(segmentNumber), point, {
+            method: opts.method ?? "trilinear",
+            outOfBounds: 0,
+        });
+    }
+}
+/** Parse one DICOM SEG object's bytes. Throws `NotSegmentationError` /
+ *  `MalformedSegmentationError` / `UnsupportedSegmentationTypeError`. */
+export function readSeg(bytes) {
+    return Segmentation.fromDicom(bytes);
+}

package/dist/types.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Segmentation type. dicom-seg-js 0.1.0 handles `BINARY` and `FRACTIONAL`; `LABELMAP`
+ * (PS3.3 Sup 243) throws {@link UnsupportedSegmentationTypeError} until 0.2.0.
+ */
+export type SegmentationType = "BINARY" | "FRACTIONAL";
+/**
+ * `SegmentationFractionalType` (0062,0010). PROBABILITY = "the probability that the
+ * segmented property occupies the voxel"; OCCUPANCY = "the fraction of the voxel volume
+ * the property occupies". A stored 0.5 means very different things under each — never
+ * assume one (roadmap §7.1). Undefined when the SEG did not declare it.
+ */
+export type FractionalType = "PROBABILITY" | "OCCUPANCY";
+/** `SegmentsOverlap` (0062,0013) — whether segments may share voxels. */
+export type SegmentsOverlap = "YES" | "NO" | "UNDEFINED";
+/** A DICOM coded concept — `CodeValue` + `CodingSchemeDesignator` + `CodeMeaning`. */
+export interface CodedConcept {
+    readonly value: string;
+    readonly scheme: string;
+    readonly meaning: string;
+}
+/** One entry of `SegmentSequence` (0062,0002). */
+export interface SegmentInfo {
+    /** `SegmentNumber` (0062,0004) — 1-based, unique within the SEG. The key for `mask()` / `field()`. */
+    readonly number: number;
+    /** `SegmentLabel` (0062,0005). */
+    readonly label: string;
+    /** `SegmentAlgorithmType` (0062,0008) — `AUTOMATIC` | `SEMIAUTOMATIC` | `MANUAL`. */
+    readonly algorithmType: string;
+    /** `SegmentAlgorithmName` (0062,0009), when present. */
+    readonly algorithmName: string | undefined;
+    /** `SegmentedPropertyCategoryCodeSequence` (0062,0003) — e.g. Tissue, Anatomical Structure. */
+    readonly category: CodedConcept | undefined;
+    /** `SegmentedPropertyTypeCodeSequence` (0062,000F) — e.g. Liver, Tumor. */
+    readonly propertyType: CodedConcept | undefined;
+    /** `SegmentedPropertyTypeModifierCodeSequence` (0062,0011), when present — e.g. Left. */
+    readonly propertyTypeModifier: CodedConcept | undefined;
+    /** `TrackingID` (0062,0020) / `TrackingUID` (0062,0021), when present. */
+    readonly trackingId: string | undefined;
+    readonly trackingUid: string | undefined;
+    /** Number of frames actually stored for this segment (sparse SEGs omit all-empty frames). */
+    readonly frameCount: number;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/docs/FRACTIONAL-SEG.md

@@ -0,0 +1,105 @@
+# FRACTIONAL segmentations
+
+A FRACTIONAL SEG stores one 8-bit value per voxel per segment. `dicom-seg-js` rescales it
+to `[0, 1]` with `MaximumFractionalValue` (`field(n)`) and also gives you the raw integers
+(`rawField(n)`). What that number *means* is the subject of this document.
+
+## 1. PROBABILITY and OCCUPANCY are different quantities
+
+`SegmentationFractionalType` (0062,0010) declares one of two meanings:
+
+| | 0.5 means |
+|---|---|
+| **PROBABILITY** | "there is a 50% chance the segmented property is present at this voxel" |
+| **OCCUPANCY** | "the segmented property fills 50% of this voxel's volume" |
+
+They are not interchangeable. A partial-volume boundary voxel that is genuinely half tumour
+has OCCUPANCY 0.5 and (if the model is certain) PROBABILITY ≈ 1.0. A voxel the model is
+unsure about has PROBABILITY 0.5 and OCCUPANCY that is either 0 or 1 (the tumour is either
+there or not — the model just doesn't know which).
+
+`dicom-seg-js` therefore:
+
+- exposes `seg.fractionalType` and **never defaults it** — an absent
+  `SegmentationFractionalType` reads back as `undefined` with a `FRACTIONAL_TYPE_ABSENT`
+  diagnostic, not as PROBABILITY;
+- (planned) emits a diagnostic when the value distribution contradicts the declared type —
+  e.g. an OCCUPANCY field that is bimodal at 0 and `MaximumFractionalValue` with almost
+  nothing in between, which is a thresholded probability mask mislabelled.
+
+If your pipeline needs one specific meaning, check `seg.fractionalType` and reject the
+file when it is `undefined` or wrong. Do not let the library pick for you, because it
+can't.
+
+## 2. Confidence is not accuracy
+
+A per-voxel PROBABILITY is the model's **confidence** at that location. It is not the
+accuracy of the segmentation:
+
+- **Accuracy needs ground truth**, which does not exist at inference time. Averaging
+  confidence over a segment tells you how sure the model was, not how often it was right.
+- **Most model outputs are uncalibrated.** A softmax value of 0.9 does not mean 90% of
+  voxels with that value are correct; networks are typically overconfident, and the
+  mapping from score to empirical frequency is model- and dataset-specific. Calibration
+  (temperature scaling, isotonic regression, …) is a separate step that the SEG file does
+  not record.
+
+So `dicom-seg-js` exposes honest quantities only, via the re-exported `rt-geometry-js`
+functions:
+
+```ts
+import { readSeg, meanValue, volumeAboveThreshold, thresholdSensitivity } from "dicom-seg-js";
+
+const seg = readSeg(bytes);
+const field = seg.field(1);
+const support = seg.support(1);                     // voxels the model marked at all
+
+meanValue(field, support);                          // mean confidence over that region
+volumeAboveThreshold(field, support, 0.7);          // mm³ at confidence >= 0.7
+thresholdSensitivity(field, support, [0.3, 0.5, 0.7, 0.9]);
+//   how much the segmented volume moves as the confidence cut moves — a flat curve
+//   means the threshold barely matters, a steep one means it dominates the result
+```
+
+There is deliberately **no** `accuracy()`, `percentCorrect()`, `reliability()`, or single
+summary "quality" number anywhere in the API.
+
+## 3. Displaying confidence
+
+`seg.sampleConfidence(n, point)` gives an interpolated value for a cursor tooltip (§7.3) —
+the same call as `dose.sample()` on a different field.
+
+Presenting that value as "**87% confidence**" implies the model is calibrated, which it
+usually is not. Unless you have calibrated the model yourself, prefer relative
+presentation: a heatmap, or high/medium/low banding. This is a UI obligation on the
+consumer, not something the library can enforce.
+
+## 4. Validation
+
+`dicom-seg-js`'s reconstruction was checked against
+[`highdicom`](https://github.com/ImagingDataCommons/highdicom) 0.28 on real SEG files from
+TCIA. Full method and the harness are in
+[`../VALIDATION.md`](../VALIDATION.md) / [`../scripts/validation/`](../scripts/validation/);
+the headline:
+
+| File (TCIA) | Type | Segments | Result |
+|---|---|---|---|
+| C4KC-KiTS `KiTS-00007` | BINARY | 2 (Kidney, Mass) | **voxel-exact** — 122/122 slice checksums identical |
+| NSCLC-Radiomics `LUNG1-005` | BINARY | 6 (Esophagus, GTV, Heart, L/R Lung, Cord) | **voxel-exact** — 546/546 |
+| ISPY1 `ISPY1_1004` | FRACTIONAL / OCCUPANCY | 1 (PE Tumor) | **voxel-exact** — 60/60; raw value sum 22 876 305 matched exactly |
+
+728 `(segment, plane)` slices, every one byte-for-byte identical to highdicom's
+reconstruction (BINARY bit-unpacking included).
+
+### Fractional types in the wild
+
+Of the TCIA collections that publish DICOM SEG, most are `BINARY`. `FRACTIONAL` appears
+mainly in the breast-MRI collections (ISPY1/ISPY2, ACRIN-6698). In the sample checked, the
+declared fractional type was **`OCCUPANCY`** — but the `ISPY1_1004` file's non-zero values
+are **all exactly 255**: it is a binary mask stored as FRACTIONAL, not a graded occupancy
+field. `dicom-seg-js` emits a `FRACTIONAL_VALUES_LOOK_BINARY` diagnostic for exactly this
+case (≥ 98% of non-zero values pinned at `MaximumFractionalValue`). No genuinely graded
+`PROBABILITY` field turned up in the sample; that is consistent with FRACTIONAL SEG being
+rare and usually a thresholded export rather than a raw model head. Treat a FRACTIONAL SEG
+as graded only after checking its value distribution (`thresholdSensitivity`, or the
+diagnostic).

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "dicom-seg-js",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "DICOM Segmentation (SEG) reading — BINARY masks and FRACTIONAL probability/occupancy fields — built on rt-geometry-js.",
+  "keywords": [
+    "dicom",
+    "segmentation",
+    "dicom-seg",
+    "seg",
+    "medical-imaging",
+    "mask",
+    "fractional",
+    "dcmjs"
+  ],
+  "license": "MIT",
+  "author": "Adeel Khan",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/adeelbarki/dicom-imaging-toolkit-packages.git",
+    "directory": "packages/dicom-seg"
+  },
+  "homepage": "https://github.com/adeelbarki/dicom-imaging-toolkit-packages/tree/main/packages/dicom-seg#readme",
+  "bugs": {
+    "url": "https://github.com/adeelbarki/dicom-imaging-toolkit-packages/issues"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md",
+    "docs/FRACTIONAL-SEG.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "pretest": "npm run check:deps",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "check:deps": "node ../../scripts/check-dependency-rule.mjs",
+    "build": "tsc -p tsconfig.build.json",
+    "prebuild": "npm run build --workspace rt-geometry-js",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "peerDependencies": {
+    "rt-geometry-js": "^0.1.2"
+  },
+  "devDependencies": {
+    "@types/node": "^26.2.0",
+    "rt-geometry-js": "^0.1.2",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.4"
+  },
+  "dependencies": {
+    "dcmjs": "^0.52.0"
+  }
+}