dicom-synth 1.12.0 → 1.14.0

package/bin/dicom-synth-describe.mjs

@@ -6,12 +6,14 @@ 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>] [--gzip]\n' +
+    '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' +
       '\n' +
       'Scans a DICOM tree and emits a DatasetSpec describing its shape\n' +
       '(studies/series, per-file size, modality).\n' +
       '\n' +
-      'By default only the shape is reproduced — no tags are copied.\n' +
+      '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' +
       '--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" +
@@ -19,6 +21,11 @@ function usage() {
       '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' +
+      '--no-preserve-uids emits shape only with freshly minted UIDs (no link\n' +
+      'preservation).\n' +
+      '--uid-salt fixes the hashing salt (hex) for a specific namespace; when\n' +
+      "omitted the salt derives from the dataset's own study UIDs (reproducible,\n" +
+      'and disjoint across datasets). The salt is reported on stderr.\n' +
       '--gzip (or a .gz --out suffix) writes the spec gzip-compressed.',
   )
   process.exit(1)
@@ -38,6 +45,8 @@ if (args.length === 0) usage()
 let dir
 let outPath
 let sizeTolerance
+let preserveUids = true
+let uidSalt
 let gzip = false
 const keepTags = []
 
@@ -64,6 +73,10 @@ for (let i = 0; i < args.length; i++) {
       console.error('--size-tolerance must be a non-negative number')
       process.exit(1)
     }
