dicom-synth 1.14.0 → 1.16.0

package/dist/esm/index.js

@@ -8,47 +8,6 @@ import { dirname, resolve as resolve3 } from "node:path";
 var MAX_PIXEL_BYTES = 512 * 1024 * 1024;
 var MAX_STREAM_BYTES = 50 * 1024 * 1024 * 1024;
 
-// src/loadDcmjs.ts
-import dcmjsDefaultImport, * as dcmjsNamespace from "dcmjs";
-function loadDcmjs() {
-  if (dcmjsNamespace.data?.DicomDict) {
-    return dcmjsNamespace;
-  }
-  const d = dcmjsDefaultImport;
-  if (d?.data?.DicomDict) {
-    return d;
-  }
-  if (d?.default?.data?.DicomDict) {
-    return d.default;
-  }
-  throw new Error(
-    "dcmjs failed to load (missing data.DicomDict). Install dcmjs >= 0.29."
-  );
-}
-var dcmjs = loadDcmjs();
-
-// src/nonStandardDicom/dicomdir.ts
-import { mkdirSync, writeFileSync } from "node:fs";
-import { resolve } from "node:path";
-var DICOMDIR_SOP_CLASS_UID = "1.2.840.10008.1.3.10";
-function buildDicomdirBuffer() {
-  const uid = DICOMDIR_SOP_CLASS_UID;
-  const buf = Buffer.alloc(256, 0);
-  buf.write("DICM", 128, 4, "ascii");
-  let off = 132;
-  buf.writeUInt16LE(2, off);
-  off += 2;
-  buf.writeUInt16LE(2, off);
-  off += 2;
-  buf.write("UI", off, 2, "ascii");
-  off += 2;
-  buf.writeUInt16LE(uid.length, off);
-  off += 2;
-  buf.write(uid, off, uid.length, "ascii");
-  off += uid.length;
-  return buf.subarray(0, off);
-}
-
 // src/syntheticFixtures/tagTemplate.ts
 var TEMPLATE_VOCAB = [
   "index",
@@ -103,6 +62,9 @@ var TYPE_CAPABILITIES = {
   "non-dicom": { image: false },
   dicomdir: { image: false }
 };
+function isImageType(type) {
+  return TYPE_CAPABILITIES[type].image;
+}
 var VALID_MODALITIES = {
   CT: true,
   PT: true,
@@ -161,11 +123,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)}`);
@@ -203,6 +168,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(
@@ -230,6 +218,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"`
@@ -437,6 +441,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");
@@ -448,11 +547,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(
@@ -461,6 +564,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) {
@@ -477,6 +583,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 } : {},
@@ -607,6 +714,47 @@ function validateParametricSpec(raw) {
   };
 }
 
