dicom-seg-js 0.1.0

package/dist/dicom/port.js

@@ -0,0 +1,508 @@
+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";
+// 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.
+const dcmjs = createRequire(import.meta.url)("dcmjs");
+const { DicomMessage, DicomMetaDictionary, DicomDict, BitArray } = dcmjs.data;
+const SEG_STORAGE_SOP_CLASS_UID = "1.2.840.10008.5.1.4.1.1.66.4";
+const TRANSFER_SYNTAX_UID = "1.2.840.10008.1.2.1"; // Explicit VR Little Endian
+const TAG_PIXEL_DATA = "7FE00010";
+function at(arr, index) {
+    const value = arr[index];
+    if (value === undefined)
+        throw new RangeError(`index ${index} out of range (length ${arr.length})`);
+    return value;
+}
+function naturalize(bytes) {
+    const dicomData = DicomMessage.readFile(bytes);
+    return DicomMetaDictionary.naturalizeDataset(dicomData.dict);
+}
+function asArray(value) {
+    if (Array.isArray(value))
+        return value;
+    if (value === undefined || value === null)
+        return [];
+    return [value];
+}
+function asNumberArray(value) {
+    if (Array.isArray(value))
+        return value.map(Number);
+    if (typeof value === "number")
+        return [value];
+    if (typeof value === "string") {
+        return value.split("\\").map((s) => Number(s.trim())).filter((n) => !Number.isNaN(n));
+    }
+    return undefined;
+}
+function readCode(seq) {
+    const item = asArray(seq)[0];
+    if (!item)
+        return undefined;
+    const value = item["CodeValue"];
+    const scheme = item["CodingSchemeDesignator"];
+    const meaning = item["CodeMeaning"];
+    if (value === undefined && meaning === undefined)
+        return undefined;
+    return { value: value ?? "", scheme: scheme ?? "", meaning: meaning ?? "" };
+}
+/** Parse one SEG object's bytes. Throws NotSegmentationError / MalformedSegmentationError /
+ *  UnsupportedSegmentationTypeError. */
+export function readSegDataset(bytes) {
+    const ds = naturalize(bytes);
+    const diagnostics = [];
+    const sopClassUID = ds["SOPClassUID"];
+    const modality = ds["Modality"];
+    if (sopClassUID !== undefined && sopClassUID !== SEG_STORAGE_SOP_CLASS_UID && modality !== "SEG") {
+        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`);
+    }
+    const segmentationType = rawType;
+    const rows = ds["Rows"];
+    const columns = ds["Columns"];
+    const numberOfFrames = ds["NumberOfFrames"] ?? 0;
+    if (!Number.isInteger(rows) || rows <= 0)
+        throw new MalformedSegmentationError("missing or invalid Rows");
+    if (!Number.isInteger(columns) || columns <= 0)
+        throw new MalformedSegmentationError("missing or invalid Columns");
+    if (!Number.isInteger(numberOfFrames) || numberOfFrames <= 0) {
+        throw new MalformedSegmentationError(`missing or invalid NumberOfFrames (${numberOfFrames})`);
+    }
+    // --- shared functional groups: orientation + pixel spacing ---
+    const shared = asArray(ds["SharedFunctionalGroupsSequence"])[0];
+    const sharedOrientation = asNumberArray(asArray(shared?.["PlaneOrientationSequence"])[0]?.["ImageOrientationPatient"]);
+    const pixelMeasures = asArray(shared?.["PixelMeasuresSequence"])[0];
+    const pixelSpacing = asNumberArray(pixelMeasures?.["PixelSpacing"]);
+    if (!sharedOrientation || sharedOrientation.length !== 6) {
+        throw new MalformedSegmentationError("SharedFunctionalGroupsSequence is missing PlaneOrientationSequence/ImageOrientationPatient");
+    }
+    if (!pixelSpacing || pixelSpacing.length !== 2) {
+        throw new MalformedSegmentationError("SharedFunctionalGroupsSequence is missing PixelMeasuresSequence/PixelSpacing");
+    }
+    const rowDirection = [at(sharedOrientation, 0), at(sharedOrientation, 1), at(sharedOrientation, 2)];
+    const columnDirection = [at(sharedOrientation, 3), at(sharedOrientation, 4), at(sharedOrientation, 5)];
+    const normal = normalize(cross(rowDirection, columnDirection));
+    // --- per-frame functional groups ---
+    const perFrame = asArray(ds["PerFrameFunctionalGroupsSequence"]);
+    if (perFrame.length !== numberOfFrames) {
+        throw new MalformedSegmentationError(`PerFrameFunctionalGroupsSequence has ${perFrame.length} items but NumberOfFrames is ${numberOfFrames}`);
+    }
+    const rawFrames = perFrame.map((fg, frameIndex) => {
+        const segId = asArray(fg["SegmentIdentificationSequence"])[0];
+        const segmentNumber = Number(segId?.["ReferencedSegmentNumber"]);
+        const ipp = asNumberArray(asArray(fg["PlanePositionSequence"])[0]?.["ImagePositionPatient"]);
+        if (!Number.isInteger(segmentNumber) || segmentNumber <= 0) {
+            throw new MalformedSegmentationError(`frame ${frameIndex}: missing SegmentIdentificationSequence/ReferencedSegmentNumber`);
+        }
+        if (!ipp || ipp.length !== 3) {
+            throw new MalformedSegmentationError(`frame ${frameIndex}: missing PlanePositionSequence/ImagePositionPatient`);
+        }
+        const perFrameOrientation = asNumberArray(asArray(fg["PlaneOrientationSequence"])[0]?.["ImageOrientationPatient"]);
+        if (perFrameOrientation && perFrameOrientation.some((v, i) => Math.abs(v - sharedOrientation[i]) > 1e-6)) {
+            diagnostics.push(createDiagnostic("PER_FRAME_ORIENTATION_VARIES", "warning", `frame ${frameIndex} declares a PlaneOrientationSequence that differs from the shared one; the shared orientation is used`));
+        }
+        return { segmentNumber, position: [at(ipp, 0), at(ipp, 1), at(ipp, 2)], frameIndex };
+    });
+    // --- segments ---
+    const segSeq = asArray(ds["SegmentSequence"]);
+    if (segSeq.length === 0)
+        throw new MalformedSegmentationError("SegmentSequence is absent or empty");
+    const declaredNumbers = new Set();
+    const framesBySegment = new Map();
+    for (const f of rawFrames)
+        framesBySegment.set(f.segmentNumber, (framesBySegment.get(f.segmentNumber) ?? 0) + 1);
+    const segments = segSeq.map((s) => {
+        const number = Number(s["SegmentNumber"]);
+        if (!Number.isInteger(number) || number <= 0) {
+            throw new MalformedSegmentationError(`SegmentSequence item has an invalid SegmentNumber (${s["SegmentNumber"]})`);
+        }
+        declaredNumbers.add(number);
+        return {
+            number,
+            label: s["SegmentLabel"] ?? "",
+            algorithmType: s["SegmentAlgorithmType"] ?? "",
+            algorithmName: s["SegmentAlgorithmName"] || undefined,
+            category: readCode(s["SegmentedPropertyCategoryCodeSequence"]),
+            propertyType: readCode(s["SegmentedPropertyTypeCodeSequence"]),
+            propertyTypeModifier: readCode(s["SegmentedPropertyTypeModifierCodeSequence"]),
+            trackingId: s["TrackingID"] || undefined,
+            trackingUid: s["TrackingUID"] || undefined,
+            frameCount: 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`);
+        }
+    }
+    // --- geometry: distinct plane positions across every frame ---
+    const uniquePositions = [];
+    const tol = DEFAULT_TOLERANCE.positionMm;
+    for (const f of rawFrames) {
+        if (!uniquePositions.some((p) => Math.abs(dot(sub(p, f.position), normal)) <= tol
+            && Math.hypot(...sub(p, f.position)) <= tol)) {
+            uniquePositions.push(f.position);
+        }
+    }
+    const geometry = createGridGeometry({
+        rows: rows,
+        columns: columns,
+        rowDirection,
+        columnDirection,
+        pixelSpacing: [at(pixelSpacing, 0), at(pixelSpacing, 1)],
+        planePositions: uniquePositions,
+        frameOfReferenceUID: ds["FrameOfReferenceUID"],
+    });
+    // map each frame's IPP -> the sorted plane index
+    const planeProjections = geometry.planes.map((p) => dot(p.position, normal));
+    const planeIndexOf = (position) => {
+        const s = dot(position, normal);
+        let best = 0;
+        let bestDist = Infinity;
+        for (let i = 0; i < planeProjections.length; i++) {
+            const d = Math.abs(planeProjections[i] - s);
+            if (d < bestDist) {
+                bestDist = d;
+                best = i;
+            }
+        }
+        return best;
+    };
+    const frames = rawFrames.map((f) => ({
+        segmentNumber: f.segmentNumber,
+        planeIndex: planeIndexOf(f.position),
+        frameIndex: f.frameIndex,
+    }));
+    // --- pixel data ---
+    const pdBuffers = ds["PixelData"];
+    const first = Array.isArray(pdBuffers) ? pdBuffers[0] : pdBuffers;
+    if (!(first instanceof ArrayBuffer)) {
+        throw new MalformedSegmentationError("PixelData (7FE0,0010) is absent or not decodable as raw bytes");
+    }
+    const pixelData = new Uint8Array(first);
+    const rc = rows * columns;
+    let binaryFramesByteAligned = false;
+    if (segmentationType === "BINARY") {
+        const continuousBytes = Math.ceil((numberOfFrames * rc) / 8);
+        const perFrameBytes = numberOfFrames * Math.ceil(rc / 8);
+        if (pixelData.length >= continuousBytes) {
+            binaryFramesByteAligned = false;
+        }
+        else if (pixelData.length >= perFrameBytes && perFrameBytes !== continuousBytes) {
+            binaryFramesByteAligned = true;
+            diagnostics.push(createDiagnostic("BINARY_FRAMES_BYTE_ALIGNED", "info", "BINARY frames are individually byte-padded rather than packed as one continuous bitstream"));
+        }
+        else {
+            throw new MalformedSegmentationError(`PixelData is ${pixelData.length} bytes; a BINARY SEG of ${numberOfFrames} frames × ${rc} px needs ${continuousBytes}`);
+        }
+    }
+    else {
+        if (pixelData.length < numberOfFrames * rc) {
+            throw new MalformedSegmentationError(`PixelData is ${pixelData.length} bytes; a FRACTIONAL SEG of ${numberOfFrames} frames × ${rc} px needs ${numberOfFrames * rc}`);
+        }
+    }
+    // --- fractional-specific ---
+    let fractionalType;
+    let maximumFractionalValue;
+    if (segmentationType === "FRACTIONAL") {
+        const rawFrac = (ds["SegmentationFractionalType"] ?? "").toUpperCase();
+        if (rawFrac === "PROBABILITY" || rawFrac === "OCCUPANCY") {
+            fractionalType = rawFrac;
+        }
+        else {
+            diagnostics.push(createDiagnostic("FRACTIONAL_TYPE_ABSENT", "warning", "FRACTIONAL SEG did not declare SegmentationFractionalType (0062,0010); PROBABILITY vs OCCUPANCY is unknown"));
+        }
+        const maxRaw = ds["MaximumFractionalValue"];
+        if (Number.isFinite(maxRaw) && maxRaw > 0) {
+            maximumFractionalValue = maxRaw;
+        }
+        else {
+            maximumFractionalValue = 255;
+            diagnostics.push(createDiagnostic("MISSING_MAX_FRACTIONAL_VALUE", "warning", `MaximumFractionalValue (0062,000E) is ${maxRaw === undefined ? "absent" : `invalid (${maxRaw})`}; assuming 255`));
+        }
+        // Bimodal check (roadmap §7.1): a FRACTIONAL field whose non-zero values are almost all
+        // pinned at the max is a thresholded / binary mask stored as FRACTIONAL, not a graded
+        // probability or occupancy. One pass over the 8-bit pixel bytes.
+        const max = maximumFractionalValue;
+        const nearMax = max - Math.max(1, Math.floor(max * 0.02));
+        let nonZero = 0;
+        let atExtreme = 0;
+        for (let i = 0; i < pixelData.length; i++) {
+            const v = pixelData[i];
+            if (v === 0)
+                continue;
+            nonZero++;
+            if (v >= nearMax)
+                atExtreme++;
+        }
+        if (nonZero > 0 && atExtreme / nonZero >= 0.98) {
+            diagnostics.push(createDiagnostic("FRACTIONAL_VALUES_LOOK_BINARY", "warning", `${((atExtreme / nonZero) * 100).toFixed(1)}% of non-zero values are at (or within 2% of) MaximumFractionalValue ` +
+                `(${max}) — this ${fractionalType ?? "FRACTIONAL"} field is effectively a binary mask stored as FRACTIONAL, ` +
+                `not a graded field`));
+        }
+    }
+    const segmentsOverlap = (ds["SegmentsOverlap"] ?? "UNDEFINED").toUpperCase();
+    if (segmentsOverlap === "YES") {
+        diagnostics.push(createDiagnostic("SEGMENTS_OVERLAP", "info", "SegmentsOverlap is YES — segments may share voxels; do not assume a partition"));
+    }
+    return {
+        segmentationType,
+        fractionalType,
+        maximumFractionalValue,
+        segmentsOverlap,
+        geometry,
+        frameOfReferenceUID: ds["FrameOfReferenceUID"],
+        contentLabel: ds["ContentLabel"] || undefined,
+        rows: rows,
+        columns: columns,
+        numberOfFrames,
+        segments,
+        frames,
+        pixelData,
+        binaryFramesByteAligned,
+        diagnostics,
+    };
+}
+// The full continuous bitstream, unpacked once per ParsedSeg (BitArray.unpack returns
+// one byte per bit, so this is ~8× the PixelData size — still cheap next to re-unpacking
+// the whole stream for every frame, which is O(frames²) work on a large SEG).
+const continuousBitsCache = new WeakMap();
+/** Unpacked 0/1 bits for BINARY frame `frameIndex` (length rows·columns). */
+export function binaryFrame(parsed, frameIndex) {
+    const rc = parsed.rows * parsed.columns;
+    const out = new Uint8Array(rc);
+    if (parsed.binaryFramesByteAligned) {
+        const frameBytes = Math.ceil(rc / 8);
+        const offset = frameIndex * frameBytes;
+        const bits = BitArray.unpack(parsed.pixelData.subarray(offset, offset + frameBytes));
+        for (let i = 0; i < rc; i++)
+            out[i] = bits[i] ? 1 : 0;
+        return out;
+    }
+    let allBits = continuousBitsCache.get(parsed);
+    if (!allBits) {
+        allBits = BitArray.unpack(parsed.pixelData);
+        continuousBitsCache.set(parsed, allBits);
+    }
+    const base = frameIndex * rc;
+    for (let i = 0; i < rc; i++)
+        out[i] = allBits[base + i] ? 1 : 0;
+    return out;
+}
+/** Raw 8-bit values for FRACTIONAL frame `frameIndex` (length rows·columns). */
+export function fractionalFrame(parsed, frameIndex) {
+    const rc = parsed.rows * parsed.columns;
+    const offset = frameIndex * rc;
+    return parsed.pixelData.subarray(offset, offset + rc);
+}
+export function encodeSegFrames(options) {
+    const rows = options.rows;
+    const columns = options.columns;
+    const rc = rows * columns;
+    const rowDirection = options.rowDirection ?? [1, 0, 0];
+    const columnDirection = options.columnDirection ?? [0, 1, 0];
+    const isBinary = options.segmentationType === "BINARY";
+    const perFrameGroups = options.frames.map((f) => ({
+        FrameContentSequence: [{ StackID: "1", InStackPositionNumber: 1, DimensionIndexValues: [f.segmentNumber, 1] }],
+        PlanePositionSequence: [{ ImagePositionPatient: [...f.position] }],
+        SegmentIdentificationSequence: [{ ReferencedSegmentNumber: f.segmentNumber }],
+    }));
+    let pixelBuffer;
+    if (isBinary) {
+        const bits = [];
+        for (const f of options.frames)
+            for (let i = 0; i < rc; i++)
+                bits.push(f.pixels[i] ? 1 : 0);
+        pixelBuffer = BitArray.pack(bits).buffer.slice(0);
+    }
+    else {
+        const bytes = new Uint8Array(options.frames.length * rc);
+        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);
+    }
+    const dataset = {
+        _meta: {},
+        SOPClassUID: options.sopClassUID ?? SEG_STORAGE_SOP_CLASS_UID,
+        SOPInstanceUID: DicomMetaDictionary.uid(),
+        Modality: options.modality ?? "SEG",
+        SamplesPerPixel: 1,
+        PhotometricInterpretation: "MONOCHROME2",
+        Rows: rows,
+        Columns: columns,
+        NumberOfFrames: options.frames.length,
+        BitsAllocated: isBinary ? 1 : 8,
+        BitsStored: isBinary ? 1 : 8,
+        HighBit: isBinary ? 0 : 7,
+        PixelRepresentation: 0,
+        SegmentationType: options.forceType ?? options.segmentationType,
+        SegmentsOverlap: options.segmentsOverlap ?? "NO",
+        FrameOfReferenceUID: options.frameOfReferenceUID ?? DicomMetaDictionary.uid(),
+        ContentLabel: "SEG",
+        SegmentSequence: options.segments.map((s) => {
+            const code = (c) => ({
+                CodeValue: c.value,
+                CodingSchemeDesignator: c.scheme,
+                CodeMeaning: c.meaning,
+            });
+            const item = {
+                SegmentNumber: s.number,
+                SegmentLabel: s.label ?? `segment-${s.number}`,
+                SegmentAlgorithmType: s.algorithmType ?? "AUTOMATIC",
+                SegmentAlgorithmName: s.algorithmName ?? "dicom-seg-js",
+                SegmentedPropertyCategoryCodeSequence: [
+                    s.category ? code(s.category) : { CodeValue: "T-D0050", CodingSchemeDesignator: "SRT", CodeMeaning: "Tissue" },
+                ],
+                SegmentedPropertyTypeCodeSequence: [
+                    s.propertyType ? code(s.propertyType) : { CodeValue: "T-62000", CodingSchemeDesignator: "SRT", CodeMeaning: "Liver" },
+                ],
+            };
+            if (s.propertyTypeModifier)
+                item["SegmentedPropertyTypeModifierCodeSequence"] = [code(s.propertyTypeModifier)];
+            if (s.trackingId !== undefined)
+                item["TrackingID"] = s.trackingId;
+            if (s.trackingUid !== undefined)
+                item["TrackingUID"] = s.trackingUid;
+            return item;
+        }),
+        SharedFunctionalGroupsSequence: [
+            {
+                PlaneOrientationSequence: [{ ImageOrientationPatient: [...rowDirection, ...columnDirection] }],
+                PixelMeasuresSequence: [
+                    {
+                        PixelSpacing: [...(options.pixelSpacing ?? [1, 1])],
+                        SliceThickness: options.sliceThickness ?? 1,
+                        SpacingBetweenSlices: options.sliceThickness ?? 1,
+                    },
+                ],
+            },
+        ],
+        PerFrameFunctionalGroupsSequence: perFrameGroups,
+    };
+    if (!isBinary) {
+        if (!options.omitFractionalType)
+            dataset["SegmentationFractionalType"] = options.fractionalType ?? "PROBABILITY";
+        if (!options.omitMaximumFractionalValue)
+            dataset["MaximumFractionalValue"] = options.maximumFractionalValue ?? 255;
+    }
+    const meta = {
+        MediaStorageSOPClassUID: dataset["SOPClassUID"],
+        MediaStorageSOPInstanceUID: dataset["SOPInstanceUID"],
+        ImplementationClassUID: DicomMetaDictionary.uid(),
+        ImplementationVersionName: "dicom-seg-js",
+        TransferSyntaxUID: TRANSFER_SYNTAX_UID,
+    };
+    const dicomDict = new DicomDict(DicomMetaDictionary.denaturalizeDataset(meta));
+    dicomDict.dict = DicomMetaDictionary.denaturalizeDataset(dataset);
+    dicomDict.dict[TAG_PIXEL_DATA] = { vr: "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)}`);
+    }
+    if (!isBinary && 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 numbers = new Set();
+    for (const s of options.segments) {
+        if (!Number.isInteger(s.number) || s.number <= 0) {
+            throw new RangeError(`writeSeg: segment number must be a positive integer, got ${s.number}`);
+        }
+        if (numbers.has(s.number))
+            throw new RangeError(`writeSeg: duplicate segment number ${s.number}`);
+        numbers.add(s.number);
+    }
+    const maxFractional = options.maximumFractionalValue ?? 255;
+    if (!isBinary && (!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 structures = options.segments.map((s) => {
+        const structure = isBinary ? s.mask : s.field;
+        if (!structure) {
+            throw new TypeError(`writeSeg: segment ${s.number} is missing its ${isBinary ? "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`);
+        }
+    }
+    const columns = geometry.columns;
+    const rows = geometry.rows;
+    const rc = columns * rows;
+    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.)
+    const frames = [];
+    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);
+            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;
+                }
+            }
+            frames.push({ segmentNumber: s.number, position: planePositions[k], pixels });
+        }
+    });
+    const segmentsOverlap = options.segmentsOverlap ?? (options.segments.length === 1 ? "NO" : "UNDEFINED");
+    const encodeOptions = {
+        rows,
+        columns,
+        segmentationType: options.segmentationType,
+        rowDirection: geometry.rowDirection,
+        columnDirection: geometry.columnDirection,
+        pixelSpacing: geometry.pixelSpacing,
+        sliceThickness,
+        segmentsOverlap,
+        segments: options.segments.map((s) => ({
+            number: s.number,
+            label: s.label,
+            algorithmType: s.algorithmType ?? "AUTOMATIC",
+            algorithmName: s.algorithmName ?? "dicom-seg-js",
+            ...(s.category ? { category: s.category } : {}),
+            ...(s.propertyType ? { propertyType: s.propertyType } : {}),
+            ...(s.propertyTypeModifier ? { propertyTypeModifier: s.propertyTypeModifier } : {}),
+            ...(s.trackingId !== undefined ? { trackingId: s.trackingId } : {}),
+            ...(s.trackingUid !== undefined ? { trackingUid: s.trackingUid } : {}),
+        })),
+        frames,
+        ...(options.frameOfReferenceUID ?? geometry.frameOfReferenceUID
+            ? { frameOfReferenceUID: (options.frameOfReferenceUID ?? geometry.frameOfReferenceUID) }
+            : {}),
+        ...(isBinary ? {} : { fractionalType: options.fractionalType, maximumFractionalValue: maxFractional }),
+    };
+    return encodeSegFrames(encodeOptions);
+}

