nuxt-cornerstone 1.0.0

package/dist/runtime/composables/useCornerstoneTools.js

@@ -0,0 +1,105 @@
+import { ensureCornerstone, getCornerstoneOptions, getLoadedCornerstone } from "../cornerstone.js";
+import { t } from "../i18n/index.js";
+export function useCornerstoneTools(toolGroupId) {
+  const groupId = toolGroupId ?? getCornerstoneOptions().toolGroupId;
+  function resolveToolName(tools, tool) {
+    const exported = tools[tool];
+    return exported?.toolName ?? tool;
+  }
+  async function ensureGroup() {
+    const { tools } = await ensureCornerstone();
+    const existing = tools.ToolGroupManager.getToolGroup(groupId);
+    if (existing) return existing;
+    const group = tools.ToolGroupManager.createToolGroup(groupId);
+    if (!group) {
+      throw new Error(`[nuxt-cornerstone] ${t("error.toolGroupCreate", { groupId })}`);
+    }
+    const registered = getCornerstoneOptions().tools.register;
+    const classNames = registered === false ? [] : registered;
+    for (const className of classNames) {
+      const toolName = resolveToolName(tools, className);
+      if (!group.hasTool(toolName)) group.addTool(toolName);
+    }
+    const { MouseBindings } = tools.Enums;
+    const activate = (className, bindings) => {
+      const toolName = resolveToolName(tools, className);
+      if (group.hasTool(toolName)) group.setToolActive(toolName, { bindings });
+    };
+    activate("WindowLevelTool", [{ mouseButton: MouseBindings.Primary }]);
+    activate("ZoomTool", [{ mouseButton: MouseBindings.Secondary }]);
+    activate("PanTool", [{ mouseButton: MouseBindings.Auxiliary }]);
+    activate("StackScrollTool", [{ mouseButton: MouseBindings.Wheel }]);
+    return group;
+  }
+  async function addViewport(viewportId, renderingEngineId) {
+    const group = await ensureGroup();
+    group.addViewport(viewportId, renderingEngineId ?? getCornerstoneOptions().renderingEngineId);
+  }
+  function removeViewport(viewportId, renderingEngineId) {
+    const tools = getLoadedCornerstone()?.tools;
+    if (!tools) return;
+    const group = tools.ToolGroupManager.getToolGroup(groupId);
+    group?.removeViewports(
+      renderingEngineId ?? getCornerstoneOptions().renderingEngineId,
+      viewportId
+    );
+  }
+  async function setActive(tool, bindings) {
+    const { tools } = await ensureCornerstone();
+    const group = await ensureGroup();
+    const toolName = resolveToolName(tools, tool);
+    if (!group.hasTool(toolName)) {
+      throw new Error(
+        `[nuxt-cornerstone] ${t("error.toolNotInGroup", { tool: toolName, groupId })}`
+      );
+    }
+    const resolved = bindings ?? [{ mouseButton: tools.Enums.MouseBindings.Primary }];
+    const takesPrimary = resolved.some(
+      (binding) => binding.mouseButton === tools.Enums.MouseBindings.Primary
+    );
+    if (takesPrimary) {
+      const previous = group.getCurrentActivePrimaryToolName();
+      if (previous && previous !== toolName) group.setToolPassive(previous);
+    }
+    group.setToolActive(toolName, { bindings: resolved });
+  }
+  async function setPassive(tool) {
+    const { tools } = await ensureCornerstone();
+    const group = await ensureGroup();
+    group.setToolPassive(resolveToolName(tools, tool));
+  }
+  async function setEnabled(tool) {
+    const { tools } = await ensureCornerstone();
+    const group = await ensureGroup();
+    group.setToolEnabled(resolveToolName(tools, tool));
+  }
+  async function setDisabled(tool) {
+    const { tools } = await ensureCornerstone();
+    const group = await ensureGroup();
+    group.setToolDisabled(resolveToolName(tools, tool));
+  }
+  function getActiveTool() {
+    const tools = getLoadedCornerstone()?.tools;
+    if (!tools) return null;
+    return tools.ToolGroupManager.getToolGroup(groupId)?.getCurrentActivePrimaryToolName() ?? null;
+  }
+  function destroy() {
+    const tools = getLoadedCornerstone()?.tools;
+    if (!tools) return;
+    if (tools.ToolGroupManager.getToolGroup(groupId)) {
+      tools.ToolGroupManager.destroyToolGroup(groupId);
+    }
+  }
+  return {
+    toolGroupId: groupId,
+    ensureGroup,
+    addViewport,
+    removeViewport,
+    setActive,
+    setPassive,
+    setEnabled,
+    setDisabled,
+    getActiveTool,
+    destroy
+  };
+}

