@knopkem/dicomview 0.1.0

package/README.md

@@ -0,0 +1,43 @@
+# @dicomview/core
+
+`@dicomview/core` is the browser package for `dicomview-rs`. It wraps the Rust/WASM viewer, handles wasm initialization, and provides a DICOMweb loader with optional worker-based decode.
+
+## Build
+
+```bash
+npm install
+npm run build
+```
+
+`npm run build` performs two steps:
+
+1. `wasm-pack build ../crates/dicomview-wasm --target web --out-dir ../../js/wasm`
+2. `tsc -p tsconfig.json`
+
+The wasm-pack output is emitted into `js/wasm/`, which is the directory shipped in the npm tarball.
+
+## Publish checklist
+
+```bash
+npm install
+npm run build
+npm pack --dry-run
+npm publish
+```
+
+
+## Public API
+
+```ts
+import { DICOMwebLoader, Presets, Viewer } from "@dicomview/core";
+```
+
+- `Viewer.create(...)` mounts the four-canvas Rust/WebGPU renderer
+- `DICOMwebLoader.loadSeries(...)` streams a DICOMweb series into the viewer
+- `Presets` exposes the built-in CT/MR transfer-function identifiers
+
+## Notes
+
+- the loader currently expects single-frame instances from DICOMweb
+- worker decode is optional and enabled with `decodeWorkers > 0`
+- rendering requires browser WebGPU support

package/dist/decode-worker.d.ts

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

package/dist/decode-worker.js

