dicom-synth 1.17.0 → 1.19.0

package/dist/esm/describe/describe.js

@@ -1,5 +1,5 @@
 // src/describe/describe.ts
-import { createHash as createHash2 } from "node:crypto";
+import { createHash } from "node:crypto";
 import {
   closeSync,
   openSync,
@@ -687,11 +687,148 @@ function validateDatasetSpec(raw) {
   };
 }
 
+// src/platform/bytes.ts
+function bytesToHex(bytes) {
+  let hex = "";
+  for (const byte of bytes) {
+    hex += byte.toString(16).padStart(2, "0");
+  }
+  return hex;
+}
+
+// src/platform/sha256.ts
+var K = new Uint32Array([
+  1116352408,
+  1899447441,
+  3049323471,
+  3921009573,
+  961987163,
+  1508970993,
+  2453635748,
+  2870763221,
+  3624381080,
+  310598401,
+  607225278,
+  1426881987,
+  1925078388,
+  2162078206,
+  2614888103,
+  3248222580,
+  3835390401,
+  4022224774,
+  264347078,
+  604807628,
+  770255983,
+  1249150122,
+  1555081692,
+  1996064986,
+  2554220882,
+  2821834349,
+  2952996808,
+  3210313671,
+  3336571891,
+  3584528711,
+  113926993,
+  338241895,
+  666307205,
+  773529912,
+  1294757372,
+  1396182291,
+  1695183700,
+  1986661051,
+  2177026350,
+  2456956037,
+  2730485921,
+  2820302411,
+  3259730800,
+  3345764771,
+  3516065817,
+  3600352804,
+  4094571909,
+  275423344,
+  430227734,
+  506948616,
+  659060556,
+  883997877,
+  958139571,
+  1322822218,
+  1537002063,
+  1747873779,
+  1955562222,
+  2024104815,
+  2227730452,
+  2361852424,
+  2428436474,
+  2756734187,
+  3204031479,
+  3329325298
+]);
+var rotr = (x, n) => x >>> n | x << 32 - n;
+function sha256(input) {
+  const data2 = typeof input === "string" ? new TextEncoder().encode(input) : input;
+  const padded = new Uint8Array((data2.length + 8 >> 6) + 1 << 6);
+  padded.set(data2);
+  padded[data2.length] = 128;
+  new DataView(padded.buffer).setBigUint64(
+    padded.length - 8,
+    BigInt(data2.length * 8),
+    false
+  );
+  const h = new Uint32Array([
+    1779033703,
+    3144134277,
+    1013904242,
+    2773480762,
+    1359893119,
+    2600822924,
+    528734635,
+    1541459225
+  ]);
+  const w = new Uint32Array(64);
+  const view = new DataView(padded.buffer);
+  for (let offset = 0; offset < padded.length; offset += 64) {
+    for (let t = 0; t < 16; t++) w[t] = view.getUint32(offset + t * 4, false);
+    for (let t = 16; t < 64; t++) {
+      const s0 = rotr(w[t - 15], 7) ^ rotr(w[t - 15], 18) ^ w[t - 15] >>> 3;
+      const s1 = rotr(w[t - 2], 17) ^ rotr(w[t - 2], 19) ^ w[t - 2] >>> 10;
+      w[t] = w[t - 16] + s0 + w[t - 7] + s1 >>> 0;
+    }
+    let [a, b, c, d, e, f, g, hh] = h;
+    for (let t = 0; t < 64; t++) {
+      const S1 = rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25);
+      const ch = e & f ^ ~e & g;
+      const temp1 = hh + S1 + ch + K[t] + w[t] >>> 0;
+      const S0 = rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22);
+      const maj = a & b ^ a & c ^ b & c;
+      const temp2 = S0 + maj >>> 0;
+      hh = g;
+      g = f;
+      f = e;
+      e = d + temp1 >>> 0;
+      d = c;
+      c = b;
+      b = a;
+      a = temp1 + temp2 >>> 0;
+    }
+    h[0] = h[0] + a >>> 0;
+    h[1] = h[1] + b >>> 0;
+    h[2] = h[2] + c >>> 0;
+    h[3] = h[3] + d >>> 0;
+    h[4] = h[4] + e >>> 0;
+    h[5] = h[5] + f >>> 0;
+    h[6] = h[6] + g >>> 0;
+    h[7] = h[7] + hh >>> 0;
+  }
+  const out = new Uint8Array(32);
+  const outView = new DataView(out.buffer);
+  for (let i = 0; i < 8; i++) outView.setUint32(i * 4, h[i], false);
+  return out;
+}
+
 // 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")}`);
+  const digest = sha256(`${salt} ${key}`);
+  const n = BigInt(`0x${bytesToHex(digest.subarray(0, 16))}`);
   return `2.25.${n.toString()}`;
 }
 
@@ -718,13 +855,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 +903,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 +985,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 +1052,7 @@ function readHeaderOnly(path) {
     EMPTY_OW_PIXEL_DATA
   ]);
   try {
-    return naturalize(toArrayBuffer(headerOnly));
+    return parseParts(toArrayBuffer(headerOnly));
   } catch {
     return null;
   }
@@ -950,7 +1169,7 @@ function hashUidTags(uids, salt, map) {
   return tags;
 }
 function deriveSalt(studyUids) {
-  const h = createHash2("sha256");
+  const h = createHash("sha256");
   for (const uid of [...studyUids].sort()) h.update(uid).update("\n");
   return h.digest("hex");
 }
@@ -959,6 +1178,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 +1201,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 +1216,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 +1368,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 +1386,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 +1418,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 +1437,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 +1459,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 +1474,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 +1496,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 +1504,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 +1524,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: {