dicom-synth 1.17.0 → 1.19.0

package/dist/esm/index.js

@@ -1,12 +1,46 @@
-// src/collection/writer.ts
-import { randomBytes as randomBytes2 } from "node:crypto";
-import { mkdirSync as mkdirSync3 } from "node:fs";
-import { writeFile } from "node:fs/promises";
-import { dirname, resolve as resolve3 } from "node:path";
+// src/platform/bytes.ts
+function bytesToHex(bytes) {
+  let hex = "";
+  for (const byte of bytes) {
+    hex += byte.toString(16).padStart(2, "0");
+  }
+  return hex;
+}
+function utf8Bytes(text) {
+  return new TextEncoder().encode(text);
+}
+function concatBytes(...parts) {
+  const out = new Uint8Array(parts.reduce((sum, p) => sum + p.length, 0));
+  let offset = 0;
+  for (const part of parts) {
+    out.set(part, offset);
+    offset += part.length;
+  }
+  return out;
+}
+function patternBytes(length, pattern) {
+  const out = new Uint8Array(length);
+  const seed = utf8Bytes(pattern);
+  if (length === 0 || seed.length === 0) return out;
+  out.set(seed.subarray(0, Math.min(seed.length, length)));
+  let filled = Math.min(seed.length, length);
+  while (filled < length) {
+    const chunk = Math.min(filled, length - filled);
+    out.copyWithin(filled, 0, chunk);
+    filled += chunk;
+  }
+  return out;
+}
 
-// src/schema/limits.ts
-var MAX_PIXEL_BYTES = 512 * 1024 * 1024;
-var MAX_STREAM_BYTES = 50 * 1024 * 1024 * 1024;
+// src/platform/random.ts
+function randomUint32() {
+  return globalThis.crypto.getRandomValues(new Uint32Array(1))[0];
+}
+function randomHex(byteLength) {
+  return bytesToHex(
+    globalThis.crypto.getRandomValues(new Uint8Array(byteLength))
+  );
+}
 
 // src/syntheticFixtures/tagTemplate.ts
 var TEMPLATE_VOCAB = [
@@ -52,6 +86,10 @@ function resolveString(value, context) {
   });
 }
 