package/dist/runtime/composables/useDicomAnnotations.d.ts

@@ -0,0 +1,76 @@
+import type { ReadAnnotationsOptions, ReadAnnotationsResult } from '../annotation-json.js';
+import type { MaybeRefOrGetter, Ref } from 'vue';
+import type { StackViewport } from '../types.js';
+/**
+ * A rectangle in image pixel coordinates — the space a detector or a report
+ * works in. `(x1, y1)` and `(x2, y2)` are opposite corners in either order.
+ */
+export interface PixelBox {
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+}
+/** One box to draw, on the slice its SOPInstanceUID names. */
+export interface DicomBox {
+    /** SOPInstanceUID (0008,0018) of the slice this box was drawn on. */
+    sopInstanceUid: string;
+    box: PixelBox;
+    /** Drawn beside the rectangle. Nothing is drawn when it is absent. */
+    label?: string;
+    /**
+     * A stable id of your own. Supply one when boxes arrive more than once —
+     * re-adding a box with the same id replaces it rather than stacking a second
+     * rectangle on the first. Left out, one is generated.
+     */
+    uid?: string;
+}
+export interface AddBoxesOptions {
+    /**
+     * Stroke colour, as any CSS colour. Applies to every box this composable
+     * draws, not to the user's own measurements. Default: Cornerstone's colour
+     * for locked annotations.
+     */
+    color?: string;
+    /**
+     * Lock the boxes so they cannot be dragged, resized or deleted. Default:
+     * `true` — these came from somewhere else and editing them here would
+     * silently diverge from the source.
+     */
+    locked?: boolean;
+}
+export interface AddJsonOptions extends AddBoxesOptions, ReadAnnotationsOptions {
+}
+/** What {@link useDicomAnnotations.addJson} drew, and what it read to draw it. */
+export interface AddJsonResult extends AddBoxesResult {
+    /** The reader's own account of the file. See {@link ReadAnnotationsResult}. */
+    report: ReadAnnotationsResult;
+}
+export interface AddBoxesResult {
+    /** Boxes drawn straight away, because their slice was already loaded. */
+    drawn: number;
+    /** Boxes held until their slice is shown. See {@link useDicomAnnotations}. */
+    deferred: number;
+    /** SOPInstanceUIDs that match nothing currently loaded. */
+    unresolved: string[];
+}
+/**
+ * The tool the imported boxes are drawn with.
+ *
+ * It is a RectangleROI instance under another name rather than RectangleROI
+ * itself, for two reasons. The user's own rectangles stay separately
+ * selectable and separately styled, and this instance carries its own
+ * `getTextLines`, so an imported box shows the label it arrived with instead of
+ * the area and mean a measurement would show.
+ */
+export declare const OVERLAY_TOOL_NAME = "DicomBoxOverlay";
+export declare function useDicomAnnotations(source: MaybeRefOrGetter<StackViewport | null | undefined>): {
+    addBoxes: (boxes: DicomBox[], options?: AddBoxesOptions) => Promise<AddBoxesResult>;
+    addJson: (input: File | Blob | string | unknown, options?: AddJsonOptions) => Promise<AddJsonResult>;
+    clear: () => void;
+    setVisible: (next: boolean) => void;
+    drawn: Ref<number, number>;
+    pending: Ref<number, number>;
+    visible: Ref<boolean, boolean>;
+    toolName: string;
+};

package/dist/runtime/composables/useDicomAnnotations.js

