dicom-synth 1.10.0 → 1.12.0

package/bin/dicom-synth-describe.mjs

@@ -1,11 +1,12 @@
 #!/usr/bin/env node
 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,...>] [--keep-tags-file <path>]\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' +
@@ -15,7 +16,10 @@ function usage() {
       "verbatim; if a kept tag holds PHI, handling it is the caller's\n" +
       "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.',
+      '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)
 }
@@ -33,6 +37,8 @@ if (args.length === 0) usage()
 
 let dir
 let outPath
+let sizeTolerance
+let gzip = false
 const keepTags = []
 
 for (let i = 0; i < args.length; i++) {
@@ -52,6 +58,14 @@ for (let i = 0; i < args.length; i++) {
       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()
@@ -67,18 +81,22 @@ if (dir === undefined) usage()
 
 let result
 try {
-  result = describeDirectory(dir, keepTags.length ? { 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

@@ -269,68 +269,37 @@ import { closeSync, mkdirSync as mkdirSync2, openSync, writeSync } from "node:fs
 import { resolve as resolve2 } from "node:path";
 
 // src/syntheticFixtures/uid.ts
-import { randomBytes } from "node:crypto";
-var ROLE_CODE = { study: 1, series: 2, sop: 3 };
-function lcg(seed) {
-  let s = seed >>> 0;
-  return () => {
-    s = Math.imul(1664525, s) + 1013904223 >>> 0;
-    return s;
-  };
-}
-function formatUid(a, b, role) {
-  return `2.25.${a}.${b}.${ROLE_CODE[role]}`;
-}
-function randomUid(role) {
-  const buf = randomBytes(8);
-  return formatUid(buf.readUInt32BE(0), buf.readUInt32BE(4), role);
+import { createHash, randomBytes } from "node:crypto";
+function hashUid(salt, key) {
+  const digest = createHash("sha256").update(salt).update(" ").update(key).digest();
+  const n = BigInt(`0x${digest.subarray(0, 16).toString("hex")}`);
+  return `2.25.${n.toString()}`;
 }
-function seededUid(next, role) {
-  return formatUid(next(), next(), role);
+function randomUid() {
+  const n = BigInt(`0x${randomBytes(16).toString("hex")}`);
+  return `2.25.${n.toString()}`;
 }
-var GROUP_STREAM_OFFSET = 2654435769;
-function seededStream(seed, offset, a, b) {
-  return lcg(seed * 999983 + offset + a * 1000003 + b * 7919 >>> 0);
+function seedToSalt(seed) {
+  return seed === void 0 ? void 0 : `seed:${seed}`;
 }
-function makeGroupUidGenerator(seed) {
-  if (seed === void 0) {
-    return {
-      study: () => randomUid("study"),
-      series: () => randomUid("series")
-    };
+function makeGroupUidGenerator(salt) {
+  if (salt === void 0) {
+    return { study: () => randomUid(), series: () => randomUid() };
   }
   return {
-    study: (studyIndex) => seededUid(
-      seededStream(seed, GROUP_STREAM_OFFSET, studyIndex + 1, 0),
-      "study"
-    ),
-    series: (studyIndex, seriesIndex) => seededUid(
-      seededStream(
-        seed,
-        GROUP_STREAM_OFFSET,
-        studyIndex + 1,
-        seriesIndex + 1
-      ),
-      "series"
-    )
+    study: (studyIndex) => hashUid(salt, `study:${studyIndex}`),
+    series: (studyIndex, seriesIndex) => hashUid(salt, `series:${studyIndex}:${seriesIndex}`)
   };
 }
-function makeUidGenerator(seed) {
-  if (seed === void 0) {
-    return () => ({
-      study: randomUid("study"),
-      series: randomUid("series"),
-      sop: randomUid("sop")
-    });
+function makeUidGenerator(salt) {
+  if (salt === void 0) {
+    return () => ({ study: randomUid(), series: randomUid(), sop: randomUid() });
   }
-  return (fileIndex) => {
-    const next = seededStream(seed, 0, fileIndex, 0);
-    return {
-      study: seededUid(next, "study"),
-      series: seededUid(next, "series"),
-      sop: seededUid(next, "sop")
-    };
-  };
+  return (fileIndex) => ({
+    study: hashUid(salt, `study:flat:${fileIndex}`),
+    series: hashUid(salt, `series:flat:${fileIndex}`),
+    sop: hashUid(salt, `sop:${fileIndex}`)
+  });
 }
 
 // src/syntheticFixtures/streamWrite.ts
@@ -443,7 +412,7 @@ function streamLargeImage(outPath, options) {
     fragmentBytes = FRAGMENT_MAX_BYTES
   } = options;
   const modality = options.modality ?? "CT";
-  const uid = options.uid ?? makeUidGenerator(options.seed)(0);
+  const uid = options.uid ?? makeUidGenerator(options.uidSalt ?? seedToSalt(options.seed))(0);
   const identity = { modality, uid, tags: options.tags };
   mkdirSync2(resolve2(outPath, ".."), { recursive: true });
   const zeroChunk = Buffer.alloc(Math.max(1, chunkBytes));
@@ -587,19 +556,51 @@ 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 resolveUid(seed, index, override) {
-  return { ...makeUidGenerator(seed)(index), ...override };
+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(salt, index, override) {
+  return { ...makeUidGenerator(salt)(index), ...override };
+}
+function effectiveSalt(spec) {
+  return spec.uidSalt ?? seedToSalt(spec.seed);
 }
 async function generateFile(spec, options) {
   const index = options?.index ?? 0;
   const padWidth = options?.padWidth ?? 3;
-  const uid = resolveUid(options?.seed, index, options?.uid);
+  const uid = resolveUid(effectiveSalt(options ?? {}), index, options?.uid);
   const resolvedSpec = "tags" in spec && spec.tags ? {
     ...spec,
     tags: resolveTagTemplates(spec.tags, { index, ...options?.context })
@@ -671,6 +672,9 @@ function hierarchicalName(studyOrdinal, seriesIndex, instanceNumber) {
 function withResolvedSeed(spec) {
   return spec.seed === void 0 ? { ...spec, seed: randomBytes2(4).readUInt32BE(0) } : spec;
 }
+function withResolvedSalt(spec) {
+  return spec.uidSalt === void 0 ? { ...spec, uidSalt: randomBytes2(16).toString("hex") } : spec;
+}
 function computeNames(type, index, padWidth, grouped, quirks) {
   let names;
   if (grouped) {
@@ -711,7 +715,7 @@ function* planCollection(spec) {
       globalIndex++;
     }
   }
-  const groupUids = makeGroupUidGenerator(spec.seed);
+  const groupUids = makeGroupUidGenerator(effectiveSalt(spec));
   let studyOrdinal = 0;
   for (const study of studies) {
     const copies = study.count ?? 1;
@@ -720,57 +724,56 @@ 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 },
-              context: {
-                index: globalIndex,
-                studyIndex: studyOrdinal,
-                seriesIndex,
-                instanceNumber
-              },
-              ...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++;
     }
   }
 }
-async function materialisePlan(plan, seed) {
+async function materialisePlan(plan, salt) {
   const file = await generateFile(plan.fileSpec, {
     index: plan.index,
-    seed,
+    uidSalt: salt,
     uid: plan.uidOverride,
     context: plan.context
   });
   return { ...file, filename: plan.filename, relativePath: plan.relativePath };
 }
 async function* generateCollectionFromSpec(spec) {
+  const salt = effectiveSalt(spec);
   for (const plan of planCollection(spec)) {
-    yield await materialisePlan(plan, spec.seed);
+    yield await materialisePlan(plan, salt);
   }
 }
 async function* previewCollection(spec) {
+  const salt = effectiveSalt(spec);
   for (const plan of planCollection(spec)) {
     if (plan.fileSpec.type === "large-image") {
       yield {
@@ -780,7 +783,7 @@ async function* previewCollection(spec) {
         approxBytes: plan.fileSpec.targetBytes
       };
     } else {
-      const file = await materialisePlan(plan, spec.seed);
+      const file = await materialisePlan(plan, salt);
       yield {
         relativePath: plan.relativePath,
         type: plan.fileSpec.type,
@@ -794,6 +797,7 @@ async function writeCollectionFromSpec(spec, outDir) {
   const root = resolve3(outDir);
   mkdirSync3(root, { recursive: true });
   const manifest = [];
+  const salt = effectiveSalt(spec);
   const createdDirs = /* @__PURE__ */ new Set([root]);
   const ensureDir = (filePath) => {
     const dir = dirname(filePath);
@@ -812,7 +816,7 @@ async function writeCollectionFromSpec(spec, outDir) {
           `large-image targetBytes (${large.targetBytes}) exceeds the 50 GB limit`
         );
       }
-      const uid = resolveUid(spec.seed, plan.index, plan.uidOverride);
+      const uid = resolveUid(salt, plan.index, plan.uidOverride);
       streamLargeImage(filePath, {
         targetBytes: large.targetBytes,
         modality: large.modality,
@@ -820,7 +824,7 @@ async function writeCollectionFromSpec(spec, outDir) {
         tags: resolveTagTemplates(large.tags, plan.context)
       });
     } else {
-      const file = await materialisePlan(plan, spec.seed);
+      const file = await materialisePlan(plan, salt);
       await writeFile(filePath, file.buffer);
     }
     manifest.push({
@@ -835,6 +839,7 @@ export {
   generateCollectionFromSpec,
   generateFile,
   previewCollection,
+  withResolvedSalt,
   withResolvedSeed,
   writeCollectionFromSpec
 };