dicom-seg-js 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## [0.2.0] - 2026-08-30
+
+Additive — `^1.0.0` peer unchanged.
+
+### Added
+
+- **`LABELMAP` (PS3.3 Sup 243) read and write.** `readSeg` accepts a LABELMAP SEG
+  (one 8- or 16-bit integer-per-pixel frame per plane, pixel value = `SegmentNumber`,
+  `0` = background); `seg.type === "LABELMAP"` and `seg.mask(n)` returns the voxels whose
+  label is `n`. `writeSeg({ segmentationType: "LABELMAP", segments: [{ number, mask }] })`
+  writes one — 8-bit unless a segment number exceeds 255. LABELMAP is a partition:
+  overlapping input masks throw the new `LabelmapOverlapError`. `seg.field()` throws
+  `SegmentationTypeMismatchError` on a LABELMAP.
+- **`writeSeg({ frameCoverage: "sparse" })`** — omit a frame whose slice is all-background.
+  Default stays `"full"` (one frame per segment × plane, exact `writeSeg` → `readSeg`
+  identity). Under `"sparse"` the reader reconstructs the grid only across planes that have
+  a frame; an all-empty segment throws `RangeError`.
+- `Segmentation.numberOfFrames` — the stored frame count (`< segments × planes` for a
+  sparse SEG; one per plane for LABELMAP).
+
+### Changed
+
+- `UnsupportedSegmentationTypeError` is no longer raised for LABELMAP (now supported); it
+  is reserved for an unknown/vendor `SegmentationType`. An absent `SegmentationType` is a
+  `MalformedSegmentationError`.
+- `mask()` now serves BINARY *and* LABELMAP; `field()`'s type-mismatch message names the
+  actual type.
+
+## [0.1.1] - 2026-08-30
+
+No API change. Peer dependency `rt-geometry-js` bumped `^0.1.2` → `^1.0.0` — the shared
+core was promoted to a stable major (identical code to its 0.1.2, see
+`rt-geometry-js/CONTRACT.md`).
+
 ## [0.1.0] - 2026-08-29
 
 First release. DICOM Segmentation (SEG) **read and write** — `BINARY` masks and

package/README.md

@@ -4,9 +4,11 @@ DICOM **Segmentation (SEG)** reading and writing for JavaScript/TypeScript, buil
 [`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`);
