dicom-synth 1.2.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

@@ -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,

package/dist/esm/index.js

@@ -46,13 +46,19 @@ 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,
@@ -100,22 +106,29 @@ function validateEntry(entry, path) {
   const type = e.type;
   const caps = TYPE_CAPABILITIES[type];
   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) {
+    if (!Object.hasOwn(VALID_TRANSFER_SYNTAXES, e.transferSyntax)) {
       throw new Error(
-        `${path}.transferSyntax: not supported for type "${type}"`
+        `${path}.transferSyntax: must be one of ${Object.keys(VALID_TRANSFER_SYNTAXES).join(", ")}`
       );
     }
-    if (!Object.hasOwn(VALID_TRANSFER_SYNTAXES, e.transferSyntax)) {
+  }
+  if ("modality" in e) {
+    if (typeof e.modality !== "string" || !Object.hasOwn(VALID_MODALITIES, e.modality)) {
       throw new Error(
-        `${path}.transferSyntax: must be one of ${Object.keys(VALID_TRANSFER_SYNTAXES).join(", ")}`
+        `${path}.modality: must be one of ${Object.keys(VALID_MODALITIES).join(", ")}; got ${JSON.stringify(e.modality)}`
       );
     }
   }
-  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)) {
@@ -129,7 +142,7 @@ function validateEntry(entry, path) {
       }
     }
   }
-  if (type === "large-ct") {
+  if (type === "large-image") {
     validatePositiveInt(e.rows, `${path}.rows`);
     validatePositiveInt(e.columns, `${path}.columns`);
     if ("frames" in e) validatePositiveInt(e.frames, `${path}.frames`);
@@ -162,9 +175,9 @@ function validateSeries(series, path) {
   }
   for (let i = 0; i < s.entries.length; i++) {
     const e = validateEntry(s.entries[i], `${path}.entries[${i}]`);
-    if (!TYPE_CAPABILITIES[e.type].tags) {
+    if (!TYPE_CAPABILITIES[e.type].image) {
       throw new Error(
-        `${path}.entries[${i}].type: "${e.type}" cannot be used inside a series \u2014 only types that support tags can be grouped`
+        `${path}.entries[${i}].type: "${e.type}" cannot be used inside a series \u2014 only image-generating types can be grouped`
       );
     }
   }
@@ -233,7 +246,35 @@ function validateDatasetSpec(raw) {
 }
 
 // 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"
@@ -266,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,
@@ -298,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) {
@@ -312,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);
@@ -353,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,

package/dist/esm/schema/validate.js

@@ -1,12 +1,18 @@
 // 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,
@@ -54,22 +60,29 @@ function validateEntry(entry, path) {
   const type = e.type;
   const caps = TYPE_CAPABILITIES[type];
   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) {
+    if (!Object.hasOwn(VALID_TRANSFER_SYNTAXES, e.transferSyntax)) {
       throw new Error(
-        `${path}.transferSyntax: not supported for type "${type}"`
+        `${path}.transferSyntax: must be one of ${Object.keys(VALID_TRANSFER_SYNTAXES).join(", ")}`
       );
     }
-    if (!Object.hasOwn(VALID_TRANSFER_SYNTAXES, e.transferSyntax)) {
+  }
+  if ("modality" in e) {
+    if (typeof e.modality !== "string" || !Object.hasOwn(VALID_MODALITIES, e.modality)) {
       throw new Error(
-        `${path}.transferSyntax: must be one of ${Object.keys(VALID_TRANSFER_SYNTAXES).join(", ")}`
+        `${path}.modality: must be one of ${Object.keys(VALID_MODALITIES).join(", ")}; got ${JSON.stringify(e.modality)}`
       );
     }
   }
-  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)) {
@@ -83,7 +96,7 @@ function validateEntry(entry, path) {
       }
     }
   }
