dicom-synth 1.16.0 → 1.18.0

package/dist/esm/describe/describe.js

@@ -92,6 +92,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(
@@ -289,13 +375,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)) {
@@ -612,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) {
@@ -645,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 })) {
@@ -663,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;
   }
@@ -727,7 +915,7 @@ function readHeaderOnly(path) {
     EMPTY_OW_PIXEL_DATA
   ]);
   try {
-    return naturalize(toArrayBuffer(headerOnly));
+    return parseParts(toArrayBuffer(headerOnly));
   } catch {
     return null;
   }
@@ -853,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 {
@@ -862,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;
@@ -877,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(
@@ -1022,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()) {
@@ -1038,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);
@@ -1069,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
@@ -1087,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) {
@@ -1106,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(
@@ -1121,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") {
@@ -1140,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 = {
@@ -1148,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) {
@@ -1167,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: {