+**Status:** published — [`dicom-seg-js`](https://www.npmjs.com/package/dicom-seg-js) 0.2.0 on npm. Reads **and writes** `BINARY` masks, `FRACTIONAL`
+probability/occupancy fields, and **`LABELMAP`** (PS3.3 Sup 243) — one label per pixel,
+`seg.mask(n)` returns the voxels whose label is `n`. `writeSeg` also takes
+`frameCoverage: "sparse"` to omit all-background frames. Requires the peer
+dependency [`rt-geometry-js`](https://www.npmjs.com/package/rt-geometry-js) (`^1.0.0`);
 `npm install dicom-seg-js rt-geometry-js`.
 
 **Validated against real DICOM files**, not just its own fixtures — `dicom-seg-js`'s
@@ -87,32 +89,41 @@ const probBytes = writeSeg({
 ```
 
 `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
+must be on the same grid (`GridMismatchError` otherwise). By default (`frameCoverage:
+"full"`) one frame is written per `(segment, plane)` across the whole grid, so `writeSeg` →
+`readSeg` is an exact round trip. `frameCoverage: "sparse"` omits a frame whose slice is
+all-background — smaller output, matching how real files are stored, but the reader can
+only reconstruct the grid across planes that have a frame (empty-plane extent is not
+preserved). Pass `fieldScale: "raw"` when your `field` values are already integers in
 `[0, maximumFractionalValue]` rather than `[0, 1]`.
 
+**LABELMAP** (`segmentationType: "LABELMAP"`) writes one integer-per-pixel frame per plane,
+each pixel a `SegmentNumber` (`0` = background); 8-bit unless a segment number exceeds 255,
+then 16-bit. It is a **partition** — overlapping input masks raise `LabelmapOverlapError`.
+LABELMAP is multi-*segment*, a different axis from FRACTIONAL's multi-*confidence*; there
+is no `seg.field()` for it.
+
 ## What it reads
 
 | Element | Handling |
 |---|---|
-| `SegmentationType` (0062,0001) | `BINARY` → `mask(n)`; `FRACTIONAL` → `field(n)` / `rawField(n)`. `LABELMAP` → `UnsupportedSegmentationTypeError` (0.2.0) |
+| `SegmentationType` (0062,0001) | `BINARY` → `mask(n)`; `FRACTIONAL` → `field(n)` / `rawField(n)`; `LABELMAP` → `mask(n)` (voxels whose label is `n`). An unknown value → `UnsupportedSegmentationTypeError` |
 | `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 |
+| `PixelData` | BINARY bit-unpacked (continuous bitstream; the byte-aligned-per-frame variant is detected and handled with a diagnostic). FRACTIONAL 8-bit. LABELMAP 8- or 16-bit little-endian integers |
 
 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`).
+`UnsupportedSegmentationTypeError` for an unknown `SegmentationType`, 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`, LABELMAP `BitsAllocated` not 8/16).
 
 ## License
 

package/dist/dicom/port.d.ts

@@ -19,11 +19,14 @@ export interface ParsedSeg {
     readonly numberOfFrames: number;
     readonly segments: readonly SegmentInfo[];
     readonly frames: readonly FrameRef[];
-    /** Raw PixelData bytes (bit-packed for BINARY, one byte per pixel for FRACTIONAL). */
+    /** Raw PixelData bytes (bit-packed for BINARY, one byte per pixel for FRACTIONAL,
+     *  8- or 16-bit integers per pixel for LABELMAP). */
     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;
+    /** LABELMAP only — bits per label pixel (8 or 16). */
+    readonly labelmapBitsAllocated: 8 | 16 | undefined;
     readonly diagnostics: readonly Diagnostic[];
 }
 /** Parse one SEG object's bytes. Throws NotSegmentationError / MalformedSegmentationError /
@@ -33,6 +36,9 @@ export declare function readSegDataset(bytes: ArrayBuffer): ParsedSeg;
 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;
+/** Label values for LABELMAP frame `frameIndex` (length rows·columns; each entry a
+ *  SegmentNumber, 0 = background). Handles 8- and 16-bit little-endian pixel data. */
+export declare function labelmapFrame(parsed: ParsedSeg, frameIndex: number): Uint8Array | Uint16Array;
 export interface EncodeSegSegment {
     readonly number: number;
     readonly label?: string;
@@ -45,9 +51,12 @@ export interface EncodeSegSegment {
     readonly trackingUid?: string;
 }
 export interface WriteSegFrame {
+    /** BINARY / FRACTIONAL: the segment this frame belongs to. LABELMAP: unused (0) — one
+     *  frame per plane carries every label. */
     readonly segmentNumber: number;
     readonly position: Vec3;
-    /** BINARY: 0/1 per pixel. FRACTIONAL: 0..maximumFractionalValue per pixel. Length rows·columns. */
+    /** BINARY: 0/1 per pixel. FRACTIONAL: 0..maximumFractionalValue per pixel. LABELMAP: a
+     *  SegmentNumber (0 = background) per pixel. Length rows·columns. */
     readonly pixels: ArrayLike<number>;
 }
 export interface EncodeSegOptions {
@@ -62,6 +71,8 @@ export interface EncodeSegOptions {
     readonly segmentsOverlap?: SegmentsOverlap;
     readonly fractionalType?: FractionalType;
     readonly maximumFractionalValue?: number;
+    /** LABELMAP only — bits per label pixel. Default 8. */
+    readonly labelmapBitsAllocated?: 8 | 16;
     readonly segments: readonly EncodeSegSegment[];
     readonly frames: readonly WriteSegFrame[];
     /** Override to exercise NotSegmentationError. */
@@ -107,8 +118,16 @@ export interface WriteSegOptions {
      */
     readonly fieldScale?: "unit" | "raw";
     readonly segments: readonly WriteSegSegment[];
-    /** Default `"NO"` for one segment, `"UNDEFINED"` for more. */
+    /** Default `"NO"` for one segment, `"UNDEFINED"` for more. Forced to `"NO"` for LABELMAP
+     *  (a partition). */
     readonly segmentsOverlap?: SegmentsOverlap;
+    /**
+     * `"full"` (default) — one frame per (segment, plane) over the whole grid, so
+     * `writeSeg` → `readSeg` is an exact identity, empty planes included. `"sparse"` — omit a
+     * frame whose slice is entirely background (BINARY/FRACTIONAL: all-zero; LABELMAP:
+     * all-zero after labelling). Matches how real files are stored; `readSeg` reads either.
+     */
+    readonly frameCoverage?: "full" | "sparse";
     /** Default: the shared geometry's `frameOfReferenceUID`, else a fresh UID. */
     readonly frameOfReferenceUID?: string;
     readonly contentLabel?: string;

package/dist/dicom/port.js

@@ -1,6 +1,6 @@
 import { createRequire } from "node:module";
 import { createDiagnostic, createGridGeometry, cross, DEFAULT_TOLERANCE, dot, normalize, sub, GridMismatchError, } from "rt-geometry-js";
-import { MalformedSegmentationError, NotSegmentationError, UnsupportedSegmentationTypeError, } from "../errors.js";
+import { LabelmapOverlapError, MalformedSegmentationError, NotSegmentationError, UnsupportedSegmentationTypeError, } from "../errors.js";
 // THE ONLY dcmjs importer in dicom-seg-js — mirrors rtstruct-js / rtdose-js port.ts.
 // dcmjs's ESM build is CJS-with-export-syntax and trips Node's resolver; require() hits
 // the genuinely-CJS condition instead.
@@ -58,13 +58,14 @@ export function readSegDataset(bytes) {
         throw new NotSegmentationError(`SOPClassUID ${sopClassUID} is not Segmentation Storage (${SEG_STORAGE_SOP_CLASS_UID}) and Modality is ${modality ?? "absent"}`);
     }
     const rawType = (ds["SegmentationType"] ?? "").toUpperCase();
-    if (rawType === "LABELMAP") {
-        throw new UnsupportedSegmentationTypeError("LABELMAP segmentation (PS3.3 Sup 243) is not supported in dicom-seg-js 0.1.0 — planned for 0.2.0");
-    }
-    if (rawType !== "BINARY" && rawType !== "FRACTIONAL") {
-        throw new MalformedSegmentationError(`SegmentationType is ${JSON.stringify(rawType || "absent")}, expected BINARY or FRACTIONAL`);
+    if (rawType !== "BINARY" && rawType !== "FRACTIONAL" && rawType !== "LABELMAP") {
+        if (rawType === "") {
+            throw new MalformedSegmentationError("SegmentationType (0062,0001) is absent, expected BINARY, FRACTIONAL, or LABELMAP");
+        }
+        throw new UnsupportedSegmentationTypeError(`SegmentationType is ${JSON.stringify(rawType)} — dicom-seg-js handles BINARY, FRACTIONAL, and LABELMAP`);
     }
     const segmentationType = rawType;
+    const isLabelmap = segmentationType === "LABELMAP";
     const rows = ds["Rows"];
     const columns = ds["Columns"];
     const numberOfFrames = ds["NumberOfFrames"] ?? 0;
@@ -96,9 +97,12 @@ export function readSegDataset(bytes) {
     }
     const rawFrames = perFrame.map((fg, frameIndex) => {
         const segId = asArray(fg["SegmentIdentificationSequence"])[0];
-        const segmentNumber = Number(segId?.["ReferencedSegmentNumber"]);
+        const rawSegNum = Number(segId?.["ReferencedSegmentNumber"]);
+        // LABELMAP frames carry every segment via the pixel value, so a per-frame
+        // SegmentIdentificationSequence is optional; 0 stands for "all labels".
+        const segmentNumber = isLabelmap ? (Number.isInteger(rawSegNum) && rawSegNum > 0 ? rawSegNum : 0) : rawSegNum;
         const ipp = asNumberArray(asArray(fg["PlanePositionSequence"])[0]?.["ImagePositionPatient"]);
-        if (!Number.isInteger(segmentNumber) || segmentNumber <= 0) {
+        if (!isLabelmap && (!Number.isInteger(segmentNumber) || segmentNumber <= 0)) {
             throw new MalformedSegmentationError(`frame ${frameIndex}: missing SegmentIdentificationSequence/ReferencedSegmentNumber`);
         }
         if (!ipp || ipp.length !== 3) {
@@ -134,12 +138,16 @@ export function readSegDataset(bytes) {
             propertyTypeModifier: readCode(s["SegmentedPropertyTypeModifierCodeSequence"]),
             trackingId: s["TrackingID"] || undefined,
             trackingUid: s["TrackingUID"] || undefined,
-            frameCount: framesBySegment.get(number) ?? 0,
+            // LABELMAP stores one frame per plane carrying every label, so a per-segment count
+            // isn't meaningful before the pixels are scanned — report the plane count.
+            frameCount: isLabelmap ? perFrame.length : framesBySegment.get(number) ?? 0,
         };
     });
-    for (const f of rawFrames) {
-        if (!declaredNumbers.has(f.segmentNumber)) {
-            throw new MalformedSegmentationError(`frame ${f.frameIndex} references SegmentNumber ${f.segmentNumber}, which has no SegmentSequence entry`);
+    if (!isLabelmap) {
+        for (const f of rawFrames) {
+            if (!declaredNumbers.has(f.segmentNumber)) {
+                throw new MalformedSegmentationError(`frame ${f.frameIndex} references SegmentNumber ${f.segmentNumber}, which has no SegmentSequence entry`);
+            }
         }
     }
     // --- geometry: distinct plane positions across every frame ---
@@ -189,7 +197,19 @@ export function readSegDataset(bytes) {
     const pixelData = new Uint8Array(first);
     const rc = rows * columns;
     let binaryFramesByteAligned = false;
-    if (segmentationType === "BINARY") {
+    let labelmapBitsAllocated;
+    if (isLabelmap) {
+        const ba = Number(ds["BitsAllocated"]);
+        if (ba !== 8 && ba !== 16) {
+            throw new MalformedSegmentationError(`LABELMAP BitsAllocated is ${ds["BitsAllocated"]}, expected 8 or 16`);
+        }
+        labelmapBitsAllocated = ba;
+        const need = numberOfFrames * rc * (ba / 8);
+        if (pixelData.length < need) {
+            throw new MalformedSegmentationError(`PixelData is ${pixelData.length} bytes; a LABELMAP SEG of ${numberOfFrames} frames × ${rc} px × ${ba / 8} B needs ${need}`);
+        }
+    }
+    else if (segmentationType === "BINARY") {
         const continuousBytes = Math.ceil((numberOfFrames * rc) / 8);
         const perFrameBytes = numberOfFrames * Math.ceil(rc / 8);
         if (pixelData.length >= continuousBytes) {
@@ -267,6 +287,7 @@ export function readSegDataset(bytes) {
         frames,
         pixelData,
         binaryFramesByteAligned,
+        labelmapBitsAllocated,
         diagnostics,
     };
 }
@@ -302,6 +323,23 @@ export function fractionalFrame(parsed, frameIndex) {
     const offset = frameIndex * rc;
     return parsed.pixelData.subarray(offset, offset + rc);
 }
+/** Label values for LABELMAP frame `frameIndex` (length rows·columns; each entry a
+ *  SegmentNumber, 0 = background). Handles 8- and 16-bit little-endian pixel data. */
+export function labelmapFrame(parsed, frameIndex) {
+    const rc = parsed.rows * parsed.columns;
+    if (parsed.labelmapBitsAllocated === 16) {
+        const byteOffset = parsed.pixelData.byteOffset + frameIndex * rc * 2;
+        // A copy, so callers can't accidentally mutate the shared PixelData, and to sidestep
+        // any alignment constraint on the underlying buffer.
+        const out = new Uint16Array(rc);
+        const view = new DataView(parsed.pixelData.buffer, byteOffset, rc * 2);
+        for (let i = 0; i < rc; i++)
+            out[i] = view.getUint16(i * 2, true);
+        return out;
+    }
+    const offset = frameIndex * rc;
+    return parsed.pixelData.subarray(offset, offset + rc);
+}
 export function encodeSegFrames(options) {
     const rows = options.rows;
     const columns = options.columns;
@@ -309,10 +347,13 @@ export function encodeSegFrames(options) {
     const rowDirection = options.rowDirection ?? [1, 0, 0];
     const columnDirection = options.columnDirection ?? [0, 1, 0];
     const isBinary = options.segmentationType === "BINARY";
+    const isLabelmap = options.segmentationType === "LABELMAP";
+    const labelmapBits = options.labelmapBitsAllocated ?? 8;
     const perFrameGroups = options.frames.map((f) => ({
-        FrameContentSequence: [{ StackID: "1", InStackPositionNumber: 1, DimensionIndexValues: [f.segmentNumber, 1] }],
+        FrameContentSequence: [{ StackID: "1", InStackPositionNumber: 1, DimensionIndexValues: [f.segmentNumber || 1, 1] }],
         PlanePositionSequence: [{ ImagePositionPatient: [...f.position] }],
-        SegmentIdentificationSequence: [{ ReferencedSegmentNumber: f.segmentNumber }],
+        // LABELMAP carries the segment in the pixel value — no per-frame SegmentIdentificationSequence.
+        ...(isLabelmap ? {} : { SegmentIdentificationSequence: [{ ReferencedSegmentNumber: f.segmentNumber }] }),
     }));
     let pixelBuffer;
     if (isBinary) {
@@ -322,6 +363,25 @@ export function encodeSegFrames(options) {
                 bits.push(f.pixels[i] ? 1 : 0);
         pixelBuffer = BitArray.pack(bits).buffer.slice(0);
     }
+    else if (isLabelmap) {
+        const n = options.frames.length * rc;
+        if (labelmapBits === 16) {
+            const words = new Uint16Array(n);
+            options.frames.forEach((f, fi) => {
+                for (let i = 0; i < rc; i++)
+                    words[fi * rc + i] = Math.max(0, Math.round(f.pixels[i] ?? 0)) & 0xffff;
+            });
+            pixelBuffer = words.buffer.slice(0);
+        }
+        else {
+            const bytes = new Uint8Array(n);
+            options.frames.forEach((f, fi) => {
+                for (let i = 0; i < rc; i++)
+                    bytes[fi * rc + i] = Math.max(0, Math.min(255, Math.round(f.pixels[i] ?? 0)));
+            });
+            pixelBuffer = bytes.buffer.slice(0);
+        }
+    }
     else {
         const bytes = new Uint8Array(options.frames.length * rc);
         options.frames.forEach((f, fi) => {
@@ -340,9 +400,9 @@ export function encodeSegFrames(options) {
         Rows: rows,
         Columns: columns,
         NumberOfFrames: options.frames.length,
-        BitsAllocated: isBinary ? 1 : 8,
-        BitsStored: isBinary ? 1 : 8,
-        HighBit: isBinary ? 0 : 7,
+        BitsAllocated: isBinary ? 1 : isLabelmap ? labelmapBits : 8,
+        BitsStored: isBinary ? 1 : isLabelmap ? labelmapBits : 8,
+        HighBit: isBinary ? 0 : isLabelmap ? labelmapBits - 1 : 7,
         PixelRepresentation: 0,
         SegmentationType: options.forceType ?? options.segmentationType,
         SegmentsOverlap: options.segmentsOverlap ?? "NO",
@@ -388,7 +448,7 @@ export function encodeSegFrames(options) {
         ],
         PerFrameFunctionalGroupsSequence: perFrameGroups,
     };
-    if (!isBinary) {
+    if (!isBinary && !isLabelmap) {
         if (!options.omitFractionalType)
             dataset["SegmentationFractionalType"] = options.fractionalType ?? "PROBABILITY";
         if (!options.omitMaximumFractionalValue)
@@ -403,20 +463,23 @@ export function encodeSegFrames(options) {
     };
     const dicomDict = new DicomDict(DicomMetaDictionary.denaturalizeDataset(meta));
     dicomDict.dict = DicomMetaDictionary.denaturalizeDataset(dataset);
-    dicomDict.dict[TAG_PIXEL_DATA] = { vr: "OB", Value: [pixelBuffer] };
+    dicomDict.dict[TAG_PIXEL_DATA] = { vr: isLabelmap && labelmapBits === 16 ? "OW" : "OB", Value: [pixelBuffer] };
     return dicomDict.write();
 }
 export function writeSeg(options) {
     const isBinary = options.segmentationType === "BINARY";
-    if (options.segmentationType !== "BINARY" && options.segmentationType !== "FRACTIONAL") {
-        throw new TypeError(`writeSeg: segmentationType must be "BINARY" or "FRACTIONAL", got ${JSON.stringify(options.segmentationType)}`);
+    const isLabelmap = options.segmentationType === "LABELMAP";
+    const isFractional = options.segmentationType === "FRACTIONAL";
+    if (!isBinary && !isFractional && !isLabelmap) {
+        throw new TypeError(`writeSeg: segmentationType must be "BINARY", "FRACTIONAL", or "LABELMAP", got ${JSON.stringify(options.segmentationType)}`);
     }
-    if (!isBinary && options.fractionalType === undefined) {
+    if (isFractional && options.fractionalType === undefined) {
         throw new TypeError('writeSeg: a FRACTIONAL segmentation requires an explicit fractionalType ("PROBABILITY" or "OCCUPANCY") — ' +
             "there is no default (FRACTIONAL-SEG.md §1)");
     }
     if (options.segments.length === 0)
         throw new RangeError("writeSeg: at least one segment is required");
+    const sparse = options.frameCoverage === "sparse";
     const numbers = new Set();
     for (const s of options.segments) {
         if (!Number.isInteger(s.number) || s.number <= 0) {
@@ -427,21 +490,22 @@ export function writeSeg(options) {
         numbers.add(s.number);
     }
     const maxFractional = options.maximumFractionalValue ?? 255;
-    if (!isBinary && (!Number.isInteger(maxFractional) || maxFractional < 1 || maxFractional > 255)) {
+    if (isFractional && (!Number.isInteger(maxFractional) || maxFractional < 1 || maxFractional > 255)) {
         throw new RangeError(`writeSeg: maximumFractionalValue must be an integer in [1, 255], got ${maxFractional}`);
     }
     const rawScale = options.fieldScale === "raw";
+    const wantsMask = isBinary || isLabelmap;
     const structures = options.segments.map((s) => {
-        const structure = isBinary ? s.mask : s.field;
+        const structure = wantsMask ? s.mask : s.field;
         if (!structure) {
-            throw new TypeError(`writeSeg: segment ${s.number} is missing its ${isBinary ? "mask" : "field"}`);
+            throw new TypeError(`writeSeg: segment ${s.number} is missing its ${wantsMask ? "mask" : "field"}`);
         }
         return structure;
     });
     const geometry = structures[0].geometry;
     for (let i = 1; i < structures.length; i++) {
         if (!structures[i].geometry.equals(geometry, options.tolerance)) {
-            throw new GridMismatchError(`writeSeg: segment ${options.segments[i].number}'s ${isBinary ? "mask" : "field"} is on a different grid than segment ${options.segments[0].number}'s — every segment must share one GridGeometry`);
+            throw new GridMismatchError(`writeSeg: segment ${options.segments[i].number}'s ${wantsMask ? "mask" : "field"} is on a different grid than segment ${options.segments[0].number}'s — every segment must share one GridGeometry`);
         }
     }
     const columns = geometry.columns;
@@ -450,34 +514,70 @@ export function writeSeg(options) {
     const planeCount = geometry.planes.length;
     const planePositions = geometry.planes.map((p) => p.position);
     const sliceThickness = planeCount >= 2 ? geometry.planeThicknessMm(0) : 1;
-    // One frame per (segment, plane) across the whole shared geometry — so
-    // writeSeg → readSeg is an exact identity on the grid, empty planes included.
-    // (Real files usually omit all-zero frames; reading handles that, sparse
-    // *writing* is a later feature.)
+    // `"full"` (default): one frame per (segment, plane) over the whole grid, so
+    // writeSeg → readSeg is an exact identity. `"sparse"`: skip an all-background slice.
     const frames = [];
-    options.segments.forEach((s, si) => {
-        const structure = structures[si];
+    let labelmapBits = 8;
+    if (isLabelmap) {
+        const maxSeg = Math.max(...options.segments.map((s) => s.number));
+        labelmapBits = maxSeg > 255 ? 16 : 8;
         for (let k = 0; k < planeCount; k++) {
-            const slice = structure.getSliceBuffer(k);
-            const pixels = new Uint8Array(rc);
-            for (let i = 0; i < rc; i++) {
-                const v = slice[i];
-                if (isBinary) {
-                    pixels[i] = v !== 0 ? 1 : 0;
-                }
-                else {
-                    let stored = Math.round(rawScale ? v : v * maxFractional);
-                    if (stored < 0)
-                        stored = 0;
-                    if (stored > maxFractional)
-                        stored = maxFractional;
-                    pixels[i] = stored;
+            const pixels = maxSeg > 255 ? new Uint16Array(rc) : new Uint8Array(rc);
+            let anySet = false;
+            for (let si = 0; si < options.segments.length; si++) {
+                const s = options.segments[si];
+                const slice = structures[si].getSliceBuffer(k);
+                for (let i = 0; i < rc; i++) {
+                    if (slice[i] === 0)
+                        continue;
+                    if (pixels[i] !== 0) {
+                        throw new LabelmapOverlapError(`segments ${pixels[i]} and ${s.number} both set the voxel at plane ${k}, index ${i} — ` +
+                            "LABELMAP stores one label per pixel. Use segmentationType \"BINARY\" for overlapping segments.");
+                    }
+                    pixels[i] = s.number;
+                    anySet = true;
                 }
             }
-            frames.push({ segmentNumber: s.number, position: planePositions[k], pixels });
+            if (sparse && !anySet)
+                continue;
+            frames.push({ segmentNumber: 0, position: planePositions[k], pixels });
         }
-    });
-    const segmentsOverlap = options.segmentsOverlap ?? (options.segments.length === 1 ? "NO" : "UNDEFINED");
+    }
+    else {
+        options.segments.forEach((s, si) => {
+            const structure = structures[si];
+            for (let k = 0; k < planeCount; k++) {
+                const slice = structure.getSliceBuffer(k);
+                const pixels = new Uint8Array(rc);
+                let anySet = false;
+                for (let i = 0; i < rc; i++) {
+                    const v = slice[i];
+                    if (isBinary) {
+                        pixels[i] = v !== 0 ? 1 : 0;
+                    }
+                    else {
+                        let stored = Math.round(rawScale ? v : v * maxFractional);
+                        if (stored < 0)
+                            stored = 0;
+                        if (stored > maxFractional)
+                            stored = maxFractional;
+                        pixels[i] = stored;
+                    }
+                    if (pixels[i] !== 0)
+                        anySet = true;
+                }
+                if (sparse && !anySet)
+                    continue;
+                frames.push({ segmentNumber: s.number, position: planePositions[k], pixels });
+            }
+        });
+    }
+    if (frames.length === 0) {
+        throw new RangeError("writeSeg: frameCoverage \"sparse\" produced no frames — every segment is empty");
+    }
+    const segmentsOverlap = isLabelmap
+        ? "NO"
+        : options.segmentsOverlap ?? (options.segments.length === 1 ? "NO" : "UNDEFINED");
     const encodeOptions = {
         rows,
         columns,
@@ -502,7 +602,8 @@ export function writeSeg(options) {
         ...(options.frameOfReferenceUID ?? geometry.frameOfReferenceUID
             ? { frameOfReferenceUID: (options.frameOfReferenceUID ?? geometry.frameOfReferenceUID) }
             : {}),
-        ...(isBinary ? {} : { fractionalType: options.fractionalType, maximumFractionalValue: maxFractional }),
+        ...(isFractional ? { fractionalType: options.fractionalType, maximumFractionalValue: maxFractional } : {}),
+        ...(isLabelmap ? { labelmapBitsAllocated: labelmapBits } : {}),
     };
     return encodeSegFrames(encodeOptions);
 }

package/dist/errors.d.ts

@@ -22,16 +22,26 @@ export declare class MalformedSegmentationError extends Error {
     constructor(message: string);
 }
 /**
- * `SegmentationType` (0062,0001) is `LABELMAP`. dicom-seg-js 0.1.0 reads `BINARY` and
- * `FRACTIONAL` only; LABELMAP (PS3.3 Supplement 243) support is planned for 0.2.0.
+ * `SegmentationType` (0062,0001) is a value dicom-seg-js does not handle. As of 0.2.0
+ * `BINARY`, `FRACTIONAL`, and `LABELMAP` (PS3.3 Supplement 243) are all supported, so this
+ * is now raised only for an unknown/vendor value.
  */
 export declare class UnsupportedSegmentationTypeError extends Error {
     constructor(message: string);
 }
 /**
- * `mask()` was called on a FRACTIONAL segmentation, or `field()` on a BINARY one. The two
- * are not interchangeable and there is no safe default threshold to turn a probability
- * field into a mask (roadmap §7.1) — the caller must pick one explicitly.
+ * A `writeSeg({ segmentationType: "LABELMAP" })` call was given segments whose masks
+ * overlap. LABELMAP is a partition — each pixel stores exactly one `SegmentNumber` — so
+ * overlapping input cannot be represented. Use `BINARY` (with `SegmentsOverlap`) instead.
+ */
+export declare class LabelmapOverlapError extends Error {
+    constructor(message: string);
+}
+/**
+ * `mask()` was called on a FRACTIONAL segmentation, `field()` on a BINARY or LABELMAP one,
+ * or `field()` on LABELMAP. The forms are not interchangeable and there is no safe default
+ * threshold to turn a probability field into a mask (roadmap §7.1) — the caller must pick
+ * one explicitly.
  */
 export declare class SegmentationTypeMismatchError extends Error {
     constructor(message: string);

package/dist/errors.js

@@ -28,8 +28,9 @@ export class MalformedSegmentationError extends Error {
     }
 }
 /**
- * `SegmentationType` (0062,0001) is `LABELMAP`. dicom-seg-js 0.1.0 reads `BINARY` and
- * `FRACTIONAL` only; LABELMAP (PS3.3 Supplement 243) support is planned for 0.2.0.
+ * `SegmentationType` (0062,0001) is a value dicom-seg-js does not handle. As of 0.2.0
+ * `BINARY`, `FRACTIONAL`, and `LABELMAP` (PS3.3 Supplement 243) are all supported, so this
+ * is now raised only for an unknown/vendor value.
  */
 export class UnsupportedSegmentationTypeError extends Error {
     constructor(message) {
@@ -38,9 +39,21 @@ export class UnsupportedSegmentationTypeError extends Error {
     }
 }
 /**
- * `mask()` was called on a FRACTIONAL segmentation, or `field()` on a BINARY one. The two
- * are not interchangeable and there is no safe default threshold to turn a probability
- * field into a mask (roadmap §7.1) — the caller must pick one explicitly.
+ * A `writeSeg({ segmentationType: "LABELMAP" })` call was given segments whose masks
+ * overlap. LABELMAP is a partition — each pixel stores exactly one `SegmentNumber` — so
+ * overlapping input cannot be represented. Use `BINARY` (with `SegmentsOverlap`) instead.
+ */
+export class LabelmapOverlapError extends Error {
+    constructor(message) {
+        super(`LabelmapOverlapError: ${message}`);
+        this.name = "LabelmapOverlapError";
+    }
+}
+/**
+ * `mask()` was called on a FRACTIONAL segmentation, `field()` on a BINARY or LABELMAP one,
+ * or `field()` on LABELMAP. The forms are not interchangeable and there is no safe default
+ * threshold to turn a probability field into a mask (roadmap §7.1) — the caller must pick
+ * one explicitly.
  */
 export class SegmentationTypeMismatchError extends Error {
     constructor(message) {

package/dist/index.d.ts

@@ -39,6 +39,9 @@ export declare class Segmentation {
     readonly geometry: GridGeometry;
     readonly frameOfReferenceUID: string | undefined;
     readonly contentLabel: string | undefined;
+    /** `NumberOfFrames` (0028,0008) — total frames stored. A sparse SEG has fewer than
+     *  `segments × planes`; a LABELMAP has one per plane. */
+    readonly numberOfFrames: number;
     readonly diagnostics: readonly Diagnostic[];
     private readonly parsed;
     private readonly maskCache;
@@ -52,7 +55,8 @@ export declare class Segmentation {
     private assertSegment;
     private get sliceSize();
     /**
-     * The boolean mask for a **BINARY** segment. Throws {@link SegmentationTypeMismatchError}
+     * The boolean mask for a segment. **BINARY** — the segment's frames. **LABELMAP** — the
+     * voxels whose label equals `segmentNumber`. Throws {@link SegmentationTypeMismatchError}
      * on a FRACTIONAL SEG — threshold `field(n)` yourself, there is no safe default cut.
      */
     mask(segmentNumber: number): Mask3D;

package/dist/index.js

@@ -14,7 +14,7 @@
  * 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 { binaryFrame, fractionalFrame, labelmapFrame, readSegDataset } from "./dicom/port.js";
 import { SegmentationTypeMismatchError } from "./errors.js";
 export * from "rt-geometry-js";
 export * from "./types.js";
@@ -41,6 +41,9 @@ export class Segmentation {
     geometry;
     frameOfReferenceUID;
     contentLabel;
+    /** `NumberOfFrames` (0028,0008) — total frames stored. A sparse SEG has fewer than
+     *  `segments × planes`; a LABELMAP has one per plane. */
+    numberOfFrames;
     diagnostics;
     parsed;
     maskCache = new Map();
@@ -55,6 +58,7 @@ export class Segmentation {
         this.geometry = parsed.geometry;
         this.frameOfReferenceUID = parsed.frameOfReferenceUID;
         this.contentLabel = parsed.contentLabel;
+        this.numberOfFrames = parsed.numberOfFrames;
         this.diagnostics = parsed.diagnostics;
     }
     static fromDicom(bytes) {
@@ -76,27 +80,39 @@ export class Segmentation {
         return this.parsed.rows * this.parsed.columns;
     }
     /**
-     * The boolean mask for a **BINARY** segment. Throws {@link SegmentationTypeMismatchError}
+     * The boolean mask for a segment. **BINARY** — the segment's frames. **LABELMAP** — the
+     * voxels whose label equals `segmentNumber`. 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`);
+        if (this.type === "FRACTIONAL") {
+            throw new SegmentationTypeMismatchError(`mask() is for BINARY / LABELMAP 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;
+        if (this.type === "LABELMAP") {
+            for (const fr of this.parsed.frames) {
+                const labels = labelmapFrame(this.parsed, fr.frameIndex);
+                const base = fr.planeIndex * rc;
+                for (let i = 0; i < rc; i++)
+                    if (labels[i] === segmentNumber)
+                        data[base + i] = 1;
+            }
+        }
+        else {
+            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);
@@ -117,7 +133,7 @@ export class Segmentation {
     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})`);
+            throw new SegmentationTypeMismatchError(`field() is for FRACTIONAL segmentations; this is ${this.type} — use mask(${segmentNumber})`);
         }
         const cached = cache.get(segmentNumber);
         if (cached)
@@ -144,7 +160,7 @@ export class Segmentation {
      * region the model marked at all".
      */
     support(segmentNumber) {
-        if (this.type === "BINARY")
+        if (this.type === "BINARY" || this.type === "LABELMAP")
             return this.mask(segmentNumber);
         const raw = this.rawField(segmentNumber);
         const [columns, rows, planes] = raw.dimensions;

package/dist/types.d.ts

@@ -1,8 +1,16 @@
 /**
- * Segmentation type. dicom-seg-js 0.1.0 handles `BINARY` and `FRACTIONAL`; `LABELMAP`
- * (PS3.3 Sup 243) throws {@link UnsupportedSegmentationTypeError} until 0.2.0.
+ * `SegmentationType` (0062,0001).
+ *
+ * - `BINARY` — 1 bit per pixel, one frame per (segment, plane).
+ * - `FRACTIONAL` — 8 bits per pixel, `0..MaximumFractionalValue`, one frame per
+ *   (segment, plane). {@link FractionalType} says whether the value is a probability or an
+ *   occupancy.
+ * - `LABELMAP` (PS3.3 Sup 243) — one frame per **plane**, each pixel an integer equal to
+ *   the `SegmentNumber` it belongs to (`0` = background). A partition: a voxel has at most
+ *   one label. `seg.mask(n)` returns the voxels whose label is `n`; there is no
+ *   `seg.field()`.
  */
-export type SegmentationType = "BINARY" | "FRACTIONAL";
+export type SegmentationType = "BINARY" | "FRACTIONAL" | "LABELMAP";
 /**
  * `SegmentationFractionalType` (0062,0010). PROBABILITY = "the probability that the
  * segmented property occupies the voxel"; OCCUPANCY = "the fraction of the voxel volume

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "dicom-seg-js",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
-  "description": "DICOM Segmentation (SEG) reading — BINARY masks and FRACTIONAL probability/occupancy fields — built on rt-geometry-js.",
+  "description": "DICOM Segmentation (SEG) reading and writing — BINARY masks and FRACTIONAL probability/occupancy fields — built on rt-geometry-js.",
   "keywords": [
     "dicom",
     "segmentation",
@@ -48,16 +48,17 @@
     "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"
+    "prepublishOnly": "npm run build && npm test",
+    "bench": "vitest bench --run"
   },
   "peerDependencies": {
-    "rt-geometry-js": "^0.1.2"
+    "rt-geometry-js": "^1.0.0"
   },
   "devDependencies": {
     "@types/node": "^26.2.0",
-    "rt-geometry-js": "^0.1.2",
+    "rt-geometry-js": "^1.0.0",
     "typescript": "^5.6.3",
-    "vitest": "^2.1.4"
+    "vitest": "^3.2.7"
   },
   "dependencies": {
     "dcmjs": "^0.52.0"