@@ -0,0 +1,30 @@
+import initWasm, { decode_dicom_pixels } from "../wasm/dicomview_wasm.js";
+let wasmReady = null;
+self.addEventListener("message", async (event) => {
+    const message = event.data;
+    if (message.type !== "decode") {
+        return;
+    }
+    try {
+        if (!wasmReady) {
+            wasmReady = initWasm(message.wasmUrl);
+        }
+        await wasmReady;
+        const pixels = decode_dicom_pixels(new Uint8Array(message.bytes));
+        const response = {
+            type: "decoded",
+            jobId: message.jobId,
+            sliceIndex: message.sliceIndex,
+            pixels,
+        };
+        self.postMessage(response, [pixels.buffer]);
+    }
+    catch (error) {
+        const response = {
+            type: "error",
+            jobId: message.jobId,
+            message: error instanceof Error ? error.message : String(error),
+        };
+        self.postMessage(response);
+    }
+});

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { DICOMwebLoader } from "./loader.js";
+export { Presets } from "./presets.js";
+export { ensureDicomviewWasm, Viewer } from "./viewer.js";
+export type { BlendMode, DICOMwebLoaderOptions, ProgressCallback, ProjectionMode, SeriesParams, ThickSlabOptions, ViewportId, ViewerOptions, VolumeGeometry, VolumePreset, WasmSource, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { DICOMwebLoader } from "./loader.js";
+export { Presets } from "./presets.js";
+export { ensureDicomviewWasm, Viewer } from "./viewer.js";

package/dist/loader.d.ts

@@ -0,0 +1,9 @@
+import { Viewer } from "./viewer.js";
+import type { DICOMwebLoaderOptions, ProgressCallback, SeriesParams } from "./types.js";
+export declare class DICOMwebLoader {
+    #private;
+    constructor(options: DICOMwebLoaderOptions);
+    onProgress(callback: ProgressCallback): void;
+    abort(): void;
+    loadSeries(viewer: Viewer, params: SeriesParams): Promise<void>;
+}

package/dist/loader.js

@@ -0,0 +1,344 @@
+export class DICOMwebLoader {
+    #options;
+    #progressCallback = null;
+    #abortController = null;
+    constructor(options) {
+        this.#options = {
+            ...options,
+            concurrency: Math.max(1, options.concurrency ?? 4),
+            decodeWorkers: Math.max(0, options.decodeWorkers ?? 0),
+        };
+    }
+    onProgress(callback) {
+        this.#progressCallback = callback;
+    }
+    abort() {
+        this.#abortController?.abort();
+        this.#abortController = null;
+    }
+    async loadSeries(viewer, params) {
+        const controller = new AbortController();
+        this.#abortController = controller;
+        const metadataUrl = [
+            trimRoot(this.#options.wadoRoot),
+            "studies",
+            encodeURIComponent(params.studyUid),
+            "series",
+            encodeURIComponent(params.seriesUid),
+            "metadata",
+        ].join("/");
+        const metadataJson = (await this.#fetchJson(metadataUrl, controller.signal));
+        const instances = parseSeriesMetadata(metadataJson);
+        const geometry = deriveGeometry(instances);
+        viewer.prepareVolume(geometry);
+        const pool = this.#createDecodeWorkerPool();
+        const total = instances.length;
+        let loaded = 0;
+        let nextIndex = 0;
+        let renderScheduled = false;
+        const scheduleRender = () => {
+            if (renderScheduled) {
+                return;
+            }
+            renderScheduled = true;
+            const requestFrame = typeof requestAnimationFrame === "function"
+                ? requestAnimationFrame
+                : (callback) => {
+                    callback(0);
+                    return 0;
+                };
+            requestFrame(() => {
+                renderScheduled = false;
+                viewer.render();
+            });
+        };
+        try {
+            const workers = Array.from({ length: Math.min(this.#options.concurrency ?? 1, total) }, async () => {
+                while (true) {
+                    const sliceIndex = nextIndex;
+                    nextIndex += 1;
+                    if (sliceIndex >= total) {
+                        return;
+                    }
+                    const instance = instances[sliceIndex];
+                    const instanceUrl = [
+                        trimRoot(this.#options.wadoRoot),
+                        "studies",
+                        encodeURIComponent(params.studyUid),
+                        "series",
+                        encodeURIComponent(params.seriesUid),
+                        "instances",
+                        encodeURIComponent(instance.sopInstanceUid),
+                    ].join("/");
+                    const bytes = await this.#fetchBytes(instanceUrl, controller.signal);
+                    if (pool) {
+                        const decoded = await pool.decode(sliceIndex, bytes);
+                        viewer.feedPixelSlice(decoded.sliceIndex, decoded.pixels);
+                    }
+                    else {
+                        viewer.feedDicomSlice(sliceIndex, bytes);
+                    }
+                    loaded += 1;
+                    this.#progressCallback?.(loaded, total);
+                    scheduleRender();
+                }
+            });
+            await Promise.all(workers);
+            viewer.render();
+        }
+        finally {
+            pool?.destroy();
+            if (this.#abortController === controller) {
+                this.#abortController = null;
+            }
+        }
+    }
+    async #fetchJson(url, signal) {
+        const response = await this.#fetch(url, signal, "application/dicom+json");
+        return response.json();
+    }
+    async #fetchBytes(url, signal) {
+        const response = await this.#fetch(url, signal, "application/dicom; transfer-syntax=*");
+        return new Uint8Array(await response.arrayBuffer());
+    }
+    async #fetch(url, signal, accept) {
+        const fetchImpl = this.#options.fetch ?? globalThis.fetch.bind(globalThis);
+        const headers = new Headers(this.#options.headers);
+        headers.set("Accept", accept);
+        const response = await fetchImpl(url, {
+            method: "GET",
+            headers,
+            signal,
+        });
+        if (!response.ok) {
+            throw new Error(`HTTP ${response.status} while fetching ${url}`);
+        }
+        return response;
+    }
+    #createDecodeWorkerPool() {
+        const requested = this.#options.decodeWorkers ?? 0;
+        if (requested <= 0 || typeof Worker === "undefined") {
+            return null;
+        }
+        const wasmUrl = normalizeWorkerWasmUrl(this.#options.wasmUrl);
+        return new DecodeWorkerPool(requested, wasmUrl);
+    }
+}
+class DecodeWorkerPool {
+    #workers;
+    #pending = new Map();
+    #workerUrl = new URL("./decode-worker.js", import.meta.url);
+    #nextWorkerIndex = 0;
+    #nextJobId = 1;
+    constructor(size, wasmUrl) {
+        this.#workers = Array.from({ length: size }, () => {
+            const worker = new Worker(this.#workerUrl, { type: "module" });
+            worker.addEventListener("message", (event) => {
+                const message = event.data;
+                const pending = this.#pending.get(message.jobId);
+                if (!pending) {
+                    return;
+                }
+                this.#pending.delete(message.jobId);
+                if (message.type === "decoded") {
+                    pending.resolve({
+                        sliceIndex: message.sliceIndex,
+                        pixels: message.pixels,
+                    });
+                }
+                else {
+                    pending.reject(new Error(message.message));
+                }
+            });
+            worker.addEventListener("error", (event) => {
+                for (const [jobId, pending] of this.#pending) {
+                    this.#pending.delete(jobId);
+                    pending.reject(event.error ?? new Error(event.message));
+                }
+            });
+            worker.__dicomviewWasmUrl = wasmUrl;
+            return worker;
+        });
+    }
+    decode(sliceIndex, bytes) {
+        const worker = this.#workers[this.#nextWorkerIndex];
+        this.#nextWorkerIndex = (this.#nextWorkerIndex + 1) % this.#workers.length;
+        const jobId = this.#nextJobId;
+        this.#nextJobId += 1;
+        const buffer = bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+        const message = {
+            type: "decode",
+            jobId,
+            sliceIndex,
+            wasmUrl: worker.__dicomviewWasmUrl,
+            bytes: buffer,
+        };
+        worker.postMessage(message, [buffer]);
+        return new Promise((resolve, reject) => {
+            this.#pending.set(jobId, { resolve, reject });
+        });
+    }
+    destroy() {
+        for (const worker of this.#workers) {
+            worker.terminate();
+        }
+        this.#workers.length = 0;
+        this.#pending.clear();
+    }
+}
+function parseSeriesMetadata(metadata) {
+    const instances = metadata.map(parseInstanceMetadata);
+    instances.sort(compareInstances);
+    return instances;
+}
+function parseInstanceMetadata(instance) {
+    const sopInstanceUid = firstString(instance, "00080018");
+    if (!sopInstanceUid) {
+        throw new Error("DICOMweb metadata is missing SOP Instance UID");
+    }
+    const rows = firstNumber(instance, "00280010");
+    const columns = firstNumber(instance, "00280011");
+    if (rows === undefined || columns === undefined) {
+        throw new Error("DICOMweb metadata is missing image dimensions");
+    }
+    const orientation = firstNumberArray(instance, "00200037", 6);
+    return {
+        sopInstanceUid,
+        instanceNumber: firstNumber(instance, "00200013") ?? 0,
+        rows,
+        columns,
+        pixelSpacing: pairNumberArray(instance, "00280030"),
+        sliceThickness: firstNumber(instance, "00180050"),
+        imagePosition: tripletNumberArray(instance, "00200032"),
+        imageOrientation: orientation
+            ? [
+                [orientation[0], orientation[1], orientation[2]],
+                [orientation[3], orientation[4], orientation[5]],
+            ]
+            : undefined,
+        numberOfFrames: firstNumber(instance, "00280008") ?? 1,
+    };
+}
+function deriveGeometry(instances) {
+    if (instances.length === 0) {
+        throw new Error("Series metadata is empty");
+    }
+    if (instances.some((instance) => instance.numberOfFrames !== 1)) {
+        throw new Error("Multi-frame DICOMweb metadata is not yet supported");
+    }
+    const first = instances[0];
+    if (instances.some((instance) => instance.rows !== first.rows || instance.columns !== first.columns)) {
+        throw new Error("Series contains inconsistent frame dimensions");
+    }
+    const rowDirection = first.imageOrientation?.[0] ?? [1, 0, 0];
+    const columnDirection = first.imageOrientation?.[1] ?? [0, 1, 0];
+    const normal = normalize(cross(rowDirection, columnDirection));
+    const pixelSpacing = first.pixelSpacing ?? [1, 1];
+    const sliceSpacing = projectedSliceSpacing(instances) ?? first.sliceThickness ?? 1;
+    return {
+        dimensions: [first.columns, first.rows, instances.length],
+        spacing: [pixelSpacing[1], pixelSpacing[0], sliceSpacing],
+        origin: first.imagePosition ?? [0, 0, 0],
+        direction: [rowDirection, columnDirection, normal],
+    };
+}
+function projectedSliceSpacing(instances) {
+    if (instances.length < 2) {
+        return undefined;
+    }
+    const row = instances[0].imageOrientation?.[0];
+    const col = instances[0].imageOrientation?.[1];
+    const first = instances[0].imagePosition;
+    const second = instances[1].imagePosition;
+    if (!row || !col || !first || !second) {
+        return undefined;
+    }
+    const normal = normalize(cross(row, col));
+    return Math.abs(dot(normal, subtract(second, first)));
+}
+function compareInstances(left, right) {
+    const row = left.imageOrientation?.[0];
+    const col = left.imageOrientation?.[1];
+    if (left.imagePosition && right.imagePosition && row && col) {
+        const normal = normalize(cross(row, col));
+        const leftDistance = dot(normal, left.imagePosition);
+        const rightDistance = dot(normal, right.imagePosition);
+        return leftDistance - rightDistance;
+    }
+    return (left.instanceNumber - right.instanceNumber ||
+        left.sopInstanceUid.localeCompare(right.sopInstanceUid));
+}
+function tripletNumberArray(instance, tag) {
+    const values = firstNumberArray(instance, tag, 3);
+    return values ? [values[0], values[1], values[2]] : undefined;
+}
+function pairNumberArray(instance, tag) {
+    const values = firstNumberArray(instance, tag, 2);
+    return values ? [values[0], values[1]] : undefined;
+}
+function firstNumberArray(instance, tag, length) {
+    const values = instance[tag]?.Value;
+    if (!values || values.length < length) {
+        return undefined;
+    }
+    return values.slice(0, length).map((value) => {
+        if (typeof value === "number") {
+            return value;
+        }
+        const parsed = Number.parseFloat(value);
+        if (!Number.isFinite(parsed)) {
+            throw new Error(`Tag ${tag} contains a non-numeric value`);
+        }
+        return parsed;
+    });
+}
+function firstNumber(instance, tag) {
+    const value = instance[tag]?.Value?.[0];
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value === "number") {
+        return value;
+    }
+    const parsed = Number.parseFloat(value);
+    if (!Number.isFinite(parsed)) {
+        throw new Error(`Tag ${tag} contains a non-numeric value`);
+    }
+    return parsed;
+}
+function firstString(instance, tag) {
+    const value = instance[tag]?.Value?.[0];
+    return typeof value === "string" ? value : undefined;
+}
+function trimRoot(root) {
+    return root.replace(/\/+$/, "");
+}
+function normalizeWorkerWasmUrl(wasmUrl) {
+    if (typeof wasmUrl === "string") {
+        return wasmUrl;
+    }
+    if (wasmUrl instanceof URL) {
+        return wasmUrl.toString();
+    }
+    return undefined;
+}
+function subtract(left, right) {
+    return [left[0] - right[0], left[1] - right[1], left[2] - right[2]];
+}
+function cross(left, right) {
+    return [
+        left[1] * right[2] - left[2] * right[1],
+        left[2] * right[0] - left[0] * right[2],
+        left[0] * right[1] - left[1] * right[0],
+    ];
+}
+function dot(left, right) {
+    return left[0] * right[0] + left[1] * right[1] + left[2] * right[2];
+}
+function normalize(vector) {
+    const length = Math.hypot(vector[0], vector[1], vector[2]);
+    if (length === 0) {
+        return [0, 0, 1];
+    }
+    return [vector[0] / length, vector[1] / length, vector[2] / length];
+}

