dicom-synth 1.1.0 → 1.3.0

package/README.md

@@ -4,7 +4,7 @@ Schema-driven **synthetic DICOM fixture generation** and **public fixture** fetc
 
 ## Disclaimer
 
-Still in early release. APIs may change without notice.
+⚠️ Still in early release. APIs may change without notice. Version 2+ will be the first stable release ⚠️
 
 ## Install
 
@@ -24,16 +24,16 @@ Generation is a three-layer API. Each layer is a thin wrapper over the one below
 ```ts
 import { generateFile } from 'dicom-synth'
 
-const { buffer, filename, type, index } = await generateFile({ type: 'valid-ct' })
+const { buffer, filename, type, index } = await generateFile({ type: 'valid-image' })
 // buffer: Buffer ready to write or pass to a parser
-// filename: 'valid-ct-000.dcm'
+// filename: 'valid-image-000.dcm'
 ```
 
 With options:
 
 ```ts
 const { buffer } = await generateFile(
-  { type: 'valid-ct', tags: { PatientID: 'P001' }, violations: ['uid-too-long'] },
+  { type: 'valid-image', tags: { PatientID: 'P001' }, violations: ['uid-too-long'] },
   { seed: 42, index: 7 },
 )
 ```
@@ -44,7 +44,7 @@ Write a single file to disk:
 import { writeFileSync } from 'node:fs'
 import { generateFile } from 'dicom-synth'
 
-const { buffer, filename } = await generateFile({ type: 'valid-ct' })
+const { buffer, filename } = await generateFile({ type: 'valid-image' })
 writeFileSync(`./out/${filename}`, buffer)
 ```
 
@@ -55,8 +55,8 @@ import { generateCollectionFromSpec } from 'dicom-synth'
 
 for await (const file of generateCollectionFromSpec({
   entries: [
-    { type: 'valid-ct', count: 10 },
-    { type: 'invalid-uid-ct', count: 3 },
+    { type: 'valid-image', count: 10 },
+    { type: 'invalid-uid-image', count: 3 },
   ],
   seed: 42,
 })) {
@@ -72,7 +72,7 @@ Files are yielded one at a time — safe to pipe without buffering the entire co
 import { writeCollectionFromSpec } from 'dicom-synth'
 
 const manifest = await writeCollectionFromSpec(
-  { entries: [{ type: 'valid-ct', count: 5 }], seed: 42 },
+  { entries: [{ type: 'valid-image', count: 5 }], seed: 42 },
   './fixtures/generated',
 )
 // manifest: Array<{ path: string; type: string; index: number }>
@@ -95,7 +95,7 @@ import { writeCollectionFromSpec } from 'dicom-synth'
 const dir = await mkdtemp(join(tmpdir(), 'synth-'))
 try {
   await writeCollectionFromSpec(
-    { entries: [{ type: 'valid-ct', count: 3 }], seed: 42 },
+    { entries: [{ type: 'valid-image', count: 3 }], seed: 42 },
     dir,
   )
   // run pipeline against dir
@@ -148,7 +148,7 @@ Use layer 2 when passing generated files directly to a parser or pipeline withou
 import { generateCollectionFromSpec, type GeneratedFile } from 'dicom-synth'
 
 const files: GeneratedFile[] = []
-for await (const file of generateCollectionFromSpec({ entries: [{ type: 'valid-ct', count: 5 }] })) {
+for await (const file of generateCollectionFromSpec({ entries: [{ type: 'valid-image', count: 5 }] })) {
   files.push(file)
 }
 ```
