dicom-synth 1.17.0 → 1.18.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]>] [--tree] [--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>] [--keep-private-tags] [--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' +
@@ -22,6 +22,13 @@ function usage() {
       "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' +
+      '--keep-private-tags captures ALL private (odd-group) elements as-is as\n' +
+      'raw { vr, value } tag forms — creators, scalars, nested private\n' +
+      'sequences. Private blocks routinely carry PHI/device detail: handling\n' +
+      "that is the caller's responsibility. UID-valued leaves are still\n" +
+      'hashed unless --no-preserve-uids. Individual private tags can instead\n' +
+      'be named (8-hex) in --keep-tags. Binary/unparseable payloads are\n' +
+      'skipped and counted.\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' +
@@ -52,6 +59,7 @@ let preserveUids = true
 let uidSalt
 let gzip = false
 let captureTree = false
+let keepPrivateTags = false
 const keepTags = []
 
 for (let i = 0; i < args.length; i++) {
@@ -77,6 +85,8 @@ 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] === '--keep-private-tags') {
+    keepPrivateTags = true
   } else if (args[i] === '--no-preserve-uids') {
     preserveUids = false
   } else if (args[i] === '--tree') {
@@ -107,6 +117,7 @@ let result
 try {
   result = describeDirectory(dir, {
     ...(keepTags.length ? { keepTags } : {}),
+    ...(keepPrivateTags ? { keepPrivateTags: true } : {}),
     ...(sizeTolerance !== undefined ? { sizeTolerance } : {}),
     preserveUids,
     ...(uidSalt !== undefined ? { uidSalt } : {}),

package/dist/esm/describe/describe.js

@@ -718,13 +718,28 @@ function buildHexToKeyword() {
   }
   return map;
 }
+function buildKeepPlan(options) {
+  const { keywords, privateHex } = options.keepTags ? resolveKeepTags(options.keepTags) : { keywords: [], privateHex: /* @__PURE__ */ new Set() };
+  const allPrivate = options.keepPrivateTags === true;
+  return {
+    keywords,
+    privateHex,
+    allPrivate,
+    capturingPrivate: allPrivate || privateHex.size > 0
+  };
+}
 function resolveKeepTags(keepTags) {
   const nameMap = dcmjsAny.data.DicomMetaDictionary.nameMap;
   let hexToKeyword;
   const kept = [];
+  const privateHex = /* @__PURE__ */ new Set();
   for (const tag of keepTags) {
     let keyword;
     if (HEX_TAG_RE2.test(tag)) {
+      if (isPrivateHexTag(tag)) {
+        privateHex.add(tag.toUpperCase());
+        continue;
+      }
       hexToKeyword ?? (hexToKeyword = buildHexToKeyword());
       const mapped = hexToKeyword.get(tag.toUpperCase());
       if (!mapped) {
@@ -751,7 +766,71 @@ function resolveKeepTags(keepTags) {
     }
     kept.push(keyword);
   }
-  return kept;
+  return { keywords: kept, privateHex };
+}
+function isUnrepresentableValue(value) {
+  return value === null || value === void 0 || typeof value === "number" && !Number.isFinite(value) || value instanceof ArrayBuffer || ArrayBuffer.isView(value);
+}
+function toRawCapture(el, skipped) {
+  const vr = el.vr;
+  if (typeof vr !== "string") {
+    skipped.count++;
+    return null;
+  }
+  if (vr === "SQ") {
+    const items = [];
+    for (const item of el.Value ?? []) {
+      if (typeof item !== "object" || item === null) continue;
+      const converted = {};
+      for (const [tag, nested] of Object.entries(item)) {
+        if (!HEX_TAG_RE2.test(tag)) continue;
+        const capture = toRawCapture(nested, skipped);
+        if (capture) converted[tag.toUpperCase()] = capture;
+      }
+      items.push(converted);
+    }
+    return { vr, value: items };
+  }
+  const values = el.Value ?? [];
+  if (values.some(isUnrepresentableValue)) {
+    skipped.count++;
+    return null;
+  }
+  return { vr, value: values.length === 1 ? values[0] : values };
+}
+function capturePrivateTags(rawDict, keep, skipped) {
+  const captured = {};
+  let found = false;
+  for (const [tag, el] of Object.entries(rawDict)) {
+    if (!HEX_TAG_RE2.test(tag) || !isPrivateHexTag(tag)) continue;
+    if (!keep.allPrivate && !keep.privateHex.has(tag.toUpperCase())) continue;
+    const capture = toRawCapture(el, skipped);
+    if (capture) {
+      captured[tag.toUpperCase()] = capture;
+      found = true;
+    }
+  }
+  return found ? captured : void 0;
+}
+function hashRawCaptureUids(capture, salt, map) {
+  if (capture.vr === "UI") {
+    return isUidLeaf(capture.value) ? { vr: "UI", value: hashUidValue(capture.value, salt, map) } : capture;
+  }
+  if (capture.vr === "SQ") {
+    const items = capture.value;
+    return {
+      vr: "SQ",
+      value: items.map(
+        (item) => Object.fromEntries(
+          Object.entries(item).map(([tag, nested]) => [
+            tag,
+            hashRawCaptureUids(nested, salt, map)
+          ])
+        )
+      )
+    };
+  }
+  return capture;
 }
 function* walkFiles(dir) {
   for (const entry of readdirSync(dir, { withFileTypes: true })) {
@@ -769,13 +848,16 @@ function toArrayBuffer(buf) {
     buf.byteOffset + buf.byteLength
   );
 }
-function naturalize(ab) {
+function parseParts(ab) {
   const parsed = dcmjsAny.data.DicomMessage.readFile(ab);
-  return dcmjsAny.data.DicomMetaDictionary.naturalizeDataset(parsed.dict);
+  return {
+    record: dcmjsAny.data.DicomMetaDictionary.naturalizeDataset(parsed.dict),
+    rawDict: parsed.dict
+  };
 }
 function parseFull(path) {
   try {
-    return naturalize(toArrayBuffer(readFileSync(path)));
+    return parseParts(toArrayBuffer(readFileSync(path)));
   } catch {
     return null;
   }
@@ -833,7 +915,7 @@ function readHeaderOnly(path) {
     EMPTY_OW_PIXEL_DATA
   ]);
   try {
-    return naturalize(toArrayBuffer(headerOnly));
+    return parseParts(toArrayBuffer(headerOnly));
   } catch {
     return null;
   }
@@ -959,6 +1041,20 @@ function mergeTags(a, b) {
   if (!b) return a;
   return { ...a, ...b };
 }
+function mergePrivateTags(rec, salt, uidMap) {
+  if (!rec.privateTags) return;
+  const hashed = Object.fromEntries(
+    Object.entries(rec.privateTags).map(([tag, capture]) => [
+      tag,
+      salt === void 0 ? capture : hashRawCaptureUids(
+        capture,
+        salt,
+        uidMap
+      )
+    ])
+  );
+  rec.tags = mergeTags(rec.tags, hashed);
+}
 function scanFile(path) {
   let size;
   try {
@@ -968,7 +1064,7 @@ function scanFile(path) {
   }
   if (size > MAX_STREAM_BYTES) return null;
   const large = size > MAX_PIXEL_BYTES;
-  return { size, large, record: large ? readHeaderOnly(path) : parseFull(path) };
+  return { size, large, parsed: large ? readHeaderOnly(path) : parseFull(path) };
 }
 function presetModalityOf(record) {
   if (typeof record.Modality !== "string") return void 0;
@@ -983,6 +1079,13 @@ function hashRecordUids(rec, salt, uidMap, sweptKeepTags) {
   }
   rec.tags = mergeTags(rec.tags, hashUidTags(rec.uidOriginals, salt, uidMap));
 }
+function warnPrivateBinarySkipped(count) {
+  if (count > 0) {
+    console.warn(
+      `describe: ${count} private element(s) with binary payloads were not captured \u2014 binary values cannot ride a JSON spec`
+    );
+  }
+}
 function warnSweptKeepTags(sweptKeepTags) {
   for (const keyword of sweptKeepTags) {
     console.warn(
@@ -1128,14 +1231,16 @@ function emitTree(acc) {
   }
   return nodes;
 }
-function describeTree(dir, options, keepKeywords) {
+function describeTree(dir, options, keep) {
   const root = { dirs: /* @__PURE__ */ new Map(), files: [] };
   const stats = {
     dicomFiles: 0,
     skipped: 0,
     unknownModality: 0,
-    nonDicomFiles: 0
+    nonDicomFiles: 0,
+    privateBinarySkipped: 0
   };
+  const privateSkipped = { count: 0 };
   const studyUids = /* @__PURE__ */ new Set();
   const dicomLeaves = [];
   for (const path of [...walkFiles(dir)].sort()) {
@@ -1144,7 +1249,8 @@ function describeTree(dir, options, keepKeywords) {
       stats.skipped++;
       continue;
     }
-    const { size, large, record } = scanned;
+    const { size, large, parsed } = scanned;
+    const record = parsed?.record;
     const studyUid = record?.StudyInstanceUID;
     const seriesUid = record?.SeriesInstanceUID;
     const relDirs = relative(dir, path).split(sep).slice(0, -1);
@@ -1175,9 +1281,10 @@ function describeTree(dir, options, keepKeywords) {
         modality,
         tags: mergeTags(
           instanceNumber,
-          keepKeywords.length ? extractTags(record, keepKeywords) : void 0
+          keep.keywords.length ? extractTags(record, keep.keywords) : void 0
         ),
-        uidOriginals: collectUidOriginals(record)
+        uidOriginals: collectUidOriginals(record),
+        privateTags: keep.capturingPrivate && parsed ? capturePrivateTags(parsed.rawDict, keep, privateSkipped) : void 0
       },
       studyUid,
       seriesUid
@@ -1193,18 +1300,21 @@ function describeTree(dir, options, keepKeywords) {
   const sweptKeepTags = /* @__PURE__ */ new Set();
   for (const { rec, studyUid, seriesUid } of dicomLeaves) {
     hashRecordUids(rec, salt, uidMap, sweptKeepTags);
+    mergePrivateTags(rec, salt, uidMap);
     rec.tags = mergeTags(rec.tags, {
       StudyInstanceUID: hashUidVia(uidMap, salt, studyUid),
       SeriesInstanceUID: hashUidVia(uidMap, salt, seriesUid)
     });
   }
   warnSweptKeepTags(sweptKeepTags);
+  stats.privateBinarySkipped = privateSkipped.count;
+  warnPrivateBinarySkipped(privateSkipped.count);
   const spec = { tree: emitTree(root), uidSalt: salt };
   validateDatasetSpec(spec);
   return { spec, stats };
 }
 function describeDirectory(dir, options = {}) {
-  const keepKeywords = options.keepTags ? resolveKeepTags(options.keepTags) : [];
+  const keep = buildKeepPlan(options);
   const preserveUids = options.preserveUids ?? true;
   if (options.captureTree) {
     if (!preserveUids) {
@@ -1212,10 +1322,10 @@ function describeDirectory(dir, options = {}) {
         "describe: captureTree requires preserveUids \u2014 the captured tree carries its grouping as hashed UID tags"
       );
     }
-    return describeTree(dir, options, keepKeywords);
+    return describeTree(dir, options, keep);
   }
   const uidMap = /* @__PURE__ */ new Map();
-  const useRecords = keepKeywords.length > 0 || preserveUids;
+  const useRecords = keep.keywords.length > 0 || preserveUids || keep.capturingPrivate;
   const tolerance = options.sizeTolerance ?? 0;
   if (!Number.isFinite(tolerance) || tolerance < 0) {
     throw new Error(
@@ -1227,15 +1337,18 @@ function describeDirectory(dir, options = {}) {
     dicomFiles: 0,
     skipped: 0,
     unknownModality: 0,
-    nonDicomFiles: 0
+    nonDicomFiles: 0,
+    privateBinarySkipped: 0
   };
+  const privateSkipped = { count: 0 };
   for (const path of [...walkFiles(dir)].sort()) {
     const scanned = scanFile(path);
     if (!scanned) {
       stats.skipped++;
       continue;
     }
-    const { size, large, record } = scanned;
+    const { size, large, parsed } = scanned;
+    const record = parsed?.record;
     const studyUid = record?.StudyInstanceUID;
     const seriesUid = record?.SeriesInstanceUID;
     if (!record || typeof studyUid !== "string" || typeof seriesUid !== "string") {
@@ -1246,7 +1359,7 @@ function describeDirectory(dir, options = {}) {
     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 keptTags = keep.keywords.length ? extractTags(record, keep.keywords) : void 0;
     const uidOriginals = preserveUids ? collectUidOriginals(record) : void 0;
     const bytes = large ? size : Math.min(bucketBytes(size, tolerance), MAX_PIXEL_BYTES);
     const fileRecord = {
@@ -1254,7 +1367,8 @@ function describeDirectory(dir, options = {}) {
       bytes,
       modality,
       tags: keptTags,
-      uidOriginals
+      uidOriginals,
+      privateTags: keep.capturingPrivate && parsed ? capturePrivateTags(parsed.rawDict, keep, privateSkipped) : void 0
     };
     let study = studies.get(studyUid);
     if (!study) {
@@ -1273,18 +1387,23 @@ function describeDirectory(dir, options = {}) {
     }
   }
   const salt = preserveUids ? options.uidSalt ?? deriveSalt([...studies.keys()]) : void 0;
-  if (salt !== void 0) {
+  if (salt !== void 0 || keep.capturingPrivate) {
     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) {
-          hashRecordUids(rec, salt, uidMap, sweptKeepTags);
+          if (salt !== void 0) {
+            hashRecordUids(rec, salt, uidMap, sweptKeepTags);
+          }
+          mergePrivateTags(rec, salt, uidMap);
         }
       }
     }
     warnSweptKeepTags(sweptKeepTags);
   }
+  stats.privateBinarySkipped = privateSkipped.count;
+  warnPrivateBinarySkipped(privateSkipped.count);
   const withGroupUid = (spec2, seriesUid) => salt === void 0 ? spec2 : {
     ...spec2,
     tags: {

package/dist/esm/index.js

@@ -1816,13 +1816,28 @@ function buildHexToKeyword() {
   }
   return map;
 }
+function buildKeepPlan(options) {
+  const { keywords, privateHex } = options.keepTags ? resolveKeepTags(options.keepTags) : { keywords: [], privateHex: /* @__PURE__ */ new Set() };
+  const allPrivate = options.keepPrivateTags === true;
+  return {
+    keywords,
+    privateHex,
+    allPrivate,
+    capturingPrivate: allPrivate || privateHex.size > 0
+  };
+}
 function resolveKeepTags(keepTags) {
   const nameMap = dcmjsAny2.data.DicomMetaDictionary.nameMap;
   let hexToKeyword;
   const kept = [];
+  const privateHex = /* @__PURE__ */ new Set();
   for (const tag of keepTags) {
     let keyword;
     if (HEX_TAG_RE2.test(tag)) {
+      if (isPrivateHexTag(tag)) {
+        privateHex.add(tag.toUpperCase());
+        continue;
+      }
       hexToKeyword ?? (hexToKeyword = buildHexToKeyword());
       const mapped = hexToKeyword.get(tag.toUpperCase());
       if (!mapped) {
@@ -1849,7 +1864,71 @@ function resolveKeepTags(keepTags) {
     }
     kept.push(keyword);
   }
-  return kept;
+  return { keywords: kept, privateHex };
+}
+function isUnrepresentableValue(value) {
+  return value === null || value === void 0 || typeof value === "number" && !Number.isFinite(value) || value instanceof ArrayBuffer || ArrayBuffer.isView(value);
+}
+function toRawCapture(el, skipped) {
+  const vr = el.vr;
+  if (typeof vr !== "string") {
+    skipped.count++;
+    return null;
+  }
+  if (vr === "SQ") {
+    const items = [];
+    for (const item of el.Value ?? []) {
+      if (typeof item !== "object" || item === null) continue;
+      const converted = {};
+      for (const [tag, nested] of Object.entries(item)) {
+        if (!HEX_TAG_RE2.test(tag)) continue;
+        const capture = toRawCapture(nested, skipped);
+        if (capture) converted[tag.toUpperCase()] = capture;
+      }
+      items.push(converted);
+    }
+    return { vr, value: items };
+  }
+  const values = el.Value ?? [];
+  if (values.some(isUnrepresentableValue)) {
+    skipped.count++;
+    return null;
+  }
+  return { vr, value: values.length === 1 ? values[0] : values };
+}
+function capturePrivateTags(rawDict, keep, skipped) {
+  const captured = {};
+  let found = false;
+  for (const [tag, el] of Object.entries(rawDict)) {
+    if (!HEX_TAG_RE2.test(tag) || !isPrivateHexTag(tag)) continue;
+    if (!keep.allPrivate && !keep.privateHex.has(tag.toUpperCase())) continue;
+    const capture = toRawCapture(el, skipped);
+    if (capture) {
+      captured[tag.toUpperCase()] = capture;
+      found = true;
+    }
+  }
+  return found ? captured : void 0;
+}
+function hashRawCaptureUids(capture, salt, map) {
+  if (capture.vr === "UI") {
+    return isUidLeaf(capture.value) ? { vr: "UI", value: hashUidValue(capture.value, salt, map) } : capture;
+  }
+  if (capture.vr === "SQ") {
+    const items = capture.value;
+    return {
+      vr: "SQ",
+      value: items.map(
+        (item) => Object.fromEntries(
+          Object.entries(item).map(([tag, nested]) => [
+            tag,
+            hashRawCaptureUids(nested, salt, map)
+          ])
+        )
+      )
+    };
+  }
+  return capture;
 }
 function* walkFiles(dir) {
   for (const entry of readdirSync(dir, { withFileTypes: true })) {
@@ -1867,13 +1946,16 @@ function toArrayBuffer(buf) {
     buf.byteOffset + buf.byteLength
   );
 }
-function naturalize(ab) {
+function parseParts(ab) {
   const parsed = dcmjsAny2.data.DicomMessage.readFile(ab);
-  return dcmjsAny2.data.DicomMetaDictionary.naturalizeDataset(parsed.dict);
+  return {
+    record: dcmjsAny2.data.DicomMetaDictionary.naturalizeDataset(parsed.dict),
+    rawDict: parsed.dict
+  };
 }
 function parseFull(path) {
   try {
-    return naturalize(toArrayBuffer(readFileSync(path)));
+    return parseParts(toArrayBuffer(readFileSync(path)));
   } catch {
     return null;
   }
@@ -1931,7 +2013,7 @@ function readHeaderOnly(path) {
     EMPTY_OW_PIXEL_DATA
   ]);
   try {
-    return naturalize(toArrayBuffer(headerOnly));
+    return parseParts(toArrayBuffer(headerOnly));
   } catch {
     return null;
   }
@@ -2057,6 +2139,20 @@ function mergeTags(a, b) {
   if (!b) return a;
   return { ...a, ...b };
 }
+function mergePrivateTags(rec, salt, uidMap) {
+  if (!rec.privateTags) return;
+  const hashed = Object.fromEntries(
+    Object.entries(rec.privateTags).map(([tag, capture]) => [
+      tag,
+      salt === void 0 ? capture : hashRawCaptureUids(
+        capture,
+        salt,
+        uidMap
+      )
+    ])
+  );
+  rec.tags = mergeTags(rec.tags, hashed);
+}
 function scanFile(path) {
   let size;
   try {
@@ -2066,7 +2162,7 @@ function scanFile(path) {
   }
   if (size > MAX_STREAM_BYTES) return null;
   const large = size > MAX_PIXEL_BYTES;
-  return { size, large, record: large ? readHeaderOnly(path) : parseFull(path) };
+  return { size, large, parsed: large ? readHeaderOnly(path) : parseFull(path) };
 }
 function presetModalityOf(record) {
   if (typeof record.Modality !== "string") return void 0;
@@ -2081,6 +2177,13 @@ function hashRecordUids(rec, salt, uidMap, sweptKeepTags) {
   }
   rec.tags = mergeTags(rec.tags, hashUidTags(rec.uidOriginals, salt, uidMap));
 }
+function warnPrivateBinarySkipped(count) {
+  if (count > 0) {
+    console.warn(
+      `describe: ${count} private element(s) with binary payloads were not captured \u2014 binary values cannot ride a JSON spec`
+    );
+  }
+}
 function warnSweptKeepTags(sweptKeepTags) {
   for (const keyword of sweptKeepTags) {
     console.warn(
@@ -2226,14 +2329,16 @@ function emitTree(acc) {
   }
   return nodes;
 }
-function describeTree(dir, options, keepKeywords) {
+function describeTree(dir, options, keep) {
   const root = { dirs: /* @__PURE__ */ new Map(), files: [] };
   const stats = {
     dicomFiles: 0,
     skipped: 0,
     unknownModality: 0,
-    nonDicomFiles: 0
+    nonDicomFiles: 0,
+    privateBinarySkipped: 0
   };
+  const privateSkipped = { count: 0 };
   const studyUids = /* @__PURE__ */ new Set();
   const dicomLeaves = [];
   for (const path of [...walkFiles(dir)].sort()) {
@@ -2242,7 +2347,8 @@ function describeTree(dir, options, keepKeywords) {
       stats.skipped++;
       continue;
     }
-    const { size, large, record } = scanned;
+    const { size, large, parsed } = scanned;
+    const record = parsed?.record;
     const studyUid = record?.StudyInstanceUID;
     const seriesUid = record?.SeriesInstanceUID;
     const relDirs = relative(dir, path).split(sep).slice(0, -1);
@@ -2273,9 +2379,10 @@ function describeTree(dir, options, keepKeywords) {
         modality,
         tags: mergeTags(
           instanceNumber,
-          keepKeywords.length ? extractTags(record, keepKeywords) : void 0
+          keep.keywords.length ? extractTags(record, keep.keywords) : void 0
         ),
-        uidOriginals: collectUidOriginals(record)
+        uidOriginals: collectUidOriginals(record),
+        privateTags: keep.capturingPrivate && parsed ? capturePrivateTags(parsed.rawDict, keep, privateSkipped) : void 0
       },
       studyUid,
       seriesUid
@@ -2291,18 +2398,21 @@ function describeTree(dir, options, keepKeywords) {
   const sweptKeepTags = /* @__PURE__ */ new Set();
   for (const { rec, studyUid, seriesUid } of dicomLeaves) {
     hashRecordUids(rec, salt, uidMap, sweptKeepTags);
+    mergePrivateTags(rec, salt, uidMap);
     rec.tags = mergeTags(rec.tags, {
       StudyInstanceUID: hashUidVia(uidMap, salt, studyUid),
       SeriesInstanceUID: hashUidVia(uidMap, salt, seriesUid)
     });
   }
   warnSweptKeepTags(sweptKeepTags);
+  stats.privateBinarySkipped = privateSkipped.count;
+  warnPrivateBinarySkipped(privateSkipped.count);
   const spec = { tree: emitTree(root), uidSalt: salt };
   validateDatasetSpec(spec);
   return { spec, stats };
 }
 function describeDirectory(dir, options = {}) {
-  const keepKeywords = options.keepTags ? resolveKeepTags(options.keepTags) : [];
+  const keep = buildKeepPlan(options);
   const preserveUids = options.preserveUids ?? true;
   if (options.captureTree) {
     if (!preserveUids) {
@@ -2310,10 +2420,10 @@ function describeDirectory(dir, options = {}) {
         "describe: captureTree requires preserveUids \u2014 the captured tree carries its grouping as hashed UID tags"
       );
     }
-    return describeTree(dir, options, keepKeywords);
+    return describeTree(dir, options, keep);
   }
   const uidMap = /* @__PURE__ */ new Map();
-  const useRecords = keepKeywords.length > 0 || preserveUids;
+  const useRecords = keep.keywords.length > 0 || preserveUids || keep.capturingPrivate;
   const tolerance = options.sizeTolerance ?? 0;
   if (!Number.isFinite(tolerance) || tolerance < 0) {
     throw new Error(
@@ -2325,15 +2435,18 @@ function describeDirectory(dir, options = {}) {
     dicomFiles: 0,
     skipped: 0,
     unknownModality: 0,
-    nonDicomFiles: 0
+    nonDicomFiles: 0,
+    privateBinarySkipped: 0
   };
+  const privateSkipped = { count: 0 };
   for (const path of [...walkFiles(dir)].sort()) {
     const scanned = scanFile(path);
     if (!scanned) {
       stats.skipped++;
       continue;
     }
-    const { size, large, record } = scanned;
+    const { size, large, parsed } = scanned;
+    const record = parsed?.record;
     const studyUid = record?.StudyInstanceUID;
     const seriesUid = record?.SeriesInstanceUID;
     if (!record || typeof studyUid !== "string" || typeof seriesUid !== "string") {
@@ -2344,7 +2457,7 @@ function describeDirectory(dir, options = {}) {
     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 keptTags = keep.keywords.length ? extractTags(record, keep.keywords) : void 0;
     const uidOriginals = preserveUids ? collectUidOriginals(record) : void 0;
     const bytes = large ? size : Math.min(bucketBytes(size, tolerance), MAX_PIXEL_BYTES);
     const fileRecord = {
@@ -2352,7 +2465,8 @@ function describeDirectory(dir, options = {}) {
       bytes,
       modality,
       tags: keptTags,
-      uidOriginals
+      uidOriginals,
+      privateTags: keep.capturingPrivate && parsed ? capturePrivateTags(parsed.rawDict, keep, privateSkipped) : void 0
     };
     let study = studies.get(studyUid);
     if (!study) {
@@ -2371,18 +2485,23 @@ function describeDirectory(dir, options = {}) {
     }
   }
   const salt = preserveUids ? options.uidSalt ?? deriveSalt([...studies.keys()]) : void 0;
-  if (salt !== void 0) {
+  if (salt !== void 0 || keep.capturingPrivate) {
     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) {
-          hashRecordUids(rec, salt, uidMap, sweptKeepTags);
+          if (salt !== void 0) {
+            hashRecordUids(rec, salt, uidMap, sweptKeepTags);
+          }
+          mergePrivateTags(rec, salt, uidMap);
         }
       }
     }
     warnSweptKeepTags(sweptKeepTags);
   }
+  stats.privateBinarySkipped = privateSkipped.count;
+  warnPrivateBinarySkipped(privateSkipped.count);
   const withGroupUid = (spec2, seriesUid) => salt === void 0 ? spec2 : {
     ...spec2,
     tags: {

package/dist/esm/schema/validate.js

@@ -788,6 +788,7 @@ function validateParametricSpec(raw) {
 export {
   HEX_TAG_RE,
   isImageType,
+  isPrivateHexTag,
   isRawTagValue,
   positionalName,
   validateDatasetSpec,

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

@@ -4,6 +4,7 @@ export type DescribeOptions = {
     sizeTolerance?: number;
     preserveUids?: boolean;
     uidSalt?: string;
+    keepPrivateTags?: boolean;
     captureTree?: boolean;
 };
 export type DescribeResult = {
@@ -13,8 +14,18 @@ export type DescribeResult = {
         skipped: number;
         unknownModality: number;
         nonDicomFiles: number;
+        privateBinarySkipped: number;
     };
 };
-export declare function readHeaderOnly(path: string): Record<string, unknown> | null;
+type RawDictElement = {
+    vr?: string;
+    Value?: unknown[];
+};
+export type ParsedFile = {
+    record: Record<string, unknown>;
+    rawDict: Record<string, RawDictElement>;
+};
+export declare function readHeaderOnly(path: string): ParsedFile | null;
 export declare function tagValuesEqual(a: unknown, b: unknown): boolean;
 export declare function describeDirectory(dir: string, options?: DescribeOptions): DescribeResult;
+export {};

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

@@ -1,6 +1,7 @@
 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 isPrivateHexTag(key: string): boolean;
 export declare function isRawTagValue(value: unknown): value is {
     vr: string;
     value: unknown;

package/package.json

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