-  if (type === "large-ct") {
+  if (type === "large-image") {
     validatePositiveInt(e.rows, `${path}.rows`);
     validatePositiveInt(e.columns, `${path}.columns`);
     if ("frames" in e) validatePositiveInt(e.frames, `${path}.frames`);
@@ -116,9 +129,9 @@ function validateSeries(series, path) {
   }
   for (let i = 0; i < s.entries.length; i++) {
     const e = validateEntry(s.entries[i], `${path}.entries[${i}]`);
-    if (!TYPE_CAPABILITIES[e.type].tags) {
+    if (!TYPE_CAPABILITIES[e.type].image) {
       throw new Error(
-        `${path}.entries[${i}].type: "${e.type}" cannot be used inside a series \u2014 only types that support tags can be grouped`
+        `${path}.entries[${i}].type: "${e.type}" cannot be used inside a series \u2014 only image-generating types can be grouped`
       );
     }
   }

package/dist/esm/syntheticFixtures/generator.js

@@ -44,7 +44,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"
@@ -77,22 +105,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,
@@ -109,7 +138,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) {
@@ -123,36 +153,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);
@@ -164,15 +194,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,

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 { DatasetLayout, DatasetSpec, DicomdirSpec, DicomTagOverrides, FakeSignatureSpec, FileSpec, ImageSpec, InvalidUidCtSpec, LargeCtSpec, NonDicomSpec, SeriesEntrySpec, SeriesSpec, StudySpec, TransferSyntax, ValidCtSpec, VendorCtSpec, ViolationClass, } from './schema/types.js';
+export type { DatasetLayout, DatasetSpec, DicomdirSpec, DicomTagOverrides, FakeSignatureSpec, FileSpec, ImageSpec, InvalidUidImageSpec, LargeImageSpec, Modality, NonDicomSpec, SeriesEntrySpec, SeriesSpec, StudySpec, TransferSyntax, ValidImageSpec, VendorWarningsImageSpec, ViolationClass, } from './schema/types.js';
 export { validateDatasetSpec } from './schema/validate.js';

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

@@ -7,22 +7,24 @@ export type DicomTagOverrides = {
     [tag: string]: unknown;
 };
 export type ViolationClass = 'uid-too-long' | 'non-conformant-uid' | 'missing-meta-header' | 'malformed-sq-delimiter' | 'vr-max-length-exceeded' | 'missing-type1-tag';
-type BaseCtSpec = {
+export type Modality = 'CT' | 'PT' | 'MR' | 'CR';
+type BaseImageSpec = {
+    modality?: Modality;
     tags?: DicomTagOverrides;
     transferSyntax?: TransferSyntax;
     violations?: ViolationClass[];
 };
-export type ValidCtSpec = BaseCtSpec & {
-    type: 'valid-ct';
+export type ValidImageSpec = BaseImageSpec & {
+    type: 'valid-image';
 };
-export type InvalidUidCtSpec = BaseCtSpec & {
-    type: 'invalid-uid-ct';
+export type InvalidUidImageSpec = BaseImageSpec & {
+    type: 'invalid-uid-image';
 };
-export type VendorCtSpec = BaseCtSpec & {
-    type: 'vendor-warnings-ct';
+export type VendorWarningsImageSpec = BaseImageSpec & {
+    type: 'vendor-warnings-image';
 };
-export type LargeCtSpec = BaseCtSpec & {
-    type: 'large-ct';
+export type LargeImageSpec = BaseImageSpec & {
+    type: 'large-image';
     rows: number;
     columns: number;
     frames?: number;
@@ -37,7 +39,7 @@ export type NonDicomSpec = {
 export type DicomdirSpec = {
     type: 'dicomdir';
 };
-export type ImageSpec = ValidCtSpec | InvalidUidCtSpec | VendorCtSpec | LargeCtSpec;
+export type ImageSpec = ValidImageSpec | InvalidUidImageSpec | VendorWarningsImageSpec | LargeImageSpec;
 export type FileSpec = ImageSpec | FakeSignatureSpec | NonDicomSpec | DicomdirSpec;
 export type EntrySpec = FileSpec & {
     count?: number;

package/package.json

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