dicom-synth 1.8.0 → 1.10.0

package/dist/esm/index.js

@@ -1,8 +1,12 @@
 // src/collection/writer.ts
 import { randomBytes as randomBytes2 } from "node:crypto";
-import { mkdirSync as mkdirSync2 } from "node:fs";
+import { mkdirSync as mkdirSync3 } from "node:fs";
 import { writeFile } from "node:fs/promises";
-import { dirname, resolve as resolve2 } from "node:path";
+import { dirname, resolve as resolve3 } from "node:path";
+
+// src/schema/limits.ts
+var MAX_PIXEL_BYTES = 512 * 1024 * 1024;
+var MAX_STREAM_BYTES = 50 * 1024 * 1024 * 1024;
 
 // src/loadDcmjs.ts
 import dcmjsDefaultImport, * as dcmjsNamespace from "dcmjs";
@@ -45,11 +49,56 @@ function buildDicomdirBuffer() {
   return buf.subarray(0, off);
 }
 
+// src/syntheticFixtures/tagTemplate.ts
+var TEMPLATE_VOCAB = [
+  "index",
+  "studyIndex",
+  "seriesIndex",
+  "instanceNumber"
+];
+var TEMPLATE_PART_RE = /\{\{|\}\}|\{([a-zA-Z]+)\}/g;
+function escapeTagTemplate(value) {
+  return value.replace(/\{/g, "{{").replace(/\}/g, "}}");
+}
+function findTemplateTokens(value) {
+  const names = [];
+  for (const m of value.matchAll(TEMPLATE_PART_RE)) {
+    if (m[1] !== void 0) names.push(m[1]);
+  }
+  return names;
+}
+function resolveTagTemplates(tags, context) {
+  if (!tags) return tags;
+  const resolved = {};
+  for (const [key, value] of Object.entries(tags)) {
+    resolved[key] = typeof value === "string" ? resolveString(value, context) : value;
+  }
+  return resolved;
+}
+function resolveString(value, context) {
+  return value.replace(TEMPLATE_PART_RE, (match, name) => {
+    if (name === void 0) return match === "{{" ? "{" : "}";
+    if (!TEMPLATE_VOCAB.includes(name)) {
+      throw new Error(
+        `tag template: unknown placeholder "{${name}}" \u2014 allowed: ${TEMPLATE_VOCAB.map((v) => `{${v}}`).join(", ")}`
+      );
+    }
+    const resolved = context[name];
+    if (resolved === void 0) {
+      throw new Error(
+        `tag template: placeholder "{${name}}" is not available here \u2014 it only applies inside grouped studies`
+      );
+    }
+    return String(resolved);
+  });
+}
+
 // src/schema/validate.ts
 var TYPE_CAPABILITIES = {
   "valid-image": { image: true },
   "invalid-uid-image": { image: true },
   "vendor-warnings-image": { image: true },
+  "large-image": { image: true },
   "fake-signature": { image: false },
   "non-dicom": { image: false },
   dicomdir: { image: false }
@@ -74,7 +123,6 @@ var VALID_TRANSFER_SYNTAXES = {
   "explicit-vr-little-endian": true,
   "implicit-vr-little-endian": true
 };
-var MAX_PIXEL_BYTES = 512 * 1024 * 1024;
 var VALID_VIOLATIONS = {
   "uid-too-long": true,
   "non-conformant-uid": true,
@@ -92,6 +140,13 @@ function validatePositiveInt(value, path) {
     );
   }
 }