@@ -0,0 +1,220 @@
+import { getCurrentScope, onScopeDispose, ref, toValue } from "vue";
+import { readAnnotationJson } from "../annotation-json.js";
+import { ensureCornerstone } from "../cornerstone.js";
+import { imageIdForSopInstanceUid } from "../dicom-instances.js";
+import { t } from "../i18n/index.js";
+export const OVERLAY_TOOL_NAME = "DicomBoxOverlay";
+const PARENT_TOOL_CLASS = "RectangleROITool";
+function resolveToolClass(tools, name) {
+  const exported = tools[name];
+  return typeof exported === "function" ? exported : null;
+}
+export function useDicomAnnotations(source) {
+  const waiting = /* @__PURE__ */ new Map();
+  const owned = /* @__PURE__ */ new Set();
+  const drawn = ref(0);
+  const pending = ref(0);
+  const visible = ref(true);
+  let libs = null;
+  let listening = null;
+  let locked = true;
+  function requireViewport() {
+    const viewport = toValue(source);
+    if (!viewport) throw new Error(`[nuxt-cornerstone] ${t("error.annotationViewport")}`);
+    return viewport;
+  }
+  async function ensureOverlayTool(viewport, color) {
+    const { tools } = libs;
+    const group = tools.ToolGroupManager.getToolGroupForViewport(
+      viewport.id,
+      viewport.renderingEngineId
+    );
+    if (!group) {
+      throw new Error(`[nuxt-cornerstone] ${t("error.annotationToolGroup")}`);
+    }
+    if (!group.hasTool(OVERLAY_TOOL_NAME)) {
+      const ParentTool = resolveToolClass(tools, PARENT_TOOL_CLASS);
+      if (!ParentTool) {
+        throw new Error(`[nuxt-cornerstone] ${t("error.annotationTool")}`);
+      }
+      try {
+        tools.addTool(ParentTool);
+      } catch {
+      }
+      group.addToolInstance(OVERLAY_TOOL_NAME, ParentTool.toolName);
+      group.setToolConfiguration(OVERLAY_TOOL_NAME, {
+        getTextLines: (data) => data.label ? [data.label] : []
+      });
+    }
+    const mode = group.getToolInstance(OVERLAY_TOOL_NAME)?.mode;
+    if (mode !== tools.Enums.ToolModes.Enabled) group.setToolEnabled(OVERLAY_TOOL_NAME);
+    if (color) {
+      tools.annotation.config.style.setToolGroupToolStyles(group.id, {
+        [OVERLAY_TOOL_NAME]: { color, colorLocked: color, colorAutoGenerated: color }
+      });
+    }
+  }
+  function draw(prepared, viewport) {
+    const { core, tools } = libs;
+    const { imageId } = prepared;
+    let points;
+    try {
+      const toWorld = (x, y) => core.utilities.imageToWorldCoords(imageId, [x, y]);
+      const left = Math.min(prepared.box.x1, prepared.box.x2);
+      const right = Math.max(prepared.box.x1, prepared.box.x2);
+      const top = Math.min(prepared.box.y1, prepared.box.y2);
+      const bottom = Math.max(prepared.box.y1, prepared.box.y2);
+      points = [
+        toWorld(left, top),
+        toWorld(right, top),
+        toWorld(left, bottom),
+        toWorld(right, bottom)
+      ];
+    } catch {
+      return false;
+    }
+    const camera = viewport.getCamera();
+    const annotation = {
+      annotationUID: prepared.uid,
+      highlighted: false,
+      invalidated: true,
+      isLocked: locked,
+      isVisible: visible.value,
+      autoGenerated: true,
+      metadata: {
+        toolName: OVERLAY_TOOL_NAME,
+        // referencedImageId is what pins the box to one slice: a stack
+        // viewport shows an annotation only while that image is the one on
+        // screen.
+        referencedImageId: imageId,
+        FrameOfReferenceUID: viewport.getFrameOfReferenceUID(),
+        viewPlaneNormal: camera.viewPlaneNormal ? [...camera.viewPlaneNormal] : void 0,
+        viewUp: camera.viewUp ? [...camera.viewUp] : void 0
+      },
+      data: {
+        label: prepared.label ?? "",
+        handles: {
+          points,
+          activeHandleIndex: null,
+          textBox: { hasMoved: false }
+        },
+        cachedStats: {}
+      }
+    };
+    const uid = tools.annotation.state.addAnnotation(
+      annotation,
+      viewport.element
+    );
+    owned.add(uid);
+    if (locked) tools.annotation.locking.setAnnotationLocked(uid, true);
+    if (!visible.value) tools.annotation.visibility.setAnnotationVisibility(uid, false);
+    return true;
+  }
+  function queue(prepared) {
+    const queued = waiting.get(prepared.imageId);
+    if (queued) queued.push(prepared);
+    else waiting.set(prepared.imageId, [prepared]);
+  }
+  function countWaiting() {
+    let total = 0;
+    for (const queued of waiting.values()) total += queued.length;
+    return total;
+  }
+  function flush(viewport) {
+    const imageId = viewport.getCurrentImageId();
+    if (!imageId) return;
+    const queued = waiting.get(imageId);
+    if (!queued) return;
+    waiting.delete(imageId);
+    let added = 0;
+    for (const prepared of queued) {
+      if (draw(prepared, viewport)) added += 1;
+    }
+    drawn.value = owned.size;
+    pending.value = countWaiting();
+    if (added) render(viewport);
+    if (waiting.size === 0) stopWatching();
+  }
+  function onStackNewImage() {
+    const viewport = toValue(source);
+    if (viewport) flush(viewport);
+  }
+  function watchViewport(viewport) {
+    const element = viewport.element;
+    if (listening === element) return;
+    stopWatching();
+    element.addEventListener(libs.core.Enums.Events.STACK_NEW_IMAGE, onStackNewImage);
+    listening = element;
+  }
+  function stopWatching() {
+    if (!listening || !libs) return;
+    listening.removeEventListener(libs.core.Enums.Events.STACK_NEW_IMAGE, onStackNewImage);
+    listening = null;
+  }
+  function render(viewport) {
+    libs?.tools.utilities.triggerAnnotationRenderForViewportIds([viewport.id]);
+  }
+  async function addBoxes(boxes, options = {}) {
+    libs = await ensureCornerstone();
+    const viewport = requireViewport();
+    locked = options.locked ?? true;
+    await ensureOverlayTool(viewport, options.color);
+    const unresolved = [];
+    let immediate = 0;
+    let deferred = 0;
+    for (const entry of boxes) {
+      const imageId = imageIdForSopInstanceUid(entry.sopInstanceUid);
+      if (!imageId) {
+        unresolved.push(entry.sopInstanceUid);
+        continue;
+      }
+      if (entry.uid && owned.has(entry.uid)) remove(entry.uid);
+      const prepared = {
+        imageId,
+        box: entry.box,
+        label: entry.label,
+        uid: entry.uid
+      };
+      if (draw(prepared, viewport)) immediate += 1;
+      else {
+        queue(prepared);
+        deferred += 1;
+      }
+    }
+    if (deferred > 0) watchViewport(viewport);
+    drawn.value = owned.size;
+    pending.value = countWaiting();
+    if (immediate > 0) render(viewport);
+    return { drawn: immediate, deferred, unresolved };
+  }
+  async function addJson(input, options = {}) {
+    const report = await readAnnotationJson(input, options);
+    const result = await addBoxes(report.boxes, options);
+    return { ...result, report };
+  }
+  function remove(uid) {
+    libs?.tools.annotation.state.removeAnnotation(uid);
+    owned.delete(uid);
+  }
+  function clear() {
+    for (const uid of owned) libs?.tools.annotation.state.removeAnnotation(uid);
+    owned.clear();
+    waiting.clear();
+    stopWatching();
+    drawn.value = 0;
+    pending.value = 0;
+    const viewport = toValue(source);
+    if (viewport) render(viewport);
+  }
+  function setVisible(next) {
+    visible.value = next;
+    const tools = libs?.tools;
+    if (tools) {
+      for (const uid of owned) tools.annotation.visibility.setAnnotationVisibility(uid, next);
+    }
+    const viewport = toValue(source);
+    if (viewport) render(viewport);
+  }
+  if (getCurrentScope()) onScopeDispose(stopWatching);
+  return { addBoxes, addJson, clear, setVisible, drawn, pending, visible, toolName: OVERLAY_TOOL_NAME };
+}

