dicom-synth 1.18.0 → 1.19.0

package/dist/esm/collection/generate.js

@@ -0,0 +1,977 @@
+// 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/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 = [
+  "index",
+  "studyIndex",
+  "seriesIndex",
+  "instanceNumber"
+];
+var TEMPLATE_PART_RE = /\{\{|\}\}|\{([a-zA-Z]+)\}/g;
+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/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 },
+  "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 }
+};
+function isImageType(type) {
+  return TYPE_CAPABILITIES[type].image;
+}
+var HEX_TAG_RE = /^[0-9a-fA-F]{8}$/;
+function isRawTagValue(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) && typeof value.vr === "string";
+}
+function positionalName(prefix, ordinal) {
+  return `${prefix}-${String(ordinal).padStart(3, "0")}`;
+}
+
+// src/loadDcmjs.ts
+import dcmjsDefaultImport, * as dcmjsNamespace from "dcmjs";
+function loadDcmjs() {
+  if (dcmjsNamespace.data?.DicomDict) {
+    return dcmjsNamespace;
+  }
+  const d = dcmjsDefaultImport;
+  if (d?.data?.DicomDict) {
+    return d;
+  }
+  if (d?.default?.data?.DicomDict) {
+    return d.default;
+  }
+  throw new Error(
+    "dcmjs failed to load (missing data.DicomDict). Install dcmjs >= 0.29."
+  );
+}
+var dcmjs = loadDcmjs();
+
+// src/nonStandardDicom/dicomdir.ts
+var DICOMDIR_SOP_CLASS_UID = "1.2.840.10008.1.3.10";
+function buildDicomdirBuffer() {
+  const uid = DICOMDIR_SOP_CLASS_UID;
+  const buf = new Uint8Array(256);
+  const view = new DataView(buf.buffer);
+  buf.set(utf8Bytes("DICM"), 128);
+  let off = 132;
+  view.setUint16(off, 2, true);
+  off += 2;
+  view.setUint16(off, 2, true);
+  off += 2;
+  buf.set(utf8Bytes("UI"), off);
+  off += 2;
+  view.setUint16(off, uid.length, true);
+  off += 2;
+  buf.set(utf8Bytes(uid), off);
+  off += uid.length;
+  return buf.subarray(0, off);
+}
+
+// src/syntheticFixtures/generator.ts
+var MODALITY_PRESETS = {
+  CT: {
+    sopClassUid: "1.2.840.10008.5.1.4.1.1.2",
+    // CT Image Storage
+    attributes: {}
+  },
+  PT: {
+    sopClassUid: "1.2.840.10008.5.1.4.1.1.128",
+    // PET Image Storage
+    attributes: {
+      Units: "BQML",
+      DecayCorrection: "NONE",
+      CorrectedImage: ["ATTN", "DECY"]
+    }
+  },
+  MR: {
+    sopClassUid: "1.2.840.10008.5.1.4.1.1.4",
+    // MR Image Storage
+    attributes: {
+      ScanningSequence: "SE",
+      SequenceVariant: "NONE"
+    }
+  },
+  CR: {
+    sopClassUid: "1.2.840.10008.5.1.4.1.1.1",
+    // CR Image Storage
+    attributes: {}
+  }
+};
+var TRANSFER_SYNTAX_UID = {
+  "explicit-vr-little-endian": "1.2.840.10008.1.2.1",
+  "implicit-vr-little-endian": "1.2.840.10008.1.2"
+};
+function buildTagToKeyword() {
+  const map = /* @__PURE__ */ new Map();
+  const nm = dcmjs.data?.DicomMetaDictionary?.nameMap;
+  if (!nm) return map;
+  for (const [keyword, info] of Object.entries(nm)) {
+    if (info?.tag) {
+      const hex = info.tag.replace(/[(,)]/g, "").toUpperCase();
+      if (hex.length === 8) map.set(hex, keyword);
+    }
+  }
+  return map;
+}
+var tagToKeyword = buildTagToKeyword();
+function toRawElement(raw) {
+  const value = raw.vr === "SQ" ? raw.value.map(
+    (item) => Object.fromEntries(
+      Object.entries(item).map(([tag, nested]) => [
+        tag.toUpperCase(),
+        toRawElement(nested)
+      ])
+    )
+  ) : raw.value;
+  return { vr: raw.vr, Value: Array.isArray(value) ? value : [value] };
+}
+function applyTagOverrides(dataset, tags) {
+  if (!tags) return void 0;
+  let raw;
+  for (const [key, value] of Object.entries(tags)) {
+    if (isRawTagValue(value)) {
+      raw ?? (raw = {});
+      raw[key.toUpperCase()] = toRawElement(value);
+    } else if (HEX_TAG_RE.test(key)) {
+      const keyword = tagToKeyword.get(key.toUpperCase());
+      if (!keyword) {
+        throw new Error(
+          `dicom-synth: unknown hex tag "${key}" \u2014 dictionary tags take plain values; private/unknown tags require the raw { vr, value } form`
+        );
+      }
+      dataset[keyword] = value;
+    } else {
+      dataset[key] = value;
+    }
+  }
+  return raw;
+}
+function rawScalarString(rawElements, tag) {
+  const value = rawElements?.[tag]?.Value;
+  return value?.length === 1 && typeof value[0] === "string" ? value[0] : void 0;
+}
+function syncMetaWithDataset(meta, dataset, rawElements) {
+  const sopInstance = rawScalarString(rawElements, "00080018") ?? (typeof dataset.SOPInstanceUID === "string" ? dataset.SOPInstanceUID : void 0);
+  if (sopInstance !== void 0) {
+    meta.MediaStorageSOPInstanceUID = sopInstance;
+  }
+  const sopClass = rawScalarString(rawElements, "00080016") ?? (typeof dataset.SOPClassUID === "string" ? dataset.SOPClassUID : void 0);
+  if (sopClass !== void 0) {
+    meta.MediaStorageSOPClassUID = sopClass;
+  }
+}
+function buildMeta(uid, modality, transferSyntax = "explicit-vr-little-endian") {
+  return {
+    FileMetaInformationVersion: new Uint8Array([0, 1]).buffer,
+    MediaStorageSOPClassUID: MODALITY_PRESETS[modality].sopClassUid,
+    MediaStorageSOPInstanceUID: uid.sop,
+    TransferSyntaxUID: TRANSFER_SYNTAX_UID[transferSyntax],
+    ImplementationClassUID: "1.2.3.4",
+    ImplementationVersionName: "SYNTH"
+  };
+}
+function buildBaseImageDataset(uid, modality) {
+  const preset = MODALITY_PRESETS[modality];
+  return {
+    PatientName: "SYNTH^SUBJECT",
+    PatientID: "SYNTH_PID",
+    Modality: modality,
+    SOPClassUID: preset.sopClassUid,
+    SOPInstanceUID: uid.sop,
+    SeriesInstanceUID: uid.series,
+    StudyInstanceUID: uid.study,
+    StudyDescription: "Synthetic study",
+    SeriesDescription: "Synthetic series",
+    Rows: 1,
+    Columns: 1,
+    BitsAllocated: 16,
+    BitsStored: 16,
+    HighBit: 15,
+    SamplesPerPixel: 1,
+    PhotometricInterpretation: "MONOCHROME2",
+    PixelRepresentation: 0,
+    PixelData: new Uint8Array([0, 0]).buffer,
+    // Declares PixelData's VR explicitly — without it dcmjs logs
+    // "No value representation given for PixelData" and falls back to OW anyway.
+    _vrMap: { PixelData: "OW" },
+    ...preset.attributes
+  };
+}
+function serializeDict(meta, dataset, rawElements) {
+  const dicomDict = new dcmjs.data.DicomDict(
+    dcmjs.data.DicomMetaDictionary.denaturalizeDataset(
+      meta
+    )
+  );
+  dicomDict.dict = dcmjs.data.DicomMetaDictionary.denaturalizeDataset(
+    dataset
+  );
+  if (rawElements) {
+    Object.assign(dicomDict.dict, rawElements);
+  }
+  return new Uint8Array(dicomDict.write({ allowInvalidVRLength: true }));
+}
+var MAX_DIMENSION = 65535;
+function applySizing(dataset, meta, spec, rawElements) {
+  if (spec.targetSizeKb !== void 0) {
+    const clampDim = (n) => Math.min(MAX_DIMENSION, Math.max(1, Math.round(n)));
+    const minimalPixelBytes = dataset.PixelData.byteLength;
+    const overhead = serializeDict(meta, dataset, rawElements).length - minimalPixelBytes;
+    const cells = Math.max(
+      1,
+      Math.round((spec.targetSizeKb * 1024 - overhead) / 2)
+    );
+    const rows = clampDim(Math.sqrt(cells));
+    const columns = clampDim(cells / rows);
+    dataset.Rows = rows;
+    dataset.Columns = columns;
+    dataset.PixelData = new ArrayBuffer(rows * columns * 2);
+  } else if (spec.rows !== void 0 && spec.columns !== void 0) {
+    dataset.Rows = spec.rows;
+    dataset.Columns = spec.columns;
+    if (spec.frames !== void 0) dataset.NumberOfFrames = spec.frames;
+    dataset.PixelData = new ArrayBuffer(
+      spec.rows * spec.columns * (spec.frames ?? 1) * 2
+    );
+  }
+}
+function buildImageBuffer(spec, uid) {
+  const modality = spec.modality ?? "CT";
+  const effectiveUid = spec.type === "invalid-uid-image" ? {
+    study: `2.25.invalid.study.${uid.study.slice(-6)}`,
+    series: `2.25.invalid.series.${uid.series.slice(-6)}`,
+    sop: `2.25.invalid.sop.${uid.sop.slice(-6)}`
+  } : uid;
+  const dataset = buildBaseImageDataset(effectiveUid, modality);
+  if (spec.type === "vendor-warnings-image") {
+    dataset.Laterality = "";
+    dataset.PatientWeight = "0";
+  }
+  const rawElements = applyTagOverrides(dataset, spec.tags);
+  const meta = buildMeta(effectiveUid, modality, spec.transferSyntax);
+  syncMetaWithDataset(meta, dataset, rawElements);
+  applySizing(dataset, meta, spec, rawElements);
+  return { buffer: serializeDict(meta, dataset, rawElements), rawElements };
+}
+function buildFakeSignatureBuffer() {
+  const buf = new Uint8Array(200);
+  buf.set(utf8Bytes("XXXX"), 128);
+  return buf;
+}
+function sizedNonDicomBytes(spec) {
+  return spec.targetBytes ?? (spec.targetSizeKb !== void 0 ? spec.targetSizeKb * 1024 : void 0);
+}
+function buildNonDicomBuffer(spec) {
+  const bytes = sizedNonDicomBytes(spec);
+  if (bytes !== void 0) return patternBytes(bytes, "not dicom ");
+  return utf8Bytes(spec.content ?? "not dicom");
+}
+function buildBufferForSpec(spec, uid) {
+  switch (spec.type) {
+    case "valid-image":
+    case "invalid-uid-image":
+    case "vendor-warnings-image":
+      return buildImageBuffer(spec, uid);
+    case "fake-signature":
+      return { buffer: buildFakeSignatureBuffer() };
+    case "non-dicom":
+      return { buffer: buildNonDicomBuffer(spec) };
+    case "dicomdir":
+      return { buffer: buildDicomdirBuffer() };
+    case "large-image":
+      throw new Error(
+        "large-image cannot be generated in memory \u2014 use writeCollectionFromSpec (disk-only streaming)"
+      );
+  }
+}
+
+// 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
+function hashUid(salt, key) {
+  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${randomHex(16)}`);
+  return `2.25.${n.toString()}`;
+}
+function seedToSalt(seed) {
+  return seed === void 0 ? void 0 : `seed:${seed}`;
+}
+function makeGroupUidGenerator(salt) {
+  if (salt === void 0) {
+    return { study: () => randomUid(), series: () => randomUid() };
+  }
+  return {
+    study: (studyIndex) => hashUid(salt, `study:${studyIndex}`),
+    series: (studyIndex, seriesIndex) => hashUid(salt, `series:${studyIndex}:${seriesIndex}`)
+  };
+}
+function makeUidGenerator(salt) {
+  if (salt === void 0) {
+    return () => ({ study: randomUid(), series: randomUid(), sop: randomUid() });
+  }
+  return (fileIndex) => ({
+    study: hashUid(salt, `study:flat:${fileIndex}`),
+    series: hashUid(salt, `series:flat:${fileIndex}`),
+    sop: hashUid(salt, `sop:${fileIndex}`)
+  });
+}
+
+// src/syntheticFixtures/violations.ts
+var dcmjsAny = dcmjs;
+function parseBuffer(buffer) {
+  const ab = buffer.buffer.slice(
+    buffer.byteOffset,
+    buffer.byteOffset + buffer.byteLength
+  );
+  return dcmjsAny.data.DicomMessage.readFile(ab);
+}
+function reserialize(parsed) {
+  return new Uint8Array(parsed.write({ allowInvalidVRLength: true }));
+}
+var OVERLONG_UID = `2.25.${"0".repeat(60)}`;
+var VIOLATION_LEVEL = {
+  "uid-too-long": "tag",
+  "non-conformant-uid": "tag",
+  "vr-max-length-exceeded": "tag",
+  "missing-type1-tag": "tag",
+  "missing-meta-header": "byte",
+  "malformed-sq-delimiter": "byte"
+};
+function applyTagLevel(buffer, violations, rawElements) {
+  if (violations.length === 0) return buffer;
+  let parsed;
+  try {
+    parsed = parseBuffer(buffer);
+  } catch {
+    console.warn(
+      "dicom-synth: could not parse buffer for tag-level violations \u2014 skipping"
+    );
+    return buffer;
+  }
+  const natural = dcmjsAny.data.DicomMetaDictionary.naturalizeDataset(
+    parsed.dict
+  );
+  for (const v of violations) {
+    switch (v) {
+      case "uid-too-long":
+        break;
+      case "non-conformant-uid":
+        natural.SOPInstanceUID = "2.25.01.234.567";
+        break;
+      case "vr-max-length-exceeded":
+        natural.StudyDescription = "X".repeat(65);
+        break;
+      case "missing-type1-tag":
+        delete natural.SOPClassUID;
+        break;
+      default:
+        throw new Error(
+          `dicom-synth: unhandled tag-level violation "${v}"`
+        );
+    }
+  }
+  parsed.dict = dcmjsAny.data.DicomMetaDictionary.denaturalizeDataset(natural);
+  if (rawElements) {
+    Object.assign(parsed.dict, rawElements);
+  }
+  if (violations.includes("uid-too-long")) {
+    ;
+    parsed.dict["00080018"] = {
+      vr: "UI",
+      Value: [OVERLONG_UID]
+    };
+  }
+  return reserialize(parsed);
+}
+function applyByteLevel(buffer, violations) {
+  let result = buffer;
+  for (const v of violations) {
+    switch (v) {
+      case "missing-meta-header":
+        result = result.subarray(132);
+        break;
+      case "malformed-sq-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:
+        throw new Error(
+          `dicom-synth: unhandled byte-level violation "${v}"`
+        );
+    }
+  }
+  return result;
+}
+function applyViolations(buffer, violations, rawElements) {
+  if (violations.length === 0) return buffer;
+  const tagViolations = violations.filter((v) => VIOLATION_LEVEL[v] === "tag");
+  const byteViolations = violations.filter((v) => VIOLATION_LEVEL[v] === "byte");
+  return applyByteLevel(
+    applyTagLevel(buffer, tagViolations, rawElements),
+    byteViolations
+  );
+}
+
+// src/collection/generate.ts
+var NO_EXTENSION_TYPES = /* @__PURE__ */ new Set([
+  "fake-signature",
+  "non-dicom"
+]);
+function filename(type, index, padWidth) {
+  const padded = String(index).padStart(padWidth, "0");
+  const base = `${type}-${padded}`;
+  return NO_EXTENSION_TYPES.has(type) ? base : `${base}.dcm`;
+}
+function entryCount(entries) {
+  return entries.reduce((sum, e) => sum + (e.count ?? 1), 0);
+}
+function seriesFileCount(series) {
+  return series.instances ? series.instances.count : entryCount(series.entries ?? []);
+}
+function studyFileCount(studies) {
+  return studies.reduce(
+    (sum, study) => sum + (study.count ?? 1) * study.series.reduce((s, series) => s + seriesFileCount(series), 0),
+    0
+  );
+}
+function isDirNode(node) {
+  return "children" in node;
+}
+function treeFileCount(nodes) {
+  return nodes.reduce(
+    (sum, node) => sum + (isDirNode(node) ? treeFileCount(node.children) : node.count ?? 1),
+    0
+  );
+}
+function* seriesFiles(series) {
+  if (series.instances) {
+    const inst = series.instances;
+    for (let i = 0; i < inst.count; i++) {
+      const modality = Array.isArray(inst.modality) ? inst.modality[i] : inst.modality;
+      const baseSpec = {
+        ...inst.targetBytes ? { type: "large-image", targetBytes: inst.targetBytes[i] } : { type: "valid-image", targetSizeKb: inst.targetSizeKb?.[i] },
+        ...modality !== void 0 ? { modality } : {}
+      };
+      const instanceTags = {};
+      if (inst.tags) {
+        for (const [key, values] of Object.entries(inst.tags)) {
+          instanceTags[key] = values[i];
+        }
+      }
+      yield { baseSpec, instanceTags };
+    }
+    return;
+  }
+  for (const entry of series.entries ?? []) {
+    const { count = 1, tags, ...baseSpec } = entry;
+    for (let i = 0; i < count; i++) {
+      yield { baseSpec, instanceTags: tags ?? {} };
+    }
+  }
+}
+function resolveUid(salt, index, override) {
+  return { ...makeUidGenerator(salt)(index), ...override };
+}
+function effectiveSalt(spec) {
+  return spec.uidSalt ?? seedToSalt(spec.seed);
+}
+async function generateFile(spec, options) {
+  const index = options?.index ?? 0;
+  const padWidth = options?.padWidth ?? 3;
+  const uid = resolveUid(effectiveSalt(options ?? {}), index, options?.uid);
+  const resolvedSpec = "tags" in spec && spec.tags ? {
+    ...spec,
+    tags: resolveTagTemplates(spec.tags, { index, ...options?.context })
+  } : spec;
+  const built = buildBufferForSpec(resolvedSpec, uid);
+  let buffer = built.buffer;
+  const violations = "violations" in spec ? spec.violations : void 0;
+  if (violations?.length) {
+    buffer = applyViolations(buffer, violations, built.rawElements);
+  }
+  const name = filename(spec.type, index, padWidth);
+  return {
+    filename: name,
+    relativePath: name,
+    buffer,
+    type: spec.type,
+    index
+  };
+}
+function hashString(s) {
+  let h = 2166136261;
+  for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return h >>> 0;
+}
+var UNICODE_TOKENS = ["\xE9", "\xFC", "\xF1", "\u65E5", "\u2122", "\u03A9"];
+var NEST_DEPTH = 8;
+var LONG_NAME_TARGET = 200;
+function applyPathQuirks(relativePath, quirks) {
+  const segments = relativePath.split("/");
+  let dirs = segments.slice(0, -1);
+  const leaf = segments[segments.length - 1];
+  const dot = leaf.lastIndexOf(".");
+  let stem = dot > 0 ? leaf.slice(0, dot) : leaf;
+  const ext = dot > 0 ? leaf.slice(dot) : "";
+  const unicode = (s) => `${s}${UNICODE_TOKENS[hashString(s) % UNICODE_TOKENS.length]}`;
+  const has = (q) => quirks.includes(q);
+  if (has("deep-nesting")) {
+    dirs = [...dirs, ...Array.from({ length: NEST_DEPTH }, (_, i) => `d${i}`)];
+  }
+  if (has("unicode")) {
+    dirs = dirs.map(unicode);
+    stem = unicode(stem);
+  }
+  if (has("long-name")) {
+    const pad = (s) => s.length < LONG_NAME_TARGET ? s + "x".repeat(LONG_NAME_TARGET - s.length) : s;
+    stem = pad(stem);
+    if (dirs.length > 0) {
+      const last = dirs.length - 1;
+      dirs = dirs.map((d, i) => i === last ? pad(d) : d);
+    }
+  }
+  let newLeaf = stem + ext;
+  if (has("trailing-dot")) {
+    if (dirs.length > 0) dirs = dirs.map((d) => `${d}.`);
+    else newLeaf += ".";
+  }
+  return { relativePath: [...dirs, newLeaf].join("/"), filename: newLeaf };
+}
+function decorateNames(names, quirks) {
+  return quirks.length === 0 ? names : applyPathQuirks(names.relativePath, quirks);
+}
+function hierarchicalName(studyOrdinal, seriesIndex, instanceNumber) {
+  const pad3 = (n) => String(n).padStart(3, "0");
+  const name = `${String(instanceNumber).padStart(5, "0")}.dcm`;
+  return {
+    filename: name,
+    relativePath: `study-${pad3(studyOrdinal + 1)}/series-${pad3(seriesIndex + 1)}/${name}`
+  };
+}
+function withResolvedSeed(spec) {
+  return spec.seed === void 0 ? { ...spec, seed: randomUint32() } : spec;
+}
+function withResolvedSalt(spec) {
+  return spec.uidSalt === void 0 ? { ...spec, uidSalt: randomHex(16) } : 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 decorateNames(names, quirks);
+}
+function* planTree(nodes, scope, env) {
+  let dirOrdinal = 0;
+  for (const node of nodes) {
+    if (isDirNode(node)) {
+      dirOrdinal++;
+      const dirName = node.name ?? positionalName("dir", dirOrdinal);
+      const child = {
+        ...scope,
+        dirs: [...scope.dirs, dirName],
+        tags: { ...scope.tags, ...node.tags }
+      };
+      if (node.role === "study") {
+        const ordinal = env.counters.study++;
+        child.study = {
+          ordinal,
+          uid: env.groupUids.study(ordinal),
+          seriesCount: 0
+        };
+      } else if (node.role === "series" && child.study) {
+        const index = child.study.seriesCount++;
+        child.series = {
+          index,
+          uid: env.groupUids.series(child.study.ordinal, index),
+          instanceCount: 0
+        };
+      }
+      yield* planTree(node.children, child, env);
+      continue;
+    }
+    const { count = 1, name, ...fileSpec } = node;
+    const image = isImageType(fileSpec.type);
+    for (let i = 0; i < count; i++) {
+      const index = env.counters.file++;
+      const instanceNumber = image && scope.series ? ++scope.series.instanceCount : void 0;
+      const leaf = name ?? filename(fileSpec.type, index, env.padWidth);
+      const names = decorateNames(
+        { filename: leaf, relativePath: [...scope.dirs, leaf].join("/") },
+        env.quirks
+      );
+      const tags = image ? {
+        ...instanceNumber !== void 0 ? { InstanceNumber: instanceNumber } : {},
+        ...scope.tags,
+        ..."tags" in fileSpec ? fileSpec.tags : void 0
+      } : void 0;
+      yield {
+        fileSpec: tags ? { ...fileSpec, tags } : fileSpec,
+        index,
+        ...image && scope.study ? {
+          uidOverride: {
+            study: scope.study.uid,
+            ...scope.series ? { series: scope.series.uid } : {}
+          }
+        } : {},
+        context: {
+          index,
+          ...scope.study ? { studyIndex: scope.study.ordinal } : {},
+          ...scope.series ? { seriesIndex: scope.series.index } : {},
+          ...instanceNumber !== void 0 ? { instanceNumber } : {}
+        },
+        filename: names.filename,
+        relativePath: names.relativePath
+      };
+    }
+  }
+}
+function* planCollection(spec) {
+  const flatEntries = spec.entries ?? [];
+  const studies = spec.studies ?? [];
+  const tree = spec.tree ?? [];
+  const totalFiles = entryCount(flatEntries) + studyFileCount(studies) + treeFileCount(tree);
+  const padWidth = String(totalFiles).length;
+  const hierarchical = spec.layout === "hierarchical";
+  const quirks = spec.pathQuirks ?? [];
+  let globalIndex = 0;
+  for (const entry of flatEntries) {
+    const { count = 1, ...fileSpec } = entry;
+    for (let i = 0; i < count; i++) {
+      yield {
+        fileSpec,
+        index: globalIndex,
+        context: { index: globalIndex },
+        ...computeNames(
+          fileSpec.type,
+          globalIndex,
+          padWidth,
+          void 0,
+          quirks
+        )
+      };
+      globalIndex++;
+    }
+  }
+  const groupUids = makeGroupUidGenerator(effectiveSalt(spec));
+  let studyOrdinal = 0;
+  for (const study of studies) {
+    const copies = study.count ?? 1;
+    for (let copy = 0; copy < copies; copy++) {
+      const studyUid = groupUids.study(studyOrdinal);
+      for (const [seriesIndex, series] of study.series.entries()) {
+        const seriesUid = groupUids.series(studyOrdinal, seriesIndex);
+        let instanceNumber = 0;
+        for (const { baseSpec, instanceTags } of seriesFiles(series)) {
+          instanceNumber++;
+          const tags = {
+            InstanceNumber: instanceNumber,
+            ...study.tags,
+            ...series.tags,
+            ...instanceTags
+          };
+          yield {
+            fileSpec: { ...baseSpec, tags },
+            index: globalIndex,
+            uidOverride: { study: studyUid, series: seriesUid },
+            context: {
+              index: globalIndex,
+              studyIndex: studyOrdinal,
+              seriesIndex,
+              instanceNumber
+            },
+            ...computeNames(
+              baseSpec.type,
+              globalIndex,
+              padWidth,
+              hierarchical ? { studyOrdinal, seriesIndex, instanceNumber } : void 0,
+              quirks
+            )
+          };
+          globalIndex++;
+        }
+      }
+      studyOrdinal++;
+    }
+  }
+  if (tree.length > 0) {
+    yield* planTree(
+      tree,
+      { dirs: [], tags: {} },
+      {
+        groupUids,
+        padWidth,
+        quirks,
+        counters: { file: globalIndex, study: studyOrdinal }
+      }
+    );
+  }
+}
+async function materialisePlan(plan, salt) {
+  const file = await generateFile(plan.fileSpec, {
+    index: plan.index,
+    uidSalt: salt,
+    uid: plan.uidOverride,
+    context: plan.context
+  });
+  return { ...file, filename: plan.filename, relativePath: plan.relativePath };
+}
+async function* generateCollectionFromSpec(spec) {
+  const salt = effectiveSalt(spec);
+  for (const plan of planCollection(spec)) {
+    yield await materialisePlan(plan, salt);
+  }
+}
+async function* previewCollection(spec) {
+  const salt = effectiveSalt(spec);
+  for (const plan of planCollection(spec)) {
+    const knownBytes = plan.fileSpec.type === "large-image" ? plan.fileSpec.targetBytes : plan.fileSpec.type === "non-dicom" ? sizedNonDicomBytes(plan.fileSpec) : void 0;
+    if (knownBytes !== void 0) {
+      yield {
+        relativePath: plan.relativePath,
+        type: plan.fileSpec.type,
+        index: plan.index,
+        approxBytes: knownBytes
+      };
+    } else {
+      const file = await materialisePlan(plan, salt);
+      yield {
+        relativePath: plan.relativePath,
+        type: plan.fileSpec.type,
+        index: plan.index,
+        approxBytes: file.buffer.length
+      };
+    }
+  }
+}
+export {
+  effectiveSalt,
+  generateCollectionFromSpec,
+  generateFile,
+  materialisePlan,
+  planCollection,
+  previewCollection,
+  resolveUid,
+  withResolvedSalt,
+  withResolvedSeed
+};