+  } else if (args[i] === '--no-preserve-uids') {
+    preserveUids = false
+  } else if (args[i] === '--uid-salt' && args[i + 1]) {
+    uidSalt = args[++i]
   } else if (args[i] === '--gzip') {
     gzip = true
   } else if (args[i].startsWith('--')) {
@@ -79,11 +92,18 @@ for (let i = 0; i < args.length; i++) {
 
 if (dir === undefined) usage()
 
+if (uidSalt !== undefined && !preserveUids) {
+  console.error('--uid-salt cannot be combined with --no-preserve-uids')
+  process.exit(1)
+}
+
 let result
 try {
   result = describeDirectory(dir, {
     ...(keepTags.length ? { keepTags } : {}),
     ...(sizeTolerance !== undefined ? { sizeTolerance } : {}),
+    preserveUids,
+    ...(uidSalt !== undefined ? { uidSalt } : {}),
   })
 } catch (err) {
   console.error(`Error: ${err.message}`)
@@ -103,6 +123,11 @@ const { dicomFiles, skipped, unknownModality } = result.stats
 console.error(
   `Described ${dicomFiles} DICOM file(s); skipped ${skipped} non-DICOM/ungroupable file(s)`,
 )
+if (result.spec.uidSalt) {
+  console.error(
+    `  UIDs hash-derived with salt ${result.spec.uidSalt} (reuse via --uid-salt to reproduce)`,
+  )
+}
 if (unknownModality > 0) {
   console.error(
     `  ${unknownModality} file(s) had an unsupported Modality — emitted as default (CT)`,

package/dist/esm/describe/describe.js

@@ -1,4 +1,5 @@
 // src/describe/describe.ts
+import { createHash as createHash2 } from "node:crypto";
 import {
   closeSync,
   openSync,
@@ -435,6 +436,14 @@ function validateDatasetSpec(raw) {
   };
 }
 
+// src/syntheticFixtures/uid.ts
+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()}`;
+}
+
 // src/describe/describe.ts
 var dcmjsAny = dcmjs;
 var HEX_TAG_RE2 = /^[0-9a-fA-F]{8}$/;
@@ -592,6 +601,113 @@ function extractTags(record, keepKeywords) {
   }
   return found ? tags : void 0;
 }
+var DICOM_ORG_ROOT = "1.2.840.10008.";
+var UID_SWEEP_EXCLUDE = /* @__PURE__ */ new Set([
+  "StudyInstanceUID",
+  "SeriesInstanceUID",
+  "SOPClassUID"
+]);
+var vrCache = /* @__PURE__ */ new Map();
+function vrOf(keyword) {
+  if (vrCache.has(keyword)) return vrCache.get(keyword);
+  const nm = dcmjsAny.data.DicomMetaDictionary.nameMap;
+  const vr = (nm?.[keyword] ?? nm?.[`RETIRED_${keyword}`])?.vr;
+  vrCache.set(keyword, vr);
+  return vr;
+}
+function hashUidVia(map, salt, original) {
+  let synthetic = map.get(original);
+  if (synthetic === void 0) {
+    synthetic = hashUid(salt, original);
+    map.set(original, synthetic);
+  }
+  return synthetic;
+}
+function isUidLeaf(value) {
+  return typeof value === "string" || Array.isArray(value) && value.every((v) => typeof v === "string");
+}
+function hasHashableUid(value) {
+  const uids = typeof value === "string" ? [value] : value;
+  return uids.some((v) => !v.startsWith(DICOM_ORG_ROOT));
+}
+function pruneUidSequence(value) {
+  const items = Array.isArray(value) ? value : [value];
+  const pruned = [];
+  for (const item of items) {
+    if (typeof item !== "object" || item === null || Array.isArray(item))
+      continue;
+    const skeleton = {};
+    let hashable = false;
+    for (const [keyword, v] of Object.entries(item)) {
+      if (keyword === "_vrMap") continue;
+      const vr = vrOf(keyword);
+      if (vr === "UI") {
+        if (isUidLeaf(v)) {
+          skeleton[keyword] = v;
+          if (hasHashableUid(v)) hashable = true;
+        }
+      } else if (vr === "SQ") {
+        const nested = pruneUidSequence(v);
+        if (nested) {
+          skeleton[keyword] = nested;
+          hashable = true;
+        }
+      }
+    }
+    if (hashable) pruned.push(skeleton);
+  }
+  return pruned.length > 0 ? pruned : void 0;
+}
+function collectUidOriginals(record) {
+  const uids = {};
+  let found = false;
+  for (const [keyword, value] of Object.entries(record)) {
+    if (UID_SWEEP_EXCLUDE.has(keyword)) continue;
+    const vr = vrOf(keyword);
+    if (vr === "UI") {
+      if (isUidLeaf(value) && hasHashableUid(value)) {
+        uids[keyword] = value;
+        found = true;
+      }
+    } else if (vr === "SQ") {
+      const pruned = pruneUidSequence(value);
+      if (pruned) {
+        uids[keyword] = pruned;
+        found = true;
+      }
+    }
+  }
+  return found ? uids : void 0;
+}
+function hashUidValue(value, salt, map) {
+  if (typeof value === "string") {
+    return value.startsWith(DICOM_ORG_ROOT) ? value : hashUidVia(map, salt, value);
+  }
+  if (Array.isArray(value)) return value.map((v) => hashUidValue(v, salt, map));
+  return Object.fromEntries(
+    Object.entries(value).map(([k, v]) => [
+      k,
+      hashUidValue(v, salt, map)
+    ])
+  );
+}
+function hashUidTags(uids, salt, map) {
+  const tags = {};
+  for (const [keyword, original] of Object.entries(uids)) {
+    tags[keyword] = hashUidValue(original, salt, map);
+  }
+  return tags;
+}
+function deriveSalt(studyUids) {
+  const h = createHash2("sha256");
+  for (const uid of [...studyUids].sort()) h.update(uid).update("\n");
+  return h.digest("hex");
+}
+function mergeTags(a, b) {
+  if (!a) return b;
+  if (!b) return a;
+  return { ...a, ...b };
+}
 function sizeKbOf(bytes) {
   return Math.max(1, Math.round(bytes / 1024));
 }
@@ -696,7 +812,9 @@ function seriesSpecFromAccum(accum) {
 }
 function describeDirectory(dir, options = {}) {
   const keepKeywords = options.keepTags ? resolveKeepTags(options.keepTags) : [];
-  const keepTags = keepKeywords.length > 0;
+  const preserveUids = options.preserveUids ?? true;
+  const uidMap = /* @__PURE__ */ new Map();
+  const useRecords = keepKeywords.length > 0 || preserveUids;
   const tolerance = options.sizeTolerance ?? 0;
   if (!Number.isFinite(tolerance) || tolerance < 0) {
     throw new Error(
@@ -734,9 +852,16 @@ function describeDirectory(dir, options = {}) {
         stats.unknownModality++;
       }
     }
-    const tags = keepTags ? extractTags(record, keepKeywords) : void 0;
+    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);
-    const fileRecord = { large, bytes, modality, tags };
+    const fileRecord = {
+      large,
+      bytes,
+      modality,
+      tags: keptTags,
+      uidOriginals
+    };
     let study = studies.get(studyUid);
     if (!study) {
       study = /* @__PURE__ */ new Map();
@@ -744,7 +869,7 @@ function describeDirectory(dir, options = {}) {
     }
     let series = study.get(seriesUid);
     if (!series) {
-      series = keepTags ? [] : /* @__PURE__ */ new Map();
+      series = useRecords ? [] : /* @__PURE__ */ new Map();
       study.set(seriesUid, series);
     }
     if (Array.isArray(series)) {
@@ -753,13 +878,56 @@ function describeDirectory(dir, options = {}) {
       accumulate(series, fileRecord);
     }
   }
-  const studySpecs = [...studies.values()].map((study) => ({
-    series: [...study.values()].map(seriesSpecFromAccum)
-  }));
+  const salt = preserveUids ? options.uidSalt ?? deriveSalt([...studies.keys()]) : void 0;
+  if (salt !== void 0) {
+    const sweptKeepTags = /* @__PURE__ */ new Set();
+    for (const study of studies.values()) {
+      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)
+            );
+          }
+        }
+      }
+    }
+    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)`
+      );
+    }
+  }
+  const withGroupUid = (spec2, seriesUid) => salt === void 0 ? spec2 : {
+    ...spec2,
+    tags: {
+      ...spec2.tags,
+      SeriesInstanceUID: hashUidVia(uidMap, salt, seriesUid)
+    }
+  };
+  const studySpecs = [...studies.entries()].map(
+    ([studyUid, study]) => ({
+      ...salt !== void 0 ? { tags: { StudyInstanceUID: hashUidVia(uidMap, salt, studyUid) } } : {},
+      series: [...study.entries()].map(
+        ([seriesUid, accum]) => withGroupUid(seriesSpecFromAccum(accum), seriesUid)
+      )
+    })
+  );
   if (studySpecs.length === 0) {
     throw new Error(`describe: no DICOM series found in ${dir}`);
   }
-  const spec = { studies: studySpecs, layout: "hierarchical" };
+  const spec = {
+    studies: studySpecs,
+    layout: "hierarchical",
+    ...salt !== void 0 ? { uidSalt: salt } : {}
+  };
   validateDatasetSpec(spec);
   return { spec, stats };
 }