+// src/schema/limits.ts
+var MAX_PIXEL_BYTES = 512 * 1024 * 1024;
+var MAX_STREAM_BYTES = 50 * 1024 * 1024 * 1024;
+
 // src/schema/validate.ts
 var TYPE_CAPABILITIES = {
   "valid-image": { image: true },
@@ -840,23 +878,22 @@ function loadDcmjs() {
 var dcmjs = loadDcmjs();
 
 // src/nonStandardDicom/dicomdir.ts
-import { mkdirSync, writeFileSync } from "node:fs";
-import { resolve } from "node:path";
 var DICOMDIR_SOP_CLASS_UID = "1.2.840.10008.1.3.10";
 function buildDicomdirBuffer() {
   const uid = DICOMDIR_SOP_CLASS_UID;
-  const buf = Buffer.alloc(256, 0);
-  buf.write("DICM", 128, 4, "ascii");
+  const buf = new Uint8Array(256);
+  const view = new DataView(buf.buffer);
+  buf.set(utf8Bytes("DICM"), 128);
   let off = 132;
-  buf.writeUInt16LE(2, off);
+  view.setUint16(off, 2, true);
   off += 2;
-  buf.writeUInt16LE(2, off);
+  view.setUint16(off, 2, true);
   off += 2;
-  buf.write("UI", off, 2, "ascii");
+  buf.set(utf8Bytes("UI"), off);
   off += 2;
-  buf.writeUInt16LE(uid.length, off);
+  view.setUint16(off, uid.length, true);
   off += 2;
-  buf.write(uid, off, uid.length, "ascii");
+  buf.set(utf8Bytes(uid), off);
   off += uid.length;
   return buf.subarray(0, off);
 }
@@ -1003,7 +1040,7 @@ function serializeDict(meta, dataset, rawElements) {
   if (rawElements) {
     Object.assign(dicomDict.dict, rawElements);
   }
-  return Buffer.from(dicomDict.write({ allowInvalidVRLength: true }));
+  return new Uint8Array(dicomDict.write({ allowInvalidVRLength: true }));
 }
 var MAX_DIMENSION = 65535;
 function applySizing(dataset, meta, spec, rawElements) {
@@ -1048,8 +1085,8 @@ function buildImageBuffer(spec, uid) {
   return { buffer: serializeDict(meta, dataset, rawElements), rawElements };
 }
 function buildFakeSignatureBuffer() {
-  const buf = Buffer.alloc(200, 0);
-  buf.write("XXXX", 128, 4, "ascii");
+  const buf = new Uint8Array(200);
+  buf.set(utf8Bytes("XXXX"), 128);
   return buf;
 }
 function sizedNonDicomBytes(spec) {
@@ -1057,8 +1094,8 @@ function sizedNonDicomBytes(spec) {
 }
 function buildNonDicomBuffer(spec) {
   const bytes = sizedNonDicomBytes(spec);
-  if (bytes !== void 0) return Buffer.alloc(bytes, "not dicom ");
-  return Buffer.from(spec.content ?? "not dicom", "utf8");
+  if (bytes !== void 0) return patternBytes(bytes, "not dicom ");
+  return utf8Bytes(spec.content ?? "not dicom");
 }
 function buildBufferForSpec(spec, uid) {
   switch (spec.type) {
@@ -1079,19 +1116,143 @@ function buildBufferForSpec(spec, uid) {
   }
 }
 
-// src/syntheticFixtures/streamWrite.ts
-import { closeSync, mkdirSync as mkdirSync2, openSync, writeSync } from "node:fs";
-import { resolve as resolve2 } from "node:path";
+// 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()}`;
 }
 function randomUid() {
-  const n = BigInt(`0x${randomBytes(16).toString("hex")}`);
+  const n = BigInt(`0x${randomHex(16)}`);
   return `2.25.${n.toString()}`;
 }
 function seedToSalt(seed) {
@@ -1128,176 +1289,6 @@ function makeUidGenerator(salt) {
   });
 }
 
-// src/syntheticFixtures/streamWrite.ts
-var OW_MAX_BYTES = 4294967294;
-var FRAGMENT_MAX_BYTES = 4294967294;
-var DEFAULT_CHUNK_BYTES = 8 * 1024 * 1024;
-var RLE_TRANSFER_SYNTAX_UID = "1.2.840.10008.1.2.5";
-var PIXEL_DATA_OW_HEADER = Buffer.from([224, 127, 16, 0, 79, 87]);
-var PIXEL_DATA_OB_HEADER = Buffer.from([224, 127, 16, 0, 79, 66]);
-var ITEM_TAG_GROUP = 65534;
-var ITEM_TAG_ELEMENT = 57344;
-var SEQUENCE_DELIMITER_ELEMENT = 57565;
-function itemTag(element, byteLength = 0) {
-  const b = Buffer.alloc(8);
-  b.writeUInt16LE(ITEM_TAG_GROUP, 0);
-  b.writeUInt16LE(element, 2);
-  b.writeUInt32LE(byteLength, 4);
-  return b;
-}
-function nativeDimensions(pixelBytes) {
-  const cells = Math.max(1, Math.floor(pixelBytes / 2));
-  const rows = Math.min(65535, Math.max(1, Math.round(Math.sqrt(cells))));
-  const columns = Math.min(65535, Math.max(1, Math.floor(cells / rows)));
-  return { rows, columns, bytes: rows * columns * 2 };
-}
-function streamZeros(fd, totalBytes, zeroChunk) {
-  let remaining = totalBytes;
-  while (remaining > 0) {
-    const n = Math.min(zeroChunk.length, remaining);
-    writeSync(fd, zeroChunk, 0, n);
-    remaining -= n;
-  }
-}
-function writeNative(outPath, params, dims, zeroChunk) {
-  const { modality, uid, tags } = params;
-  const meta = buildMeta(uid, modality);
-  const dataset = buildBaseImageDataset(uid, modality);
-  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, rawElements);
-  const pixelElement = Buffer.alloc(12);
-  PIXEL_DATA_OW_HEADER.copy(pixelElement);
-  pixelElement.writeUInt32LE(minimalPixelBytes, 8);
-  const owIdx = probe.indexOf(pixelElement);
-  if (owIdx < 0) {
-    throw new Error("failed to locate native PixelData element header");
-  }
-  const dataStart = owIdx + 12;
-  const header = Buffer.from(probe.subarray(0, dataStart));
-  header.writeUInt32LE(dims.bytes, owIdx + 8);
-  const trailing = probe.subarray(dataStart + minimalPixelBytes);
-  const fd = openSync(outPath, "w");
-  try {
-    writeSync(fd, header);
-    streamZeros(fd, dims.bytes, zeroChunk);
-    if (trailing.length > 0) writeSync(fd, trailing);
-  } finally {
-    closeSync(fd);
-  }
-  return header.length + dims.bytes + trailing.length;
-}
-function writeEncapsulated(outPath, params, pixelBytes, fragmentBytes, zeroChunk) {
-  const { modality, uid, tags } = params;
-  const meta = {
-    ...buildMeta(uid, modality),
-    TransferSyntaxUID: RLE_TRANSFER_SYNTAX_UID
-  };
-  const dataset = buildBaseImageDataset(uid, modality);
-  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, 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");
-  }
-  const prefix = Buffer.from(probe.subarray(0, idx + 12));
-  const fd = openSync(outPath, "w");
-  let bytesWritten = 0;
-  try {
-    writeSync(fd, prefix);
-    bytesWritten += prefix.length;
-    const bot = itemTag(ITEM_TAG_ELEMENT, 0);
-    writeSync(fd, bot);
-    bytesWritten += bot.length;
-    let remaining = pixelBytes;
-    while (remaining > 0) {
-      const fragLen = Math.min(fragmentBytes, remaining);
-      const fh = itemTag(ITEM_TAG_ELEMENT, fragLen);
-      writeSync(fd, fh);
-      streamZeros(fd, fragLen, zeroChunk);
-      bytesWritten += fh.length + fragLen;
-      remaining -= fragLen;
-    }
-    const delimiter = itemTag(SEQUENCE_DELIMITER_ELEMENT);
-    writeSync(fd, delimiter);
-    bytesWritten += delimiter.length;
-  } finally {
-    closeSync(fd);
-  }
-  return bytesWritten;
-}
-function streamLargeImage(outPath, options) {
-  const {
-    targetBytes,
-    chunkBytes = DEFAULT_CHUNK_BYTES,
-    owMaxBytes = OW_MAX_BYTES,
-    fragmentBytes = FRAGMENT_MAX_BYTES
-  } = options;
-  const modality = options.modality ?? "CT";
-  const uid = options.uid ?? makeUidGenerator(options.uidSalt ?? seedToSalt(options.seed))(0);
-  const identity = { modality, uid, tags: options.tags };
-  mkdirSync2(resolve2(outPath, ".."), { recursive: true });
-  const zeroChunk = Buffer.alloc(Math.max(1, chunkBytes));
-  const probe = serializeDict(
-    buildMeta(uid, modality),
-    buildBaseImageDataset(uid, modality)
-  );
-  const nativeHeaderLen = probe.length - 2;
-  const requestedPixel = Math.max(2, targetBytes - nativeHeaderLen);
-  if (requestedPixel <= owMaxBytes) {
-    const dims = nativeDimensions(requestedPixel);
-    const bytesWritten2 = writeNative(outPath, identity, dims, zeroChunk);
-    return {
-      path: outPath,
-      bytesWritten: bytesWritten2,
-      encoding: "native",
-      pixelBytes: dims.bytes
-    };
-  }
-  const estimateFrags = Math.max(
-    1,
-    Math.ceil((targetBytes - nativeHeaderLen - 16) / fragmentBytes)
-  );
-  const overhead = nativeHeaderLen + 8 + estimateFrags * 8 + 8;
-  let pixelBytes = Math.max(2, targetBytes - overhead);
-  pixelBytes -= pixelBytes % 2;
-  const bytesWritten = writeEncapsulated(
-    outPath,
-    identity,
-    pixelBytes,
-    fragmentBytes - fragmentBytes % 2,
-    zeroChunk
-  );
-  return { path: outPath, bytesWritten, encoding: "encapsulated", pixelBytes };
-}
-function writeLargeImageFile(spec, outPath, options = {}) {
-  const { targetBytes } = spec;
-  if (!Number.isInteger(targetBytes)) {
-    throw new Error("writeLargeImageFile: targetBytes must be an integer");
-  }
-  if (targetBytes <= MAX_PIXEL_BYTES) {
-    throw new Error(
-      "writeLargeImageFile is for files above the 512 MB in-memory limit \u2014 use targetSizeKb for smaller files"
-    );
-  }
-  if (targetBytes > MAX_STREAM_BYTES) {
-    throw new Error("writeLargeImageFile: targetBytes exceeds the 50 GB limit");
-  }
-  return streamLargeImage(outPath, {
-    targetBytes,
-    modality: spec.modality,
-    uidSalt: spec.uidSalt,
-    seed: spec.seed,
-    chunkBytes: options.chunkBytes
-  });
-}
-
 // src/syntheticFixtures/violations.ts
 var dcmjsAny = dcmjs;
 function parseBuffer(buffer) {
@@ -1308,7 +1299,7 @@ function parseBuffer(buffer) {
   return dcmjsAny.data.DicomMessage.readFile(ab);
 }
 function reserialize(parsed) {
-  return Buffer.from(parsed.write({ allowInvalidVRLength: true }));
+  return new Uint8Array(parsed.write({ allowInvalidVRLength: true }));
 }
 var OVERLONG_UID = `2.25.${"0".repeat(60)}`;
 var VIOLATION_LEVEL = {
@@ -1373,11 +1364,12 @@ function applyByteLevel(buffer, violations) {
         result = result.subarray(132);
         break;
       case "malformed-sq-delimiter": {
-        const delimiter = Buffer.alloc(8);
-        delimiter.writeUInt16LE(65534, 0);
-        delimiter.writeUInt16LE(57565, 2);
-        delimiter.writeUInt32LE(4, 4);
-        result = Buffer.concat([result, delimiter]);
+        const delimiter = new Uint8Array(8);
+        const view = new DataView(delimiter.buffer);
+        view.setUint16(0, 65534, true);
+        view.setUint16(2, 57565, true);
+        view.setUint32(4, 4, true);
+        result = concatBytes(result, delimiter);
         break;
       }
       default:
@@ -1398,7 +1390,7 @@ function applyViolations(buffer, violations, rawElements) {
   );
 }
 
-// src/collection/writer.ts
+// src/collection/generate.ts
 var NO_EXTENSION_TYPES = /* @__PURE__ */ new Set([
   "fake-signature",
   "non-dicom"
@@ -1538,10 +1530,10 @@ function hierarchicalName(studyOrdinal, seriesIndex, instanceNumber) {
   };
 }
 function withResolvedSeed(spec) {
-  return spec.seed === void 0 ? { ...spec, seed: randomBytes2(4).readUInt32BE(0) } : spec;
+  return spec.seed === void 0 ? { ...spec, seed: randomUint32() } : spec;
 }
 function withResolvedSalt(spec) {
-  return spec.uidSalt === void 0 ? { ...spec, uidSalt: randomBytes2(16).toString("hex") } : spec;
+  return spec.uidSalt === void 0 ? { ...spec, uidSalt: randomHex(16) } : spec;
 }
 function computeNames(type, index, padWidth, grouped, quirks) {
   let names;
@@ -1740,21 +1732,203 @@ async function* previewCollection(spec) {
     }
   }
 }
+
+// src/collection/writer.ts
+import { mkdirSync as mkdirSync2 } from "node:fs";
+import { writeFile } from "node:fs/promises";
+import { dirname, resolve as resolve2 } from "node:path";
+
+// src/syntheticFixtures/streamWrite.ts
+import { closeSync, mkdirSync, openSync, writeSync } from "node:fs";
+import { resolve } from "node:path";
+var OW_MAX_BYTES = 4294967294;
+var FRAGMENT_MAX_BYTES = 4294967294;
+var DEFAULT_CHUNK_BYTES = 8 * 1024 * 1024;
+var RLE_TRANSFER_SYNTAX_UID = "1.2.840.10008.1.2.5";
+var PIXEL_DATA_OW_HEADER = Buffer.from([224, 127, 16, 0, 79, 87]);
+var PIXEL_DATA_OB_HEADER = Buffer.from([224, 127, 16, 0, 79, 66]);
+var ITEM_TAG_GROUP = 65534;
+var ITEM_TAG_ELEMENT = 57344;
+var SEQUENCE_DELIMITER_ELEMENT = 57565;
+function asBuffer(bytes) {
+  return Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+}
+function itemTag(element, byteLength = 0) {
+  const b = Buffer.alloc(8);
+  b.writeUInt16LE(ITEM_TAG_GROUP, 0);
+  b.writeUInt16LE(element, 2);
+  b.writeUInt32LE(byteLength, 4);
+  return b;
+}
+function nativeDimensions(pixelBytes) {
+  const cells = Math.max(1, Math.floor(pixelBytes / 2));
+  const rows = Math.min(65535, Math.max(1, Math.round(Math.sqrt(cells))));
+  const columns = Math.min(65535, Math.max(1, Math.floor(cells / rows)));
+  return { rows, columns, bytes: rows * columns * 2 };
+}
+function streamZeros(fd, totalBytes, zeroChunk) {
+  let remaining = totalBytes;
+  while (remaining > 0) {
+    const n = Math.min(zeroChunk.length, remaining);
+    writeSync(fd, zeroChunk, 0, n);
+    remaining -= n;
+  }
+}
+function writeNative(outPath, params, dims, zeroChunk) {
+  const { modality, uid, tags } = params;
+  const meta = buildMeta(uid, modality);
+  const dataset = buildBaseImageDataset(uid, modality);
+  const rawElements = applyTagOverrides(dataset, tags);
+  syncMetaWithDataset(meta, dataset, rawElements);
+  dataset.Rows = dims.rows;
+  dataset.Columns = dims.columns;
+  const minimalPixelBytes = dataset.PixelData.byteLength;
+  const probe = asBuffer(serializeDict(meta, dataset, rawElements));
+  const pixelElement = Buffer.alloc(12);
+  PIXEL_DATA_OW_HEADER.copy(pixelElement);
+  pixelElement.writeUInt32LE(minimalPixelBytes, 8);
+  const owIdx = probe.indexOf(pixelElement);
+  if (owIdx < 0) {
+    throw new Error("failed to locate native PixelData element header");
+  }
+  const dataStart = owIdx + 12;
+  const header = Buffer.from(probe.subarray(0, dataStart));
+  header.writeUInt32LE(dims.bytes, owIdx + 8);
+  const trailing = probe.subarray(dataStart + minimalPixelBytes);
+  const fd = openSync(outPath, "w");
+  try {
+    writeSync(fd, header);
+    streamZeros(fd, dims.bytes, zeroChunk);
+    if (trailing.length > 0) writeSync(fd, trailing);
+  } finally {
+    closeSync(fd);
+  }
+  return header.length + dims.bytes + trailing.length;
+}
+function writeEncapsulated(outPath, params, pixelBytes, fragmentBytes, zeroChunk) {
+  const { modality, uid, tags } = params;
+  const meta = {
+    ...buildMeta(uid, modality),
+    TransferSyntaxUID: RLE_TRANSFER_SYNTAX_UID
+  };
+  const dataset = buildBaseImageDataset(uid, modality);
+  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 = asBuffer(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");
+  }
+  const prefix = Buffer.from(probe.subarray(0, idx + 12));
+  const fd = openSync(outPath, "w");
+  let bytesWritten = 0;
+  try {
+    writeSync(fd, prefix);
+    bytesWritten += prefix.length;
+    const bot = itemTag(ITEM_TAG_ELEMENT, 0);
+    writeSync(fd, bot);
+    bytesWritten += bot.length;
+    let remaining = pixelBytes;
+    while (remaining > 0) {
+      const fragLen = Math.min(fragmentBytes, remaining);
+      const fh = itemTag(ITEM_TAG_ELEMENT, fragLen);
+      writeSync(fd, fh);
+      streamZeros(fd, fragLen, zeroChunk);
+      bytesWritten += fh.length + fragLen;
+      remaining -= fragLen;
+    }
+    const delimiter = itemTag(SEQUENCE_DELIMITER_ELEMENT);
+    writeSync(fd, delimiter);
+    bytesWritten += delimiter.length;
+  } finally {
+    closeSync(fd);
+  }
+  return bytesWritten;
+}
+function streamLargeImage(outPath, options) {
+  const {
+    targetBytes,
+    chunkBytes = DEFAULT_CHUNK_BYTES,
+    owMaxBytes = OW_MAX_BYTES,
+    fragmentBytes = FRAGMENT_MAX_BYTES
+  } = options;
+  const modality = options.modality ?? "CT";
+  const uid = options.uid ?? makeUidGenerator(options.uidSalt ?? seedToSalt(options.seed))(0);
+  const identity = { modality, uid, tags: options.tags };
+  mkdirSync(resolve(outPath, ".."), { recursive: true });
+  const zeroChunk = Buffer.alloc(Math.max(1, chunkBytes));
+  const probe = serializeDict(
+    buildMeta(uid, modality),
+    buildBaseImageDataset(uid, modality)
+  );
+  const nativeHeaderLen = probe.length - 2;
+  const requestedPixel = Math.max(2, targetBytes - nativeHeaderLen);
+  if (requestedPixel <= owMaxBytes) {
+    const dims = nativeDimensions(requestedPixel);
+    const bytesWritten2 = writeNative(outPath, identity, dims, zeroChunk);
+    return {
+      path: outPath,
+      bytesWritten: bytesWritten2,
+      encoding: "native",
+      pixelBytes: dims.bytes
+    };
+  }
+  const estimateFrags = Math.max(
+    1,
+    Math.ceil((targetBytes - nativeHeaderLen - 16) / fragmentBytes)
+  );
+  const overhead = nativeHeaderLen + 8 + estimateFrags * 8 + 8;
+  let pixelBytes = Math.max(2, targetBytes - overhead);
+  pixelBytes -= pixelBytes % 2;
+  const bytesWritten = writeEncapsulated(
+    outPath,
+    identity,
+    pixelBytes,
+    fragmentBytes - fragmentBytes % 2,
+    zeroChunk
+  );
+  return { path: outPath, bytesWritten, encoding: "encapsulated", pixelBytes };
+}
+function writeLargeImageFile(spec, outPath, options = {}) {
+  const { targetBytes } = spec;
+  if (!Number.isInteger(targetBytes)) {
+    throw new Error("writeLargeImageFile: targetBytes must be an integer");
+  }
+  if (targetBytes <= MAX_PIXEL_BYTES) {
+    throw new Error(
+      "writeLargeImageFile is for files above the 512 MB in-memory limit \u2014 use targetSizeKb for smaller files"
+    );
+  }
+  if (targetBytes > MAX_STREAM_BYTES) {
+    throw new Error("writeLargeImageFile: targetBytes exceeds the 50 GB limit");
+  }
+  return streamLargeImage(outPath, {
+    targetBytes,
+    modality: spec.modality,
+    uidSalt: spec.uidSalt,
+    seed: spec.seed,
+    chunkBytes: options.chunkBytes
+  });
+}
+
+// src/collection/writer.ts
 async function writeCollectionFromSpec(spec, outDir) {
-  const root = resolve3(outDir);
-  mkdirSync3(root, { recursive: true });
+  const root = resolve2(outDir);
+  mkdirSync2(root, { recursive: true });
   const manifest = [];
   const salt = effectiveSalt(spec);
   const createdDirs = /* @__PURE__ */ new Set([root]);
   const ensureDir = (filePath) => {
     const dir = dirname(filePath);
     if (!createdDirs.has(dir)) {
-      mkdirSync3(dir, { recursive: true });
+      mkdirSync2(dir, { recursive: true });
       createdDirs.add(dir);
     }
   };
   for (const plan of planCollection(spec)) {
-    const filePath = resolve3(root, plan.relativePath);
+    const filePath = resolve2(root, plan.relativePath);
     ensureDir(filePath);
     if (plan.fileSpec.type === "large-image") {
       const large = plan.fileSpec;
@@ -1784,7 +1958,7 @@ async function writeCollectionFromSpec(spec, outDir) {
 }
 
 // src/describe/describe.ts
-import { createHash as createHash2 } from "node:crypto";
+import { createHash } from "node:crypto";
 import {
   closeSync as closeSync2,
   openSync as openSync2,
@@ -1816,13 +1990,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 +2038,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 +2120,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 +2187,7 @@ function readHeaderOnly(path) {
     EMPTY_OW_PIXEL_DATA
   ]);
   try {
-    return naturalize(toArrayBuffer(headerOnly));
+    return parseParts(toArrayBuffer(headerOnly));
   } catch {
     return null;
   }
@@ -2048,7 +2304,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");
 }
@@ -2057,6 +2313,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 +2336,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 +2351,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 +2503,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 +2521,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 +2553,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 +2572,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 +2594,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 +2609,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 +2631,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 +2639,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 +2659,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: {
@@ -2442,16 +2735,16 @@ function loadCaseById(casesJsonPath, id) {
 }
 
 // src/public-fixtures/fetch.ts
-import { createHash as createHash3 } from "node:crypto";
-import { existsSync, mkdirSync as mkdirSync4, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "node:fs";
+import { createHash as createHash2 } from "node:crypto";
+import { existsSync, mkdirSync as mkdirSync3, readFileSync as readFileSync3, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join as join3 } from "node:path";
 var DEFAULT_CACHE_ROOT = join3(homedir(), ".cache", "dicom-synth-testcases");
-function caseCachePath(sha256, root = DEFAULT_CACHE_ROOT) {
-  return join3(root, sha256, "file.dcm");
+function caseCachePath(sha2562, root = DEFAULT_CACHE_ROOT) {
+  return join3(root, sha2562, "file.dcm");
 }
 function verifySha256(buffer, expected) {
-  const h = createHash3("sha256").update(buffer).digest("hex");
+  const h = createHash2("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.`
@@ -2470,7 +2763,7 @@ async function fetchPublicCaseToCache(record, cacheRoot = DEFAULT_CACHE_ROOT) {
     verifySha256(buf2, record.sha256);
     return dest;
   }
-  mkdirSync4(join3(cacheRoot, record.sha256), { recursive: true });
+  mkdirSync3(join3(cacheRoot, record.sha256), { recursive: true });
   const res = await fetch(record.source.url);
   if (!res.ok) {
     throw new Error(
@@ -2479,12 +2772,11 @@ async function fetchPublicCaseToCache(record, cacheRoot = DEFAULT_CACHE_ROOT) {
   }
   const buf = Buffer.from(await res.arrayBuffer());
   verifySha256(buf, record.sha256);
-  writeFileSync2(dest, buf);
+  writeFileSync(dest, buf);
   return dest;
 }
 
 // src/schema/parametric.ts
-import { randomBytes as randomBytes3 } from "node:crypto";
 function sample(next, range) {
   if (typeof range === "number") return range;
   return range.min + next() % (range.max - range.min + 1);
@@ -2503,7 +2795,7 @@ function fraction(next) {
 }
 function resolveParametricSpec(spec) {
   const validated = validateParametricSpec(spec);
-  const seed = validated.seed ?? randomBytes3(4).readUInt32BE(0);
+  const seed = validated.seed ?? randomUint32();
   const next = seededStream(seed, PARAMETRIC_STREAM_OFFSET, 0, 0);
   const params = validated.studies;
   const studies = [];