dicom-synth 1.14.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

@@ -8,6 +8,58 @@ import { dirname, resolve as resolve3 } from "node:path";
 var MAX_PIXEL_BYTES = 512 * 1024 * 1024;
 var MAX_STREAM_BYTES = 50 * 1024 * 1024 * 1024;
 
+// src/syntheticFixtures/tagTemplate.ts
+var TEMPLATE_VOCAB = [
+  "index",
+  "studyIndex",
+  "seriesIndex",
+  "instanceNumber"
+];
+var TEMPLATE_PART_RE = /\{\{|\}\}|\{([a-zA-Z]+)\}/g;
+function resolveTagTemplates(tags, context) {
+  if (!tags) return tags;
+  const resolved = {};
+  for (const [key, value] of Object.entries(tags)) {
+    resolved[key] = typeof value === "string" ? resolveString(value, context) : value;
+  }
+  return resolved;
+}
+function resolveString(value, context) {
+  return value.replace(TEMPLATE_PART_RE, (match, name) => {
+    if (name === void 0) return match === "{{" ? "{" : "}";
+    if (!TEMPLATE_VOCAB.includes(name)) {
+      throw new Error(
+        `tag template: unknown placeholder "{${name}}" \u2014 allowed: ${TEMPLATE_VOCAB.map((v) => `{${v}}`).join(", ")}`
+      );
+    }
+    const resolved = context[name];
+    if (resolved === void 0) {
+      throw new Error(
+        `tag template: placeholder "{${name}}" is not available here \u2014 it only applies inside grouped studies`
+      );
+    }
+    return String(resolved);
+  });
+}
+
+// src/schema/validate.ts
+var TYPE_CAPABILITIES = {
+  "valid-image": { image: true },
+  "invalid-uid-image": { image: true },
+  "vendor-warnings-image": { image: true },
+  "large-image": { image: true },
+  "fake-signature": { image: false },
+  "non-dicom": { image: false },
+  dicomdir: { image: false }
+};
+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";
 function loadDcmjs() {
@@ -49,43 +101,6 @@ function buildDicomdirBuffer() {
   return buf.subarray(0, off);
 }
 
-// src/syntheticFixtures/tagTemplate.ts
-var TEMPLATE_VOCAB = [
-  "index",
-  "studyIndex",
-  "seriesIndex",
-  "instanceNumber"
-];
-var TEMPLATE_PART_RE = /\{\{|\}\}|\{([a-zA-Z]+)\}/g;
-function resolveTagTemplates(tags, context) {
-  if (!tags) return tags;
-  const resolved = {};
-  for (const [key, value] of Object.entries(tags)) {
-    resolved[key] = typeof value === "string" ? resolveString(value, context) : value;
-  }
-  return resolved;
-}
-function resolveString(value, context) {
-  return value.replace(TEMPLATE_PART_RE, (match, name) => {
-    if (name === void 0) return match === "{{" ? "{" : "}";
-    if (!TEMPLATE_VOCAB.includes(name)) {
-      throw new Error(
-        `tag template: unknown placeholder "{${name}}" \u2014 allowed: ${TEMPLATE_VOCAB.map((v) => `{${v}}`).join(", ")}`
-      );
-    }
-    const resolved = context[name];
-    if (resolved === void 0) {
-      throw new Error(
-        `tag template: placeholder "{${name}}" is not available here \u2014 it only applies inside grouped studies`
-      );
-    }
-    return String(resolved);
-  });
-}
-
-// src/schema/validate.ts
-var HEX_TAG_RE = /^[0-9a-fA-F]{8}$/;
-
 // src/syntheticFixtures/generator.ts
 var MODALITY_PRESETS = {
   CT: {
@@ -148,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,
@@ -234,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);
 }
@@ -242,8 +266,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) {
@@ -254,7 +283,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":
@@ -338,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;
@@ -371,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);
@@ -565,6 +596,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;
@@ -661,6 +701,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`;
@@ -687,12 +730,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 ?? [];
@@ -756,6 +865,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, {
@@ -775,12 +896,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);