package/dist/esm/index.js

@@ -1390,6 +1390,7 @@ async function writeCollectionFromSpec(spec, outDir) {
 }
 
 // src/describe/describe.ts
+import { createHash as createHash2 } from "node:crypto";
 import {
   closeSync as closeSync2,
   openSync as openSync2,
@@ -1555,6 +1556,113 @@ function extractTags(record, keepKeywords) {
   }
   return found ? tags : void 0;
 }
+var DICOM_ORG_ROOT = "1.2.840.10008.";
+var UID_SWEEP_EXCLUDE = /* @__PURE__ */ new Set([
+  "StudyInstanceUID",
+  "SeriesInstanceUID",
+  "SOPClassUID"
+]);
+var vrCache = /* @__PURE__ */ new Map();
+function vrOf(keyword) {
+  if (vrCache.has(keyword)) return vrCache.get(keyword);
+  const nm = dcmjsAny2.data.DicomMetaDictionary.nameMap;
+  const vr = (nm?.[keyword] ?? nm?.[`RETIRED_${keyword}`])?.vr;
+  vrCache.set(keyword, vr);
+  return vr;
+}
+function hashUidVia(map, salt, original) {
+  let synthetic = map.get(original);
+  if (synthetic === void 0) {
+    synthetic = hashUid(salt, original);
+    map.set(original, synthetic);
+  }
+  return synthetic;
+}
+function isUidLeaf(value) {
+  return typeof value === "string" || Array.isArray(value) && value.every((v) => typeof v === "string");
+}
+function hasHashableUid(value) {
+  const uids = typeof value === "string" ? [value] : value;
+  return uids.some((v) => !v.startsWith(DICOM_ORG_ROOT));
+}
+function pruneUidSequence(value) {
+  const items = Array.isArray(value) ? value : [value];
+  const pruned = [];
+  for (const item of items) {
+    if (typeof item !== "object" || item === null || Array.isArray(item))
+      continue;
+    const skeleton = {};
+    let hashable = false;
+    for (const [keyword, v] of Object.entries(item)) {
+      if (keyword === "_vrMap") continue;
+      const vr = vrOf(keyword);
+      if (vr === "UI") {
+        if (isUidLeaf(v)) {
+          skeleton[keyword] = v;
+          if (hasHashableUid(v)) hashable = true;
+        }
+      } else if (vr === "SQ") {
+        const nested = pruneUidSequence(v);
+        if (nested) {
+          skeleton[keyword] = nested;
+          hashable = true;
+        }
+      }
+    }
+    if (hashable) pruned.push(skeleton);
+  }
+  return pruned.length > 0 ? pruned : void 0;
+}
+function collectUidOriginals(record) {
+  const uids = {};
+  let found = false;
+  for (const [keyword, value] of Object.entries(record)) {
+    if (UID_SWEEP_EXCLUDE.has(keyword)) continue;
+    const vr = vrOf(keyword);
+    if (vr === "UI") {
+      if (isUidLeaf(value) && hasHashableUid(value)) {
+        uids[keyword] = value;
+        found = true;
+      }
+    } else if (vr === "SQ") {
+      const pruned = pruneUidSequence(value);
+      if (pruned) {
+        uids[keyword] = pruned;
+        found = true;
+      }
+    }
+  }
+  return found ? uids : void 0;
+}
+function hashUidValue(value, salt, map) {
+  if (typeof value === "string") {
+    return value.startsWith(DICOM_ORG_ROOT) ? value : hashUidVia(map, salt, value);
+  }
+  if (Array.isArray(value)) return value.map((v) => hashUidValue(v, salt, map));
+  return Object.fromEntries(
+    Object.entries(value).map(([k, v]) => [
+      k,
+      hashUidValue(v, salt, map)
+    ])
+  );
+}
+function hashUidTags(uids, salt, map) {
+  const tags = {};
+  for (const [keyword, original] of Object.entries(uids)) {
+    tags[keyword] = hashUidValue(original, salt, map);
+  }
+  return tags;
+}
+function deriveSalt(studyUids) {
+  const h = createHash2("sha256");
+  for (const uid of [...studyUids].sort()) h.update(uid).update("\n");
+  return h.digest("hex");
+}
+function mergeTags(a, b) {
+  if (!a) return b;
+  if (!b) return a;
+  return { ...a, ...b };
+}
 function sizeKbOf(bytes) {
   return Math.max(1, Math.round(bytes / 1024));
 }