package/dist/errors.d.ts

@@ -0,0 +1,38 @@
+/**
+ * dicom-seg-js-specific errors. Geometry-core errors (ResourceLimitError,
+ * GridMismatchError, NonParallelPlanesError, …) live in rt-geometry-js and are re-exported
+ * from this package's entry point.
+ */
+/**
+ * The supplied bytes are not a DICOM Segmentation. `SOPClassUID` (0008,0016) is present and
+ * is not Segmentation Storage (`1.2.840.10008.5.1.4.1.1.66.4`), and `Modality` (0008,0060)
+ * is not `"SEG"`.
+ */
+export declare class NotSegmentationError extends Error {
+    constructor(message: string);
+}
+/**
+ * The segmentation cannot be assembled: a required element is missing
+ * (`SegmentSequence`, the shared `PixelMeasuresSequence` / `PlaneOrientationSequence`,
+ * `Rows`/`Columns`), the per-frame functional-group count disagrees with `NumberOfFrames`,
+ * a frame references an undeclared `SegmentNumber`, or the decoded `PixelData` is too
+ * short for the frame count.
+ */
+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.
+ */
+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.
+ */
+export declare class SegmentationTypeMismatchError extends Error {
+    constructor(message: string);
+}

package/dist/errors.js

@@ -0,0 +1,50 @@
+/**
+ * dicom-seg-js-specific errors. Geometry-core errors (ResourceLimitError,
+ * GridMismatchError, NonParallelPlanesError, …) live in rt-geometry-js and are re-exported
+ * from this package's entry point.
+ */
+/**
+ * The supplied bytes are not a DICOM Segmentation. `SOPClassUID` (0008,0016) is present and
+ * is not Segmentation Storage (`1.2.840.10008.5.1.4.1.1.66.4`), and `Modality` (0008,0060)
+ * is not `"SEG"`.
+ */
+export class NotSegmentationError extends Error {
+    constructor(message) {
+        super(`NotSegmentationError: ${message}`);
+        this.name = "NotSegmentationError";
+    }
+}
+/**
+ * The segmentation cannot be assembled: a required element is missing
+ * (`SegmentSequence`, the shared `PixelMeasuresSequence` / `PlaneOrientationSequence`,
+ * `Rows`/`Columns`), the per-frame functional-group count disagrees with `NumberOfFrames`,
+ * a frame references an undeclared `SegmentNumber`, or the decoded `PixelData` is too
+ * short for the frame count.
+ */
+export class MalformedSegmentationError extends Error {
+    constructor(message) {
+        super(`MalformedSegmentationError: ${message}`);
+        this.name = "MalformedSegmentationError";
+    }
+}
+/**
+ * `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.
+ */
+export class UnsupportedSegmentationTypeError extends Error {
+    constructor(message) {
+        super(`UnsupportedSegmentationTypeError: ${message}`);
+        this.name = "UnsupportedSegmentationTypeError";
+    }
+}
+/**
+ * `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.
+ */
+export class SegmentationTypeMismatchError extends Error {
+    constructor(message) {
+        super(`SegmentationTypeMismatchError: ${message}`);
+        this.name = "SegmentationTypeMismatchError";
+    }
+}