dicom-synth 1.1.0 → 1.2.0

package/dist/esm/collection/writer.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";
@@ -213,6 +213,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 () => ({
@@ -222,7 +249,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"),
@@ -335,28 +362,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, {
@@ -367,13 +416,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 });
   }

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";
@@ -54,6 +54,10 @@ var TYPE_CAPABILITIES = {
   "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
@@ -69,6 +73,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,13 +99,7 @@ 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`);
   if ("transferSyntax" in e) {
     if (!caps.transferSyntax) {
       throw new Error(
@@ -111,14 +116,7 @@ function validateEntry(entry, path) {
     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 ("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`);
@@ -132,17 +130,9 @@ 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`);
-      }
-    }
+    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 +144,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].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 (!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 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 = r.entries.map(
+  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,9 +217,18 @@ 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 } : {}
   };
 }
 
@@ -346,6 +397,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 +433,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 +546,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 +600,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 +664,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() {

package/dist/esm/schema/validate.js

@@ -8,6 +8,10 @@ var TYPE_CAPABILITIES = {
   "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
@@ -23,6 +27,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(
@@ -42,13 +53,7 @@ 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`);
   if ("transferSyntax" in e) {
     if (!caps.transferSyntax) {
       throw new Error(
@@ -65,14 +70,7 @@ function validateEntry(entry, path) {
     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 ("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`);
@@ -86,17 +84,9 @@ 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`);
-      }
-    }
+    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;
@@ -108,20 +98,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].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 (!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 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 = r.entries.map(
+  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(
@@ -129,9 +171,18 @@ 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 } : {}
   };
 }
 export {

package/dist/esm/syntheticFixtures/uid.js

@@ -18,6 +18,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 () => ({
@@ -27,7 +54,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"),
@@ -36,5 +63,6 @@ function makeUidGenerator(seed) {
   };
 }
 export {
+  makeGroupUidGenerator,
   makeUidGenerator
 };

package/dist/types/collection/writer.d.ts

@@ -1,6 +1,8 @@
 import type { DatasetSpec, FileSpec } from '../schema/types.js';
+import type { UidSet } from '../syntheticFixtures/uid.js';
 export type GeneratedFile = {
     filename: string;
+    relativePath: string;
     buffer: Buffer;
     type: FileSpec['type'];
     index: number;
@@ -14,6 +16,7 @@ export declare function generateFile(spec: FileSpec, options?: {
     index?: number;
     seed?: number;
     padWidth?: number;
+    uid?: Partial<UidSet>;
 }): Promise<GeneratedFile>;
 export declare function generateCollectionFromSpec(spec: DatasetSpec): AsyncGenerator<GeneratedFile>;
 export declare function writeCollectionFromSpec(spec: DatasetSpec, outDir: string): Promise<CollectionManifest>;

package/dist/types/index.d.ts

@@ -1,5 +1,5 @@
 export { type CollectionManifest, type GeneratedFile, generateCollectionFromSpec, generateFile, writeCollectionFromSpec, } from './collection/writer.js';
 export { defaultPublicCasesPath, loadCaseById, loadCasesFromJson, loadDefaultCases, type PublicCaseRecord, type PublicCaseSource, } from './public-fixtures/catalog.js';
 export { caseCachePath, fetchPublicCaseToCache, verifySha256, } from './public-fixtures/fetch.js';
-export type { DatasetSpec, DicomdirSpec, DicomTagOverrides, FakeSignatureSpec, FileSpec, InvalidUidCtSpec, LargeCtSpec, NonDicomSpec, TransferSyntax, ValidCtSpec, VendorCtSpec, ViolationClass, } from './schema/types.js';
+export type { DatasetLayout, DatasetSpec, DicomdirSpec, DicomTagOverrides, FakeSignatureSpec, FileSpec, ImageSpec, InvalidUidCtSpec, LargeCtSpec, NonDicomSpec, SeriesEntrySpec, SeriesSpec, StudySpec, TransferSyntax, ValidCtSpec, VendorCtSpec, ViolationClass, } from './schema/types.js';
 export { validateDatasetSpec } from './schema/validate.js';

package/dist/types/schema/types.d.ts

@@ -37,12 +37,28 @@ export type NonDicomSpec = {
 export type DicomdirSpec = {
     type: 'dicomdir';
 };
-export type FileSpec = ValidCtSpec | InvalidUidCtSpec | VendorCtSpec | LargeCtSpec | FakeSignatureSpec | NonDicomSpec | DicomdirSpec;
+export type ImageSpec = ValidCtSpec | InvalidUidCtSpec | VendorCtSpec | LargeCtSpec;
+export type FileSpec = ImageSpec | FakeSignatureSpec | NonDicomSpec | DicomdirSpec;
 export type EntrySpec = FileSpec & {
     count?: number;
 };
+export type SeriesEntrySpec = ImageSpec & {
+    count?: number;
+};
+export type SeriesSpec = {
+    entries: SeriesEntrySpec[];
+    tags?: DicomTagOverrides;
+};
+export type StudySpec = {
+    series: SeriesSpec[];
+    tags?: DicomTagOverrides;
+    count?: number;
+};
+export type DatasetLayout = 'flat' | 'hierarchical';
 export type DatasetSpec = {
-    entries: EntrySpec[];
+    entries?: EntrySpec[];
+    studies?: StudySpec[];
     seed?: number;
+    layout?: DatasetLayout;
 };
 export {};

package/dist/types/syntheticFixtures/uid.d.ts

@@ -3,5 +3,10 @@ export type UidSet = {
     series: string;
     sop: string;
 };
+export type GroupUidGenerator = {
+    study: (studyIndex: number) => string;
+    series: (studyIndex: number, seriesIndex: number) => string;
+};
+export declare function makeGroupUidGenerator(seed?: number): GroupUidGenerator;
 export type UidGenerator = (fileIndex: number) => UidSet;
 export declare function makeUidGenerator(seed?: number): UidGenerator;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dicom-synth",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Toolkit for synthetic DICOM fixtures and public fixture fetch/cache.",
   "license": "Apache-2.0",
   "type": "module",