package/dist/presets.d.ts

@@ -0,0 +1,9 @@
+export declare const Presets: {
+    readonly CT_BONE: "ct-bone";
+    readonly CT_SOFT_TISSUE: "ct-soft-tissue";
+    readonly CT_LUNG: "ct-lung";
+    readonly CT_MIP: "ct-mip";
+    readonly MR_DEFAULT: "mr-default";
+    readonly MR_ANGIO: "mr-angio";
+    readonly MR_T2_BRAIN: "mr-t2-brain";
+};

package/dist/presets.js

@@ -0,0 +1,9 @@
+export const Presets = {
+    CT_BONE: "ct-bone",
+    CT_SOFT_TISSUE: "ct-soft-tissue",
+    CT_LUNG: "ct-lung",
+    CT_MIP: "ct-mip",
+    MR_DEFAULT: "mr-default",
+    MR_ANGIO: "mr-angio",
+    MR_T2_BRAIN: "mr-t2-brain",
+};

package/dist/types.d.ts

@@ -0,0 +1,52 @@
+export type ViewportId = "axial" | "coronal" | "sagittal";
+export type BlendMode = "composite" | "mip" | "minip" | "average";
+export type ProjectionMode = "thin" | "mip" | "minip" | "average";
+export type VolumePreset = "ct-bone" | "ct-soft-tissue" | "ct-lung" | "ct-mip" | "mr-default" | "mr-angio" | "mr-t2-brain";
+export type WasmSource = string | URL | Request | Response;
+export interface VolumeGeometry {
+    dimensions: [number, number, number];
+    spacing: [number, number, number];
+    origin: [number, number, number];
+    direction: [
+        [
+            number,
+            number,
+            number
+        ],
+        [
+            number,
+            number,
+            number
+        ],
+        [
+            number,
+            number,
+            number
+        ]
+    ];
+}
+export interface ViewerOptions {
+    axial: HTMLCanvasElement;
+    coronal: HTMLCanvasElement;
+    sagittal: HTMLCanvasElement;
+    volume: HTMLCanvasElement;
+    wasmUrl?: WasmSource;
+}
+export interface ThickSlabOptions {
+    viewport: ViewportId;
+    thickness: number;
+    projection: ProjectionMode;
+}
+export interface SeriesParams {
+    studyUid: string;
+    seriesUid: string;
+}
+export type ProgressCallback = (loaded: number, total: number) => void;
+export interface DICOMwebLoaderOptions {
+    wadoRoot: string;
+    fetch?: typeof fetch;
+    headers?: HeadersInit;
+    concurrency?: number;
+    decodeWorkers?: number;
+    wasmUrl?: WasmSource;
+}

