dicom-synth 1.16.0 → 1.18.0

package/dist/esm/index.js

@@ -95,6 +95,92 @@ var VALID_VIOLATIONS = {
 };
 var HEX_TAG_RE = /^[0-9a-fA-F]{8}$/;
 var KEYWORD_RE = /^[A-Z][A-Za-z0-9]*$/;
+var VALID_VRS = /* @__PURE__ */ new Set([
+  "AE",
+  "AS",
+  "AT",
+  "CS",
+  "DA",
+  "DS",
+  "DT",
+  "FL",
+  "FD",
+  "IS",
+  "LO",
+  "LT",
+  "OB",
+  "OD",
+  "OF",
+  "OL",
+  "OV",
+  "OW",
+  "PN",
+  "SH",
+  "SL",
+  "SQ",
+  "SS",
+  "ST",
+  "SV",
+  "TM",
+  "UC",
+  "UI",
+  "UL",
+  "UN",
+  "UR",
+  "US",
+  "UT",
+  "UV"
+]);
+function isPrivateHexTag(key) {
+  return HEX_TAG_RE.test(key) && Number.parseInt(key.slice(0, 4), 16) % 2 === 1;
+}
+function isRawTagValue(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) && typeof value.vr === "string";
+}
+function validateRawTagValue(raw, path) {
+  for (const key of Object.keys(raw)) {
+    if (key !== "vr" && key !== "value") {
+      throw new Error(
+        `${path}: raw tag form accepts only "vr" and "value"; got "${key}"`
+      );
+    }
+  }
+  const vr = raw.vr;
+  if (!VALID_VRS.has(vr)) {
+    throw new Error(`${path}.vr: "${vr}" is not a standard DICOM VR`);
+  }
+  if (!("value" in raw)) {
+    throw new Error(`${path}.value: is required in the raw tag form`);
+  }
+  if (vr === "SQ") {
+    if (!Array.isArray(raw.value)) {
+      throw new Error(`${path}.value: an SQ raw tag requires an array of items`);
+    }
+    raw.value.forEach((item, i) => {
+      if (typeof item !== "object" || item === null || Array.isArray(item)) {
+        throw new Error(
+          `${path}.value[${i}]: must be an object of hex-tag entries`
+        );
+      }
+      for (const [tag, nested] of Object.entries(item)) {
+        if (!HEX_TAG_RE.test(tag)) {
+          throw new Error(
+            `${path}.value[${i}]: invalid item tag "${tag}" \u2014 SQ items use 8-hex-char tags`
+          );
+        }
+        if (!isRawTagValue(nested)) {
+          throw new Error(
+            `${path}.value[${i}].${tag}: SQ item entries must use the raw { vr, value } form`
+          );
+        }
+        validateRawTagValue(
+          nested,
+          `${path}.value[${i}].${tag}`
+        );
+      }
+    });
+  }
+}
 function validatePositiveInt(value, path) {
   if (typeof value !== "number" || !Number.isInteger(value) || value < 1) {
     throw new Error(
@@ -299,13 +385,33 @@ function validateEntry(entry, path) {
   return e;
 }
 var MODALITY_TAG = "00080060";
-function validateTagValue(key, value, path) {
+function validateModalityGuard(key, candidate, path) {
   const isModalityKey = key === "Modality" || key.toUpperCase() === MODALITY_TAG;
-  if (isModalityKey && typeof value === "string" && Object.hasOwn(VALID_MODALITIES, value)) {
+  if (isModalityKey && typeof candidate === "string" && Object.hasOwn(VALID_MODALITIES, candidate)) {
     throw new Error(
       `${path}.${key}: set a preset modality (${Object.keys(VALID_MODALITIES).join("/")}) via the "modality" field, not tags \u2014 it is coupled to SOPClassUID and type-1 attributes`
     );
   }
+}
+function validateTagValue(key, value, path) {
+  if (isRawTagValue(value)) {
+    if (!HEX_TAG_RE.test(key)) {
+      throw new Error(
+        `${path}.${key}: the raw { vr, value } form requires an 8-hex-char tag key \u2014 keyword tags take plain values`
+      );
+    }
+    validateRawTagValue(value, `${path}.${key}`);
+    const raw = value.value;
+    const scalar = Array.isArray(raw) && raw.length === 1 ? raw[0] : raw;
+    validateModalityGuard(key, scalar, path);
+    return;
+  }
+  if (isPrivateHexTag(key)) {
+    throw new Error(
+      `${path}.${key}: private tags have no dictionary VR \u2014 use the raw form, e.g. { "vr": "LO", "value": \u2026 }`
+    );
+  }
+  validateModalityGuard(key, value, path);
   if (typeof value === "string") {
     for (const name of findTemplateTokens(value)) {
       if (!TEMPLATE_VOCAB.includes(name)) {
@@ -802,27 +908,50 @@ function buildTagToKeyword() {
   return map;
 }
 var tagToKeyword = buildTagToKeyword();
+function toRawElement(raw) {
+  const value = raw.vr === "SQ" ? raw.value.map(
+    (item) => Object.fromEntries(
+      Object.entries(item).map(([tag, nested]) => [
+        tag.toUpperCase(),
+        toRawElement(nested)
+      ])
+    )
+  ) : raw.value;
+  return { vr: raw.vr, Value: Array.isArray(value) ? value : [value] };
+}
 function applyTagOverrides(dataset, tags) {
-  if (!tags) return;
+  if (!tags) return void 0;
+  let raw;
   for (const [key, value] of Object.entries(tags)) {
-    if (HEX_TAG_RE.test(key)) {
+    if (isRawTagValue(value)) {
+      raw ?? (raw = {});
+      raw[key.toUpperCase()] = toRawElement(value);
+    } else if (HEX_TAG_RE.test(key)) {
       const keyword = tagToKeyword.get(key.toUpperCase());
-      if (keyword) {
-        dataset[keyword] = value;
-      } else {
-        console.warn(`dicom-synth: unknown hex tag "${key}" \u2014 skipping`);
+      if (!keyword) {
+        throw new Error(
+          `dicom-synth: unknown hex tag "${key}" \u2014 dictionary tags take plain values; private/unknown tags require the raw { vr, value } form`
+        );
       }
+      dataset[keyword] = value;
     } else {
       dataset[key] = value;
     }
   }
+  return raw;
 }
-function syncMetaWithDataset(meta, dataset) {
-  if (typeof dataset.SOPInstanceUID === "string") {
-    meta.MediaStorageSOPInstanceUID = dataset.SOPInstanceUID;
+function rawScalarString(rawElements, tag) {
+  const value = rawElements?.[tag]?.Value;
+  return value?.length === 1 && typeof value[0] === "string" ? value[0] : void 0;
+}
+function syncMetaWithDataset(meta, dataset, rawElements) {
+  const sopInstance = rawScalarString(rawElements, "00080018") ?? (typeof dataset.SOPInstanceUID === "string" ? dataset.SOPInstanceUID : void 0);
+  if (sopInstance !== void 0) {
+    meta.MediaStorageSOPInstanceUID = sopInstance;
   }
-  if (typeof dataset.SOPClassUID === "string") {
-    meta.MediaStorageSOPClassUID = dataset.SOPClassUID;
+  const sopClass = rawScalarString(rawElements, "00080016") ?? (typeof dataset.SOPClassUID === "string" ? dataset.SOPClassUID : void 0);
+  if (sopClass !== void 0) {
+    meta.MediaStorageSOPClassUID = sopClass;
   }
 }
 function buildMeta(uid, modality, transferSyntax = "explicit-vr-little-endian") {
@@ -862,7 +991,7 @@ function buildBaseImageDataset(uid, modality) {
     ...preset.attributes
   };
 }
-function serializeDict(meta, dataset) {
+function serializeDict(meta, dataset, rawElements) {
   const dicomDict = new dcmjs.data.DicomDict(
     dcmjs.data.DicomMetaDictionary.denaturalizeDataset(
       meta
@@ -871,14 +1000,17 @@ function serializeDict(meta, dataset) {
   dicomDict.dict = dcmjs.data.DicomMetaDictionary.denaturalizeDataset(
     dataset
   );
+  if (rawElements) {
+    Object.assign(dicomDict.dict, rawElements);
+  }
   return Buffer.from(dicomDict.write({ allowInvalidVRLength: true }));
 }
 var MAX_DIMENSION = 65535;
-function applySizing(dataset, meta, spec) {
+function applySizing(dataset, meta, spec, rawElements) {
   if (spec.targetSizeKb !== void 0) {
     const clampDim = (n) => Math.min(MAX_DIMENSION, Math.max(1, Math.round(n)));
     const minimalPixelBytes = dataset.PixelData.byteLength;
-    const overhead = serializeDict(meta, dataset).length - minimalPixelBytes;
+    const overhead = serializeDict(meta, dataset, rawElements).length - minimalPixelBytes;
     const cells = Math.max(
       1,
       Math.round((spec.targetSizeKb * 1024 - overhead) / 2)
@@ -909,11 +1041,11 @@ function buildImageBuffer(spec, uid) {
     dataset.Laterality = "";
     dataset.PatientWeight = "0";
   }
-  applyTagOverrides(dataset, spec.tags);
+  const rawElements = applyTagOverrides(dataset, spec.tags);
   const meta = buildMeta(effectiveUid, modality, spec.transferSyntax);
-  syncMetaWithDataset(meta, dataset);
-  applySizing(dataset, meta, spec);
-  return serializeDict(meta, dataset);
+  syncMetaWithDataset(meta, dataset, rawElements);
+  applySizing(dataset, meta, spec, rawElements);
+  return { buffer: serializeDict(meta, dataset, rawElements), rawElements };
 }
 function buildFakeSignatureBuffer() {
   const buf = Buffer.alloc(200, 0);
@@ -935,11 +1067,11 @@ function buildBufferForSpec(spec, uid) {
     case "vendor-warnings-image":
       return buildImageBuffer(spec, uid);
     case "fake-signature":
-      return buildFakeSignatureBuffer();
+      return { buffer: buildFakeSignatureBuffer() };
     case "non-dicom":
-      return buildNonDicomBuffer(spec);
+      return { buffer: buildNonDicomBuffer(spec) };
     case "dicomdir":
-      return buildDicomdirBuffer();
+      return { buffer: buildDicomdirBuffer() };
     case "large-image":
       throw new Error(
         "large-image cannot be generated in memory \u2014 use writeCollectionFromSpec (disk-only streaming)"
@@ -1031,12 +1163,12 @@ function writeNative(outPath, params, dims, zeroChunk) {
   const { modality, uid, tags } = params;
   const meta = buildMeta(uid, modality);
   const dataset = buildBaseImageDataset(uid, modality);
-  applyTagOverrides(dataset, tags);
-  syncMetaWithDataset(meta, dataset);
+  const rawElements = applyTagOverrides(dataset, tags);
+  syncMetaWithDataset(meta, dataset, rawElements);
   dataset.Rows = dims.rows;
   dataset.Columns = dims.columns;
   const minimalPixelBytes = dataset.PixelData.byteLength;
-  const probe = serializeDict(meta, dataset);
+  const probe = serializeDict(meta, dataset, rawElements);
   const pixelElement = Buffer.alloc(12);
   PIXEL_DATA_OW_HEADER.copy(pixelElement);
   pixelElement.writeUInt32LE(minimalPixelBytes, 8);
@@ -1065,11 +1197,11 @@ function writeEncapsulated(outPath, params, pixelBytes, fragmentBytes, zeroChunk
     TransferSyntaxUID: RLE_TRANSFER_SYNTAX_UID
   };
   const dataset = buildBaseImageDataset(uid, modality);
-  applyTagOverrides(dataset, tags);
-  syncMetaWithDataset(meta, dataset);
+  const rawElements = applyTagOverrides(dataset, tags);
+  syncMetaWithDataset(meta, dataset, rawElements);
   dataset.PixelData = [new Uint8Array([]).buffer, new Uint8Array([0, 0]).buffer];
   dataset._vrMap = { PixelData: "OB" };
-  const probe = serializeDict(meta, dataset);
+  const probe = serializeDict(meta, dataset, rawElements);
   const idx = probe.indexOf(PIXEL_DATA_OB_HEADER);
   if (idx < 0 || probe.readUInt32LE(idx + 8) !== 4294967295) {
     throw new Error("failed to locate encapsulated PixelData element header");
@@ -1187,7 +1319,7 @@ var VIOLATION_LEVEL = {
   "missing-meta-header": "byte",
   "malformed-sq-delimiter": "byte"
 };
-function applyTagLevel(buffer, violations) {
+function applyTagLevel(buffer, violations, rawElements) {
   if (violations.length === 0) return buffer;
   let parsed;
   try {
@@ -1221,6 +1353,9 @@ function applyTagLevel(buffer, violations) {
     }
   }
   parsed.dict = dcmjsAny.data.DicomMetaDictionary.denaturalizeDataset(natural);
+  if (rawElements) {
+    Object.assign(parsed.dict, rawElements);
+  }
   if (violations.includes("uid-too-long")) {
     ;
     parsed.dict["00080018"] = {
@@ -1253,11 +1388,14 @@ function applyByteLevel(buffer, violations) {
   }
   return result;
 }
-function applyViolations(buffer, violations) {
+function applyViolations(buffer, violations, rawElements) {
   if (violations.length === 0) return buffer;
   const tagViolations = violations.filter((v) => VIOLATION_LEVEL[v] === "tag");
   const byteViolations = violations.filter((v) => VIOLATION_LEVEL[v] === "byte");
-  return applyByteLevel(applyTagLevel(buffer, tagViolations), byteViolations);
+  return applyByteLevel(
+    applyTagLevel(buffer, tagViolations, rawElements),
+    byteViolations
+  );
 }
 
 // src/collection/writer.ts
@@ -1331,10 +1469,11 @@ async function generateFile(spec, options) {
     ...spec,
     tags: resolveTagTemplates(spec.tags, { index, ...options?.context })
   } : spec;
-  let buffer = buildBufferForSpec(resolvedSpec, uid);
+  const built = buildBufferForSpec(resolvedSpec, uid);
+  let buffer = built.buffer;
   const violations = "violations" in spec ? spec.violations : void 0;
   if (violations?.length) {
-    buffer = applyViolations(buffer, violations);
+    buffer = applyViolations(buffer, violations, built.rawElements);
   }
   const name = filename(spec.type, index, padWidth);
   return {
@@ -1677,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) {
@@ -1710,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 })) {
@@ -1728,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;
   }
@@ -1792,7 +2013,7 @@ function readHeaderOnly(path) {
     EMPTY_OW_PIXEL_DATA
   ]);
   try {
-    return naturalize(toArrayBuffer(headerOnly));
+    return parseParts(toArrayBuffer(headerOnly));
   } catch {
     return null;
   }
@@ -1918,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 {
@@ -1927,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;
@@ -1942,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(
@@ -2087,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()) {
@@ -2103,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);
@@ -2134,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
@@ -2152,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) {
@@ -2171,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(
@@ -2186,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") {
@@ -2205,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 = {
@@ -2213,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) {
@@ -2232,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: {