dicom-synth 1.15.0 → 1.16.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,9 @@ function isImageType(type) {
   return TYPE_CAPABILITIES[type].image;
 }
 var HEX_TAG_RE = /^[0-9a-fA-F]{8}$/;
+function positionalName(prefix, ordinal) {
+  return `${prefix}-${String(ordinal).padStart(3, "0")}`;
+}
 
 // src/loadDcmjs.ts
 import dcmjsDefaultImport, * as dcmjsNamespace from "dcmjs";
@@ -160,6 +163,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,
@@ -246,6 +257,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);
 }
@@ -355,6 +367,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;
@@ -388,6 +401,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);
@@ -723,7 +737,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";
@@ -431,6 +431,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 +514,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 +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));
 }
@@ -952,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;
@@ -964,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 {
+    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") {
@@ -986,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);
@@ -1027,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,

package/dist/esm/index.js

@@ -441,6 +441,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
@@ -521,7 +524,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);
@@ -814,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,
@@ -900,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);
 }
@@ -1020,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;
@@ -1053,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);
@@ -1409,7 +1423,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],
@@ -1640,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"]);
@@ -1904,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));
 }
@@ -2006,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;
@@ -2018,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 {
-      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") {
@@ -2040,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);
@@ -2081,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,

package/dist/esm/schema/validate.js

@@ -407,6 +407,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
@@ -487,7 +490,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);
@@ -679,6 +682,7 @@ function validateParametricSpec(raw) {
 export {
   HEX_TAG_RE,
   isImageType,
+  positionalName,
   validateDatasetSpec,
   validateParametricSpec
 };

package/dist/esm/syntheticFixtures/generator.js

@@ -108,6 +108,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,
@@ -194,6 +202,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);
 }
@@ -234,5 +243,6 @@ export {
   buildBufferForSpec,
   buildMeta,
   serializeDict,
-  sizedNonDicomBytes
+  sizedNonDicomBytes,
+  syncMetaWithDataset
 };

package/dist/esm/syntheticFixtures/streamWrite.js

@@ -94,6 +94,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,
@@ -204,6 +212,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;
@@ -237,6 +246,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);

package/dist/types/describe/describe.d.ts

@@ -4,6 +4,7 @@ export type DescribeOptions = {
     sizeTolerance?: number;
     preserveUids?: boolean;
     uidSalt?: string;
+    captureTree?: boolean;
 };
 export type DescribeResult = {
     spec: DatasetSpec;
@@ -11,6 +12,7 @@ export type DescribeResult = {
         dicomFiles: number;
         skipped: number;
         unknownModality: number;
+        nonDicomFiles: number;
     };
 };
 export declare function readHeaderOnly(path: string): Record<string, unknown> | null;

package/dist/types/schema/validate.d.ts

@@ -1,5 +1,6 @@
 import type { DatasetSpec, FileSpec, ParametricSpec } from './types.js';
 export declare function isImageType(type: FileSpec['type']): boolean;
 export declare const HEX_TAG_RE: RegExp;
+export declare function positionalName(prefix: string, ordinal: number): string;
 export declare function validateDatasetSpec(raw: unknown): DatasetSpec;
 export declare function validateParametricSpec(raw: unknown): ParametricSpec;

package/dist/types/syntheticFixtures/generator.d.ts

@@ -1,6 +1,7 @@
 import type { DicomTagOverrides, FileSpec, Modality, NonDicomSpec, TransferSyntax } from '../schema/types.js';
 import type { UidSet } from './uid.js';
 export declare function applyTagOverrides(dataset: Record<string, unknown>, tags: DicomTagOverrides | undefined): void;
+export declare function syncMetaWithDataset(meta: Record<string, unknown>, dataset: Record<string, unknown>): void;
 export declare function buildMeta(uid: UidSet, modality: Modality, transferSyntax?: TransferSyntax): Record<string, unknown>;
 export declare function buildBaseImageDataset(uid: UidSet, modality: Modality): Record<string, unknown>;
 export declare function serializeDict(meta: Record<string, unknown>, dataset: Record<string, unknown>): Buffer;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dicom-synth",
-  "version": "1.15.0",
+  "version": "1.16.0",
   "description": "Toolkit for synthetic DICOM fixtures and public fixture fetch/cache.",
   "license": "Apache-2.0",
   "type": "module",