+function validateNonNegativeInt(value, path) {
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
+    throw new Error(
+      `${path}: must be a non-negative integer; got ${JSON.stringify(value)}`
+    );
+  }
+}
 function validateSeed(value, path) {
   if (typeof value !== "number" || !Number.isFinite(value)) {
     throw new Error(
@@ -104,6 +159,43 @@ function validateSizeKbLimit(kb, path) {
     throw new Error(`${path}: exceeds the 512 MB limit`);
   }
 }
+function validateLargeTargetBytes(value, path) {
+  if (typeof value !== "number" || !Number.isInteger(value)) {
+    throw new Error(`${path}: must be an integer; got ${JSON.stringify(value)}`);
+  }
+  if (value <= MAX_PIXEL_BYTES) {
+    throw new Error(
+      `${path}: must exceed 512 MB \u2014 use targetSizeKb for smaller files`
+    );
+  }
+  if (value > MAX_STREAM_BYTES) {
+    throw new Error(`${path}: exceeds the 50 GB limit`);
+  }
+}
+function validateLargeImageEntry(e, path) {
+  for (const field of [
+    "rows",
+    "columns",
+    "frames",
+    "targetSizeKb",
+    "violations",
+    "transferSyntax"
+  ]) {
+    if (field in e) {
+      throw new Error(
+        `${path}.${field}: not supported for type "large-image" \u2014 use targetBytes`
+      );
+    }
+  }
+  if (!("targetBytes" in e)) {
+    throw new Error(`${path}.targetBytes: is required for type "large-image"`);
+  }
+  validateLargeTargetBytes(e.targetBytes, `${path}.targetBytes`);
+  if ("modality" in e) {
+    validateEnum(e.modality, VALID_MODALITIES, `${path}.modality`);
+  }
+  if ("tags" in e) validateTags(e.tags, `${path}.tags`);
+}
 function validateEnum(value, valid, path) {
   if (typeof value !== "string" || !Object.hasOwn(valid, value)) {
     throw new Error(
@@ -127,6 +219,15 @@ function validateEntry(entry, path) {
   const type = e.type;
   const caps = TYPE_CAPABILITIES[type];
   if ("count" in e) validatePositiveInt(e.count, `${path}.count`);
+  if (type === "large-image") {
+    validateLargeImageEntry(e, path);
+    return e;
+  }
+  if ("targetBytes" in e) {
+    throw new Error(
+      `${path}.targetBytes: only supported for type "large-image"`
+    );
+  }
   for (const field of [
     "modality",
     "rows",
@@ -186,12 +287,28 @@ function validateEntry(entry, path) {
   }
   return e;
 }
+var MODALITY_TAG = "00080060";
 function validateTags(tags, path) {
   if (typeof tags !== "object" || tags === null || Array.isArray(tags)) {
     throw new Error(`${path}: must be an object`);
   }
-  for (const key of Object.keys(tags)) {
+  for (const [key, value] of Object.entries(tags)) {
     validateTagKey(key, path);
+    const isModalityKey = key === "Modality" || key.toUpperCase() === MODALITY_TAG;
+    if (isModalityKey && typeof value === "string" && Object.hasOwn(VALID_MODALITIES, value)) {
+      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`
+      );
+    }
+    if (typeof value === "string") {
+      for (const name of findTemplateTokens(value)) {
+        if (!TEMPLATE_VOCAB.includes(name)) {
+          throw new Error(
+            `${path}.${key}: unknown placeholder "{${name}}" \u2014 allowed: ${TEMPLATE_VOCAB.map((v) => `{${v}}`).join(", ")}`
+          );
+        }
+      }
+    }
   }
 }
 function validateSeries(series, path) {
@@ -272,19 +389,20 @@ function validateDatasetSpec(raw) {
     ...r.pathQuirks !== void 0 ? { pathQuirks: r.pathQuirks } : {}
   };
 }
-function validateRange(value, path) {
+function validateRange(value, path, options = {}) {
+  const checkInt = options.allowZero ? validateNonNegativeInt : validatePositiveInt;
   if (typeof value === "number") {
-    validatePositiveInt(value, path);
+    checkInt(value, path);
     return value;
   }
   if (typeof value !== "object" || value === null || Array.isArray(value)) {
     throw new Error(
-      `${path}: must be a positive integer or { min, max }; got ${JSON.stringify(value)}`
+      `${path}: must be an integer or { min, max }; got ${JSON.stringify(value)}`
     );
   }
   const r = value;
-  validatePositiveInt(r.min, `${path}.min`);
-  validatePositiveInt(r.max, `${path}.max`);
+  checkInt(r.min, `${path}.min`);
+  checkInt(r.max, `${path}.max`);
   if (r.min > r.max) {
     throw new Error(`${path}: min (${r.min}) must be \u2264 max (${r.max})`);
   }
@@ -293,6 +411,9 @@ function validateRange(value, path) {
 function rangeMax(range) {
   return typeof range === "number" ? range : range.max;
 }
+function rangeMin(range) {
+  return typeof range === "number" ? range : range.min;
+}
 function validateParametricStudies(studies, path) {
   if (typeof studies !== "object" || studies === null || Array.isArray(studies)) {
     throw new Error(`${path}: must be an object`);
@@ -306,6 +427,32 @@ function validateParametricStudies(studies, path) {
     validateRange(s.fileSizeKb, `${path}.fileSizeKb`);
     validateSizeKbLimit(rangeMax(s.fileSizeKb), `${path}.fileSizeKb`);
   }
+  if ("largeFilesPerSeries" in s) {
+    validateRange(s.largeFilesPerSeries, `${path}.largeFilesPerSeries`, {
+      allowZero: true
+    });
+    if (!("largeFileBytes" in s)) {
+      throw new Error(
+        `${path}.largeFileBytes: is required when largeFilesPerSeries is set`
+      );
+    }
+  }
+  if ("largeFileBytes" in s) {
+    if (!("largeFilesPerSeries" in s)) {
+      throw new Error(
+        `${path}.largeFilesPerSeries: is required when largeFileBytes is set`
+      );
+    }
+    validateRange(s.largeFileBytes, `${path}.largeFileBytes`);
+    validateLargeTargetBytes(
+      rangeMin(s.largeFileBytes),
+      `${path}.largeFileBytes (min)`
+    );
+    validateLargeTargetBytes(
+      rangeMax(s.largeFileBytes),
+      `${path}.largeFileBytes (max)`
+    );
+  }
   if ("modalities" in s) {
     if (!Array.isArray(s.modalities) || s.modalities.length === 0) {
       throw new Error(`${path}.modalities: must be a non-empty array`);
@@ -535,9 +682,17 @@ function buildBufferForSpec(spec, uid) {
       return buildNonDicomBuffer(spec.content);
     case "dicomdir":
       return buildDicomdirBuffer();
+    case "large-image":
+      throw new Error(
+        "large-image cannot be generated in memory \u2014 use writeCollectionFromSpec (disk-only streaming)"
+      );
   }
 }
 
+// src/syntheticFixtures/streamWrite.ts
+import { closeSync, mkdirSync as mkdirSync2, openSync, writeSync } from "node:fs";
+import { resolve as resolve2 } from "node:path";
+
 // src/syntheticFixtures/uid.ts
 import { randomBytes } from "node:crypto";
 var ROLE_CODE = { study: 1, series: 2, sop: 3 };
@@ -604,6 +759,173 @@ function makeUidGenerator(seed) {
   };
 }
 
+// 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);
+  applyTagOverrides(dataset, tags);
+  dataset.Rows = dims.rows;
+  dataset.Columns = dims.columns;
+  const minimalPixelBytes = dataset.PixelData.byteLength;
+  const probe = serializeDict(meta, dataset);
+  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);
+  applyTagOverrides(dataset, tags);
+  dataset.PixelData = [new Uint8Array([]).buffer, new Uint8Array([0, 0]).buffer];
+  dataset._vrMap = { PixelData: "OB" };
+  const probe = serializeDict(meta, dataset);
+  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.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,
+    seed: spec.seed,
+    chunkBytes: options.chunkBytes
+  });
+}
+
 // src/syntheticFixtures/violations.ts
 var dcmjsAny = dcmjs;
 function parseBuffer(buffer) {
@@ -717,12 +1039,18 @@ function studyFileCount(studies) {
     0
   );
 }
+function resolveUid(seed, index, override) {
+  return { ...makeUidGenerator(seed)(index), ...override };
+}
 async function generateFile(spec, options) {
   const index = options?.index ?? 0;
   const padWidth = options?.padWidth ?? 3;
-  const uidGen = makeUidGenerator(options?.seed);
-  const uid = { ...uidGen(index), ...options?.uid };
-  let buffer = buildBufferForSpec(spec, uid);
+  const uid = resolveUid(options?.seed, index, options?.uid);
+  const resolvedSpec = "tags" in spec && spec.tags ? {
+    ...spec,
+    tags: resolveTagTemplates(spec.tags, { index, ...options?.context })
+  } : spec;
+  let buffer = buildBufferForSpec(resolvedSpec, uid);
   const violations = "violations" in spec ? spec.violations : void 0;
   if (violations?.length) {
     buffer = applyViolations(buffer, violations);
@@ -789,25 +1117,43 @@ function hierarchicalName(studyOrdinal, seriesIndex, instanceNumber) {
 function withResolvedSeed(spec) {
   return spec.seed === void 0 ? { ...spec, seed: randomBytes2(4).readUInt32BE(0) } : spec;
 }
-async function* generateCollectionFromSpec(spec) {
+function computeNames(type, index, padWidth, grouped, quirks) {
+  let names;
+  if (grouped) {
+    names = hierarchicalName(
+      grouped.studyOrdinal,
+      grouped.seriesIndex,
+      grouped.instanceNumber
+    );
+  } else {
+    const name = filename(type, index, padWidth);
+    names = { filename: name, relativePath: name };
+  }
+  return quirks.length === 0 ? names : applyPathQuirks(names.relativePath, quirks);
+}
+function* planCollection(spec) {
   const flatEntries = spec.entries ?? [];
   const studies = spec.studies ?? [];
   const totalFiles = entryCount(flatEntries) + studyFileCount(studies);
   const padWidth = String(totalFiles).length;
   const hierarchical = spec.layout === "hierarchical";
   const quirks = spec.pathQuirks ?? [];
-  const decorate = (file) => quirks.length === 0 ? file : { ...file, ...applyPathQuirks(file.relativePath, quirks) };
   let globalIndex = 0;
   for (const entry of flatEntries) {
     const { count = 1, ...fileSpec } = entry;
     for (let i = 0; i < count; i++) {
-      yield decorate(
-        await generateFile(fileSpec, {
-          index: globalIndex,
-          seed: spec.seed,
-          padWidth
-        })
-      );
+      yield {
+        fileSpec,
+        index: globalIndex,
+        context: { index: globalIndex },
+        ...computeNames(
+          fileSpec.type,
+          globalIndex,
+          padWidth,
+          void 0,
+          quirks
+        )
+      };
       globalIndex++;
     }
   }
@@ -830,25 +1176,24 @@ async function* generateCollectionFromSpec(spec) {
               ...series.tags,
               ...fileSpec.tags
             };
-            const file = await generateFile(
-              { ...fileSpec, tags },
-              {
+            yield {
+              fileSpec: { ...fileSpec, tags },
+              index: globalIndex,
+              uidOverride: { study: studyUid, series: seriesUid },
+              context: {
                 index: globalIndex,
-                seed: spec.seed,
+                studyIndex: studyOrdinal,
+                seriesIndex,
+                instanceNumber
+              },
+              ...computeNames(
+                fileSpec.type,
+                globalIndex,
                 padWidth,
-                uid: { study: studyUid, series: seriesUid }
-              }
-            );
-            yield decorate(
-              hierarchical ? {
-                ...file,
-                ...hierarchicalName(
-                  studyOrdinal,
-                  seriesIndex,
-                  instanceNumber
-                )
-              } : file
-            );
+                hierarchical ? { studyOrdinal, seriesIndex, instanceNumber } : void 0,
+                quirks
+              )
+            };
             globalIndex++;
           }
         }
@@ -857,30 +1202,102 @@ async function* generateCollectionFromSpec(spec) {
     }
   }
 }
+async function materialisePlan(plan, seed) {
+  const file = await generateFile(plan.fileSpec, {
+    index: plan.index,
+    seed,
+    uid: plan.uidOverride,
+    context: plan.context
+  });
+  return { ...file, filename: plan.filename, relativePath: plan.relativePath };
+}
+async function* generateCollectionFromSpec(spec) {
+  for (const plan of planCollection(spec)) {
+    yield await materialisePlan(plan, spec.seed);
+  }
+}
+async function* previewCollection(spec) {
+  for (const plan of planCollection(spec)) {
+    if (plan.fileSpec.type === "large-image") {
+      yield {
+        relativePath: plan.relativePath,
+        type: "large-image",
+        index: plan.index,
+        approxBytes: plan.fileSpec.targetBytes
+      };
+    } else {
+      const file = await materialisePlan(plan, spec.seed);
+      yield {
+        relativePath: plan.relativePath,
+        type: plan.fileSpec.type,
+        index: plan.index,
+        approxBytes: file.buffer.length
+      };
+    }
+  }
+}
 async function writeCollectionFromSpec(spec, outDir) {
-  const root = resolve2(outDir);
-  mkdirSync2(root, { recursive: true });
+  const root = resolve3(outDir);
+  mkdirSync3(root, { recursive: true });
   const manifest = [];
   const createdDirs = /* @__PURE__ */ new Set([root]);
-  for await (const file of generateCollectionFromSpec(spec)) {
-    const filePath = resolve2(root, file.relativePath);
+  const ensureDir = (filePath) => {
     const dir = dirname(filePath);
     if (!createdDirs.has(dir)) {
-      mkdirSync2(dir, { recursive: true });
+      mkdirSync3(dir, { recursive: true });
       createdDirs.add(dir);
     }
-    await writeFile(filePath, file.buffer);
-    manifest.push({ path: filePath, type: file.type, index: file.index });
+  };
+  for (const plan of planCollection(spec)) {
+    const filePath = resolve3(root, plan.relativePath);
+    ensureDir(filePath);
+    if (plan.fileSpec.type === "large-image") {
+      const large = plan.fileSpec;
+      if (large.targetBytes > MAX_STREAM_BYTES) {
+        throw new Error(
+          `large-image targetBytes (${large.targetBytes}) exceeds the 50 GB limit`
+        );
+      }
+      const uid = resolveUid(spec.seed, plan.index, plan.uidOverride);
+      streamLargeImage(filePath, {
+        targetBytes: large.targetBytes,
+        modality: large.modality,
+        uid,
+        tags: resolveTagTemplates(large.tags, plan.context)
+      });
+    } else {
+      const file = await materialisePlan(plan, spec.seed);
+      await writeFile(filePath, file.buffer);
+    }
+    manifest.push({
+      path: filePath,
+      type: plan.fileSpec.type,
+      index: plan.index
+    });
   }
   return manifest;
 }
 
 // src/describe/describe.ts
-import { readdirSync, readFileSync } from "node:fs";
+import {
+  closeSync as closeSync2,
+  openSync as openSync2,
+  readdirSync,
+  readFileSync,
+  readSync,
+  statSync
+} from "node:fs";
 import { join } from "node:path";
 var dcmjsAny2 = dcmjs;
 var HEX_TAG_RE2 = /^[0-9a-fA-F]{8}$/;
 var SUPPORTED_MODALITIES = /* @__PURE__ */ new Set(["CT", "PT", "MR", "CR"]);
+var RESERVED_KEEP_KEYWORDS = /* @__PURE__ */ new Set([
+  "Units",
+  "DecayCorrection",
+  "CorrectedImage",
+  "ScanningSequence",
+  "SequenceVariant"
+]);
 function buildHexToKeyword() {
   const map = /* @__PURE__ */ new Map();
   const nm = dcmjsAny2.data.DicomMetaDictionary.nameMap;
@@ -896,20 +1313,37 @@ function buildHexToKeyword() {
 function resolveKeepTags(keepTags) {
   const nameMap = dcmjsAny2.data.DicomMetaDictionary.nameMap;
   let hexToKeyword;
-  return keepTags.map((tag) => {
+  const kept = [];
+  for (const tag of keepTags) {
+    let keyword;
     if (HEX_TAG_RE2.test(tag)) {
       hexToKeyword ?? (hexToKeyword = buildHexToKeyword());
-      const keyword = hexToKeyword.get(tag.toUpperCase());
-      if (!keyword) {
+      const mapped = hexToKeyword.get(tag.toUpperCase());
+      if (!mapped) {
         throw new Error(`describe: unknown hex tag "${tag}"`);
       }
-      return keyword;
+      keyword = mapped;
+    } else {
+      if (nameMap && !Object.hasOwn(nameMap, tag)) {
+        throw new Error(`describe: unknown tag keyword "${tag}"`);
+      }
+      keyword = tag;
     }
-    if (nameMap && !Object.hasOwn(nameMap, tag)) {
-      throw new Error(`describe: unknown tag keyword "${tag}"`);
+    if (RESERVED_KEEP_KEYWORDS.has(keyword)) {
+      console.warn(
+        `describe: ignoring keep-tag "${keyword}" \u2014 modality-coupled tags are reproduced from the modality field`
+      );
+      continue;
     }
-    return tag;
-  });
+    if (nameMap?.[keyword]?.vr === "UI") {
+      console.warn(
+        `describe: ignoring keep-tag "${keyword}" \u2014 UID-valued tags are not kept verbatim`
+      );
+      continue;
+    }
+    kept.push(keyword);
+  }
+  return kept;
 }
 function* walkFiles(dir) {
   for (const entry of readdirSync(dir, { withFileTypes: true })) {
@@ -921,18 +1355,77 @@ function* walkFiles(dir) {
     }
   }
 }
-function parseFile(path) {
+function toArrayBuffer(buf) {
+  return buf.buffer.slice(
+    buf.byteOffset,
+    buf.byteOffset + buf.byteLength
+  );
+}
+function naturalize(ab) {
+  const parsed = dcmjsAny2.data.DicomMessage.readFile(ab);
+  return dcmjsAny2.data.DicomMetaDictionary.naturalizeDataset(parsed.dict);
+}
+function parseFull(path) {
   try {
-    const buf = readFileSync(path);
-    const ab = buf.buffer.slice(
-      buf.byteOffset,
-      buf.byteOffset + buf.byteLength
-    );
-    const parsed = dcmjsAny2.data.DicomMessage.readFile(ab);
-    const record = dcmjsAny2.data.DicomMetaDictionary.naturalizeDataset(
-      parsed.dict
-    );
-    return { record, size: buf.byteLength };
+    return naturalize(toArrayBuffer(readFileSync(path)));
+  } catch {
+    return null;
+  }
+}
+var PIXEL_DATA_OW = Buffer.from([224, 127, 16, 0, 79, 87]);
+var PIXEL_DATA_OB = Buffer.from([224, 127, 16, 0, 79, 66]);
+var EMPTY_OW_PIXEL_DATA = Buffer.from([
+  224,
+  127,
+  16,
+  0,
+  79,
+  87,
+  0,
+  0,
+  0,
+  0,
+  0,
+  0
+]);
+var HEADER_READ_BYTES = 2 * 1024 * 1024;
+function findPixelDataOffset(prefix) {
+  let best = -1;
+  for (const pattern of [PIXEL_DATA_OW, PIXEL_DATA_OB]) {
+    for (let from = 0; ; ) {
+      const i = prefix.indexOf(pattern, from);
+      if (i < 0) break;
+      if (prefix[i + 6] === 0 && prefix[i + 7] === 0) {
+        if (best < 0 || i < best) best = i;
+        break;
+      }
+      from = i + 1;
+    }
+  }
+  return best;
+}
+function readHeaderOnly(path) {
+  let prefix;
+  try {
+    const fd = openSync2(path, "r");
+    try {
+      const buf = Buffer.alloc(HEADER_READ_BYTES);
+      const n = readSync(fd, buf, 0, HEADER_READ_BYTES, 0);
+      prefix = buf.subarray(0, n);
+    } finally {
+      closeSync2(fd);
+    }
+  } catch {
+    return null;
+  }
+  const tagIdx = findPixelDataOffset(prefix);
+  if (tagIdx < 0) return null;
+  const headerOnly = Buffer.concat([
+    prefix.subarray(0, tagIdx),
+    EMPTY_OW_PIXEL_DATA
+  ]);
+  try {
+    return naturalize(toArrayBuffer(headerOnly));
   } catch {
     return null;
   }
@@ -942,10 +1435,12 @@ function extractTags(record, keepKeywords) {
   let found = false;
   for (const keyword of keepKeywords) {
     const value = record[keyword];
-    if (value !== void 0) {
-      tags[keyword] = value;
-      found = true;
+    if (value === void 0) continue;
+    if (keyword === "Modality" && typeof value === "string" && SUPPORTED_MODALITIES.has(value)) {
+      continue;
     }
+    tags[keyword] = typeof value === "string" ? escapeTagTemplate(value) : value;
+    found = true;
   }
   return found ? tags : void 0;
 }
@@ -954,14 +1449,25 @@ function describeDirectory(dir, options = {}) {
   const studies = /* @__PURE__ */ new Map();
   const stats = { dicomFiles: 0, skipped: 0, unknownModality: 0 };
   for (const path of [...walkFiles(dir)].sort()) {
-    const parsed = parseFile(path);
-    const studyUid = parsed?.record.StudyInstanceUID;
-    const seriesUid = parsed?.record.SeriesInstanceUID;
-    if (!parsed || typeof studyUid !== "string" || typeof seriesUid !== "string") {
+    let size;
+    try {
+      size = statSync(path).size;
+    } catch {
+      stats.skipped++;
+      continue;
+    }
+    if (size > MAX_STREAM_BYTES) {
+      stats.skipped++;
+      continue;
+    }
+    const large = size > MAX_PIXEL_BYTES;
+    const record = large ? readHeaderOnly(path) : parseFull(path);
+    const studyUid = record?.StudyInstanceUID;
+    const seriesUid = record?.SeriesInstanceUID;
+    if (!record || typeof studyUid !== "string" || typeof seriesUid !== "string") {
       stats.skipped++;
       continue;
     }
-    const { record } = parsed;
     stats.dicomFiles++;
     let modality;
     if (typeof record.Modality === "string") {
@@ -971,7 +1477,7 @@ function describeDirectory(dir, options = {}) {
         stats.unknownModality++;
       }
     }
-    const sizeKb = Math.max(1, Math.round(parsed.size / 1024));
+    const sizeKb = Math.max(1, Math.round(size / 1024));
     const tags = keepKeywords.length ? extractTags(record, keepKeywords) : void 0;
     let study = studies.get(studyUid);
     if (!study) {
@@ -983,25 +1489,27 @@ function describeDirectory(dir, options = {}) {
       series = /* @__PURE__ */ new Map();
       study.set(seriesUid, series);
     }
-    const collapseKey = JSON.stringify([modality ?? null, sizeKb, tags ?? null]);
+    const collapseKey = JSON.stringify([
+      large,
+      modality ?? null,
+      large ? size : sizeKb,
+      tags ?? null
+    ]);
     const existing = series.get(collapseKey);
     if (existing) {
       existing.count++;
     } else {
-      series.set(collapseKey, {
-        modality,
-        targetSizeKb: sizeKb,
-        tags,
-        count: 1
-      });
+      series.set(collapseKey, { modality, large, bytes: size, tags, count: 1 });
     }
   }
   const studySpecs = [...studies.values()].map((study) => {
     const seriesSpecs = [...study.values()].map((series) => {
       const entries = [...series.values()].map((acc) => ({
-        type: "valid-image",
         ...acc.modality !== void 0 ? { modality: acc.modality } : {},
-        targetSizeKb: acc.targetSizeKb,
+        ...acc.large ? { type: "large-image", targetBytes: acc.bytes } : {
+          type: "valid-image",
+          targetSizeKb: Math.max(1, Math.round(acc.bytes / 1024))
+        },
         ...acc.tags !== void 0 ? { tags: acc.tags } : {},
         ...acc.count > 1 ? { count: acc.count } : {}
       }));
@@ -1050,7 +1558,7 @@ function loadCaseById(casesJsonPath, id) {
 
 // src/public-fixtures/fetch.ts
 import { createHash } from "node:crypto";
-import { existsSync, mkdirSync as mkdirSync3, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "node:fs";
+import { existsSync, mkdirSync as mkdirSync4, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } 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");
@@ -1077,7 +1585,7 @@ async function fetchPublicCaseToCache(record, cacheRoot = DEFAULT_CACHE_ROOT) {
     verifySha256(buf2, record.sha256);
     return dest;
   }
-  mkdirSync3(join3(cacheRoot, record.sha256), { recursive: true });
+  mkdirSync4(join3(cacheRoot, record.sha256), { recursive: true });
   const res = await fetch(record.source.url);
   if (!res.ok) {
     throw new Error(
@@ -1096,6 +1604,12 @@ function sample(next, range) {
   if (typeof range === "number") return range;
   return range.min + next() % (range.max - range.min + 1);
 }
+var BYTES_PER_MB = 1024 * 1024;
+function sampleBytes(next, range) {
+  if (typeof range === "number") return range;
+  const spanMb = Math.floor((range.max - range.min) / BYTES_PER_MB) + 1;
+  return range.min + next() % spanMb * BYTES_PER_MB;
+}
 function pick(next, items) {
   return items[next() % items.length];
 }
@@ -1136,6 +1650,30 @@ function resolveParametricSpec(spec) {
           ...fileCount > 1 ? { count: fileCount } : {}
         });
       }
+      if (params.largeFilesPerSeries !== void 0 && params.largeFileBytes !== void 0) {
+        const largeCount = sample(next, params.largeFilesPerSeries);
+        const largeBase = {
+          type: "large-image",
+          targetBytes: 0,
+          ...modality !== void 0 ? { modality } : {}
+        };
+        if (typeof params.largeFileBytes === "number") {
+          if (largeCount > 0) {
+            entries2.push({
+              ...largeBase,
+              targetBytes: params.largeFileBytes,
+              ...largeCount > 1 ? { count: largeCount } : {}
+            });
+          }
+        } else {
+          for (let lf = 0; lf < largeCount; lf++) {
+            entries2.push({
+              ...largeBase,
+              targetBytes: sampleBytes(next, params.largeFileBytes)
+            });
+          }
+        }
+      }
       series.push({ entries: entries2 });
     }
     studies.push({
@@ -1164,6 +1702,9 @@ function resolveParametricSpec(spec) {
   };
 }
 export {
+  MAX_PIXEL_BYTES,
+  MAX_STREAM_BYTES,
+  TEMPLATE_VOCAB,
   caseCachePath,
   defaultPublicCasesPath,
   describeDirectory,
@@ -1173,10 +1714,14 @@ export {
   loadCaseById,
   loadCasesFromJson,
   loadDefaultCases,
+  previewCollection,
   resolveParametricSpec,
+  resolveTagTemplates,
+  streamLargeImage,
   validateDatasetSpec,
   validateParametricSpec,
   verifySha256,
   withResolvedSeed,
-  writeCollectionFromSpec
+  writeCollectionFromSpec,
+  writeLargeImageFile
 };