package/dist/types.js

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

package/dist/viewer.d.ts

@@ -0,0 +1,23 @@
+import type { BlendMode, ThickSlabOptions, ViewerOptions, ViewportId, VolumeGeometry, VolumePreset, WasmSource } from "./types.js";
+export declare function ensureDicomviewWasm(wasmUrl?: WasmSource): Promise<void>;
+export declare class Viewer {
+    #private;
+    private constructor();
+    static create(options: ViewerOptions): Promise<Viewer>;
+    get loadingProgress(): number;
+    prepareVolume(geometry: VolumeGeometry): void;
+    feedDicomSlice(zIndex: number, bytes: ArrayBuffer | ArrayBufferView): void;
+    feedPixelSlice(zIndex: number, pixels: Int16Array | ArrayBuffer): void;
+    render(): void;
+    setCrosshair(x: number, y: number, z: number): void;
+    scrollSlice(viewport: ViewportId, delta: number): void;
+    setWindowLevel(center: number, width: number): void;
+    orbit(dx: number, dy: number): void;
+    pan(dx: number, dy: number): void;
+    zoom(factor: number): void;
+    setBlendMode(mode: BlendMode): void;
+    setThickSlab(options: ThickSlabOptions): void;
+    setVolumePreset(preset: VolumePreset): void;
+    reset(): void;
+    destroy(): void;
+}

