dicom-synth 1.15.0 → 1.17.0

package/bin/dicom-synth-describe.mjs

@@ -6,7 +6,7 @@ import { describeDirectory } from '../dist/esm/index.js'
 
 function usage() {
   console.error(
-    'Usage: dicom-synth-describe <dir> [--out <spec.json[.gz]>] [--keep-tags <a,b,...>] [--keep-tags-file <path>] [--size-tolerance <fraction>] [--no-preserve-uids] [--uid-salt <hex>] [--gzip]\n' +
+    'Usage: dicom-synth-describe <dir> [--out <spec.json[.gz]>] [--tree] [--keep-tags <a,b,...>] [--keep-tags-file <path>] [--size-tolerance <fraction>] [--no-preserve-uids] [--uid-salt <hex>] [--gzip]\n' +
       '\n' +
       'Scans a DICOM tree and emits a DatasetSpec describing its shape\n' +
       '(studies/series, per-file size, modality).\n' +
@@ -14,6 +14,9 @@ function usage() {
       'UIDs are preserved by default as hash-derived synthetic UIDs, keeping\n' +
       'cross-file links (FrameOfReferenceUID etc.) without emitting any original\n' +
       'UID. Other tags are not copied unless named.\n' +
+      '--tree captures the real directory structure as a generic tree spec\n' +
+      '(anonymised names, sized non-DICOM placeholders included) instead of\n' +
+      'the compact studies/series form. Requires UID preservation.\n' +
       '--keep-tags copies the named tags (DICOM keywords or 8-hex tags)\n' +
       "verbatim; if a kept tag holds PHI, handling it is the caller's\n" +
       "responsibility, not this tool's.\n" +
@@ -48,6 +51,7 @@ let sizeTolerance
 let preserveUids = true
 let uidSalt
 let gzip = false
+let captureTree = false
 const keepTags = []
 
 for (let i = 0; i < args.length; i++) {
@@ -75,6 +79,8 @@ for (let i = 0; i < args.length; i++) {
     }
   } else if (args[i] === '--no-preserve-uids') {
     preserveUids = false
+  } else if (args[i] === '--tree') {
+    captureTree = true
   } else if (args[i] === '--uid-salt' && args[i + 1]) {
     uidSalt = args[++i]
   } else if (args[i] === '--gzip') {
@@ -104,6 +110,7 @@ try {
     ...(sizeTolerance !== undefined ? { sizeTolerance } : {}),
     preserveUids,
     ...(uidSalt !== undefined ? { uidSalt } : {}),
+    ...(captureTree ? { captureTree: true } : {}),
   })
 } catch (err) {
   console.error(`Error: ${err.message}`)
@@ -119,10 +126,15 @@ if (outPath) {
   process.stdout.write(compress ? gzipSync(json) : json)
 }
 
-const { dicomFiles, skipped, unknownModality } = result.stats
+const { dicomFiles, skipped, unknownModality, nonDicomFiles } = result.stats
 console.error(
   `Described ${dicomFiles} DICOM file(s); skipped ${skipped} non-DICOM/ungroupable file(s)`,
 )
+if (nonDicomFiles > 0) {
+  console.error(
+    `  ${nonDicomFiles} non-DICOM file(s) captured as sized placeholders`,
+  )
+}
 if (result.spec.uidSalt) {
   console.error(
     `  UIDs hash-derived with salt ${result.spec.uidSalt} (reuse via --uid-salt to reproduce)`,

package/dist/esm/collection/writer.js

@@ -56,6 +56,12 @@ function isImageType(type) {
   return TYPE_CAPABILITIES[type].image;
 }
 var HEX_TAG_RE = /^[0-9a-fA-F]{8}$/;
+function isRawTagValue(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) && typeof value.vr === "string";
+}
+function positionalName(prefix, ordinal) {
+  return `${prefix}-${String(ordinal).padStart(3, "0")}`;
+}
 
 // src/loadDcmjs.ts
 import dcmjsDefaultImport, * as dcmjsNamespace from "dcmjs";
@@ -145,20 +151,51 @@ function buildTagToKeyword() {
   return map;
 }
 var tagToKeyword = buildTagToKeyword();
+function toRawElement(raw) {
+  const value = raw.vr === "SQ" ? raw.value.map(
+    (item) => Object.fromEntries(
+      Object.entries(item).map(([tag, nested]) => [
+        tag.toUpperCase(),
+        toRawElement(nested)
+      ])
+    )
+  ) : raw.value;
+  return { vr: raw.vr, Value: Array.isArray(value) ? value : [value] };
+}
 function applyTagOverrides(dataset, tags) {
-  if (!tags) return;
+  if (!tags) return void 0;
+  let raw;
   for (const [key, value] of Object.entries(tags)) {
-    if (HEX_TAG_RE.test(key)) {
+    if (isRawTagValue(value)) {
+      raw ?? (raw = {});
+      raw[key.toUpperCase()] = toRawElement(value);
+    } else if (HEX_TAG_RE.test(key)) {
       const keyword = tagToKeyword.get(key.toUpperCase());
-      if (keyword) {
-        dataset[keyword] = value;
-      } else {
-        console.warn(`dicom-synth: unknown hex tag "${key}" \u2014 skipping`);
+      if (!keyword) {
+        throw new Error(
+          `dicom-synth: unknown hex tag "${key}" \u2014 dictionary tags take plain values; private/unknown tags require the raw { vr, value } form`
+        );
       }
+      dataset[keyword] = value;
     } else {
       dataset[key] = value;
     }
   }
+  return raw;
+}
+function rawScalarString(rawElements, tag) {
+  const value = rawElements?.[tag]?.Value;
+  return value?.length === 1 && typeof value[0] === "string" ? value[0] : void 0;
+}
+function syncMetaWithDataset(meta, dataset, rawElements) {
+  const sopInstance = rawScalarString(rawElements, "00080018") ?? (typeof dataset.SOPInstanceUID === "string" ? dataset.SOPInstanceUID : void 0);
+  if (sopInstance !== void 0) {
+    meta.MediaStorageSOPInstanceUID = sopInstance;
+  }
+  const sopClass = rawScalarString(rawElements, "00080016") ?? (typeof dataset.SOPClassUID === "string" ? dataset.SOPClassUID : void 0);
+  if (sopClass !== void 0) {
+    meta.MediaStorageSOPClassUID = sopClass;
+  }
 }
 function buildMeta(uid, modality, transferSyntax = "explicit-vr-little-endian") {
   return {
@@ -197,7 +234,7 @@ function buildBaseImageDataset(uid, modality) {
     ...preset.attributes
   };
 }
-function serializeDict(meta, dataset) {
+function serializeDict(meta, dataset, rawElements) {
   const dicomDict = new dcmjs.data.DicomDict(
     dcmjs.data.DicomMetaDictionary.denaturalizeDataset(
       meta
@@ -206,14 +243,17 @@ function serializeDict(meta, dataset) {
   dicomDict.dict = dcmjs.data.DicomMetaDictionary.denaturalizeDataset(
     dataset
   );
+  if (rawElements) {
+    Object.assign(dicomDict.dict, rawElements);
+  }
   return Buffer.from(dicomDict.write({ allowInvalidVRLength: true }));
 }
 var MAX_DIMENSION = 65535;
-function applySizing(dataset, meta, spec) {
+function applySizing(dataset, meta, spec, rawElements) {
   if (spec.targetSizeKb !== void 0) {
     const clampDim = (n) => Math.min(MAX_DIMENSION, Math.max(1, Math.round(n)));
     const minimalPixelBytes = dataset.PixelData.byteLength;
-    const overhead = serializeDict(meta, dataset).length - minimalPixelBytes;
+    const overhead = serializeDict(meta, dataset, rawElements).length - minimalPixelBytes;
     const cells = Math.max(
       1,
       Math.round((spec.targetSizeKb * 1024 - overhead) / 2)
@@ -244,10 +284,11 @@ function buildImageBuffer(spec, uid) {
     dataset.Laterality = "";
     dataset.PatientWeight = "0";
   }
-  applyTagOverrides(dataset, spec.tags);
+  const rawElements = applyTagOverrides(dataset, spec.tags);
   const meta = buildMeta(effectiveUid, modality, spec.transferSyntax);
-  applySizing(dataset, meta, spec);
-  return serializeDict(meta, dataset);
+  syncMetaWithDataset(meta, dataset, rawElements);
+  applySizing(dataset, meta, spec, rawElements);
+  return { buffer: serializeDict(meta, dataset, rawElements), rawElements };
 }
 function buildFakeSignatureBuffer() {
   const buf = Buffer.alloc(200, 0);
@@ -269,11 +310,11 @@ function buildBufferForSpec(spec, uid) {
     case "vendor-warnings-image":
       return buildImageBuffer(spec, uid);
     case "fake-signature":
-      return buildFakeSignatureBuffer();
+      return { buffer: buildFakeSignatureBuffer() };
     case "non-dicom":
-      return buildNonDicomBuffer(spec);
+      return { buffer: buildNonDicomBuffer(spec) };
     case "dicomdir":
-      return buildDicomdirBuffer();
+      return { buffer: buildDicomdirBuffer() };
     case "large-image":
       throw new Error(
         "large-image cannot be generated in memory \u2014 use writeCollectionFromSpec (disk-only streaming)"
@@ -354,11 +395,12 @@ function writeNative(outPath, params, dims, zeroChunk) {
   const { modality, uid, tags } = params;
   const meta = buildMeta(uid, modality);
   const dataset = buildBaseImageDataset(uid, modality);
-  applyTagOverrides(dataset, tags);
+  const rawElements = applyTagOverrides(dataset, tags);
+  syncMetaWithDataset(meta, dataset, rawElements);
   dataset.Rows = dims.rows;
   dataset.Columns = dims.columns;
   const minimalPixelBytes = dataset.PixelData.byteLength;
-  const probe = serializeDict(meta, dataset);
+  const probe = serializeDict(meta, dataset, rawElements);
   const pixelElement = Buffer.alloc(12);
   PIXEL_DATA_OW_HEADER.copy(pixelElement);
   pixelElement.writeUInt32LE(minimalPixelBytes, 8);
@@ -387,10 +429,11 @@ function writeEncapsulated(outPath, params, pixelBytes, fragmentBytes, zeroChunk
     TransferSyntaxUID: RLE_TRANSFER_SYNTAX_UID
   };
   const dataset = buildBaseImageDataset(uid, modality);
-  applyTagOverrides(dataset, tags);
+  const rawElements = applyTagOverrides(dataset, tags);
+  syncMetaWithDataset(meta, dataset, rawElements);
   dataset.PixelData = [new Uint8Array([]).buffer, new Uint8Array([0, 0]).buffer];
   dataset._vrMap = { PixelData: "OB" };
-  const probe = serializeDict(meta, dataset);
+  const probe = serializeDict(meta, dataset, rawElements);
   const idx = probe.indexOf(PIXEL_DATA_OB_HEADER);
   if (idx < 0 || probe.readUInt32LE(idx + 8) !== 4294967295) {
     throw new Error("failed to locate encapsulated PixelData element header");
@@ -487,7 +530,7 @@ var VIOLATION_LEVEL = {
   "missing-meta-header": "byte",
   "malformed-sq-delimiter": "byte"
 };
-function applyTagLevel(buffer, violations) {
+function applyTagLevel(buffer, violations, rawElements) {
   if (violations.length === 0) return buffer;
   let parsed;
   try {
@@ -521,6 +564,9 @@ function applyTagLevel(buffer, violations) {
     }
   }
   parsed.dict = dcmjsAny.data.DicomMetaDictionary.denaturalizeDataset(natural);
+  if (rawElements) {
+    Object.assign(parsed.dict, rawElements);
+  }
   if (violations.includes("uid-too-long")) {
     ;
     parsed.dict["00080018"] = {
@@ -553,11 +599,14 @@ function applyByteLevel(buffer, violations) {
   }
   return result;
 }
-function applyViolations(buffer, violations) {
+function applyViolations(buffer, violations, rawElements) {
   if (violations.length === 0) return buffer;
   const tagViolations = violations.filter((v) => VIOLATION_LEVEL[v] === "tag");
   const byteViolations = violations.filter((v) => VIOLATION_LEVEL[v] === "byte");
-  return applyByteLevel(applyTagLevel(buffer, tagViolations), byteViolations);
+  return applyByteLevel(
+    applyTagLevel(buffer, tagViolations, rawElements),
+    byteViolations
+  );
 }
 
 // src/collection/writer.ts
@@ -631,10 +680,11 @@ async function generateFile(spec, options) {
     ...spec,
     tags: resolveTagTemplates(spec.tags, { index, ...options?.context })
   } : spec;
-  let buffer = buildBufferForSpec(resolvedSpec, uid);
+  const built = buildBufferForSpec(resolvedSpec, uid);
+  let buffer = built.buffer;
   const violations = "violations" in spec ? spec.violations : void 0;
   if (violations?.length) {
-    buffer = applyViolations(buffer, violations);
+    buffer = applyViolations(buffer, violations, built.rawElements);
   }
   const name = filename(spec.type, index, padWidth);
   return {
@@ -723,7 +773,7 @@ function* planTree(nodes, scope, env) {
   for (const node of nodes) {
     if (isDirNode(node)) {
       dirOrdinal++;
-      const dirName = node.name ?? `dir-${String(dirOrdinal).padStart(3, "0")}`;
+      const dirName = node.name ?? positionalName("dir", dirOrdinal);
       const child = {
         ...scope,
         dirs: [...scope.dirs, dirName],

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";
@@ -92,6 +92,92 @@ var VALID_VIOLATIONS = {
 };
 var HEX_TAG_RE = /^[0-9a-fA-F]{8}$/;
 var KEYWORD_RE = /^[A-Z][A-Za-z0-9]*$/;
+var VALID_VRS = /* @__PURE__ */ new Set([
+  "AE",
+  "AS",
+  "AT",
+  "CS",
+  "DA",
+  "DS",
+  "DT",
+  "FL",
+  "FD",
+  "IS",
+  "LO",
+  "LT",
+  "OB",
+  "OD",
+  "OF",
+  "OL",
+  "OV",
+  "OW",
+  "PN",
+  "SH",
+  "SL",
+  "SQ",
+  "SS",
+  "ST",
+  "SV",
+  "TM",
+  "UC",
+  "UI",
+  "UL",
+  "UN",
+  "UR",
+  "US",
+  "UT",
+  "UV"
+]);
+function isPrivateHexTag(key) {
+  return HEX_TAG_RE.test(key) && Number.parseInt(key.slice(0, 4), 16) % 2 === 1;
+}
+function isRawTagValue(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) && typeof value.vr === "string";
+}
+function validateRawTagValue(raw, path) {
+  for (const key of Object.keys(raw)) {
+    if (key !== "vr" && key !== "value") {
+      throw new Error(
+        `${path}: raw tag form accepts only "vr" and "value"; got "${key}"`
+      );
+    }
+  }
+  const vr = raw.vr;
+  if (!VALID_VRS.has(vr)) {
+    throw new Error(`${path}.vr: "${vr}" is not a standard DICOM VR`);
+  }
+  if (!("value" in raw)) {
+    throw new Error(`${path}.value: is required in the raw tag form`);
+  }
+  if (vr === "SQ") {
+    if (!Array.isArray(raw.value)) {
+      throw new Error(`${path}.value: an SQ raw tag requires an array of items`);
+    }
+    raw.value.forEach((item, i) => {
+      if (typeof item !== "object" || item === null || Array.isArray(item)) {
+        throw new Error(
+          `${path}.value[${i}]: must be an object of hex-tag entries`
+        );
+      }
+      for (const [tag, nested] of Object.entries(item)) {
+        if (!HEX_TAG_RE.test(tag)) {
+          throw new Error(
+            `${path}.value[${i}]: invalid item tag "${tag}" \u2014 SQ items use 8-hex-char tags`
+          );
+        }
+        if (!isRawTagValue(nested)) {
+          throw new Error(
+            `${path}.value[${i}].${tag}: SQ item entries must use the raw { vr, value } form`
+          );
+        }
+        validateRawTagValue(
+          nested,
+          `${path}.value[${i}].${tag}`
+        );
+      }
+    });
+  }
+}
 function validatePositiveInt(value, path) {
   if (typeof value !== "number" || !Number.isInteger(value) || value < 1) {
     throw new Error(
@@ -289,13 +375,33 @@ function validateEntry(entry, path) {
   return e;
 }
 var MODALITY_TAG = "00080060";
-function validateTagValue(key, value, path) {
+function validateModalityGuard(key, candidate, path) {
   const isModalityKey = key === "Modality" || key.toUpperCase() === MODALITY_TAG;
-  if (isModalityKey && typeof value === "string" && Object.hasOwn(VALID_MODALITIES, value)) {
+  if (isModalityKey && typeof candidate === "string" && Object.hasOwn(VALID_MODALITIES, candidate)) {
     throw new Error(
       `${path}.${key}: set a preset modality (${Object.keys(VALID_MODALITIES).join("/")}) via the "modality" field, not tags \u2014 it is coupled to SOPClassUID and type-1 attributes`
     );
   }
+}
+function validateTagValue(key, value, path) {
+  if (isRawTagValue(value)) {
+    if (!HEX_TAG_RE.test(key)) {
+      throw new Error(
+        `${path}.${key}: the raw { vr, value } form requires an 8-hex-char tag key \u2014 keyword tags take plain values`
+      );
+    }
+    validateRawTagValue(value, `${path}.${key}`);
+    const raw = value.value;
+    const scalar = Array.isArray(raw) && raw.length === 1 ? raw[0] : raw;
+    validateModalityGuard(key, scalar, path);
+    return;
+  }
+  if (isPrivateHexTag(key)) {
+    throw new Error(
+      `${path}.${key}: private tags have no dictionary VR \u2014 use the raw form, e.g. { "vr": "LO", "value": \u2026 }`
+    );
+  }
+  validateModalityGuard(key, value, path);
   if (typeof value === "string") {
     for (const name of findTemplateTokens(value)) {
       if (!TEMPLATE_VOCAB.includes(name)) {
@@ -431,6 +537,9 @@ 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
@@ -511,7 +620,7 @@ function validateTreeChildren(children, basePath, inStudy, inSeries) {
     let name = "name" in n ? n.name : void 0;
     if ("children" in n) {
       dirOrdinal++;
-      name ?? (name = `dir-${String(dirOrdinal).padStart(3, "0")}`);
+      name ?? (name = positionalName("dir", dirOrdinal));
     }
     if (name === void 0) return;
     const prior = claimed.get(name);
@@ -850,6 +959,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));
 }
@@ -952,9 +1092,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;
@@ -964,21 +1223,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") {
@@ -986,14 +1243,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);
@@ -1027,25 +1279,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,