dicom-synth 1.9.0 → 1.11.0

package/bin/dicom-synth-describe.mjs

@@ -1,11 +1,12 @@
 #!/usr/bin/env node
-import { writeFileSync } from 'node:fs'
+import { readFileSync, writeFileSync } from 'node:fs'
 import { resolve } from 'node:path'
+import { gzipSync } from 'node:zlib'
 import { describeDirectory } from '../dist/esm/index.js'
 
 function usage() {
   console.error(
-    'Usage: dicom-synth-describe <dir> [--out <spec.json>] [--keep-tags <a,b,...>]\n' +
+    'Usage: dicom-synth-describe <dir> [--out <spec.json[.gz]>] [--keep-tags <a,b,...>] [--keep-tags-file <path>] [--size-tolerance <fraction>] [--gzip]\n' +
       '\n' +
       'Scans a DICOM tree and emits a DatasetSpec describing its shape\n' +
       '(studies/series, per-file size, modality).\n' +
@@ -13,26 +14,58 @@ function usage() {
       'By default only the shape is reproduced — no tags are copied.\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.",
+      "responsibility, not this tool's.\n" +
+      '--keep-tags-file reads the same allow-list from a file (one tag per\n' +
+      'line, # comments); merged with any --keep-tags.\n' +
+      '--size-tolerance folds near-identical file sizes (fraction, e.g. 0.05\n' +
+      '= ±5%) into one entry; default exact.\n' +
+      '--gzip (or a .gz --out suffix) writes the spec gzip-compressed.',
   )
   process.exit(1)
 }
 
+// Parse a keep-tags file: one tag per line, blank lines and # comments ignored.
+function parseKeepTagsFile(path) {
+  return readFileSync(path, 'utf8')
+    .split(/\r?\n/)
+    .map((line) => line.replace(/#.*$/, '').trim())
+    .filter(Boolean)
+}
+
 const args = process.argv.slice(2)
 if (args.length === 0) usage()
 
 let dir
 let outPath
-let keepTags
+let sizeTolerance
+let gzip = false
+const keepTags = []
 
 for (let i = 0; i < args.length; i++) {
   if (args[i] === '--out' && args[i + 1]) {
     outPath = resolve(args[++i])
   } else if (args[i] === '--keep-tags' && args[i + 1]) {
-    keepTags = args[++i]
-      .split(',')
-      .map((t) => t.trim())
-      .filter(Boolean)
+    keepTags.push(
+      ...args[++i]
+        .split(',')
+        .map((t) => t.trim())
+        .filter(Boolean),
+    )
+  } else if (args[i] === '--keep-tags-file' && args[i + 1]) {
+    try {
+      keepTags.push(...parseKeepTagsFile(resolve(args[++i])))
+    } catch (err) {
+      console.error(`Error reading keep-tags file: ${err.message}`)
+      process.exit(1)
+    }
+  } else if (args[i] === '--size-tolerance' && args[i + 1]) {
+    sizeTolerance = Number(args[++i])
+    if (!Number.isFinite(sizeTolerance) || sizeTolerance < 0) {
+      console.error('--size-tolerance must be a non-negative number')
+      process.exit(1)
+    }
+  } else if (args[i] === '--gzip') {
+    gzip = true
   } else if (args[i].startsWith('--')) {
     console.error(`Unknown argument: ${args[i]}`)
     usage()
@@ -48,18 +81,22 @@ if (dir === undefined) usage()
 
 let result
 try {
-  result = describeDirectory(dir, keepTags ? { keepTags } : {})
+  result = describeDirectory(dir, {
+    ...(keepTags.length ? { keepTags } : {}),
+    ...(sizeTolerance !== undefined ? { sizeTolerance } : {}),
+  })
 } catch (err) {
   console.error(`Error: ${err.message}`)
   process.exit(1)
 }
 
 const json = `${JSON.stringify(result.spec, null, 2)}\n`
+const compress = gzip || outPath?.endsWith('.gz')
 if (outPath) {
-  writeFileSync(outPath, json)
+  writeFileSync(outPath, compress ? gzipSync(json) : json)
   console.error(`Wrote DatasetSpec to ${outPath}`)
 } else {
-  process.stdout.write(json)
+  process.stdout.write(compress ? gzipSync(json) : json)
 }
 
 const { dicomFiles, skipped, unknownModality } = result.stats

package/dist/esm/collection/writer.js

@@ -49,6 +49,40 @@ 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}$/;
 
@@ -553,12 +587,41 @@ function filename(type, index, padWidth) {
 function entryCount(entries) {
   return entries.reduce((sum, e) => sum + (e.count ?? 1), 0);
 }
+function seriesFileCount(series) {
+  return series.instances ? series.instances.count : entryCount(series.entries ?? []);
+}
 function studyFileCount(studies) {
   return studies.reduce(
-    (sum, study) => sum + (study.count ?? 1) * study.series.reduce((s, series) => s + entryCount(series.entries), 0),
+    (sum, study) => sum + (study.count ?? 1) * study.series.reduce((s, series) => s + seriesFileCount(series), 0),
     0
   );
 }
+function* seriesFiles(series) {
+  if (series.instances) {
+    const inst = series.instances;
+    for (let i = 0; i < inst.count; i++) {
+      const modality = Array.isArray(inst.modality) ? inst.modality[i] : inst.modality;
+      const baseSpec = {
+        ...inst.targetBytes ? { type: "large-image", targetBytes: inst.targetBytes[i] } : { type: "valid-image", targetSizeKb: inst.targetSizeKb?.[i] },
+        ...modality !== void 0 ? { modality } : {}
+      };
+      const instanceTags = {};
+      if (inst.tags) {
+        for (const [key, values] of Object.entries(inst.tags)) {
+          instanceTags[key] = values[i];
+        }
+      }
+      yield { baseSpec, instanceTags };
+    }
+    return;
+  }
+  for (const entry of series.entries ?? []) {
+    const { count = 1, tags, ...baseSpec } = entry;
+    for (let i = 0; i < count; i++) {
+      yield { baseSpec, instanceTags: tags ?? {} };
+    }
+  }
+}
 function resolveUid(seed, index, override) {
   return { ...makeUidGenerator(seed)(index), ...override };
 }
@@ -566,7 +629,11 @@ async function generateFile(spec, options) {
   const index = options?.index ?? 0;
   const padWidth = options?.padWidth ?? 3;
   const uid = resolveUid(options?.seed, index, options?.uid);
-  let buffer = buildBufferForSpec(spec, uid);
+  const resolvedSpec = "tags" in spec && spec.tags ? {
+    ...spec,
+    tags: resolveTagTemplates(spec.tags, { index, ...options?.context })
+  } : spec;
+  let buffer = buildBufferForSpec(resolvedSpec, uid);
   const violations = "violations" in spec ? spec.violations : void 0;
   if (violations?.length) {
     buffer = applyViolations(buffer, violations);
@@ -661,6 +728,7 @@ function* planCollection(spec) {
       yield {
         fileSpec,
         index: globalIndex,
+        context: { index: globalIndex },
         ...computeNames(
           fileSpec.type,
           globalIndex,
@@ -681,30 +749,33 @@ function* planCollection(spec) {
       for (const [seriesIndex, series] of study.series.entries()) {
         const seriesUid = groupUids.series(studyOrdinal, seriesIndex);
         let instanceNumber = 0;
-        for (const entry of series.entries) {
-          const { count = 1, ...fileSpec } = entry;
-          for (let i = 0; i < count; i++) {
-            instanceNumber++;
-            const tags = {
-              InstanceNumber: instanceNumber,
-              ...study.tags,
-              ...series.tags,
-              ...fileSpec.tags
-            };
-            yield {
-              fileSpec: { ...fileSpec, tags },
+        for (const { baseSpec, instanceTags } of seriesFiles(series)) {
+          instanceNumber++;
+          const tags = {
+            InstanceNumber: instanceNumber,
+            ...study.tags,
+            ...series.tags,
+            ...instanceTags
+          };
+          yield {
+            fileSpec: { ...baseSpec, tags },
+            index: globalIndex,
+            uidOverride: { study: studyUid, series: seriesUid },
+            context: {
               index: globalIndex,
-              uidOverride: { study: studyUid, series: seriesUid },
-              ...computeNames(
-                fileSpec.type,
-                globalIndex,
-                padWidth,
-                hierarchical ? { studyOrdinal, seriesIndex, instanceNumber } : void 0,
-                quirks
-              )
-            };
-            globalIndex++;
-          }
+              studyIndex: studyOrdinal,
+              seriesIndex,
+              instanceNumber
+            },
+            ...computeNames(
+              baseSpec.type,
+              globalIndex,
+              padWidth,
+              hierarchical ? { studyOrdinal, seriesIndex, instanceNumber } : void 0,
+              quirks
+            )
+          };
+          globalIndex++;
         }
       }
       studyOrdinal++;
@@ -715,7 +786,8 @@ async function materialisePlan(plan, seed) {
   const file = await generateFile(plan.fileSpec, {
     index: plan.index,
     seed,
-    uid: plan.uidOverride
+    uid: plan.uidOverride,
+    context: plan.context
   });
   return { ...file, filename: plan.filename, relativePath: plan.relativePath };
 }
@@ -771,7 +843,7 @@ async function writeCollectionFromSpec(spec, outDir) {
         targetBytes: large.targetBytes,
         modality: large.modality,
         uid,
-        tags: large.tags
+        tags: resolveTagTemplates(large.tags, plan.context)
       });
     } else {
       const file = await materialisePlan(plan, spec.seed);