@@ -163,11 +163,15 @@ for await (const file of generateCollectionFromSpec({ entries: [{ type: 'valid-c
 import type { DatasetSpec } from 'dicom-synth'
 
 type DatasetSpec = {
-  entries: EntrySpec[]   // one or more entry specs; must not be empty
-  seed?: number          // optional: fixed seed for deterministic UID generation
+  entries?: EntrySpec[]              // flat entries — each file gets its own UIDs
+  studies?: StudySpec[]              // grouped entries — shared study/series UIDs
+  seed?: number                      // optional: fixed seed for deterministic UID generation
+  layout?: 'flat' | 'hierarchical'   // optional: directory layout for grouped files
 }
 ```
 
+At least one of `entries` or `studies` must be present and non-empty; both may be used together.
+
 `seed` makes UID generation fully deterministic across runs. Omit it for random UIDs.
 
 ### `EntrySpec`
@@ -175,7 +179,7 @@ type DatasetSpec = {
 An `EntrySpec` is a `FileSpec` plus an optional `count` field (how many times to generate it):
 
 ```json
-{ "type": "valid-ct", "count": 10 }
+{ "type": "valid-image", "count": 10 }
 ```
 
 `count` defaults to 1 and must be a positive integer. It is a collection-layer concern — `generateFile` does not accept `count`.
@@ -184,21 +188,21 @@ An `EntrySpec` is a `FileSpec` plus an optional `count` field (how many times to
 
 | Type | Description | Conformance |
 |---|---|---|
-| `valid-ct` | Standards-valid CT image; numeric UIDs, complete meta header | strict |
-| `invalid-uid-ct` | CT with non-numeric UIDs (letters in UID components) | edge |
-| `vendor-warnings-ct` | CT with empty `Laterality` and `PatientWeight = 0` — produces dciodvfy warnings | edge |
-| `large-ct` | CT with configurable pixel dimensions; `rows` and `columns` required | strict |
+| `valid-image` | Standards-valid image (CT by default — see `modality`); numeric UIDs, complete meta header | strict |
+| `invalid-uid-image` | Image with non-numeric UIDs (letters in UID components) | edge |
+| `vendor-warnings-image` | Image with empty `Laterality` and `PatientWeight = 0` — produces dciodvfy warnings | edge |
+| `large-image` | Image with configurable pixel dimensions; `rows` and `columns` required | strict |
 | `fake-signature` | 200-byte buffer with `XXXX` at preamble offset — no DICM magic | edge |
 | `non-dicom` | Arbitrary text buffer; no extension in filename | edge |
 | `dicomdir` | Minimal DICOMDIR file | strict |
 
-**`large-ct` fields:**
+**`large-image` fields:**
 
 ```json
-{ "type": "large-ct", "rows": 512, "columns": 512, "frames": 100 }
+{ "type": "large-image", "rows": 512, "columns": 512, "frames": 100 }
 ```
 
-`frames` defaults to 1. A 512×512×100 CT produces a buffer of ~52 MB.
+`frames` defaults to 1. A 512×512×100 image produces a buffer of ~52 MB.
 
 **`non-dicom` fields:**
 
@@ -208,13 +212,75 @@ An `EntrySpec` is a `FileSpec` plus an optional `count` field (how many times to
 
 `content` defaults to `"not dicom"`.
 
+### Modality presets (`modality`)
+
+Available on `valid-image`, `invalid-uid-image`, `vendor-warnings-image`, and `large-image`. Defaults to `CT`.
+
+```json
+{ "type": "valid-image", "modality": "PT" }
+```
+
+Each preset sets the matching SOP Class UID (dataset and meta header), the `Modality` tag, and minimal modality-specific type-1 attributes:
+
+| Modality | SOP Class | Extra attributes |
+|---|---|---|
+| `CT` (default) | CT Image Storage `…1.1.2` | — |
+| `PT` | PET Image Storage `…1.1.128` | `Units`, `DecayCorrection`, `CorrectedImage` |
+| `MR` | MR Image Storage `…1.1.4` | `ScanningSequence`, `SequenceVariant` |
+| `CR` | CR Image Storage `…1.1.1` | — |
+
+Presets target shape/variance fidelity for pipeline testing, not clinical fidelity. Tag overrides win over preset attributes.
+
+```ts
+import type { Modality } from 'dicom-synth'
+```
+
+### Study/series grouping (`studies`)
+
+Group files so they share `StudyInstanceUID` (per study) and `SeriesInstanceUID` (per series). `InstanceNumber` increments from 1 within each series. SOP Instance UIDs remain unique per file.
+
+```json
+{
+  "studies": [
+    {
+      "tags": { "PatientID": "P001" },
+      "series": [
+        { "entries": [{ "type": "valid-image", "modality": "CT", "count": 50 }] },
+        { "entries": [{ "type": "valid-image", "modality": "PT", "count": 120 }] }
+      ]
+    },
+    { "series": [{ "entries": [{ "type": "valid-image" }] }], "count": 3 }
+  ],
+  "seed": 42,
+  "layout": "hierarchical"
+}
+```
+
+- `StudySpec.count` generates N copies of the whole study, each with fresh UIDs.
+- `tags` may be set at study, series, and entry level — merged into each file, with entry tags winning over series tags, which win over study tags.
+- Only image-generating types can appear in a series (`fake-signature`, `non-dicom`, and `dicomdir` are rejected).
+- With a `seed`, group UIDs are deterministic; without one they are random but still shared within each group.
+
+```ts
+import type { StudySpec, SeriesSpec, SeriesEntrySpec } from 'dicom-synth'
+```
+
+### Layout (`layout`)
+
+| Value | Effect |
+|---|---|
+| `flat` (default) | All files in the output root, named `<type>-<index>[.dcm]` |
+| `hierarchical` | Grouped files written as `study-001/series-001/00001.dcm`; flat `entries` stay in the root |
+
+`GeneratedFile.relativePath` carries the layout-aware path for in-process consumers; `filename` is always the basename.
+
 ### Tag overrides (`tags`)
 
-Available on `valid-ct`, `invalid-uid-ct`, `vendor-warnings-ct`, and `large-ct`.
+Available on `valid-image`, `invalid-uid-image`, `vendor-warnings-image`, and `large-image`.
 
 ```json
 {
-  "type": "valid-ct",
+  "type": "valid-image",
   "tags": {
     "PatientID": "P001",
     "PatientName": "DOE^JANE",
@@ -231,7 +297,7 @@ import type { DicomTagOverrides } from 'dicom-synth'
 
 ### Transfer syntax (`transferSyntax`)
 
-Available on `valid-ct`, `invalid-uid-ct`, `vendor-warnings-ct`, and `large-ct`.
+Available on `valid-image`, `invalid-uid-image`, `vendor-warnings-image`, and `large-image`.
 
 | Value | `TransferSyntaxUID` in meta header |
 |---|---|
@@ -241,7 +307,7 @@ Available on `valid-ct`, `invalid-uid-ct`, `vendor-warnings-ct`, and `large-ct`.
 
 ### Violation injection (`violations`)
 
-Available on `valid-ct`, `invalid-uid-ct`, `vendor-warnings-ct`, and `large-ct`. Violations are applied as post-processing transforms to an otherwise valid buffer.
+Available on `valid-image`, `invalid-uid-image`, `vendor-warnings-image`, and `large-image`. Violations are applied as post-processing transforms to an otherwise valid buffer.
 
 | Violation | Effect | Detectable by dciodvfy |
 |---|---|---|
@@ -255,7 +321,7 @@ Available on `valid-ct`, `invalid-uid-ct`, `vendor-warnings-ct`, and `large-ct`.
 Tag-level violations are applied before byte-level violations. Byte-level violations may produce a buffer that cannot be re-parsed.
 
 ```json
-{ "type": "valid-ct", "violations": ["uid-too-long", "missing-meta-header"] }
+{ "type": "valid-image", "violations": ["uid-too-long", "missing-meta-header"] }
 ```
 
 ```ts
@@ -277,16 +343,25 @@ The validator throws with a human-readable message on any structural error.
 ```json
 {
   "entries": [
-    { "type": "valid-ct",           "count": 10, "tags": { "PatientID": "P001" }, "transferSyntax": "explicit-vr-little-endian" },
-    { "type": "invalid-uid-ct",     "count": 3 },
-    { "type": "vendor-warnings-ct", "count": 2 },
-    { "type": "large-ct",           "count": 1, "rows": 512, "columns": 512, "frames": 100 },
-    { "type": "valid-ct",           "count": 1, "violations": ["uid-too-long", "missing-meta-header"] },
+    { "type": "valid-image",           "count": 10, "tags": { "PatientID": "P001" }, "transferSyntax": "explicit-vr-little-endian" },
+    { "type": "invalid-uid-image",     "count": 3 },
+    { "type": "vendor-warnings-image", "count": 2 },
+    { "type": "large-image",           "count": 1, "rows": 512, "columns": 512, "frames": 100 },
+    { "type": "valid-image",           "count": 1, "violations": ["uid-too-long", "missing-meta-header"] },
     { "type": "fake-signature",     "count": 5 },
     { "type": "non-dicom",          "count": 2, "content": "garbage" },
     { "type": "dicomdir",           "count": 1 }
   ],
-  "seed": 42
+  "studies": [
+    {
+      "series": [
+        { "entries": [{ "type": "valid-image", "modality": "CT", "count": 50 }] },
+        { "entries": [{ "type": "valid-image", "modality": "PT", "count": 120 }] }
+      ]
+    }
+  ],
+  "seed": 42,
+  "layout": "hierarchical"
 }
 ```
 
@@ -299,20 +374,20 @@ The validator throws with a human-readable message on any structural error.
 dicom-synth-generate --schema dataset.json --out ./fixtures/generated
 
 # Inline schema
-dicom-synth-generate --schema-inline '{"entries":[{"type":"valid-ct","count":5}]}' --out ./out
+dicom-synth-generate --schema-inline '{"entries":[{"type":"valid-image","count":5}]}' --out ./out
 
 # Default output directory is ./fixtures/generated
 dicom-synth-generate --schema dataset.json
 ```
 
-The default schema (`examples/default.json`) generates one each of `valid-ct`, `invalid-uid-ct`, and `vendor-warnings-ct`:
+The default schema (`examples/default.json`) generates one each of `valid-image`, `invalid-uid-image`, and `vendor-warnings-image`:
 
 ```bash
 dicom-synth-generate --schema examples/default.json --out /tmp/out
 # Wrote 3 file(s) to /tmp/out
-#   valid-ct: 1
-#   invalid-uid-ct: 1
-#   vendor-warnings-ct: 1
+#   valid-image: 1
+#   invalid-uid-image: 1
+#   vendor-warnings-image: 1
 ```
 
 Schema validation errors exit with code 1 and a descriptive message.
@@ -391,7 +466,7 @@ pnpm fetch:public-case -- pydicom-CT-small
 | `src/public-fixtures/fetch.ts` | Fetch, SHA-256 verify, content-addressed cache |
 | `bin/dicom-synth-generate.mjs` | Published generate CLI (requires `pnpm build`) |
 | `bin/dicom-synth-fetch.mjs` | Published fetch CLI (requires `pnpm build`) |
-| `examples/default.json` | Default `DatasetSpec` — one each of `valid-ct`, `invalid-uid-ct`, `vendor-warnings-ct` |
+| `examples/default.json` | Default `DatasetSpec` — one each of `valid-image`, `invalid-uid-image`, `vendor-warnings-image` |
 
 ---
 
@@ -417,9 +492,10 @@ Git hooks: see [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## Future development
 
-- **Multi-series study layouts** — shared `StudyInstanceUID` across files via a `studies` top-level key; no breaking schema change needed
+- **Size targeting** — generate a file of approximately N KB via a `targetSizeKb` field
+- **Parametric dataset designer** — range-based spec (`{min, max}` for counts/sizes) that resolves deterministically into a concrete `DatasetSpec`
+- **Dry-run mode** — emit the manifest (paths, types, grouping) without writing files
 - **Compressed transfer syntaxes** — JPEG-LS, JPEG 2000, RLE
-- **Modality presets** — MR, PET, CR profiles beyond CT
 - **Private fixture catalogues** — same SHA-256 fetch/cache pattern for credentials-backed sources (e.g. S3)
 
 ---

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";
@@ -49,7 +49,35 @@ var MAX_PIXEL_BYTES = 512 * 1024 * 1024;
 var HEX_TAG_RE = /^[0-9a-fA-F]{8}$/;
 
 // 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"
@@ -82,22 +110,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,
@@ -114,7 +143,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) {
@@ -128,36 +158,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);
@@ -169,15 +199,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,
@@ -213,6 +259,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 +295,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 +408,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 +462,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 });
   }