+// src/loadDcmjs.ts
+import dcmjsDefaultImport, * as dcmjsNamespace from "dcmjs";
+function loadDcmjs() {
+  if (dcmjsNamespace.data?.DicomDict) {
+    return dcmjsNamespace;
+  }
+  const d = dcmjsDefaultImport;
+  if (d?.data?.DicomDict) {
+    return d;
+  }
+  if (d?.default?.data?.DicomDict) {
+    return d.default;
+  }
+  throw new Error(
+    "dcmjs failed to load (missing data.DicomDict). Install dcmjs >= 0.29."
+  );
+}
+var dcmjs = loadDcmjs();
+
+// src/nonStandardDicom/dicomdir.ts
+import { mkdirSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+var DICOMDIR_SOP_CLASS_UID = "1.2.840.10008.1.3.10";
+function buildDicomdirBuffer() {
+  const uid = DICOMDIR_SOP_CLASS_UID;
+  const buf = Buffer.alloc(256, 0);
+  buf.write("DICM", 128, 4, "ascii");
+  let off = 132;
+  buf.writeUInt16LE(2, off);
+  off += 2;
+  buf.writeUInt16LE(2, off);
+  off += 2;
+  buf.write("UI", off, 2, "ascii");
+  off += 2;
+  buf.writeUInt16LE(uid.length, off);
+  off += 2;
+  buf.write(uid, off, uid.length, "ascii");
+  off += uid.length;
+  return buf.subarray(0, off);
+}
+
 // src/syntheticFixtures/generator.ts
 var MODALITY_PRESETS = {
   CT: {
@@ -669,6 +817,14 @@ function applyTagOverrides(dataset, tags) {
     }
   }
 }
+function syncMetaWithDataset(meta, dataset) {
+  if (typeof dataset.SOPInstanceUID === "string") {
+    meta.MediaStorageSOPInstanceUID = dataset.SOPInstanceUID;
+  }
+  if (typeof dataset.SOPClassUID === "string") {
+    meta.MediaStorageSOPClassUID = dataset.SOPClassUID;
+  }
+}
 function buildMeta(uid, modality, transferSyntax = "explicit-vr-little-endian") {
   return {
     FileMetaInformationVersion: new Uint8Array([0, 1]).buffer,
@@ -755,6 +911,7 @@ function buildImageBuffer(spec, uid) {
   }
   applyTagOverrides(dataset, spec.tags);
   const meta = buildMeta(effectiveUid, modality, spec.transferSyntax);
+  syncMetaWithDataset(meta, dataset);
   applySizing(dataset, meta, spec);
   return serializeDict(meta, dataset);
 }
@@ -763,8 +920,13 @@ function buildFakeSignatureBuffer() {
   buf.write("XXXX", 128, 4, "ascii");
   return buf;
 }
-function buildNonDicomBuffer(content = "not dicom") {
-  return Buffer.from(content, "utf8");
+function sizedNonDicomBytes(spec) {
+  return spec.targetBytes ?? (spec.targetSizeKb !== void 0 ? spec.targetSizeKb * 1024 : void 0);
+}
+function buildNonDicomBuffer(spec) {
+  const bytes = sizedNonDicomBytes(spec);
+  if (bytes !== void 0) return Buffer.alloc(bytes, "not dicom ");
+  return Buffer.from(spec.content ?? "not dicom", "utf8");
 }
 function buildBufferForSpec(spec, uid) {
   switch (spec.type) {
@@ -775,7 +937,7 @@ function buildBufferForSpec(spec, uid) {
     case "fake-signature":
       return buildFakeSignatureBuffer();
     case "non-dicom":
-      return buildNonDicomBuffer(spec.content);
+      return buildNonDicomBuffer(spec);
     case "dicomdir":
       return buildDicomdirBuffer();
     case "large-image":
@@ -870,6 +1032,7 @@ function writeNative(outPath, params, dims, zeroChunk) {
   const meta = buildMeta(uid, modality);
   const dataset = buildBaseImageDataset(uid, modality);
   applyTagOverrides(dataset, tags);
+  syncMetaWithDataset(meta, dataset);
   dataset.Rows = dims.rows;
   dataset.Columns = dims.columns;
   const minimalPixelBytes = dataset.PixelData.byteLength;
@@ -903,6 +1066,7 @@ function writeEncapsulated(outPath, params, pixelBytes, fragmentBytes, zeroChunk
   };
   const dataset = buildBaseImageDataset(uid, modality);
   applyTagOverrides(dataset, tags);
+  syncMetaWithDataset(meta, dataset);
   dataset.PixelData = [new Uint8Array([]).buffer, new Uint8Array([0, 0]).buffer];
   dataset._vrMap = { PixelData: "OB" };
   const probe = serializeDict(meta, dataset);
@@ -1118,6 +1282,15 @@ function studyFileCount(studies) {
     0
   );
 }
+function isDirNode(node) {
+  return "children" in node;
+}
+function treeFileCount(nodes) {
+  return nodes.reduce(
+    (sum, node) => sum + (isDirNode(node) ? treeFileCount(node.children) : node.count ?? 1),
+    0
+  );
+}
 function* seriesFiles(series) {
   if (series.instances) {
     const inst = series.instances;
@@ -1214,6 +1387,9 @@ function applyPathQuirks(relativePath, quirks) {
   }
   return { relativePath: [...dirs, newLeaf].join("/"), filename: newLeaf };
 }
+function decorateNames(names, quirks) {
+  return quirks.length === 0 ? names : applyPathQuirks(names.relativePath, quirks);
+}
 function hierarchicalName(studyOrdinal, seriesIndex, instanceNumber) {
   const pad3 = (n) => String(n).padStart(3, "0");
   const name = `${String(instanceNumber).padStart(5, "0")}.dcm`;
@@ -1240,12 +1416,78 @@ function computeNames(type, index, padWidth, grouped, quirks) {
     const name = filename(type, index, padWidth);
     names = { filename: name, relativePath: name };
   }
-  return quirks.length === 0 ? names : applyPathQuirks(names.relativePath, quirks);
+  return decorateNames(names, quirks);
+}
+function* planTree(nodes, scope, env) {
+  let dirOrdinal = 0;
+  for (const node of nodes) {
+    if (isDirNode(node)) {
+      dirOrdinal++;
+      const dirName = node.name ?? positionalName("dir", dirOrdinal);
+      const child = {
+        ...scope,
+        dirs: [...scope.dirs, dirName],
+        tags: { ...scope.tags, ...node.tags }
+      };
+      if (node.role === "study") {
+        const ordinal = env.counters.study++;
+        child.study = {
+          ordinal,
+          uid: env.groupUids.study(ordinal),
+          seriesCount: 0
+        };
+      } else if (node.role === "series" && child.study) {
+        const index = child.study.seriesCount++;
+        child.series = {
+          index,
+          uid: env.groupUids.series(child.study.ordinal, index),
+          instanceCount: 0
+        };
+      }
+      yield* planTree(node.children, child, env);
+      continue;
+    }
+    const { count = 1, name, ...fileSpec } = node;
+    const image = isImageType(fileSpec.type);
+    for (let i = 0; i < count; i++) {
+      const index = env.counters.file++;
+      const instanceNumber = image && scope.series ? ++scope.series.instanceCount : void 0;
+      const leaf = name ?? filename(fileSpec.type, index, env.padWidth);
+      const names = decorateNames(
+        { filename: leaf, relativePath: [...scope.dirs, leaf].join("/") },
+        env.quirks
+      );
+      const tags = image ? {
+        ...instanceNumber !== void 0 ? { InstanceNumber: instanceNumber } : {},
+        ...scope.tags,
+        ..."tags" in fileSpec ? fileSpec.tags : void 0
+      } : void 0;
+      yield {
+        fileSpec: tags ? { ...fileSpec, tags } : fileSpec,
+        index,
+        ...image && scope.study ? {
+          uidOverride: {
+            study: scope.study.uid,
+            ...scope.series ? { series: scope.series.uid } : {}
+          }
+        } : {},
+        context: {
+          index,
+          ...scope.study ? { studyIndex: scope.study.ordinal } : {},
+          ...scope.series ? { seriesIndex: scope.series.index } : {},
+          ...instanceNumber !== void 0 ? { instanceNumber } : {}
+        },
+        filename: names.filename,
+        relativePath: names.relativePath
+      };
+    }
+  }
 }
 function* planCollection(spec) {
   const flatEntries = spec.entries ?? [];
   const studies = spec.studies ?? [];
-  const totalFiles = entryCount(flatEntries) + studyFileCount(studies);
+  const tree = spec.tree ?? [];
+  const totalFiles = entryCount(flatEntries) + studyFileCount(studies) + treeFileCount(tree);
   const padWidth = String(totalFiles).length;
   const hierarchical = spec.layout === "hierarchical";
   const quirks = spec.pathQuirks ?? [];
@@ -1309,6 +1551,18 @@ function* planCollection(spec) {
       studyOrdinal++;
     }
   }
+  if (tree.length > 0) {
+    yield* planTree(
+      tree,
+      { dirs: [], tags: {} },
+      {
+        groupUids,
+        padWidth,
+        quirks,
+        counters: { file: globalIndex, study: studyOrdinal }
+      }
+    );
+  }
 }
 async function materialisePlan(plan, salt) {
   const file = await generateFile(plan.fileSpec, {
@@ -1328,12 +1582,13 @@ async function* generateCollectionFromSpec(spec) {
 async function* previewCollection(spec) {
   const salt = effectiveSalt(spec);
   for (const plan of planCollection(spec)) {
-    if (plan.fileSpec.type === "large-image") {
+    const knownBytes = plan.fileSpec.type === "large-image" ? plan.fileSpec.targetBytes : plan.fileSpec.type === "non-dicom" ? sizedNonDicomBytes(plan.fileSpec) : void 0;
+    if (knownBytes !== void 0) {
       yield {
         relativePath: plan.relativePath,
-        type: "large-image",
+        type: plan.fileSpec.type,
         index: plan.index,
-        approxBytes: plan.fileSpec.targetBytes
+        approxBytes: knownBytes
       };
     } else {
       const file = await materialisePlan(plan, salt);
@@ -1399,7 +1654,7 @@ import {
   readSync,
   statSync
 } from "node:fs";
-import { join } from "node:path";
+import { basename, extname, join, relative, sep } from "node:path";
 var dcmjsAny2 = dcmjs;
 var HEX_TAG_RE2 = /^[0-9a-fA-F]{8}$/;
 var SUPPORTED_MODALITIES = /* @__PURE__ */ new Set(["CT", "PT", "MR", "CR"]);
@@ -1663,6 +1918,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));
 }
@@ -1765,9 +2051,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;
@@ -1777,21 +2182,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 {
+    const scanned = scanFile(path);
+    if (!scanned) {
       stats.skipped++;
       continue;
     }
-    if (size > MAX_STREAM_BYTES) {
-      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") {
@@ -1799,14 +2202,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);
@@ -1840,25 +2238,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,