dicom-synth 1.0.1 → 1.2.0

package/dist/esm/index.js

@@ -1,20 +1,30 @@
-// src/negativeCases/index.ts
-import { mkdirSync, writeFileSync } from "node:fs";
-import { resolve } from "node:path";
-function writeFakeDicomSignatureFile(filePath) {
-  const buf = Buffer.alloc(200, 0);
-  buf.write("XXXX", 128, 4, "ascii");
-  mkdirSync(resolve(filePath, ".."), { recursive: true });
-  writeFileSync(filePath, buf);
-}
-function writeNonDicomFile(filePath, content = "not dicom") {
-  mkdirSync(resolve(filePath, ".."), { recursive: true });
-  writeFileSync(filePath, content);
+// 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/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
-import { mkdirSync as mkdirSync2, writeFileSync as writeFileSync2 } from "node:fs";
-import { resolve as resolve2 } from "node:path";
+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;
@@ -33,17 +43,631 @@ function buildDicomdirBuffer() {
   off += uid.length;
   return buf.subarray(0, off);
 }
-function writeDicomdirFile(filePath) {
-  mkdirSync2(resolve2(filePath, ".."), { recursive: true });
-  writeFileSync2(filePath, buildDicomdirBuffer());
+
+// src/schema/validate.ts
+var TYPE_CAPABILITIES = {
+  "valid-ct": { tags: true, violations: true, transferSyntax: true },
+  "invalid-uid-ct": { tags: true, violations: true, transferSyntax: true },
+  "vendor-warnings-ct": { tags: true, violations: true, transferSyntax: true },
+  "large-ct": { tags: true, violations: true, transferSyntax: true },
+  "fake-signature": { tags: false, violations: false, transferSyntax: false },
+  "non-dicom": { tags: false, violations: false, transferSyntax: false },
+  dicomdir: { tags: false, violations: false, transferSyntax: false }
+};
+var VALID_LAYOUTS = {
+  flat: true,
+  hierarchical: true
+};
+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,
+  "missing-meta-header": true,
+  "malformed-sq-delimiter": true,
+  "vr-max-length-exceeded": true,
+  "missing-type1-tag": true
+};
+var HEX_TAG_RE = /^[0-9a-fA-F]{8}$/;
+var KEYWORD_RE = /^[A-Z][A-Za-z0-9]*$/;
+function validatePositiveInt(value, path) {
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 1) {
+    throw new Error(
+      `${path}: must be a positive integer; got ${JSON.stringify(value)}`
+    );
+  }
+}
+function validateTagKey(key, path) {
+  if (!HEX_TAG_RE.test(key) && !KEYWORD_RE.test(key)) {
+    throw new Error(
+      `${path}: invalid tag key "${key}" \u2014 must be a DICOM keyword name (e.g. "Modality") or an 8-hex-char tag (e.g. "00080060")`
+    );
+  }
+}
+function validateEntry(entry, path) {
+  if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+    throw new Error(`${path}: must be an object`);
+  }
+  const e = entry;
+  if (typeof e.type !== "string" || !Object.hasOwn(TYPE_CAPABILITIES, e.type)) {
+    throw new Error(
+      `${path}.type: must be one of ${Object.keys(TYPE_CAPABILITIES).join(", ")}; got ${JSON.stringify(e.type)}`
+    );
+  }
+  const type = e.type;
+  const caps = TYPE_CAPABILITIES[type];
+  if ("count" in e) validatePositiveInt(e.count, `${path}.count`);
+  if ("transferSyntax" in e) {
+    if (!caps.transferSyntax) {
+      throw new Error(
+        `${path}.transferSyntax: not supported for type "${type}"`
+      );
+    }
+    if (!Object.hasOwn(VALID_TRANSFER_SYNTAXES, e.transferSyntax)) {
+      throw new Error(
+        `${path}.transferSyntax: must be one of ${Object.keys(VALID_TRANSFER_SYNTAXES).join(", ")}`
+      );
+    }
+  }
+  if (!caps.tags && "tags" in e)
+    throw new Error(`${path}.tags: not supported for type "${type}"`);
+  if (!caps.violations && "violations" in e)
+    throw new Error(`${path}.violations: not supported for type "${type}"`);
+  if ("tags" in e) validateTags(e.tags, `${path}.tags`);
+  if ("violations" in e) {
+    if (!Array.isArray(e.violations)) {
+      throw new Error(`${path}.violations: must be an array`);
+    }
+    for (const [i, v] of e.violations.entries()) {
+      if (typeof v !== "string" || !Object.hasOwn(VALID_VIOLATIONS, v)) {
+        throw new Error(
+          `${path}.violations[${i}]: must be one of ${Object.keys(VALID_VIOLATIONS).join(", ")}; got ${JSON.stringify(v)}`
+        );
+      }
+    }
+  }
+  if (type === "large-ct") {
+    validatePositiveInt(e.rows, `${path}.rows`);
+    validatePositiveInt(e.columns, `${path}.columns`);
+    if ("frames" in e) validatePositiveInt(e.frames, `${path}.frames`);
+    const rows = e.rows;
+    const columns = e.columns;
+    const frames = typeof e.frames === "number" ? e.frames : 1;
+    if (rows * columns * frames * 2 > MAX_PIXEL_BYTES) {
+      throw new Error(
+        `${path}: pixel data (${rows}\xD7${columns}\xD7${frames}\xD72 bytes) exceeds the 512 MB limit`
+      );
+    }
+  }
+  return e;
+}
+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)) {
+    validateTagKey(key, path);
+  }
+}
+function validateSeries(series, path) {
+  if (typeof series !== "object" || series === null || Array.isArray(series)) {
+    throw new Error(`${path}: must be an object`);
+  }
+  const s = series;
+  if (!Array.isArray(s.entries) || s.entries.length === 0) {
+    throw new Error(`${path}.entries: must be a non-empty array`);
+  }
+  for (let i = 0; i < s.entries.length; i++) {
+    const e = validateEntry(s.entries[i], `${path}.entries[${i}]`);
+    if (!TYPE_CAPABILITIES[e.type].tags) {
+      throw new Error(
+        `${path}.entries[${i}].type: "${e.type}" cannot be used inside a series \u2014 only types that support tags can be grouped`
+      );
+    }
+  }
+  if ("tags" in s) validateTags(s.tags, `${path}.tags`);
+  return s;
+}
+function validateStudy(study, path) {
+  if (typeof study !== "object" || study === null || Array.isArray(study)) {
+    throw new Error(`${path}: must be an object`);
+  }
+  const st = study;
+  if (!Array.isArray(st.series) || st.series.length === 0) {
+    throw new Error(`${path}.series: must be a non-empty array`);
+  }
+  for (let i = 0; i < st.series.length; i++) {
+    validateSeries(st.series[i], `${path}.series[${i}]`);
+  }
+  if ("count" in st) validatePositiveInt(st.count, `${path}.count`);
+  if ("tags" in st) validateTags(st.tags, `${path}.tags`);
+  return st;
+}
+function validateDatasetSpec(raw) {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    throw new Error("DatasetSpec: must be a JSON object");
+  }
+  const r = raw;
+  if ("entries" in r && !Array.isArray(r.entries)) {
+    throw new Error("DatasetSpec.entries: must be an array");
+  }
+  if ("studies" in r && !Array.isArray(r.studies)) {
+    throw new Error("DatasetSpec.studies: must be an array");
+  }
+  const rawEntries = r.entries ?? [];
+  const rawStudies = r.studies ?? [];
+  if (rawEntries.length === 0 && rawStudies.length === 0) {
+    throw new Error(
+      'DatasetSpec: must contain at least one of "entries" or "studies" (non-empty)'
+    );
+  }
+  const entries = rawEntries.map(
+    (entry, i) => validateEntry(entry, `entries[${i}]`)
+  );
+  const studies = rawStudies.map(
+    (study, i) => validateStudy(study, `studies[${i}]`)
+  );
+  if ("seed" in r) {
+    if (typeof r.seed !== "number" || !Number.isFinite(r.seed)) {
+      throw new Error(
+        `DatasetSpec.seed: must be a finite number; got ${JSON.stringify(r.seed)}`
+      );
+    }
+  }
+  if ("layout" in r) {
+    if (typeof r.layout !== "string" || !Object.hasOwn(VALID_LAYOUTS, r.layout)) {
+      throw new Error(
+        `DatasetSpec.layout: must be one of ${Object.keys(VALID_LAYOUTS).join(", ")}; got ${JSON.stringify(r.layout)}`
+      );
+    }
+  }
+  return {
+    ...entries.length > 0 ? { entries } : {},
+    ...studies.length > 0 ? { studies } : {},
+    ...r.seed !== void 0 ? { seed: r.seed } : {},
+    ...r.layout !== void 0 ? { layout: r.layout } : {}
+  };
+}
+
+// src/syntheticFixtures/generator.ts
+var CT_SOP_CLASS = "1.2.840.10008.5.1.4.1.1.2";
+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 applyTagOverrides(dataset, tags) {
+  if (!tags) return;
+  for (const [key, value] of Object.entries(tags)) {
+    if (HEX_TAG_RE.test(key)) {
+      const keyword = tagToKeyword.get(key.toUpperCase());
+      if (keyword) {
+        dataset[keyword] = value;
+      } else {
+        console.warn(`dicom-synth: unknown hex tag "${key}" \u2014 skipping`);
+      }
+    } else {
+      dataset[key] = value;
+    }
+  }
+}
+function buildMeta(uid, transferSyntax = "explicit-vr-little-endian") {
+  return {
+    FileMetaInformationVersion: new Uint8Array([0, 1]).buffer,
+    MediaStorageSOPClassUID: CT_SOP_CLASS,
+    MediaStorageSOPInstanceUID: uid.sop,
+    TransferSyntaxUID: TRANSFER_SYNTAX_UID[transferSyntax],
+    ImplementationClassUID: "1.2.3.4",
+    ImplementationVersionName: "SYNTH"
+  };
+}
+function buildBaseCtDataset(uid) {
+  return {
+    PatientName: "SYNTH^SUBJECT",
+    PatientID: "SYNTH_PID",
+    Modality: "CT",
+    SOPClassUID: CT_SOP_CLASS,
+    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" }
+  };
+}
+function serializeDict(meta, dataset) {
+  const dicomDict = new dcmjs.data.DicomDict(
+    dcmjs.data.DicomMetaDictionary.denaturalizeDataset(
+      meta
+    )
+  );
+  dicomDict.dict = dcmjs.data.DicomMetaDictionary.denaturalizeDataset(
+    dataset
+  );
+  return Buffer.from(dicomDict.write({ allowInvalidVRLength: true }));
+}
+function buildValidCtBuffer(uid, tags, transferSyntax) {
+  const dataset = buildBaseCtDataset(uid);
+  applyTagOverrides(dataset, tags);
+  return serializeDict(buildMeta(uid, transferSyntax), dataset);
+}
+function buildInvalidUidCtBuffer(uid, tags, transferSyntax) {
+  const invalidUid = {
+    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)}`
+  };
+  const dataset = buildBaseCtDataset(invalidUid);
+  applyTagOverrides(dataset, tags);
+  return serializeDict(buildMeta(invalidUid, transferSyntax), dataset);
+}
+function buildVendorCtBuffer(uid, tags, transferSyntax) {
+  const dataset = buildBaseCtDataset(uid);
+  dataset.Laterality = "";
+  dataset.PatientWeight = "0";
+  applyTagOverrides(dataset, tags);
+  return serializeDict(buildMeta(uid, transferSyntax), dataset);
+}
+function buildLargeCtBuffer(uid, rows, columns, frames, tags, transferSyntax) {
+  const dataset = buildBaseCtDataset(uid);
+  dataset.Rows = rows;
+  dataset.Columns = columns;
+  dataset.NumberOfFrames = frames;
+  dataset.PixelData = new Uint8Array(rows * columns * frames * 2).buffer;
+  applyTagOverrides(dataset, tags);
+  return serializeDict(buildMeta(uid, transferSyntax), dataset);
+}
+function buildFakeSignatureBuffer() {
+  const buf = Buffer.alloc(200, 0);
+  buf.write("XXXX", 128, 4, "ascii");
+  return buf;
+}
+function buildNonDicomBuffer(content = "not dicom") {
+  return Buffer.from(content, "utf8");
+}
+function buildBufferForSpec(spec, uid) {
+  switch (spec.type) {
+    case "valid-ct":
+      return buildValidCtBuffer(uid, spec.tags, spec.transferSyntax);
+    case "invalid-uid-ct":
+      return buildInvalidUidCtBuffer(uid, spec.tags, spec.transferSyntax);
+    case "vendor-warnings-ct":
+      return buildVendorCtBuffer(uid, spec.tags, spec.transferSyntax);
+    case "large-ct":
+      return buildLargeCtBuffer(
+        uid,
+        spec.rows,
+        spec.columns,
+        spec.frames ?? 1,
+        spec.tags,
+        spec.transferSyntax
+      );
+    case "fake-signature":
+      return buildFakeSignatureBuffer();
+    case "non-dicom":
+      return buildNonDicomBuffer(spec.content);
+    case "dicomdir":
+      return buildDicomdirBuffer();
+  }
+}
+
+// src/syntheticFixtures/uid.ts
+import { randomBytes } from "node:crypto";
+var ROLE_CODE = { study: 1, series: 2, sop: 3 };
+function lcg(seed) {
+  let s = seed >>> 0;
+  return () => {
+    s = Math.imul(1664525, s) + 1013904223 >>> 0;
+    return s;
+  };
+}
+function formatUid(a, b, role) {
+  return `2.25.${a}.${b}.${ROLE_CODE[role]}`;
+}
+function randomUid(role) {
+  const buf = randomBytes(8);
+  return formatUid(buf.readUInt32BE(0), buf.readUInt32BE(4), role);
+}
+function seededUid(next, role) {
+  return formatUid(next(), next(), role);
+}
+var GROUP_STREAM_OFFSET = 2654435769;
+function seededStream(seed, offset, a, b) {
+  return lcg(seed * 999983 + offset + a * 1000003 + b * 7919 >>> 0);
+}
+function makeGroupUidGenerator(seed) {
+  if (seed === void 0) {
+    return {
+      study: () => randomUid("study"),
+      series: () => randomUid("series")
+    };
+  }
+  return {
+    study: (studyIndex) => seededUid(
+      seededStream(seed, GROUP_STREAM_OFFSET, studyIndex + 1, 0),
+      "study"
+    ),
+    series: (studyIndex, seriesIndex) => seededUid(
+      seededStream(
+        seed,
+        GROUP_STREAM_OFFSET,
+        studyIndex + 1,
+        seriesIndex + 1
+      ),
+      "series"
+    )
+  };
+}
+function makeUidGenerator(seed) {
+  if (seed === void 0) {
+    return () => ({
+      study: randomUid("study"),
+      series: randomUid("series"),
+      sop: randomUid("sop")
+    });
+  }
+  return (fileIndex) => {
+    const next = seededStream(seed, 0, fileIndex, 0);
+    return {
+      study: seededUid(next, "study"),
+      series: seededUid(next, "series"),
+      sop: seededUid(next, "sop")
+    };
+  };
+}
+
+// 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 Buffer.from(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) {
+  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 (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 = Buffer.alloc(8);
+        delimiter.writeUInt16LE(65534, 0);
+        delimiter.writeUInt16LE(57565, 2);
+        delimiter.writeUInt32LE(4, 4);
+        result = Buffer.concat([result, delimiter]);
+        break;
+      }
+      default:
+        throw new Error(
+          `dicom-synth: unhandled byte-level violation "${v}"`
+        );
+    }
+  }
+  return result;
+}
+function applyViolations(buffer, violations) {
+  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), byteViolations);
+}
+
+// src/collection/writer.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 studyFileCount(studies) {
+  return studies.reduce(
+    (sum, study) => sum + (study.count ?? 1) * study.series.reduce((s, series) => s + entryCount(series.entries), 0),
+    0
+  );
+}
+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 violations = "violations" in spec ? spec.violations : void 0;
+  if (violations?.length) {
+    buffer = applyViolations(buffer, violations);
+  }
+  const name = filename(spec.type, index, padWidth);
+  return {
+    filename: name,
+    relativePath: name,
+    buffer,
+    type: spec.type,
+    index
+  };
+}
+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}`
+  };
+}
+async function* generateCollectionFromSpec(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";
+  let globalIndex = 0;
+  for (const entry of flatEntries) {
+    const { count = 1, ...fileSpec } = entry;
+    for (let i = 0; i < count; i++) {
+      yield generateFile(fileSpec, {
+        index: globalIndex,
+        seed: spec.seed,
+        padWidth
+      });
+      globalIndex++;
+    }
+  }
+  const groupUids = makeGroupUidGenerator(spec.seed);
+  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 entry of series.entries) {
+          const { count = 1, ...fileSpec } = entry;
+          for (let i = 0; i < count; i++) {
+            instanceNumber++;
+            const tags = {
+              InstanceNumber: instanceNumber,
+              ...study.tags,
+              ...series.tags,
+              ...fileSpec.tags
+            };
+            const file = await generateFile(
+              { ...fileSpec, tags },
+              {
+                index: globalIndex,
+                seed: spec.seed,
+                padWidth,
+                uid: { study: studyUid, series: seriesUid }
+              }
+            );
+            yield hierarchical ? {
+              ...file,
+              ...hierarchicalName(
+                studyOrdinal,
+                seriesIndex,
+                instanceNumber
+              )
+            } : file;
+            globalIndex++;
+          }
+        }
+      }
+      studyOrdinal++;
+    }
+  }
+}
+async function writeCollectionFromSpec(spec, outDir) {
+  const root = resolve2(outDir);
+  mkdirSync2(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 dir = dirname(filePath);
+    if (!createdDirs.has(dir)) {
+      mkdirSync2(dir, { recursive: true });
+      createdDirs.add(dir);
+    }
+    await writeFile(filePath, file.buffer);
+    manifest.push({ path: filePath, type: file.type, index: file.index });
+  }
+  return manifest;
 }
 
 // src/public-fixtures/catalog.ts
 import { readFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { dirname as dirname2, join } from "node:path";
 import { fileURLToPath } from "node:url";
 var bundledCatalogPath = join(
-  dirname(fileURLToPath(import.meta.url)),
+  dirname2(fileURLToPath(import.meta.url)),
   "../../data/public-cases.json"
 );
 function defaultPublicCasesPath() {
@@ -71,7 +695,7 @@ function loadCaseById(casesJsonPath, id) {
 
 // src/public-fixtures/fetch.ts
 import { createHash } from "node:crypto";
-import { existsSync, mkdirSync as mkdirSync3, readFileSync as readFileSync2, writeFileSync as writeFileSync3 } from "node:fs";
+import { existsSync, mkdirSync as mkdirSync3, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "node:fs";
 import { homedir } from "node:os";
 import { join as join2 } from "node:path";
 var DEFAULT_CACHE_ROOT = join2(homedir(), ".cache", "dicom-synth-testcases");
@@ -107,173 +731,19 @@ async function fetchPublicCaseToCache(record, cacheRoot = DEFAULT_CACHE_ROOT) {
   }
   const buf = Buffer.from(await res.arrayBuffer());
   verifySha256(buf, record.sha256);
-  writeFileSync3(dest, buf);
+  writeFileSync2(dest, buf);
   return dest;
 }
-
-// src/syntheticFixtures/generator.ts
-import { mkdirSync as mkdirSync4, writeFileSync as writeFileSync4 } from "node:fs";
-import { resolve as resolve3 } from "node:path";
-
-// 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/syntheticFixtures/generator.ts
-var CT_SOP_CLASS = "1.2.840.10008.5.1.4.1.1.2";
-var VARIANT_INDEX = {
-  "minimal-invalid-uid": 0,
-  "valid-uid": 1,
-  "vendor-warnings": 2
-};
-function uidFor(variant, role) {
-  const i = VARIANT_INDEX[variant];
-  if (variant === "minimal-invalid-uid") {
-    return `2.25.100000000000000000000000000000.${role}.${i}`;
-  }
-  const uidRoots = [
-    "1000000000000000000000000000000000001",
-    "1000000000000000000000000000000000002",
-    "1000000000000000000000000000000000003"
-  ];
-  const roleSuffix = role === "study" ? 1 : role === "series" ? 2 : 3;
-  return `2.25.${uidRoots[i]}.${roleSuffix}`;
-}
-function naturalDataset(variant) {
-  const studyUID = uidFor(variant, "study");
-  const seriesUID = uidFor(variant, "series");
-  const sopUID = uidFor(variant, "sop");
-  const dataset = {
-    PatientName: "SYNTH^SUBJECT",
-    PatientID: "SYNTH_PID",
-    Modality: "CT",
-    SOPClassUID: CT_SOP_CLASS,
-    SOPInstanceUID: sopUID,
-    SeriesInstanceUID: seriesUID,
-    StudyInstanceUID: studyUID,
-    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
-  };
-  if (variant === "vendor-warnings") {
-    dataset.Laterality = "";
-    dataset.PatientWeight = "0";
-  }
-  return dataset;
-}
-function buildDicomDict(variant) {
-  const meta = {
-    FileMetaInformationVersion: new Uint8Array([0, 1]).buffer,
-    MediaStorageSOPClassUID: CT_SOP_CLASS,
-    MediaStorageSOPInstanceUID: uidFor(variant, "sop"),
-    TransferSyntaxUID: "1.2.840.10008.1.2.1",
-    ImplementationClassUID: "1.2.3.4",
-    ImplementationVersionName: "SYNTH"
-  };
-  const dicomDict = new dcmjs.data.DicomDict(
-    dcmjs.data.DicomMetaDictionary.denaturalizeDataset(meta)
-  );
-  dicomDict.dict = dcmjs.data.DicomMetaDictionary.denaturalizeDataset(
-    naturalDataset(variant)
-  );
-  return dicomDict;
-}
-function buildSyntheticCtBuffer(variant) {
-  return Buffer.from(
-    buildDicomDict(variant).write({ allowInvalidVRLength: true })
-  );
-}
-var SYNTHETIC_FIXTURES = [
-  {
-    filename: "minimal-ct-0.dcm",
-    variant: "minimal-invalid-uid",
-    description: "Minimal CT with text in UIDs (many dciodvfy errors)"
-  },
-  {
-    filename: "valid-uid-ct-0.dcm",
-    variant: "valid-uid",
-    description: "Minimal CT with numeric UIDs only (missing-module noise)"
-  },
-  {
-    filename: "vendor-warnings-ct-0.dcm",
-    variant: "vendor-warnings",
-    description: "Valid UIDs plus empty Laterality and zero PatientWeight"
-  }
-];
-function writeMinimalDicomFile(filePath, tags) {
-  const patientId = tags?.patientId ?? "TEST-PATIENT-001";
-  const patientName = tags?.patientName ?? "TEST^PATIENT";
-  const sopUID = tags?.sopInstanceUid ?? "1.2.3.4.5.6.7.8.9.0.1";
-  const dataset = {
-    PatientName: patientName,
-    PatientID: patientId,
-    Modality: "CT",
-    SOPClassUID: CT_SOP_CLASS,
-    SOPInstanceUID: sopUID,
-    SeriesInstanceUID: "1.2.3.4.5.6.7.8",
-    StudyInstanceUID: "1.2.3.4.5.6.7",
-    SeriesNumber: "1",
-    Rows: 1,
-    Columns: 1,
-    BitsAllocated: 16,
-    PixelRepresentation: 0,
-    PixelData: new Uint8Array([0, 0]).buffer
-  };
-  const dicomDict = new dcmjs.data.DicomDict({});
-  dicomDict.dict = dcmjs.data.DicomMetaDictionary.denaturalizeDataset(dataset);
-  const buffer = Buffer.from(dicomDict.write({ allowInvalidVRLength: true }));
-  mkdirSync4(resolve3(filePath, ".."), { recursive: true });
-  writeFileSync4(filePath, buffer);
-}
-function writeSyntheticFixturesToDir(outDir) {
-  const root = resolve3(outDir);
-  mkdirSync4(root, { recursive: true });
-  const written = [];
-  for (const { filename, variant } of SYNTHETIC_FIXTURES) {
-    const path = resolve3(root, filename);
-    writeFileSync4(path, buildSyntheticCtBuffer(variant));
-    written.push(path);
-  }
-  return written;
-}
 export {
-  SYNTHETIC_FIXTURES,
-  buildDicomDict,
-  buildDicomdirBuffer,
-  buildSyntheticCtBuffer,
   caseCachePath,
   defaultPublicCasesPath,
   fetchPublicCaseToCache,
+  generateCollectionFromSpec,
+  generateFile,
   loadCaseById,
   loadCasesFromJson,
   loadDefaultCases,
+  validateDatasetSpec,
   verifySha256,
-  writeDicomdirFile,
-  writeFakeDicomSignatureFile,
-  writeMinimalDicomFile,
-  writeNonDicomFile,
-  writeSyntheticFixturesToDir
+  writeCollectionFromSpec
 };