dicom-synth 1.1.0 → 1.3.0

package/dist/esm/index.js

@@ -1,7 +1,7 @@
 // src/collection/writer.ts
 import { mkdirSync as mkdirSync2 } from "node:fs";
 import { writeFile } from "node:fs/promises";
-import { resolve as resolve2 } from "node:path";
+import { dirname, resolve as resolve2 } from "node:path";
 
 // src/loadDcmjs.ts
 import dcmjsDefaultImport, * as dcmjsNamespace from "dcmjs";
@@ -46,13 +46,23 @@ function 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 }
+  "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 }
+};
+var VALID_MODALITIES = {
+  CT: true,
+  PT: true,
+  MR: true,
+  CR: true
+};
+var VALID_LAYOUTS = {
+  flat: true,
+  hierarchical: true
 };
 var VALID_TRANSFER_SYNTAXES = {
   "explicit-vr-little-endian": true,
@@ -69,6 +79,13 @@ var VALID_VIOLATIONS = {
 };
 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(
@@ -88,37 +105,31 @@ function validateEntry(entry, path) {
   }
   const type = e.type;
   const caps = TYPE_CAPABILITIES[type];
-  if ("count" in e) {
-    if (typeof e.count !== "number" || !Number.isInteger(e.count) || e.count < 1) {
-      throw new Error(
-        `${path}.count: must be a positive integer; got ${JSON.stringify(e.count)}`
-      );
-    }
+  if ("count" in e) validatePositiveInt(e.count, `${path}.count`);
+  for (const field of [
+    "modality",
+    "tags",
+    "violations",
+    "transferSyntax"
+  ]) {
+    if (!caps.image && field in e)
+      throw new Error(`${path}.${field}: not supported for type "${type}"`);
   }
   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) {
-    if (typeof e.tags !== "object" || e.tags === null || Array.isArray(e.tags)) {
-      throw new Error(`${path}.tags: must be an object`);
-    }
-    for (const key of Object.keys(e.tags)) {
-      validateTagKey(key, `${path}.tags`);
+  if ("modality" in e) {
+    if (typeof e.modality !== "string" || !Object.hasOwn(VALID_MODALITIES, e.modality)) {
+      throw new Error(
+        `${path}.modality: must be one of ${Object.keys(VALID_MODALITIES).join(", ")}; got ${JSON.stringify(e.modality)}`
+      );
     }
   }
+  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`);
@@ -131,18 +142,10 @@ function validateEntry(entry, path) {
       }
     }
   }
-  if (type === "large-ct") {
-    if (typeof e.rows !== "number" || !Number.isInteger(e.rows) || e.rows < 1) {
-      throw new Error(`${path}.rows: must be a positive integer`);
-    }
-    if (typeof e.columns !== "number" || !Number.isInteger(e.columns) || e.columns < 1) {
-      throw new Error(`${path}.columns: must be a positive integer`);
-    }
-    if ("frames" in e) {
-      if (typeof e.frames !== "number" || !Number.isInteger(e.frames) || e.frames < 1) {
-        throw new Error(`${path}.frames: must be a positive integer`);
-      }
-    }
+  if (type === "large-image") {
+    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;
@@ -154,20 +157,72 @@ function validateEntry(entry, path) {
   }
   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].image) {
+      throw new Error(
+        `${path}.entries[${i}].type: "${e.type}" cannot be used inside a series \u2014 only image-generating types 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 (!Array.isArray(r.entries)) {
+  if ("entries" in r && !Array.isArray(r.entries)) {
     throw new Error("DatasetSpec.entries: must be an array");
   }
-  if (r.entries.length === 0) {
-    throw new Error("DatasetSpec.entries: must not be empty");
+  if ("studies" in r && !Array.isArray(r.studies)) {
+    throw new Error("DatasetSpec.studies: must be an array");
   }
-  const entries = r.entries.map(
+  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(
@@ -175,14 +230,51 @@ function validateDatasetSpec(raw) {
       );
     }
   }
+  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,
-    ...r.seed !== void 0 ? { seed: r.seed } : {}
+    ...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 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"
@@ -215,22 +307,23 @@ function applyTagOverrides(dataset, tags) {
     }
   }
 }
-function buildMeta(uid, transferSyntax = "explicit-vr-little-endian") {
+function buildMeta(uid, modality, transferSyntax = "explicit-vr-little-endian") {
   return {
     FileMetaInformationVersion: new Uint8Array([0, 1]).buffer,
-    MediaStorageSOPClassUID: CT_SOP_CLASS,
+    MediaStorageSOPClassUID: MODALITY_PRESETS[modality].sopClassUid,
     MediaStorageSOPInstanceUID: uid.sop,
     TransferSyntaxUID: TRANSFER_SYNTAX_UID[transferSyntax],
     ImplementationClassUID: "1.2.3.4",
     ImplementationVersionName: "SYNTH"
   };
 }
-function buildBaseCtDataset(uid) {
+function buildBaseImageDataset(uid, modality) {
+  const preset = MODALITY_PRESETS[modality];
   return {
     PatientName: "SYNTH^SUBJECT",
     PatientID: "SYNTH_PID",
-    Modality: "CT",
-    SOPClassUID: CT_SOP_CLASS,
+    Modality: modality,
+    SOPClassUID: preset.sopClassUid,
     SOPInstanceUID: uid.sop,
     SeriesInstanceUID: uid.series,
     StudyInstanceUID: uid.study,
@@ -247,7 +340,8 @@ function buildBaseCtDataset(uid) {
     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" }
+    _vrMap: { PixelData: "OW" },
+    ...preset.attributes
   };
 }
 function serializeDict(meta, dataset) {
@@ -261,36 +355,36 @@ function serializeDict(meta, dataset) {
   );
   return Buffer.from(dicomDict.write({ allowInvalidVRLength: true }));
 }
-function buildValidCtBuffer(uid, tags, transferSyntax) {
-  const dataset = buildBaseCtDataset(uid);
+function buildValidImageBuffer(uid, modality, tags, transferSyntax) {
+  const dataset = buildBaseImageDataset(uid, modality);
   applyTagOverrides(dataset, tags);
-  return serializeDict(buildMeta(uid, transferSyntax), dataset);
+  return serializeDict(buildMeta(uid, modality, transferSyntax), dataset);
 }
-function buildInvalidUidCtBuffer(uid, tags, transferSyntax) {
+function buildInvalidUidImageBuffer(uid, modality, 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);
+  const dataset = buildBaseImageDataset(invalidUid, modality);
   applyTagOverrides(dataset, tags);
-  return serializeDict(buildMeta(invalidUid, transferSyntax), dataset);
+  return serializeDict(buildMeta(invalidUid, modality, transferSyntax), dataset);
 }
-function buildVendorCtBuffer(uid, tags, transferSyntax) {
-  const dataset = buildBaseCtDataset(uid);
+function buildVendorWarningsImageBuffer(uid, modality, tags, transferSyntax) {
+  const dataset = buildBaseImageDataset(uid, modality);
   dataset.Laterality = "";
   dataset.PatientWeight = "0";
   applyTagOverrides(dataset, tags);
-  return serializeDict(buildMeta(uid, transferSyntax), dataset);
+  return serializeDict(buildMeta(uid, modality, transferSyntax), dataset);
 }
-function buildLargeCtBuffer(uid, rows, columns, frames, tags, transferSyntax) {
-  const dataset = buildBaseCtDataset(uid);
+function buildLargeImageBuffer(uid, modality, rows, columns, frames, tags, transferSyntax) {
+  const dataset = buildBaseImageDataset(uid, modality);
   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);
+  return serializeDict(buildMeta(uid, modality, transferSyntax), dataset);
 }
 function buildFakeSignatureBuffer() {
   const buf = Buffer.alloc(200, 0);
@@ -302,15 +396,31 @@ function buildNonDicomBuffer(content = "not dicom") {
 }
 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(
+    case "valid-image":
+      return buildValidImageBuffer(
+        uid,
+        spec.modality ?? "CT",
+        spec.tags,
+        spec.transferSyntax
+      );
+    case "invalid-uid-image":
+      return buildInvalidUidImageBuffer(
+        uid,
+        spec.modality ?? "CT",
+        spec.tags,
+        spec.transferSyntax
+      );
+    case "vendor-warnings-image":
+      return buildVendorWarningsImageBuffer(
+        uid,
+        spec.modality ?? "CT",
+        spec.tags,
+        spec.transferSyntax
+      );
+    case "large-image":
+      return buildLargeImageBuffer(
         uid,
+        spec.modality ?? "CT",
         spec.rows,
         spec.columns,
         spec.frames ?? 1,
@@ -346,6 +456,33 @@ function randomUid(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 () => ({
@@ -355,7 +492,7 @@ function makeUidGenerator(seed) {
     });
   }
   return (fileIndex) => {
-    const next = lcg(seed * 999983 + fileIndex * 1000003 >>> 0);
+    const next = seededStream(seed, 0, fileIndex, 0);
     return {
       study: seededUid(next, "study"),
       series: seededUid(next, "series"),
@@ -468,28 +605,50 @@ function filename(type, index, padWidth) {
   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);
+  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: filename(spec.type, index, padWidth),
+    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 totalFiles = spec.entries.reduce((sum, e) => sum + (e.count ?? 1), 0);
+  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 spec.entries) {
+  for (const entry of flatEntries) {
     const { count = 1, ...fileSpec } = entry;
     for (let i = 0; i < count; i++) {
       yield generateFile(fileSpec, {
@@ -500,13 +659,62 @@ async function* generateCollectionFromSpec(spec) {
       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.filename);
+    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 });
   }
@@ -515,10 +723,10 @@ async function writeCollectionFromSpec(spec, outDir) {
 
 // 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() {