@@ -1659,7 +1767,9 @@ function seriesSpecFromAccum(accum) {
 }
 function describeDirectory(dir, options = {}) {
   const keepKeywords = options.keepTags ? resolveKeepTags(options.keepTags) : [];
-  const keepTags = keepKeywords.length > 0;
+  const preserveUids = options.preserveUids ?? true;
+  const uidMap = /* @__PURE__ */ new Map();
+  const useRecords = keepKeywords.length > 0 || preserveUids;
   const tolerance = options.sizeTolerance ?? 0;
   if (!Number.isFinite(tolerance) || tolerance < 0) {
     throw new Error(
@@ -1697,9 +1807,16 @@ function describeDirectory(dir, options = {}) {
         stats.unknownModality++;
       }
     }
-    const tags = keepTags ? extractTags(record, keepKeywords) : void 0;
+    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);
-    const fileRecord = { large, bytes, modality, tags };
+    const fileRecord = {
+      large,
+      bytes,
+      modality,
+      tags: keptTags,
+      uidOriginals
+    };
     let study = studies.get(studyUid);
     if (!study) {
       study = /* @__PURE__ */ new Map();
@@ -1707,7 +1824,7 @@ function describeDirectory(dir, options = {}) {
     }
     let series = study.get(seriesUid);
     if (!series) {
-      series = keepTags ? [] : /* @__PURE__ */ new Map();
+      series = useRecords ? [] : /* @__PURE__ */ new Map();
       study.set(seriesUid, series);
     }
     if (Array.isArray(series)) {
@@ -1716,13 +1833,56 @@ function describeDirectory(dir, options = {}) {
       accumulate(series, fileRecord);
     }
   }
-  const studySpecs = [...studies.values()].map((study) => ({
-    series: [...study.values()].map(seriesSpecFromAccum)
-  }));
+  const salt = preserveUids ? options.uidSalt ?? deriveSalt([...studies.keys()]) : void 0;
+  if (salt !== void 0) {
+    const sweptKeepTags = /* @__PURE__ */ new Set();
+    for (const study of studies.values()) {
+      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)
+            );
+          }
+        }
+      }
+    }
+    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)`
+      );
+    }
+  }
+  const withGroupUid = (spec2, seriesUid) => salt === void 0 ? spec2 : {
+    ...spec2,
+    tags: {
+      ...spec2.tags,
+      SeriesInstanceUID: hashUidVia(uidMap, salt, seriesUid)
+    }
+  };
+  const studySpecs = [...studies.entries()].map(
+    ([studyUid, study]) => ({
+      ...salt !== void 0 ? { tags: { StudyInstanceUID: hashUidVia(uidMap, salt, studyUid) } } : {},
+      series: [...study.entries()].map(
+        ([seriesUid, accum]) => withGroupUid(seriesSpecFromAccum(accum), seriesUid)
+      )
+    })
+  );
   if (studySpecs.length === 0) {
     throw new Error(`describe: no DICOM series found in ${dir}`);
   }
-  const spec = { studies: studySpecs, layout: "hierarchical" };
+  const spec = {
+    studies: studySpecs,
+    layout: "hierarchical",
+    ...salt !== void 0 ? { uidSalt: salt } : {}
+  };
   validateDatasetSpec(spec);
   return { spec, stats };
 }
@@ -1759,7 +1919,7 @@ function loadCaseById(casesJsonPath, id) {
 }
 
 // src/public-fixtures/fetch.ts
-import { createHash as createHash2 } from "node:crypto";
+import { createHash as createHash3 } from "node:crypto";
 import { existsSync, mkdirSync as mkdirSync4, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "node:fs";
 import { homedir } from "node:os";
 import { join as join3 } from "node:path";
@@ -1768,7 +1928,7 @@ function caseCachePath(sha256, root = DEFAULT_CACHE_ROOT) {
   return join3(root, sha256, "file.dcm");
 }
 function verifySha256(buffer, expected) {
-  const h = createHash2("sha256").update(buffer).digest("hex");
+  const h = createHash3("sha256").update(buffer).digest("hex");
   if (h !== expected) {
     throw new Error(
       `SHA256 mismatch: expected ${expected}, got ${h}. Upstream may have changed; bump metadata after review.`

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

@@ -2,6 +2,8 @@ import type { DatasetSpec } from '../schema/types.js';
 export type DescribeOptions = {
     keepTags?: string[];
     sizeTolerance?: number;
+    preserveUids?: boolean;
+    uidSalt?: string;
 };
 export type DescribeResult = {
     spec: DatasetSpec;

package/package.json

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