nuxt-cornerstone 1.0.0

package/dist/runtime/composables/useDicomFiles.js

@@ -0,0 +1,234 @@
+import { ensureCornerstone } from "../cornerstone.js";
+import { clearInstanceIndex, imageIdForSopInstanceUid, registerInstance } from "../dicom-instances.js";
+import { t } from "../i18n/index.js";
+import { unzipDicom } from "../dicom-zip.js";
+const TAG = {
+  sopInstanceUid: "x00080018",
+  modality: "x00080060",
+  seriesDescription: "x0008103e",
+  seriesInstanceUid: "x0020000e",
+  seriesNumber: "x00200011",
+  instanceNumber: "x00200013"
+};
+const UNTIL_TAG = TAG.instanceNumber;
+const HEADER_PROBE_BYTES = 256 * 1024;
+const INDEX_CHUNK = 32;
+const collator = new Intl.Collator(void 0, { numeric: true, sensitivity: "base" });
+export function useDicomFiles() {
+  async function addFiles(input, options = {}) {
+    const { sort = "instanceNumber" } = options;
+    const files = Array.from(input);
+    if (files.length === 0) return [];
+    const { dicomImageLoader } = await ensureCornerstone();
+    const indexed = files.map((file) => ({
+      name: file.name,
+      imageId: dicomImageLoader.wadouri.fileManager.add(file),
+      header: null
+    }));
+    if (sort === false) return indexed.map((entry) => entry.imageId);
+    if (sort === "instanceNumber") {
+      await Promise.all(
+        files.map(async (file, i) => {
+          indexed[i].header = await readFileHeader(file);
+        })
+      );
+      indexInstances(indexed);
+    }
+    sortImages(indexed, sort);
+    return indexed.map((entry) => entry.imageId);
+  }
+  async function addZip(input, options = {}) {
+    const { sort = "instanceNumber", groupBy = "series", maxBytes, onProgress } = options;
+    onProgress?.({ phase: "reading", done: 0, total: 0 });
+    const data = await toBytes(input);
+    onProgress?.({ phase: "extracting", done: 0, total: 0 });
+    const { entries, skipped } = await unzipDicom(data, { maxBytes });
+    if (entries.length === 0) {
+      return { series: [], imageIds: [], skipped };
+    }
+    const { dicomImageLoader } = await ensureCornerstone();
+    const indexed = entries.map((entry) => ({
+      name: entry.path,
+      imageId: dicomImageLoader.wadouri.fileManager.add(toFile(entry)),
+      header: null
+    }));
+    if (groupBy === "series" || sort === "instanceNumber") {
+      await indexHeaders(entries, indexed, onProgress);
+      indexInstances(indexed);
+    }
+    const groups = groupBy === "series" ? groupBySeries(indexed) : /* @__PURE__ */ new Map([["", indexed]]);
+    const series = [];
+    for (const [key, images] of groups) {
+      if (sort !== false) sortImages(images, sort);
+      series.push(toSeries(key, images));
+    }
+    series.sort(compareSeries);
+    return {
+      series,
+      imageIds: series.flatMap((entry) => entry.imageIds),
+      skipped
+    };
+  }
+  function toImageId(url) {
+    return url.startsWith("wadouri:") ? url : `wadouri:${url}`;
+  }
+  async function indexUrls(urls, options = {}) {
+    const { concurrency = 6 } = options;
+    const failed = [];
+    let indexed = 0;
+    let next = 0;
+    async function worker() {
+      while (next < urls.length) {
+        const url = urls[next++];
+        const uid = await readUrlHeader(url);
+        if (uid) {
+          registerInstance(uid, toImageId(url));
+          indexed += 1;
+        } else failed.push(url);
+      }
+    }
+    await Promise.all(
+      Array.from({ length: Math.min(concurrency, urls.length) }, () => worker())
+    );
+    return { indexed, failed };
+  }
+  async function purge() {
+    const { dicomImageLoader } = await ensureCornerstone();
+    dicomImageLoader.wadouri.fileManager.purge();
+    clearInstanceIndex();
+  }
+  return { addFiles, addZip, toImageId, indexUrls, purge, imageIdForSopInstanceUid };
+}
+function indexInstances(images) {
+  for (const image of images) {
+    const uid = image.header?.sopInstanceUid;
+    if (uid) registerInstance(uid, image.imageId);
+  }
+}
+function toFile(entry) {
+  return new File([entry.bytes], entry.path, { type: "application/dicom" });
+}
+async function toBytes(input) {
+  if (input instanceof Uint8Array) return input;
+  if (input instanceof ArrayBuffer) return new Uint8Array(input);
+  return new Uint8Array(await input.arrayBuffer());
+}
+async function indexHeaders(entries, indexed, onProgress) {
+  const total = entries.length;
+  const dicomParser = await loadDicomParser();
+  onProgress?.({ phase: "indexing", done: 0, total });
+  for (let i = 0; i < total; i++) {
+    indexed[i].header = parseHeader(dicomParser, entries[i].bytes);
+    if ((i + 1) % INDEX_CHUNK === 0 || i + 1 === total) {
+      onProgress?.({ phase: "indexing", done: i + 1, total });
+      await yieldToEventLoop();
+    }
+  }
+}
+function yieldToEventLoop() {
+  return new Promise((resolve) => setTimeout(resolve, 0));
+}
+function sortImages(images, mode) {
+  if (mode === "name") {
+    images.sort((a, b) => collator.compare(a.name, b.name));
+    return;
+  }
+  images.sort((a, b) => {
+    const left = a.header?.instanceNumber ?? null;
+    const right = b.header?.instanceNumber ?? null;
+    if (left !== null && right !== null && left !== right) return left - right;
+    if (left !== null && right === null) return -1;
+    if (left === null && right !== null) return 1;
+    return collator.compare(a.name, b.name);
+  });
+}
+function groupBySeries(images) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const image of images) {
+    const key = image.header?.seriesInstanceUid ?? directoryOf(image.name);
+    const group = groups.get(key);
+    if (group) group.push(image);
+    else groups.set(key, [image]);
+  }
+  return groups;
+}
+function directoryOf(path) {
+  const index = path.lastIndexOf("/");
+  return index === -1 ? "" : path.slice(0, index);
+}
+function toSeries(key, images) {
+  const header = images.find((image) => image.header !== null)?.header ?? null;
+  const count = images.length;
+  const seriesNumber = header?.seriesNumber ?? null;
+  const description = header?.seriesDescription ?? null;
+  const modality = header?.modality ?? null;
+  const name = description ?? (key && !header?.seriesInstanceUid ? key : null) ?? (seriesNumber !== null ? t("series.numbered", { number: seriesNumber }) : t("series.unnamed"));
+  const details = [modality, t("series.images", { count })].filter(Boolean).join(t("list.separator"));
+  return {
+    seriesInstanceUid: header?.seriesInstanceUid ?? key,
+    seriesNumber,
+    description,
+    modality,
+    label: t("series.label", { name, details }),
+    imageIds: images.map((image) => image.imageId)
+  };
+}
+function compareSeries(a, b) {
+  if (a.seriesNumber !== null && b.seriesNumber !== null && a.seriesNumber !== b.seriesNumber) {
+    return a.seriesNumber - b.seriesNumber;
+  }
+  if (a.seriesNumber !== null && b.seriesNumber === null) return -1;
+  if (a.seriesNumber === null && b.seriesNumber !== null) return 1;
+  return collator.compare(a.label, b.label);
+}
+async function readFileHeader(file) {
+  const dicomParser = await loadDicomParser();
+  const head = await file.slice(0, HEADER_PROBE_BYTES).arrayBuffer();
+  const probed = parseHeader(dicomParser, new Uint8Array(head));
+  if (probed !== null) return probed;
+  if (file.size <= HEADER_PROBE_BYTES) return null;
+  return parseHeader(dicomParser, new Uint8Array(await file.arrayBuffer()));
+}
+async function readUrlHeader(url) {
+  try {
+    const response = await fetch(url, {
+      headers: { Range: `bytes=0-${HEADER_PROBE_BYTES - 1}` }
+    });
+    if (!response.ok) return null;
+    const dicomParser = await loadDicomParser();
+    const bytes = new Uint8Array(await response.arrayBuffer());
+    return parseHeader(dicomParser, bytes)?.sopInstanceUid ?? null;
+  } catch {
+    return null;
+  }
+}
+function parseHeader(dicomParser, bytes) {
+  try {
+    const dataSet = dicomParser.parseDicom(bytes, { untilTag: UNTIL_TAG });
+    return {
+      instanceNumber: intOrNull(dataSet.intString(TAG.instanceNumber)),
+      sopInstanceUid: textOrNull(dataSet.string(TAG.sopInstanceUid)),
+      seriesInstanceUid: textOrNull(dataSet.string(TAG.seriesInstanceUid)),
+      seriesNumber: intOrNull(dataSet.intString(TAG.seriesNumber)),
+      seriesDescription: textOrNull(dataSet.string(TAG.seriesDescription)),
+      modality: textOrNull(dataSet.string(TAG.modality))
+    };
+  } catch {
+    return null;
+  }
+}
+function intOrNull(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function textOrNull(value) {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : null;
+}
+let dicomParserPromise = null;
+function loadDicomParser() {
+  dicomParserPromise ??= import("dicom-parser").then((mod) => {
+    const candidate = mod;
+    return candidate.default ?? mod;
+  });
+  return dicomParserPromise;
+}

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

@@ -0,0 +1,24 @@
+import type { SkipReason } from '../dicom-zip.js';
+export interface RejectedFile {
+    name: string;
+    reason: SkipReason;
+}
+export interface GuardResult {
+    accepted: File[];
+    rejected: RejectedFile[];
+}
+/**
+ * Decide which of a picked or dropped selection are worth handing to
+ * `addFiles()`.
+ *
+ * `addFiles()` registers whatever it is given, so a file that is not DICOM
+ * becomes an imageId that fails later, at render, with an error pointing at
+ * the viewport rather than at the file. Answering the question up front means
+ * the failure names the file instead.
+ *
+ * Every file has to prove itself. A name is not evidence in either direction:
+ * plenty of DICOM files are called `IM000001`, and a PNG renamed to `.dcm` is
+ * still a PNG. The decision is made on content, by {@link isDicomContent},
+ * which is the same test the archive reader applies.
+ */
+export declare function guardDicomFiles(files: File[]): Promise<GuardResult>;

package/dist/runtime/composables/useDicomGuard.js

@@ -0,0 +1,30 @@
+import {
+  CONTENT_PROBE_BYTES,
+  isDicomContent,
+  nonDicomNameReason
+} from "../dicom-zip.js";
+export async function guardDicomFiles(files) {
+  const accepted = [];
+  const rejected = [];
+  for (const file of files) {
+    const nameReason = nonDicomNameReason(file.name);
+    if (nameReason) {
+      rejected.push({ name: file.name, reason: nameReason });
+      continue;
+    }
+    if (file.size === 0) {
+      rejected.push({ name: file.name, reason: "empty" });
+      continue;
+    }
+    if (!await isDicom(file)) {
+      rejected.push({ name: file.name, reason: "not-dicom" });
+      continue;
+    }
+    accepted.push(file);
+  }
+  return { accepted, rejected };
+}
+async function isDicom(file) {
+  const head = await file.slice(0, CONTENT_PROBE_BYTES).arrayBuffer();
+  return isDicomContent(new Uint8Array(head));
+}

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

@@ -0,0 +1,122 @@
+import type { DicomSeries, ZipProgress } from './useDicomFiles.js';
+/**
+ * What produced the current stack. Kept as data rather than as a finished
+ * string, so a caption re-renders in the new language when the locale changes
+ * instead of freezing whatever was picked at load time.
+ */
+export type SourceInfo = {
+    kind: 'urls';
+    count: number;
+} | {
+    kind: 'files';
+    count: number;
+    skipped: number;
+} | {
+    kind: 'zip';
+    file: string;
+    images: number;
+    series: number;
+    skipped: number;
+};
+/**
+ * A problem to show. Either a key to translate, or a message that already came
+ * out of a thrown error — those are translated at the moment they are thrown,
+ * so switching locale afterwards does not rewrite them.
+ */
+export type Problem = {
+    key: string;
+    params?: Record<string, string | number>;
+} | {
+    message: string;
+};
+export interface OpenUrlsOptions {
+    /**
+     * Read each image's headers after the stack is on screen. Default: `true`.
+     *
+     * A `wadouri:` imageId is built without reading the file, so nothing would
+     * know these slices' SOPInstanceUIDs and an annotation report could never be
+     * matched to them. Indexing afterwards keeps the images showing straight
+     * away and does not block them.
+     */
+    index?: boolean;
+    /**
+     * A caption for {@link useDicomStudy.sourceLabel} in place of the built-in
+     * count. Pass a getter rather than a string, so it re-runs on a locale
+     * switch like every other label here.
+     */
+    label?: () => string;
+}
+/**
+ * Everything an application needs to know about the stack on screen: where it
+ * came from, how loading it is going, and which series of an archive is
+ * showing.
+ *
+ * This is the orchestration layer over {@link useDicomFiles} — the part every
+ * viewer ends up writing, and the part that has nothing to do with how the
+ * viewer looks. It produces state and already-translated captions; the
+ * application supplies the buttons, the drop target and the series list.
+ *
+ * State is created per call rather than held at module scope. Module-scoped
+ * state is shared by every in-flight request during SSR, which is the same
+ * trap the README describes for the locale. Call this once, high up, and pass
+ * what each component needs down as props.
+ */
+export declare function useDicomStudy(): {
+    ready: import("vue").ComputedRef<boolean>;
+    imageIds: import("vue").Ref<string[], string[]>;
+    imageIndex: import("vue").Ref<number, number>;
+    maxIndex: import("vue").ComputedRef<number>;
+    source: import("vue").Ref<{
+        kind: "urls";
+        count: number;
+    } | {
+        kind: "files";
+        count: number;
+        skipped: number;
+    } | {
+        kind: "zip";
+        file: string;
+        images: number;
+        series: number;
+        skipped: number;
+    } | null, SourceInfo | {
+        kind: "urls";
+        count: number;
+    } | {
+        kind: "files";
+        count: number;
+        skipped: number;
+    } | {
+        kind: "zip";
+        file: string;
+        images: number;
+        series: number;
+        skipped: number;
+    } | null>;
+    busy: import("vue").Ref<boolean, boolean>;
+    problemText: import("vue").ComputedRef<string | null>;
+    series: import("vue").ShallowRef<DicomSeries[], DicomSeries[]>;
+    activeSeriesUid: import("vue").Ref<string | null, string | null>;
+    progress: import("vue").Ref<{
+        phase: "reading" | "extracting" | "indexing";
+        done: number;
+        total: number;
+    } | null, ZipProgress | {
+        phase: "reading" | "extracting" | "indexing";
+        done: number;
+        total: number;
+    } | null>;
+    progressLabel: import("vue").ComputedRef<string>;
+    progressValue: import("vue").ComputedRef<number | null>;
+    sourceLabel: import("vue").ComputedRef<string>;
+    rejectedText: import("vue").ComputedRef<string | null>;
+    openUrls: (urls: string[], options?: OpenUrlsOptions) => void;
+    openFiles: (files: File[] | FileList | null) => Promise<void>;
+    openZip: (file: File) => Promise<void>;
+    openAny: (files: File[]) => void;
+    selectSeries: (uid: string | null) => void;
+    step: (delta: number) => void;
+    stepSeries: (delta: number) => void;
+    clear: () => Promise<void>;
+    setProblem: (value: Problem | null) => void;
+};

package/dist/runtime/composables/useDicomStudy.js

@@ -0,0 +1,222 @@
+import { computed, ref, shallowRef } from "vue";
+import { t } from "../i18n/index.js";
+import { useCornerstone } from "./useCornerstone.js";
+import { useDicomFiles } from "./useDicomFiles.js";
+import { guardDicomFiles } from "./useDicomGuard.js";
+const SKIP_REASON_KEY = {
+  "metadata": "study.skip.metadata",
+  "not-dicom-extension": "study.skip.notDicomExtension",
+  "not-dicom": "study.skip.notDicom",
+  "empty": "study.skip.empty"
+};
+const MAX_NAMED_REJECTS = 3;
+export function useDicomStudy() {
+  const { ready, error: initError } = useCornerstone();
+  const { addFiles, addZip, toImageId, indexUrls, purge } = useDicomFiles();
+  const imageIds = ref([]);
+  const imageIndex = ref(0);
+  const source = ref(null);
+  const busy = ref(false);
+  const problem = ref(null);
+  const sourceLabelOverride = shallowRef(null);
+  const series = shallowRef([]);
+  const activeSeriesUid = ref(null);
+  const progress = ref(null);
+  const rejected = ref([]);
+  const maxIndex = computed(() => Math.max(0, imageIds.value.length - 1));
+  const problemText = computed(() => {
+    if (initError.value) return initError.value.message;
+    const value = problem.value;
+    if (!value) return null;
+    return "key" in value ? t(value.key, value.params) : value.message;
+  });
+  function withSkipped(summary, skipped) {
+    if (!skipped) return summary;
+    return summary + t("list.separator") + t("study.count.skipped", { count: skipped });
+  }
+  const sourceLabel = computed(() => {
+    const value = source.value;
+    if (!value) return "";
+    if (value.kind === "urls") {
+      return sourceLabelOverride.value?.() ?? t("study.source.urls", { count: value.count });
+    }
+    if (value.kind === "files") {
+      return withSkipped(t("study.source.files", { count: value.count }), value.skipped);
+    }
+    return withSkipped(
+      t("study.source.zip", {
+        file: value.file,
+        images: t("series.images", { count: value.images }),
+        series: t("study.count.series", { count: value.series })
+      }),
+      value.skipped
+    );
+  });
+  const rejectedText = computed(() => {
+    const list = rejected.value;
+    if (!list.length) return null;
+    const named = list.slice(0, MAX_NAMED_REJECTS).map((entry) => t("study.skipped.entry", {
+      name: entry.name,
+      reason: t(SKIP_REASON_KEY[entry.reason])
+    })).join(t("list.separator"));
+    const count = t("study.count.skipped", { count: list.length });
+    const rest = list.length - Math.min(list.length, MAX_NAMED_REJECTS);
+    return rest > 0 ? t("study.skipped.more", { count, named, rest }) : t("study.skipped.summary", { count, named });
+  });
+  const progressLabel = computed(() => {
+    const value = progress.value;
+    if (!value) return "";
+    if (value.phase === "reading") return t("study.progress.reading");
+    if (value.phase === "extracting") return t("study.progress.extracting");
+    return t("study.progress.indexing", { done: value.done, total: value.total });
+  });
+  const progressValue = computed(() => {
+    const value = progress.value;
+    if (!value || value.phase !== "indexing" || value.total === 0) return null;
+    return Math.round(value.done / value.total * 100);
+  });
+  function openUrls(urls, options = {}) {
+    if (!urls.length) {
+      problem.value = { key: "study.error.noUrls" };
+      return;
+    }
+    problem.value = null;
+    rejected.value = [];
+    resetSeries();
+    imageIndex.value = 0;
+    imageIds.value = urls.map(toImageId);
+    source.value = { kind: "urls", count: urls.length };
+    sourceLabelOverride.value = options.label ?? null;
+    if (options.index !== false) indexUrls(urls);
+  }
+  async function openFiles(files) {
+    if (!files) return;
+    const list = Array.from(files);
+    if (!list.length) return;
+    busy.value = true;
+    problem.value = null;
+    rejected.value = [];
+    sourceLabelOverride.value = null;
+    try {
+      const guard = await guardDicomFiles(list);
+      rejected.value = guard.rejected;
+      if (!guard.accepted.length) {
+        problem.value = { key: "study.error.noDicomFiles", params: { count: list.length } };
+        return;
+      }
+      const ids = await addFiles(guard.accepted);
+      resetSeries();
+      imageIndex.value = 0;
+      imageIds.value = ids;
+      source.value = { kind: "files", count: ids.length, skipped: guard.rejected.length };
+    } catch (caught) {
+      problem.value = { message: caught instanceof Error ? caught.message : String(caught) };
+    } finally {
+      busy.value = false;
+    }
+  }
+  async function openZip(file) {
+    busy.value = true;
+    problem.value = null;
+    progress.value = null;
+    sourceLabelOverride.value = null;
+    rejected.value = [];
+    try {
+      const result = await addZip(file, {
+        onProgress: (value) => progress.value = value
+      });
+      if (!result.series.length) {
+        resetSeries();
+        imageIds.value = [];
+        source.value = null;
+        problem.value = { key: "study.error.noDicomInZip", params: { file: file.name } };
+        return;
+      }
+      series.value = result.series;
+      selectSeries(result.series[0].seriesInstanceUid);
+      source.value = {
+        kind: "zip",
+        file: file.name,
+        images: result.imageIds.length,
+        series: result.series.length,
+        skipped: result.skipped.length
+      };
+    } catch (caught) {
+      problem.value = { message: caught instanceof Error ? caught.message : String(caught) };
+    } finally {
+      busy.value = false;
+      progress.value = null;
+    }
+  }
+  function selectSeries(uid) {
+    const chosen = series.value.find((entry) => entry.seriesInstanceUid === uid);
+    if (!chosen) return;
+    activeSeriesUid.value = chosen.seriesInstanceUid;
+    imageIndex.value = 0;
+    imageIds.value = chosen.imageIds;
+  }
+  function resetSeries() {
+    series.value = [];
+    activeSeriesUid.value = null;
+  }
+  function isZip(file) {
+    return /\.zip$/i.test(file.name) || /zip/.test(file.type);
+  }
+  function openAny(files) {
+    if (!files.length) return;
+    const archive = files.find(isZip);
+    if (archive) openZip(archive);
+    else openFiles(files);
+  }
+  function step(delta) {
+    if (!imageIds.value.length) return;
+    imageIndex.value = Math.min(maxIndex.value, Math.max(0, imageIndex.value + delta));
+  }
+  function stepSeries(delta) {
+    if (series.value.length < 2) return;
+    const current = series.value.findIndex(
+      (entry) => entry.seriesInstanceUid === activeSeriesUid.value
+    );
+    const next = Math.min(series.value.length - 1, Math.max(0, current + delta));
+    if (next === current) return;
+    selectSeries(series.value[next].seriesInstanceUid);
+  }
+  async function clear() {
+    imageIds.value = [];
+    imageIndex.value = 0;
+    source.value = null;
+    sourceLabelOverride.value = null;
+    rejected.value = [];
+    problem.value = null;
+    resetSeries();
+    await purge();
+  }
+  function setProblem(value) {
+    problem.value = value;
+  }
+  return {
+    ready,
+    imageIds,
+    imageIndex,
+    maxIndex,
+    source,
+    busy,
+    problemText,
+    series,
+    activeSeriesUid,
+    progress,
+    progressLabel,
+    progressValue,
+    sourceLabel,
+    rejectedText,
+    openUrls,
+    openFiles,
+    openZip,
+    openAny,
+    selectSeries,
+    step,
+    stepSeries,
+    clear,
+    setProblem
+  };
+}