dicom-synth 1.3.0 → 1.5.0

package/README.md

@@ -191,30 +191,43 @@ An `EntrySpec` is a `FileSpec` plus an optional `count` field (how many times to
 | `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-image` fields:**
+**`non-dicom` fields:**
 
 ```json
-{ "type": "large-image", "rows": 512, "columns": 512, "frames": 100 }
+{ "type": "non-dicom", "content": "not a dicom file" }
 ```
 
-`frames` defaults to 1. A 512×512×100 image produces a buffer of ~52 MB.
+`content` defaults to `"not dicom"`.
 
-**`non-dicom` fields:**
+### Sizing (`rows`/`columns`/`frames` or `targetSizeKb`)
+
+Available on all image types. Two mutually exclusive mechanisms; omitting both produces a minimal 1×1 image.
+
+**Explicit pixel dimensions** — for geometry-shaped cases (large frames, strips, multi-frame):
 
 ```json
-{ "type": "non-dicom", "content": "not a dicom file" }
+{ "type": "valid-image", "rows": 512, "columns": 512, "frames": 100 }
 ```
 
-`content` defaults to `"not dicom"`.
+`rows` and `columns` must be provided together; `frames` defaults to 1. A 512×512×100 image produces a buffer of ~52 MB.
+
+**Target file size** — for byte-shaped cases (upload limits, memory ceilings):
+
+```json
+{ "type": "valid-image", "targetSizeKb": 250000 }
+```
+
+Pads `PixelData` so the file lands within ±2% or ±4 KB of the target (whichever is larger), accounting for tag and transfer-syntax overhead. `Rows`/`Columns` stay consistent with the pixel data, so the file remains conformant.
+
+Both mechanisms are capped at 512 MB of pixel data to prevent accidental OOM. A target smaller than the file's fixed overhead (roughly 1 KB) produces the minimal possible file, slightly above target. When sizing fields are set they control `Rows`, `Columns`, and `PixelData` — tag overrides of those keywords do not apply.
 
 ### Modality presets (`modality`)
 
-Available on `valid-image`, `invalid-uid-image`, `vendor-warnings-image`, and `large-image`. Defaults to `CT`.
+Available on all image types. Defaults to `CT`.
 
 ```json
 { "type": "valid-image", "modality": "PT" }
@@ -276,7 +289,7 @@ import type { StudySpec, SeriesSpec, SeriesEntrySpec } from 'dicom-synth'
 
 ### Tag overrides (`tags`)
 
-Available on `valid-image`, `invalid-uid-image`, `vendor-warnings-image`, and `large-image`.
+Available on all image types.
 
 ```json
 {
@@ -297,7 +310,7 @@ import type { DicomTagOverrides } from 'dicom-synth'
 
 ### Transfer syntax (`transferSyntax`)
 
-Available on `valid-image`, `invalid-uid-image`, `vendor-warnings-image`, and `large-image`.
+Available on all image types.
 
 | Value | `TransferSyntaxUID` in meta header |
 |---|---|
@@ -307,7 +320,7 @@ Available on `valid-image`, `invalid-uid-image`, `vendor-warnings-image`, and `l
 
 ### Violation injection (`violations`)
 
-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.
+Available on all image types. Violations are applied as post-processing transforms to an otherwise valid buffer.
 
 | Violation | Effect | Detectable by dciodvfy |
 |---|---|---|
@@ -346,7 +359,8 @@ The validator throws with a human-readable message on any structural error.
     { "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, "rows": 512, "columns": 512, "frames": 100 },
+    { "type": "valid-image",           "count": 1, "targetSizeKb": 250000 },
     { "type": "valid-image",           "count": 1, "violations": ["uid-too-long", "missing-meta-header"] },
     { "type": "fake-signature",     "count": 5 },
     { "type": "non-dicom",          "count": 2, "content": "garbage" },
@@ -367,6 +381,42 @@ The validator throws with a human-readable message on any structural error.
 
 ---
 
+## Parametric designer
+
+A `ParametricSpec` describes a dataset by ranges instead of explicit entries. `resolveParametricSpec` resolves it — deterministically for a given seed — into a concrete `DatasetSpec` that can be inspected, saved, and re-run.
+
+```ts
+import { resolveParametricSpec, writeCollectionFromSpec } from 'dicom-synth'
+
+const resolved = resolveParametricSpec({
+  seed: 42,
+  studies: {
+    count: { min: 2, max: 4 },          // ranges are inclusive
+    seriesPerStudy: { min: 1, max: 3 },
+    filesPerSeries: { min: 5, max: 20 },
+    fileSizeKb: { min: 100, max: 600 }, // sampled per file
+    modalities: ['CT', 'PT'],           // one drawn per series
+  },
+  edgeCases: [{ type: 'invalid-uid-image', frequency: 0.05 }],
+  layout: 'hierarchical',
+})
+await writeCollectionFromSpec(resolved, './out')
+```
+
+- Every field of `studies` accepts a fixed number or an inclusive `{ min, max }` range (`Range`).
+- `fileSizeKb` maps to `targetSizeKb`; a fixed value collapses each series into one counted entry, a range samples per file.
+- `edgeCases` are `EntrySpec`s appended to the flat `entries` of the resolved spec. With `frequency` (0–1), the count is drawn per file across the whole dataset — the resolved spec records the actual draw. Without it, the entry is appended as-is (use `count` for absolute numbers). At small dataset sizes a low frequency may draw zero occurrences.
+- The seed (drawn randomly when omitted) is embedded in the resolved spec, so resolution is always reproducible.
+
+```ts
+import type { ParametricSpec, ParametricStudies, ParametricEdgeCase, Range } from 'dicom-synth'
+import { validateParametricSpec } from 'dicom-synth'
+```
+
+See `examples/parametric.json` for a JSON example and `examples/convert-data-shape.mjs` for converting an exported tree-shape JSON into a `DatasetSpec` (skips non-DICOM files).
+
+---
+
 ## CLI
 
 ```bash
@@ -378,8 +428,21 @@ dicom-synth-generate --schema-inline '{"entries":[{"type":"valid-image","count":
 
 # Default output directory is ./fixtures/generated
 dicom-synth-generate --schema dataset.json
+
+# Resolve and generate from a parametric spec; save the resolved DatasetSpec
+dicom-synth-generate --parametric examples/parametric.json --out ./out --emit-spec resolved.json
+
+# Preview the manifest (paths, types, sizes) without writing anything
+dicom-synth-generate --parametric examples/parametric.json --dry-run
 ```
 
+| Flag | Effect |
+|---|---|
+| `--schema <path>` / `--schema-inline <json>` / `--parametric <path>` | Input spec (mutually exclusive) |
+| `--out <dir>` | Output directory (default `./fixtures/generated`) |
+| `--emit-spec <path>` | Write the resolved `DatasetSpec` JSON (requires `--parametric`) |
+| `--dry-run` | Generate in memory and print the manifest; nothing is written |
+
 The default schema (`examples/default.json`) generates one each of `valid-image`, `invalid-uid-image`, and `vendor-warnings-image`:
 
 ```bash
@@ -457,7 +520,8 @@ pnpm fetch:public-case -- pydicom-CT-small
 | Path | Responsibility |
 |---|---|
 | `src/schema/types.ts` | All public TypeScript types (`FileSpec`, `DatasetSpec`, `ViolationClass`, etc.) |
-| `src/schema/validate.ts` | `validateDatasetSpec` — validates a raw JSON value against the schema |
+| `src/schema/validate.ts` | `validateDatasetSpec` / `validateParametricSpec` — validate raw JSON values against the schema |
+| `src/schema/parametric.ts` | `resolveParametricSpec` — seeded `ParametricSpec` → `DatasetSpec` resolution |
 | `src/syntheticFixtures/generator.ts` | Internal buffer builders keyed on `FileSpec` type |
 | `src/syntheticFixtures/uid.ts` | Seeded and random UID generation |
 | `src/syntheticFixtures/violations.ts` | Post-processing violation injection |
@@ -467,6 +531,8 @@ pnpm fetch:public-case -- pydicom-CT-small
 | `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-image`, `invalid-uid-image`, `vendor-warnings-image` |
+| `examples/parametric.json` | Example `ParametricSpec` for the `--parametric` CLI path |
+| `examples/convert-data-shape.mjs` | Example converter: tree-shape JSON → `DatasetSpec` |
 
 ---
 
@@ -492,9 +558,8 @@ Git hooks: see [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## Future development
 
-- **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
+- **Describe tool** — scan an existing DICOM tree and emit a matching `DatasetSpec` (counts, grouping, sizes, modalities; no PHI)
+- **Dimension edge-case recipes** — documented presets for geometry pathologies (1×65535 strips, high frame counts)
 - **Compressed transfer syntaxes** — JPEG-LS, JPEG 2000, RLE
 - **Private fixture catalogues** — same SHA-256 fetch/cache pattern for credentials-backed sources (e.g. S3)
 

package/bin/dicom-synth-generate.mjs

@@ -1,15 +1,18 @@
 #!/usr/bin/env node
-import { readFileSync } from 'node:fs'
+import { readFileSync, writeFileSync } from 'node:fs'
 import { resolve } from 'node:path'
 import {
+  generateCollectionFromSpec,
+  resolveParametricSpec,
   validateDatasetSpec,
   writeCollectionFromSpec,
 } from '../dist/esm/index.js'
 
 function usage() {
   console.error(
-    'Usage: dicom-synth-generate --schema <path> [--out <dir>]\n' +
-      '       dicom-synth-generate --schema-inline <json> [--out <dir>]',
+    'Usage: dicom-synth-generate --schema <path> [--out <dir>] [--dry-run]\n' +
+      '       dicom-synth-generate --schema-inline <json> [--out <dir>] [--dry-run]\n' +
+      '       dicom-synth-generate --parametric <path> [--out <dir>] [--emit-spec <path>] [--dry-run]',
   )
   process.exit(1)
 }
@@ -19,36 +22,50 @@ const args = process.argv.slice(2)
 if (args.length === 0) usage()
 
 let rawSpec
+let specSource
 let outDir = resolve('./fixtures/generated')
+let emitSpecPath
+let dryRun = false
+
+function readSpecArg(flag, value) {
+  if (rawSpec !== undefined) {
+    console.error(
+      'Error: --schema, --schema-inline and --parametric are mutually exclusive',
+    )
+    process.exit(1)
+  }
+  specSource = flag
+  if (flag === '--schema-inline') {
+    try {
+      rawSpec = JSON.parse(value)
+    } catch (err) {
+      console.error(`Error parsing inline schema: ${err.message}`)
+      process.exit(1)
+    }
+  } else {
+    try {
+      rawSpec = JSON.parse(readFileSync(resolve(value), 'utf8'))
+    } catch (err) {
+      console.error(`Error reading ${flag.slice(2)} file: ${err.message}`)
+      process.exit(1)
+    }
+  }
+}
 
 for (let i = 0; i < args.length; i++) {
   if (
-    (args[i] === '--schema' || args[i] === '--schema-inline') &&
+    (args[i] === '--schema' ||
+      args[i] === '--schema-inline' ||
+      args[i] === '--parametric') &&
     args[i + 1]
   ) {
-    if (rawSpec !== undefined) {
-      console.error(
-        'Error: --schema and --schema-inline are mutually exclusive',
-      )
-      process.exit(1)
-    }
-    if (args[i] === '--schema') {
-      try {
-        rawSpec = JSON.parse(readFileSync(resolve(args[++i]), 'utf8'))
-      } catch (err) {
-        console.error(`Error reading schema file: ${err.message}`)
-        process.exit(1)
-      }
-    } else {
-      try {
-        rawSpec = JSON.parse(args[++i])
-      } catch (err) {
-        console.error(`Error parsing inline schema: ${err.message}`)
-        process.exit(1)
-      }
-    }
+    readSpecArg(args[i], args[++i])
   } else if (args[i] === '--out' && args[i + 1]) {
     outDir = resolve(args[++i])
+  } else if (args[i] === '--emit-spec' && args[i + 1]) {
+    emitSpecPath = resolve(args[++i])
+  } else if (args[i] === '--dry-run') {
+    dryRun = true
   } else {
     console.error(`Unknown argument: ${args[i]}`)
     usage()
@@ -57,29 +74,72 @@ for (let i = 0; i < args.length; i++) {
 
 if (rawSpec === undefined) usage()
 
-let spec
-try {
-  spec = validateDatasetSpec(rawSpec)
-} catch (err) {
-  console.error(`Schema validation error: ${err.message}`)
+function printTypeCounts(counts) {
+  for (const [type, count] of Object.entries(counts)) {
+    console.log(`  ${type}: ${count}`)
+  }
+}
+
+if (emitSpecPath !== undefined && specSource !== '--parametric') {
+  console.error('Error: --emit-spec requires --parametric')
   process.exit(1)
 }
 
-let manifest
+let spec
 try {
-  manifest = await writeCollectionFromSpec(spec, outDir)
+  spec =
+    specSource === '--parametric'
+      ? resolveParametricSpec(rawSpec)
+      : validateDatasetSpec(rawSpec)
 } catch (err) {
-  console.error(`Error writing collection: ${err.message}`)
+  console.error(`Schema validation error: ${err.message}`)
   process.exit(1)
 }
 
-// Summary by type
-const counts = {}
-for (const entry of manifest) {
-  counts[entry.type] = (counts[entry.type] ?? 0) + 1
+if (emitSpecPath !== undefined) {
+  try {
+    writeFileSync(emitSpecPath, `${JSON.stringify(spec, null, 2)}\n`)
+    console.log(`Wrote resolved spec to ${emitSpecPath}`)
+  } catch (err) {
+    console.error(`Error writing resolved spec: ${err.message}`)
+    process.exit(1)
+  }
 }
 
-console.log(`Wrote ${manifest.length} file(s) to ${outDir}`)
-for (const [type, count] of Object.entries(counts)) {
-  console.log(`  ${type}: ${count}`)
+if (dryRun) {
+  const counts = {}
+  let fileCount = 0
+  let byteCount = 0
+  try {
+    for await (const file of generateCollectionFromSpec(spec)) {
+      console.log(
+        `${file.relativePath}  (${file.type}, ${(file.buffer.length / 1024).toFixed(1)} KB)`,
+      )
+      counts[file.type] = (counts[file.type] ?? 0) + 1
+      fileCount++
+      byteCount += file.buffer.length
+    }
+  } catch (err) {
+    console.error(`Error generating collection: ${err.message}`)
+    process.exit(1)
+  }
+  console.log(
+    `Dry run: ${fileCount} file(s), ${(byteCount / 1024).toFixed(1)} KB total — nothing written`,
+  )
+  printTypeCounts(counts)
+} else {
+  let manifest
+  try {
+    manifest = await writeCollectionFromSpec(spec, outDir)
+  } catch (err) {
+    console.error(`Error writing collection: ${err.message}`)
+    process.exit(1)
+  }
+
+  const counts = {}
+  for (const entry of manifest) {
+    counts[entry.type] = (counts[entry.type] ?? 0) + 1
+  }
+  console.log(`Wrote ${manifest.length} file(s) to ${outDir}`)
+  printTypeCounts(counts)
 }

package/dist/esm/collection/writer.js

@@ -158,36 +158,46 @@ function serializeDict(meta, dataset) {
   );
   return Buffer.from(dicomDict.write({ allowInvalidVRLength: true }));
 }
-function buildValidImageBuffer(uid, modality, tags, transferSyntax) {
-  const dataset = buildBaseImageDataset(uid, modality);
-  applyTagOverrides(dataset, tags);
-  return serializeDict(buildMeta(uid, modality, transferSyntax), dataset);
+var MAX_DIMENSION = 65535;
+function applySizing(dataset, meta, spec) {
+  if (spec.targetSizeKb !== void 0) {
+    const clampDim = (n) => Math.min(MAX_DIMENSION, Math.max(1, Math.round(n)));
+    const minimalPixelBytes = dataset.PixelData.byteLength;
+    const overhead = serializeDict(meta, dataset).length - minimalPixelBytes;
+    const cells = Math.max(
+      1,
+      Math.round((spec.targetSizeKb * 1024 - overhead) / 2)
+    );
+    const rows = clampDim(Math.sqrt(cells));
+    const columns = clampDim(cells / rows);
+    dataset.Rows = rows;
+    dataset.Columns = columns;
+    dataset.PixelData = new ArrayBuffer(rows * columns * 2);
+  } else if (spec.rows !== void 0 && spec.columns !== void 0) {
+    dataset.Rows = spec.rows;
+    dataset.Columns = spec.columns;
+    if (spec.frames !== void 0) dataset.NumberOfFrames = spec.frames;
+    dataset.PixelData = new ArrayBuffer(
+      spec.rows * spec.columns * (spec.frames ?? 1) * 2
+    );
+  }
 }
-function buildInvalidUidImageBuffer(uid, modality, tags, transferSyntax) {
-  const invalidUid = {
+function buildImageBuffer(spec, uid) {
+  const modality = spec.modality ?? "CT";
+  const effectiveUid = spec.type === "invalid-uid-image" ? {
     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 = buildBaseImageDataset(invalidUid, modality);
-  applyTagOverrides(dataset, tags);
-  return serializeDict(buildMeta(invalidUid, modality, transferSyntax), dataset);
-}
-function buildVendorWarningsImageBuffer(uid, modality, tags, transferSyntax) {
-  const dataset = buildBaseImageDataset(uid, modality);
-  dataset.Laterality = "";
-  dataset.PatientWeight = "0";
-  applyTagOverrides(dataset, tags);
-  return serializeDict(buildMeta(uid, modality, transferSyntax), dataset);
-}
-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, modality, transferSyntax), dataset);
+  } : uid;
+  const dataset = buildBaseImageDataset(effectiveUid, modality);
+  if (spec.type === "vendor-warnings-image") {
+    dataset.Laterality = "";
+    dataset.PatientWeight = "0";
+  }
+  applyTagOverrides(dataset, spec.tags);
+  const meta = buildMeta(effectiveUid, modality, spec.transferSyntax);
+  applySizing(dataset, meta, spec);
+  return serializeDict(meta, dataset);
 }
 function buildFakeSignatureBuffer() {
   const buf = Buffer.alloc(200, 0);
@@ -200,36 +210,9 @@ function buildNonDicomBuffer(content = "not dicom") {
 function buildBufferForSpec(spec, uid) {
   switch (spec.type) {
     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,
-        spec.tags,
-        spec.transferSyntax
-      );
+      return buildImageBuffer(spec, uid);
     case "fake-signature":
       return buildFakeSignatureBuffer();
     case "non-dicom":