package/dist/viewer.js

@@ -0,0 +1,108 @@
+import initWasm, { Viewer as WasmViewer } from "../wasm/dicomview_wasm.js";
+const VIEWPORT_CODE = {
+    axial: 0,
+    coronal: 1,
+    sagittal: 2,
+};
+const BLEND_MODE_CODE = {
+    composite: 0,
+    mip: 1,
+    minip: 2,
+    average: 3,
+};
+const PROJECTION_CODE = {
+    thin: 0,
+    mip: 1,
+    minip: 2,
+    average: 3,
+};
+let wasmInitPromise = null;
+export async function ensureDicomviewWasm(wasmUrl) {
+    if (!wasmInitPromise) {
+        wasmInitPromise = initWasm(wasmUrl);
+    }
+    await wasmInitPromise;
+}
+export class Viewer {
+    #inner;
+    constructor(inner) {
+        this.#inner = inner;
+    }
+    static async create(options) {
+        await ensureDicomviewWasm(options.wasmUrl);
+        const inner = await WasmViewer.create({
+            axial: options.axial,
+            coronal: options.coronal,
+            sagittal: options.sagittal,
+            volume: options.volume,
+        });
+        return new Viewer(inner);
+    }
+    get loadingProgress() {
+        return this.#requireInner().loading_progress();
+    }
+    prepareVolume(geometry) {
+        this.#requireInner().prepare_volume(geometry);
+    }
+    feedDicomSlice(zIndex, bytes) {
+        this.#requireInner().feed_dicom_slice(zIndex, toUint8Array(bytes));
+    }
+    feedPixelSlice(zIndex, pixels) {
+        const data = pixels instanceof Int16Array ? pixels : new Int16Array(pixels);
+        this.#requireInner().feed_pixel_slice(zIndex, data);
+    }
+    render() {
+        this.#requireInner().render();
+    }
+    setCrosshair(x, y, z) {
+        this.#requireInner().set_crosshair(x, y, z);
+    }
+    scrollSlice(viewport, delta) {
+        this.#requireInner().scroll_slice(VIEWPORT_CODE[viewport], delta);
+    }
+    setWindowLevel(center, width) {
+        this.#requireInner().set_window_level(center, width);
+    }
+    orbit(dx, dy) {
+        this.#requireInner().orbit(dx, dy);
+    }
+    pan(dx, dy) {
+        this.#requireInner().pan(dx, dy);
+    }
+    zoom(factor) {
+        this.#requireInner().zoom(factor);
+    }
+    setBlendMode(mode) {
+        this.#requireInner().set_blend_mode(BLEND_MODE_CODE[mode]);
+    }
+    setThickSlab(options) {
+        this.#requireInner().set_thick_slab(VIEWPORT_CODE[options.viewport], options.thickness, PROJECTION_CODE[options.projection]);
+    }
+    setVolumePreset(preset) {
+        this.#requireInner().set_volume_preset(preset);
+    }
+    reset() {
+        this.#requireInner().reset();
+    }
+    destroy() {
+        if (this.#inner) {
+            this.#inner.destroy();
+            this.#inner = null;
+        }
+    }
+    #requireInner() {
+        if (!this.#inner) {
+            throw new Error("Viewer has already been destroyed");
+        }
+        return this.#inner;
+    }
+}
+function toUint8Array(value) {
+    if (value instanceof Uint8Array) {
+        return value;
+    }
+    if (ArrayBuffer.isView(value)) {
+        return new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+    }
+    return new Uint8Array(value);
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@knopkem/dicomview",
+  "version": "0.1.0",
+  "description": "Rust/WASM medical imaging primitives for the web",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "wasm",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build:wasm": "wasm-pack build ../crates/dicomview-wasm --target web --out-dir ../../js/wasm --out-name dicomview_wasm && rm -f ./wasm/.gitignore ./wasm/package.json",
+    "build:ts": "tsc -p tsconfig.json",
+    "build": "npm run build:wasm && npm run build:ts",
+    "prepack": "npm run build",
+    "test": "tsc -p tsconfig.json --noEmit"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT OR Apache-2.0",
+  "devDependencies": {
+    "typescript": "^5.6.3"
+  }
+}