dicom-synth 1.14.0 → 1.16.0

package/dist/esm/describe/describe.js

@@ -8,7 +8,7 @@ import {
   readSync,
   statSync
 } from "node:fs";
-import { join } from "node:path";
+import { basename, extname, join, relative, sep } from "node:path";
 
 // src/loadDcmjs.ts
 import dcmjsDefaultImport, * as dcmjsNamespace from "dcmjs";
@@ -113,11 +113,14 @@ function validateUidSalt(value, path) {
     );
   }
 }
-function validateSizeKbLimit(kb, path) {
-  if (kb * 1024 > MAX_PIXEL_BYTES) {
+function validateInMemoryByteLimit(bytes, path) {
+  if (bytes > MAX_PIXEL_BYTES) {
     throw new Error(`${path}: exceeds the 512 MB limit`);
   }
 }
+function validateSizeKbLimit(kb, path) {
+  validateInMemoryByteLimit(kb * 1024, path);
+}
 function validateLargeTargetBytes(value, path) {
   if (typeof value !== "number" || !Number.isInteger(value)) {
     throw new Error(`${path}: must be an integer; got ${JSON.stringify(value)}`);
@@ -155,6 +158,29 @@ function validateLargeImageEntry(e, path) {
   }
   if ("tags" in e) validateTags(e.tags, `${path}.tags`);
 }
+function validateNonDicomEntry(e, path) {
+  const sizing = ["content", "targetSizeKb", "targetBytes"].filter(
+    (f) => f in e
+  );
+  if (sizing.length > 1) {
+    throw new Error(
+      `${path}: "content", "targetSizeKb" and "targetBytes" are mutually exclusive`
+    );
+  }
+  if ("content" in e && typeof e.content !== "string") {
+    throw new Error(
+      `${path}.content: must be a string; got ${JSON.stringify(e.content)}`
+    );
+  }
+  if ("targetSizeKb" in e) {
+    validatePositiveInt(e.targetSizeKb, `${path}.targetSizeKb`);
+    validateSizeKbLimit(e.targetSizeKb, `${path}.targetSizeKb`);
+  }
+  if ("targetBytes" in e) {
+    validatePositiveInt(e.targetBytes, `${path}.targetBytes`);
+    validateInMemoryByteLimit(e.targetBytes, `${path}.targetBytes`);
+  }
+}
 function validateEnum(value, valid, path) {
   if (typeof value !== "string" || !Object.hasOwn(valid, value)) {
     throw new Error(
@@ -182,6 +208,22 @@ function validateEntry(entry, path) {
     validateLargeImageEntry(e, path);
     return e;
   }
+  if (type === "non-dicom") {
+    for (const field of [
+      "modality",
+      "rows",
+      "columns",
+      "frames",
+      "tags",
+      "violations",
+      "transferSyntax"
+    ]) {
+      if (field in e)
+        throw new Error(`${path}.${field}: not supported for type "${type}"`);
+    }
+    validateNonDicomEntry(e, path);
+    return e;
+  }
   if ("targetBytes" in e) {
     throw new Error(
       `${path}.targetBytes: only supported for type "large-image"`
@@ -389,6 +431,101 @@ function validateStudy(study, path) {
   if ("tags" in st) validateTags(st.tags, `${path}.tags`);
   return st;
 }
+function positionalName(prefix, ordinal) {
+  return `${prefix}-${String(ordinal).padStart(3, "0")}`;
+}
+var VALID_TREE_ROLES = {
+  study: true,
+  series: true
+};
+function validateNodeName(value, path) {
+  if (typeof value !== "string" || value.length === 0 || value === "." || value === ".." || /[/\\]/.test(value)) {
+    throw new Error(
+      `${path}: must be a non-empty name without path separators; got ${JSON.stringify(value)}`
+    );
+  }
+}
+function validateTreeNode(node, path, inStudy, inSeries) {
+  if (typeof node !== "object" || node === null || Array.isArray(node)) {
+    throw new Error(`${path}: must be an object`);
+  }
+  const n = node;
+  if ("children" in n) {
+    if ("type" in n) {
+      throw new Error(
+        `${path}: a node cannot have both "children" (directory) and "type" (file)`
+      );
+    }
+    if ("name" in n) validateNodeName(n.name, `${path}.name`);
+    if ("tags" in n) validateTags(n.tags, `${path}.tags`);
+    let childStudy = inStudy;
+    let childSeries = inSeries;
+    if ("role" in n) {
+      validateEnum(n.role, VALID_TREE_ROLES, `${path}.role`);
+      if (n.role === "study") {
+        if (inStudy) {
+          throw new Error(
+            `${path}.role: a study directory cannot nest inside another study`
+          );
+        }
+        childStudy = true;
+      } else {
+        if (!inStudy) {
+          throw new Error(
+            `${path}.role: a series directory requires an enclosing study-role directory`
+          );
+        }
+        if (inSeries) {
+          throw new Error(
+            `${path}.role: a series directory cannot nest inside another series`
+          );
+        }
+        childSeries = true;
+      }
+    }
+    if (!Array.isArray(n.children) || n.children.length === 0) {
+      throw new Error(`${path}.children: must be a non-empty array`);
+    }
+    validateTreeChildren(
+      n.children,
+      `${path}.children`,
+      childStudy,
+      childSeries
+    );
+    return;
+  }
+  const e = validateEntry(node, path);
+  if ("name" in n) {
+    validateNodeName(n.name, `${path}.name`);
+    if ((e.count ?? 1) > 1) {
+      throw new Error(
+        `${path}: "name" cannot be combined with count > 1 \u2014 the copies would collide on one path`
+      );
+    }
+  }
+}
+function validateTreeChildren(children, basePath, inStudy, inSeries) {
+  const claimed = /* @__PURE__ */ new Map();
+  let dirOrdinal = 0;
+  children.forEach((child, i) => {
+    const path = `${basePath}[${i}]`;
+    validateTreeNode(child, path, inStudy, inSeries);
+    const n = child;
+    let name = "name" in n ? n.name : void 0;
+    if ("children" in n) {
+      dirOrdinal++;
+      name ?? (name = positionalName("dir", dirOrdinal));
+    }
+    if (name === void 0) return;
+    const prior = claimed.get(name);
+    if (prior !== void 0) {
+      throw new Error(
+        `${path}: name "${name}" collides with ${prior} \u2014 siblings must resolve to distinct paths`
+      );
+    }
+    claimed.set(name, path);
+  });
+}
 function validateDatasetSpec(raw) {
   if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
     throw new Error("DatasetSpec: must be a JSON object");
@@ -400,11 +537,15 @@ function validateDatasetSpec(raw) {
   if ("studies" in r && !Array.isArray(r.studies)) {
     throw new Error("DatasetSpec.studies: must be an array");
   }
+  if ("tree" in r && !Array.isArray(r.tree)) {
+    throw new Error("DatasetSpec.tree: must be an array");
+  }
   const rawEntries = r.entries ?? [];
   const rawStudies = r.studies ?? [];
-  if (rawEntries.length === 0 && rawStudies.length === 0) {
+  const rawTree = r.tree ?? [];
+  if (rawEntries.length === 0 && rawStudies.length === 0 && rawTree.length === 0) {
     throw new Error(
-      'DatasetSpec: must contain at least one of "entries" or "studies" (non-empty)'
+      'DatasetSpec: must contain at least one of "entries", "studies" or "tree" (non-empty)'
     );
   }
   const entries = rawEntries.map(
@@ -413,6 +554,9 @@ function validateDatasetSpec(raw) {
   const studies = rawStudies.map(
     (study, i) => validateStudy(study, `studies[${i}]`)
   );
+  if (rawTree.length > 0) {
+    validateTreeChildren(rawTree, "tree", false, false);
+  }
   if ("seed" in r) validateSeed(r.seed, "DatasetSpec.seed");
   if ("uidSalt" in r) validateUidSalt(r.uidSalt, "DatasetSpec.uidSalt");
   if ("layout" in r) {
@@ -429,6 +573,7 @@ function validateDatasetSpec(raw) {
   return {
     ...entries.length > 0 ? { entries } : {},
     ...studies.length > 0 ? { studies } : {},
+    ...rawTree.length > 0 ? { tree: r.tree } : {},
     ...r.seed !== void 0 ? { seed: r.seed } : {},
     ...r.uidSalt !== void 0 ? { uidSalt: r.uidSalt } : {},
     ...r.layout !== void 0 ? { layout: r.layout } : {},
@@ -708,6 +853,37 @@ function mergeTags(a, b) {
   if (!b) return a;
   return { ...a, ...b };
 }
+function scanFile(path) {
+  let size;
+  try {
+    size = statSync(path).size;
+  } catch {
+    return null;
+  }
+  if (size > MAX_STREAM_BYTES) return null;
+  const large = size > MAX_PIXEL_BYTES;
+  return { size, large, record: large ? readHeaderOnly(path) : parseFull(path) };
+}
+function presetModalityOf(record) {
+  if (typeof record.Modality !== "string") return void 0;
+  return SUPPORTED_MODALITIES.has(record.Modality) ? record.Modality : "unsupported";
+}
+function hashRecordUids(rec, salt, uidMap, sweptKeepTags) {
+  if (!rec.uidOriginals) return;
+  if (rec.tags) {
+    for (const keyword of Object.keys(rec.uidOriginals)) {
+      if (keyword in rec.tags) sweptKeepTags.add(keyword);
+    }
+  }
+  rec.tags = mergeTags(rec.tags, hashUidTags(rec.uidOriginals, salt, uidMap));
+}
+function warnSweptKeepTags(sweptKeepTags) {
+  for (const keyword of sweptKeepTags) {
+    console.warn(
+      `describe: keep-tag "${keyword}" contains UID references \u2014 kept as its hashed UID skeleton, not verbatim (disable with preserveUids: false)`
+    );
+  }
+}
 function sizeKbOf(bytes) {
   return Math.max(1, Math.round(bytes / 1024));
 }
@@ -810,9 +986,128 @@ function buildSeriesSpec(records) {
 function seriesSpecFromAccum(accum) {
   return Array.isArray(accum) ? buildSeriesSpec(accum) : { entries: [...accum.values()].map(entryOf) };
 }
+function dirAccumFor(root, dirs) {
+  let node = root;
+  for (const name of dirs) {
+    let child = node.dirs.get(name);
+    if (!child) {
+      child = { dirs: /* @__PURE__ */ new Map(), files: [] };
+      node.dirs.set(name, child);
+    }
+    node = child;
+  }
+  return node;
+}
+var SAFE_EXTENSION_RE = /^\.[A-Za-z0-9]{1,8}$/;
+function safeExtension(path) {
+  const ext = extname(basename(path));
+  return SAFE_EXTENSION_RE.test(ext) ? ext : "";
+}
+function emitTree(acc) {
+  const nodes = [];
+  let otherOrdinal = 0;
+  for (const leaf of acc.files) {
+    if (leaf.kind === "other") {
+      otherOrdinal++;
+      const name = `${positionalName("file", otherOrdinal)}${leaf.ext}`;
+      nodes.push(
+        leaf.bytes > 0 ? { type: "non-dicom", name, targetBytes: leaf.bytes } : { type: "non-dicom", name, content: "" }
+      );
+    } else {
+      nodes.push(entryOf({ ...leaf.rec, count: 1 }));
+    }
+  }
+  for (const sub of acc.dirs.values()) {
+    nodes.push({ children: emitTree(sub) });
+  }
+  return nodes;
+}
+function describeTree(dir, options, keepKeywords) {
+  const root = { dirs: /* @__PURE__ */ new Map(), files: [] };
+  const stats = {
+    dicomFiles: 0,
+    skipped: 0,
+    unknownModality: 0,
+    nonDicomFiles: 0
+  };
+  const studyUids = /* @__PURE__ */ new Set();
+  const dicomLeaves = [];
+  for (const path of [...walkFiles(dir)].sort()) {
+    const scanned = scanFile(path);
+    if (!scanned) {
+      stats.skipped++;
+      continue;
+    }
+    const { size, large, record } = scanned;
+    const studyUid = record?.StudyInstanceUID;
+    const seriesUid = record?.SeriesInstanceUID;
+    const relDirs = relative(dir, path).split(sep).slice(0, -1);
+    if (!record || typeof studyUid !== "string" || typeof seriesUid !== "string") {
+      if (large) {
+        stats.skipped++;
+        continue;
+      }
+      stats.nonDicomFiles++;
+      dirAccumFor(root, relDirs).files.push({
+        kind: "other",
+        bytes: size,
+        ext: safeExtension(path)
+      });
+      continue;
+    }
+    stats.dicomFiles++;
+    studyUids.add(studyUid);
+    const preset = presetModalityOf(record);
+    if (preset === "unsupported") stats.unknownModality++;
+    const modality = preset === "unsupported" ? void 0 : preset;
+    const instanceNumber = typeof record.InstanceNumber === "number" ? { InstanceNumber: record.InstanceNumber } : typeof record.InstanceNumber === "string" ? { InstanceNumber: escapeTagTemplate(record.InstanceNumber) } : void 0;
+    const leaf = {
+      kind: "dicom",
+      rec: {
+        large,
+        bytes: size,
+        modality,
+        tags: mergeTags(
+          instanceNumber,
+          keepKeywords.length ? extractTags(record, keepKeywords) : void 0
+        ),
+        uidOriginals: collectUidOriginals(record)
+      },
+      studyUid,
+      seriesUid
+    };
+    dirAccumFor(root, relDirs).files.push(leaf);
+    dicomLeaves.push(leaf);
+  }
+  if (root.files.length === 0 && root.dirs.size === 0) {
+    throw new Error(`describe: no files found in ${dir}`);
+  }
+  const salt = options.uidSalt ?? deriveSalt([...studyUids]);
+  const uidMap = /* @__PURE__ */ new Map();
+  const sweptKeepTags = /* @__PURE__ */ new Set();
+  for (const { rec, studyUid, seriesUid } of dicomLeaves) {
+    hashRecordUids(rec, salt, uidMap, sweptKeepTags);
+    rec.tags = mergeTags(rec.tags, {
+      StudyInstanceUID: hashUidVia(uidMap, salt, studyUid),
+      SeriesInstanceUID: hashUidVia(uidMap, salt, seriesUid)
+    });
+  }
+  warnSweptKeepTags(sweptKeepTags);
+  const spec = { tree: emitTree(root), uidSalt: salt };
+  validateDatasetSpec(spec);
+  return { spec, stats };
+}
 function describeDirectory(dir, options = {}) {
   const keepKeywords = options.keepTags ? resolveKeepTags(options.keepTags) : [];
   const preserveUids = options.preserveUids ?? true;
+  if (options.captureTree) {
+    if (!preserveUids) {
+      throw new Error(
+        "describe: captureTree requires preserveUids \u2014 the captured tree carries its grouping as hashed UID tags"
+      );
+    }
+    return describeTree(dir, options, keepKeywords);
+  }
   const uidMap = /* @__PURE__ */ new Map();
   const useRecords = keepKeywords.length > 0 || preserveUids;
   const tolerance = options.sizeTolerance ?? 0;
@@ -822,21 +1117,19 @@ function describeDirectory(dir, options = {}) {
     );
   }
   const studies = /* @__PURE__ */ new Map();
-  const stats = { dicomFiles: 0, skipped: 0, unknownModality: 0 };
+  const stats = {
+    dicomFiles: 0,
+    skipped: 0,
+    unknownModality: 0,
+    nonDicomFiles: 0
+  };
   for (const path of [...walkFiles(dir)].sort()) {
-    let size;
-    try {
-      size = statSync(path).size;
-    } catch {
-      stats.skipped++;
-      continue;
-    }
-    if (size > MAX_STREAM_BYTES) {
+    const scanned = scanFile(path);
+    if (!scanned) {
       stats.skipped++;
       continue;
     }
-    const large = size > MAX_PIXEL_BYTES;
-    const record = large ? readHeaderOnly(path) : parseFull(path);
+    const { size, large, record } = scanned;
     const studyUid = record?.StudyInstanceUID;
     const seriesUid = record?.SeriesInstanceUID;
     if (!record || typeof studyUid !== "string" || typeof seriesUid !== "string") {
@@ -844,14 +1137,9 @@ function describeDirectory(dir, options = {}) {
       continue;
     }
     stats.dicomFiles++;
-    let modality;
-    if (typeof record.Modality === "string") {
-      if (SUPPORTED_MODALITIES.has(record.Modality)) {
-        modality = record.Modality;
-      } else {
-        stats.unknownModality++;
-      }
-    }
+    const preset = presetModalityOf(record);
+    if (preset === "unsupported") stats.unknownModality++;
+    const modality = preset === "unsupported" ? void 0 : preset;
     const keptTags = keepKeywords.length ? extractTags(record, keepKeywords) : void 0;
     const uidOriginals = preserveUids ? collectUidOriginals(record) : void 0;
     const bytes = large ? size : Math.min(bucketBytes(size, tolerance), MAX_PIXEL_BYTES);
@@ -885,25 +1173,11 @@ function describeDirectory(dir, options = {}) {
       for (const series of study.values()) {
         if (!Array.isArray(series)) continue;
         for (const rec of series) {
-          if (rec.uidOriginals) {
-            if (rec.tags) {
-              for (const keyword of Object.keys(rec.uidOriginals)) {
-                if (keyword in rec.tags) sweptKeepTags.add(keyword);
-              }
-            }
-            rec.tags = mergeTags(
-              rec.tags,
-              hashUidTags(rec.uidOriginals, salt, uidMap)
-            );
-          }
+          hashRecordUids(rec, salt, uidMap, sweptKeepTags);
         }
       }
     }
-    for (const keyword of sweptKeepTags) {
-      console.warn(
-        `describe: keep-tag "${keyword}" contains UID references \u2014 kept as its hashed UID skeleton, not verbatim (disable with preserveUids: false)`
-      );
-    }
+    warnSweptKeepTags(sweptKeepTags);
   }
   const withGroupUid = (spec2, seriesUid) => salt === void 0 ? spec2 : {
     ...spec2,