package/dist/runtime/composables/useDicomFiles.d.ts

@@ -0,0 +1,87 @@
+import { imageIdForSopInstanceUid } from '../dicom-instances.js';
+import type { SkippedEntry } from '../dicom-zip.js';
+export type { SkippedEntry, SkipReason } from '../dicom-zip.js';
+export interface AddFilesOptions {
+    /**
+     * How to order the resulting imageIds.
+     *
+     * - `'instanceNumber'` (default) reads DICOM tag (0020,0013) from each file
+     *   and sorts on it, falling back to the filename for files that do not
+     *   carry it. This is what a viewer needs: filename order and acquisition
+     *   order disagree often enough to matter.
+     * - `'name'` sorts by filename with a natural (numeric-aware) collator.
+     * - `false` keeps the order the files came in.
+     */
+    sort?: 'instanceNumber' | 'name' | false;
+}
+export interface AddZipOptions extends AddFilesOptions {
+    /**
+     * `'series'` (default) splits the archive by SeriesInstanceUID (0020,000E),
+     * because a study ZIP normally holds several series and stacking a sagittal
+     * T1 on top of an axial T2 is not a stack. `false` returns one group holding
+     * everything, matching {@link useDicomFiles.addFiles}.
+     */
+    groupBy?: 'series' | false;
+    /** Ceiling on total uncompressed bytes. Default: 2 GiB. */
+    maxBytes?: number;
+    /** Called as the archive moves through its phases. See {@link ZipProgress}. */
+    onProgress?: (progress: ZipProgress) => void;
+}
+export interface ZipProgress {
+    /**
+     * - `'reading'` — pulling the archive into memory.
+     * - `'extracting'` — inflating; fflate reports nothing until it finishes, so
+     *   `done`/`total` are both `0` here and a UI should show an indeterminate bar.
+     * - `'indexing'` — reading DICOM headers, one file at a time and countable.
+     */
+    phase: 'reading' | 'extracting' | 'indexing';
+    done: number;
+    total: number;
+}
+/** One series' worth of images, ready to hand to a viewport. */
+export interface DicomSeries {
+    /** SeriesInstanceUID (0020,000E), or a path-derived id when the tag is absent. */
+    seriesInstanceUid: string;
+    /** SeriesNumber (0020,0011). */
+    seriesNumber: number | null;
+    /** SeriesDescription (0008,103E). */
+    description: string | null;
+    /** Modality (0008,0060). */
+    modality: string | null;
+    /** A human-readable label, already falling back when tags are missing. */
+    label: string;
+    /** imageIds in display order. */
+    imageIds: string[];
+}
+export interface AddZipResult {
+    /** Series ordered by SeriesNumber, then description. */
+    series: DicomSeries[];
+    /** Every imageId, series order then display order within each series. */
+    imageIds: string[];
+    /** Archive members that were not loaded, and why. */
+    skipped: SkippedEntry[];
+}
+/** See {@link useDicomFiles.indexUrls}. */
+export interface IndexUrlsOptions {
+    /** Files fetched at once. Default: `6`. */
+    concurrency?: number;
+}
+export interface IndexUrlsResult {
+    /** Files whose SOPInstanceUID was read and recorded. */
+    indexed: number;
+    /** URLs that could not be fetched, or were not readable DICOM. */
+    failed: string[];
+}
+/**
+ * Turn local DICOM Part 10 files into `dicomfile:` imageIds the viewport can
+ * render, unpack ZIP archives of them, and build `wadouri:` imageIds for files
+ * served over HTTP.
+ */
+export declare function useDicomFiles(): {
+    addFiles: (input: File[] | FileList, options?: AddFilesOptions) => Promise<string[]>;
+    addZip: (input: File | Blob | ArrayBuffer | Uint8Array, options?: AddZipOptions) => Promise<AddZipResult>;
+    toImageId: (url: string) => string;
+    indexUrls: (urls: string[], options?: IndexUrlsOptions) => Promise<IndexUrlsResult>;
+    purge: () => Promise<void>;
+    imageIdForSopInstanceUid: typeof imageIdForSopInstanceUid;
+};