dicom-synth 1.6.0 → 1.8.0

package/README.md

@@ -13,607 +13,50 @@ pnpm add dicom-synth
 pnpm add dcmjs   # peer dependency (^0.51.1)
 ```
 
----
+## Quick start
 
-## Synthetic fixtures
-
-Generation is a three-layer API. Each layer is a thin wrapper over the one below.
-
-### Layer 1 — single file, no I/O
-
-```ts
-import { generateFile } from 'dicom-synth'
-
-const { buffer, filename, type, index } = await generateFile({ type: 'valid-image' })
-// buffer: Buffer ready to write or pass to a parser
-// filename: 'valid-image-000.dcm'
-```
-
-With options:
-
-```ts
-const { buffer } = await generateFile(
-  { type: 'valid-image', tags: { PatientID: 'P001' }, violations: ['uid-too-long'] },
-  { seed: 42, index: 7 },
-)
-```
-
-Write a single file to disk:
-
-```ts
-import { writeFileSync } from 'node:fs'
-import { generateFile } from 'dicom-synth'
-
-const { buffer, filename } = await generateFile({ type: 'valid-image' })
-writeFileSync(`./out/${filename}`, buffer)
-```
-
-### Layer 2 — collection stream, no I/O
+In-process — generate a deterministic collection and use it without touching disk:
 
 ```ts
 import { generateCollectionFromSpec } from 'dicom-synth'
 
 for await (const file of generateCollectionFromSpec({
-  entries: [
-    { type: 'valid-image', count: 10 },
-    { type: 'invalid-uid-image', count: 3 },
-  ],
+  entries: [{ type: 'valid-image', count: 5 }],
   seed: 42,
 })) {
-  console.log(file.filename, file.buffer.length)
-}
-```
-
-Files are yielded one at a time — safe to pipe without buffering the entire collection.
-
-### Layer 3 — disk writer
-
-```ts
-import { writeCollectionFromSpec } from 'dicom-synth'
-
-const manifest = await writeCollectionFromSpec(
-  { entries: [{ type: 'valid-image', count: 5 }], seed: 42 },
-  './fixtures/generated',
-)
-// manifest: Array<{ path: string; type: string; index: number }>
-```
-
----
-
-## Usage patterns
-
-### Ephemeral fixtures in tests (CI)
-
-Generate into a temp directory per test run — nothing committed, works in any CI environment:
-
-```ts
-import { mkdtemp, rm } from 'node:fs/promises'
-import { tmpdir } from 'node:os'
-import { join } from 'node:path'
-import { writeCollectionFromSpec } from 'dicom-synth'
-
-const dir = await mkdtemp(join(tmpdir(), 'synth-'))
-try {
-  await writeCollectionFromSpec(
-    { entries: [{ type: 'valid-image', count: 3 }], seed: 42 },
-    dir,
-  )
-  // run pipeline against dir
-} finally {
-  await rm(dir, { recursive: true, force: true })
-}
-```
-
-Use a fixed `seed` in CI so UID values are identical across runs and any diff is meaningful.
-
-### Static generation (commit schema, not binaries)
-
-Commit a `dataset.json` schema to your repo. Add a script to regenerate fixtures on demand:
-
-```json
-// package.json
-{
-  "scripts": {
-    "fixtures:generate": "dicom-synth-generate --schema dataset.json --out fixtures/dicom"
-  }
+  console.log(file.filename, file.buffer.length) // Buffer ready to parse or pipe
 }
 ```
 
-```bash
-pnpm fixtures:generate     # regenerate
-```
-
-Commit `dataset.json` and `.gitignore` the output directory. Fixtures are regenerated locally or in a dedicated CI job — never stored as binaries in version control.
-
-### Calling the CLI from a consumer project
-
-After installing `dicom-synth`, the `dicom-synth-generate` binary is available via your package manager:
+Or from the command line — write fixtures to a directory:
 
 ```bash
-# pnpm
-pnpm exec dicom-synth-generate --schema dataset.json --out ./out
-
-# npm / npx
-npx dicom-synth-generate --schema dataset.json --out ./out
-
-# one-off without installing
-pnpm --package=dicom-synth dlx dicom-synth-generate --schema dataset.json --out ./out
-```
-
-### In-process pipeline (no disk I/O)
-
-Use layer 2 when passing generated files directly to a parser or pipeline without writing to disk:
-
-```ts
-import { generateCollectionFromSpec, type GeneratedFile } from 'dicom-synth'
-
-const files: GeneratedFile[] = []
-for await (const file of generateCollectionFromSpec({ entries: [{ type: 'valid-image', count: 5 }] })) {
-  files.push(file)
-}
-```
-
----
-
-## Schema reference
-
-### `DatasetSpec`
-
-```ts
-import type { DatasetSpec } from 'dicom-synth'
-
-type DatasetSpec = {
-  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`
-
-An `EntrySpec` is a `FileSpec` plus an optional `count` field (how many times to generate it):
-
-```json
-{ "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`.
-
-### `FileSpec` type catalogue
-
-| Type | Description | Conformance |
-|---|---|---|
-| `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 |
-| `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 |
-
-**`non-dicom` fields:**
-
-```json
-{ "type": "non-dicom", "content": "not a dicom file" }
-```
-
-`content` defaults to `"not dicom"`.
-
-### 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": "valid-image", "rows": 512, "columns": 512, "frames": 100 }
-```
-
-`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 all image types. 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 all image types.
-
-```json
-{
-  "type": "valid-image",
-  "tags": {
-    "PatientID": "P001",
-    "PatientName": "DOE^JANE",
-    "00081030": "Research Protocol A"
-  }
-}
-```
-
-Keys are either DICOM keyword names (PascalCase, e.g. `"Modality"`) or 8-hex-character tag strings (e.g. `"00080060"`). Unknown hex tags produce a console warning and are skipped.
-
-```ts
-import type { DicomTagOverrides } from 'dicom-synth'
-```
-
-### Transfer syntax (`transferSyntax`)
-
-Available on all image types.
-
-| Value | `TransferSyntaxUID` in meta header |
-|---|---|
-| `explicit-vr-little-endian` (default) | `1.2.840.10008.1.2.1` |
-| `implicit-vr-little-endian` | `1.2.840.10008.1.2` |
-
-
-### Violation injection (`violations`)
-
-Available on all image types. Violations are applied as post-processing transforms to an otherwise valid buffer.
-
-| Violation | Effect | Detectable by dciodvfy |
-|---|---|---|
-| `uid-too-long` | Sets `SOPInstanceUID` to a 65-character value (limit is 64) | yes |
-| `non-conformant-uid` | Sets `SOPInstanceUID` to a UID with a leading-zero component | yes |
-| `vr-max-length-exceeded` | Sets `StudyDescription` to a 65-character value (LO limit is 64) | yes |
-| `missing-type1-tag` | Removes `SOPClassUID` (Type 1 mandatory attribute) | yes |
-| `missing-meta-header` | Strips the 128-byte preamble and DICM prefix | yes |
-| `malformed-sq-delimiter` | Appends a sequence delimiter tag with a non-zero length field | yes |
-
-Tag-level violations are applied before byte-level violations. Byte-level violations may produce a buffer that cannot be re-parsed.
-
-```json
-{ "type": "valid-image", "violations": ["uid-too-long", "missing-meta-header"] }
-```
-
-```ts
-import type { ViolationClass } from 'dicom-synth'
-```
-
-### Schema validation
-
-```ts
-import { validateDatasetSpec } from 'dicom-synth'
-
-const spec = validateDatasetSpec(JSON.parse(rawJson)) // throws on invalid input
-```
-
-The validator throws with a human-readable message on any structural error.
-
-### Full schema example
-
-```json
-{
-  "entries": [
-    { "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": "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" },
-    { "type": "dicomdir",           "count": 1 }
-  ],
-  "studies": [
-    {
-      "series": [
-        { "entries": [{ "type": "valid-image", "modality": "CT", "count": 50 }] },
-        { "entries": [{ "type": "valid-image", "modality": "PT", "count": 120 }] }
-      ]
-    }
-  ],
-  "seed": 42,
-  "layout": "hierarchical"
-}
-```
-
----
-
-## 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).
-
----
-
-## Describe tool
-
-`describeDirectory` scans an existing DICOM tree and emits a concrete `DatasetSpec` reproducing its shape — studies/series grouped by their UIDs, per-file size as `targetSizeKb`, and modality. This closes the loop: real tree → spec → regenerate.
-
-```ts
-import { describeDirectory, writeCollectionFromSpec } from 'dicom-synth'
-
-const { spec, stats } = describeDirectory('./real-dataset')
-// stats: { dicomFiles, skipped, unknownModality }
-await writeCollectionFromSpec(spec, './reproduced')
-```
-
-- **Shape only by default** — no tags are copied; the regenerated dataset carries fresh UIDs and synthetic identifiers, so it cannot leak PHI from the source.
-- **Opt-in tag preservation** — `keepTags` copies the named tags verbatim (some datasets are valuable for testing *precisely because* of their problematic tags):
-
-  ```ts
-  describeDirectory('./real-dataset', { keepTags: ['Manufacturer', '00080060'] })
-  ```
-
-  ⚠️ Tags are copied exactly as found. If a kept tag contains PHI, handling that PHI is the **caller's responsibility** — the tool extracts only what you name.
-- Files in a series collapse into one counted entry only when modality, size, and kept tags all match, so tag/size variation is preserved rather than flattened.
-- Non-DICOM, unparseable, or ungroupable files (missing study/series UIDs) are skipped and counted. An unsupported `Modality` is emitted as the default (CT) and counted.
-
-```ts
-import type { DescribeOptions, DescribeResult } from 'dicom-synth'
-```
-
----
-
-## CLI
-
-```bash
-# From a schema file
-dicom-synth-generate --schema dataset.json --out ./fixtures/generated
-
-# Inline schema
 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
-
-# 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
-dicom-synth-generate --schema examples/default.json --out /tmp/out
-# Wrote 3 file(s) to /tmp/out
-#   valid-image: 1
-#   invalid-uid-image: 1
-#   vendor-warnings-image: 1
 ```
 
-Schema validation errors exit with code 1 and a descriptive message.
-
-### Describe an existing tree
-
-```bash
-# Shape only (PHI-safe) — prints the DatasetSpec to stdout
-dicom-synth-describe ./real-dataset
+The full input shape (image types, sizing, modalities, grouping, violations, …) is the [schema reference](./docs/schema-reference.md).
 
-# Save to a file, and keep selected tags (caller owns any PHI in them)
-dicom-synth-describe ./real-dataset --out spec.json --keep-tags Manufacturer,00080060
-```
+## Documentation
 
-| Flag | Effect |
+| Guide | Covers |
 |---|---|
-| `<dir>` | DICOM tree to scan (required) |
-| `--out <path>` | Write the `DatasetSpec` JSON (default: stdout) |
-| `--keep-tags <a,b,...>` | Copy the named tags (keywords or 8-hex) verbatim; omit for shape only |
-
-Scan stats (DICOM/skipped/unsupported-modality counts) are written to stderr.
-
----
-
-## Public fixtures
-
-Catalog metadata lives in `data/public-cases.json`. Fetched binaries are cached at `~/.cache/dicom-synth-testcases/<sha256>/file.dcm`.
-
-### Load and fetch
-
-```ts
-import {
-  loadDefaultCases,
-  loadCaseById,
-  loadCasesFromJson,
-  defaultPublicCasesPath,
-  fetchPublicCaseToCache,
-  caseCachePath,
-} from 'dicom-synth'
-
-// Load all bundled cases
-const cases = loadDefaultCases()
-
-// Load one bundled case by id
-const record = loadCaseById(defaultPublicCasesPath(), 'pydicom-CT-small')
-
-// Load a custom catalogue
-const custom = loadCasesFromJson('./my-cases.json')
-
-// Fetch to local cache, returns the file path
-const path = await fetchPublicCaseToCache(record)
-
-// Resolve the cache path for a known SHA-256 without fetching
-const cached = caseCachePath(record.sha256)
-```
-
-### CI caching
-
-The fetch cache is keyed by SHA-256 so cached files are safe to restore across CI runs. To avoid re-downloading on every run, cache the default cache root:
-
-```yaml
-# GitHub Actions example
-- uses: actions/cache@v4
-  with:
-    path: ~/.cache/dicom-synth-testcases
-    key: dicom-public-fixtures-${{ hashFiles('node_modules/dicom-synth/dist/data/public-cases.json') }}
-```
-
-### Published CLI
-
-```bash
-pnpm --package=dicom-synth@latest dlx dicom-synth-fetch pydicom-CT-small
-```
-
-### Local development
-
-```bash
-pnpm fetch:public-case -- pydicom-CT-small
-```
-
----
-
-## Source layout
-
-| Path | Responsibility |
-|---|---|
-| `src/schema/types.ts` | All public TypeScript types (`FileSpec`, `DatasetSpec`, `ViolationClass`, etc.) |
-| `src/schema/validate.ts` | `validateDatasetSpec` / `validateParametricSpec` — validate raw JSON values against the schema |
-| `src/schema/parametric.ts` | `resolveParametricSpec` — seeded `ParametricSpec` → `DatasetSpec` resolution |
-| `src/describe/describe.ts` | `describeDirectory` — scan a DICOM tree → `DatasetSpec` |
-| `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 |
-| `src/collection/writer.ts` | Three-layer API — `generateFile`, `generateCollectionFromSpec`, `writeCollectionFromSpec` |
-| `src/public-fixtures/catalog.ts` | Load bundled public case catalogue |
-| `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`) |
-| `bin/dicom-synth-describe.mjs` | Published describe 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` |
-
----
-
-## Development
-
-```bash
-pnpm install
-pnpm build
-pnpm test
-pnpm code:quality
-```
-
-| Script | Purpose |
-|---|---|
-| `pnpm write:synthetic` | Write `examples/default.json` to `fixtures/generated` |
-| `pnpm fetch:public-case` | Fetch one public case by id |
-| `pnpm hooks:pre-commit` | Reproduce commit hook locally |
-| `pnpm hooks:pre-push` | Reproduce push hook locally |
-
-Git hooks: see [CONTRIBUTING.md](CONTRIBUTING.md).
-
----
+| [Synthetic fixtures](./docs/synthetic-fixtures.md) | The three-layer generation API (`generateFile`, `generateCollectionFromSpec`, `writeCollectionFromSpec`) and usage patterns |
+| [Schema reference](./docs/schema-reference.md) | `DatasetSpec` and every field — types, sizing, modality, grouping, layout, path quirks, tags, transfer syntax, violations, validation |
+| [Parametric designer](./docs/parametric.md) | Range-based `ParametricSpec` that resolves deterministically into a `DatasetSpec` |
+| [Describe tool](./docs/describe.md) | Scan a real DICOM tree → `DatasetSpec` (shape-only by default; opt-in tag preservation) |
+| [CLI reference](./docs/cli.md) | `dicom-synth-generate`, `dicom-synth-describe`, `dicom-synth-fetch` |
+| [Public fixtures](./docs/public-fixtures.md) | Catalog-backed fetch/cache with SHA-256 verification |
+| [Development](./docs/development.md) | Scripts, hooks, and source layout |
+| [Examples](./examples/README.md) | Runnable example specs and the shape converter |
 
 ## Future development
 
+- **Very large (streamed) files** — synthesise single DICOMs beyond the 512 MB in-memory cap via a disk-only streaming writer
 - **Dimension edge-case recipes** — documented presets for geometry pathologies (1×65535 strips, high frame counts)
 - **Per-file tag variance templating** — patterned overrides like `"PatientID": "P{index}"` for shape replication
 - **Compressed transfer syntaxes** — JPEG-LS, JPEG 2000, RLE
 - **Private fixture catalogues** — same SHA-256 fetch/cache pattern for credentials-backed sources (e.g. S3)
 
----
-
 ## License
 
 Apache-2.0

package/bin/dicom-synth-generate.mjs

@@ -5,14 +5,18 @@ import {
   generateCollectionFromSpec,
   resolveParametricSpec,
   validateDatasetSpec,
+  withResolvedSeed,
   writeCollectionFromSpec,
 } from '../dist/esm/index.js'
 
 function usage() {
   console.error(
-    '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]',
+    'Usage: dicom-synth-generate --schema <path> [--out <dir>] [--emit-spec <path>] [--dry-run]\n' +
+      '       dicom-synth-generate --schema-inline <json> [--out <dir>] [--emit-spec <path>] [--dry-run]\n' +
+      '       dicom-synth-generate --parametric <path> [--out <dir>] [--emit-spec <path>] [--dry-run]\n' +
+      '\n' +
+      'A seed is drawn when the spec omits one; pass --emit-spec to capture the\n' +
+      'effective spec (seed included) so the dataset can be re-created.',
   )
   process.exit(1)
 }
@@ -80,22 +84,27 @@ function printTypeCounts(counts) {
   }
 }
 
-if (emitSpecPath !== undefined && specSource !== '--parametric') {
-  console.error('Error: --emit-spec requires --parametric')
-  process.exit(1)
-}
+const seedProvided =
+  rawSpec !== null && typeof rawSpec === 'object' && 'seed' in rawSpec
 
 let spec
 try {
   spec =
     specSource === '--parametric'
       ? resolveParametricSpec(rawSpec)
-      : validateDatasetSpec(rawSpec)
+      : withResolvedSeed(validateDatasetSpec(rawSpec))
 } catch (err) {
   console.error(`Schema validation error: ${err.message}`)
   process.exit(1)
 }
 
+// Surface the drawn seed so a run is reproducible even without --emit-spec.
+if (!seedProvided) {
+  console.error(
+    `Generated with seed ${spec.seed} (pass --emit-spec to capture)`,
+  )
+}
+
 if (emitSpecPath !== undefined) {
   try {
     writeFileSync(emitSpecPath, `${JSON.stringify(spec, null, 2)}\n`)

package/dist/esm/collection/writer.js

@@ -1,4 +1,5 @@
 // src/collection/writer.ts
+import { randomBytes as randomBytes2 } from "node:crypto";
 import { mkdirSync as mkdirSync2 } from "node:fs";
 import { writeFile } from "node:fs/promises";
 import { dirname, resolve as resolve2 } from "node:path";
@@ -419,6 +420,48 @@ async function generateFile(spec, options) {
     index
   };
 }
+function hashString(s) {
+  let h = 2166136261;
+  for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return h >>> 0;
+}
+var UNICODE_TOKENS = ["\xE9", "\xFC", "\xF1", "\u65E5", "\u2122", "\u03A9"];
+var NEST_DEPTH = 8;
+var LONG_NAME_TARGET = 200;
+function applyPathQuirks(relativePath, quirks) {
+  const segments = relativePath.split("/");
+  let dirs = segments.slice(0, -1);
+  const leaf = segments[segments.length - 1];
+  const dot = leaf.lastIndexOf(".");
+  let stem = dot > 0 ? leaf.slice(0, dot) : leaf;
+  const ext = dot > 0 ? leaf.slice(dot) : "";
+  const unicode = (s) => `${s}${UNICODE_TOKENS[hashString(s) % UNICODE_TOKENS.length]}`;
+  const has = (q) => quirks.includes(q);
+  if (has("deep-nesting")) {
+    dirs = [...dirs, ...Array.from({ length: NEST_DEPTH }, (_, i) => `d${i}`)];
+  }
+  if (has("unicode")) {
+    dirs = dirs.map(unicode);
+    stem = unicode(stem);
+  }
+  if (has("long-name")) {
+    const pad = (s) => s.length < LONG_NAME_TARGET ? s + "x".repeat(LONG_NAME_TARGET - s.length) : s;
+    stem = pad(stem);
+    if (dirs.length > 0) {
+      const last = dirs.length - 1;
+      dirs = dirs.map((d, i) => i === last ? pad(d) : d);
+    }
+  }
+  let newLeaf = stem + ext;
+  if (has("trailing-dot")) {
+    if (dirs.length > 0) dirs = dirs.map((d) => `${d}.`);
+    else newLeaf += ".";
+  }
+  return { relativePath: [...dirs, newLeaf].join("/"), filename: newLeaf };
+}
 function hierarchicalName(studyOrdinal, seriesIndex, instanceNumber) {
   const pad3 = (n) => String(n).padStart(3, "0");
   const name = `${String(instanceNumber).padStart(5, "0")}.dcm`;
@@ -427,21 +470,28 @@ function hierarchicalName(studyOrdinal, seriesIndex, instanceNumber) {
     relativePath: `study-${pad3(studyOrdinal + 1)}/series-${pad3(seriesIndex + 1)}/${name}`
   };
 }
+function withResolvedSeed(spec) {
+  return spec.seed === void 0 ? { ...spec, seed: randomBytes2(4).readUInt32BE(0) } : spec;
+}
 async function* generateCollectionFromSpec(spec) {
   const flatEntries = spec.entries ?? [];
   const studies = spec.studies ?? [];
   const totalFiles = entryCount(flatEntries) + studyFileCount(studies);
   const padWidth = String(totalFiles).length;
   const hierarchical = spec.layout === "hierarchical";
+  const quirks = spec.pathQuirks ?? [];
+  const decorate = (file) => quirks.length === 0 ? file : { ...file, ...applyPathQuirks(file.relativePath, quirks) };
   let globalIndex = 0;
   for (const entry of flatEntries) {
     const { count = 1, ...fileSpec } = entry;
     for (let i = 0; i < count; i++) {
-      yield generateFile(fileSpec, {
-        index: globalIndex,
-        seed: spec.seed,
-        padWidth
-      });
+      yield decorate(
+        await generateFile(fileSpec, {
+          index: globalIndex,
+          seed: spec.seed,
+          padWidth
+        })
+      );
       globalIndex++;
     }
   }
@@ -473,14 +523,16 @@ async function* generateCollectionFromSpec(spec) {
                 uid: { study: studyUid, series: seriesUid }
               }
             );
-            yield hierarchical ? {
-              ...file,
-              ...hierarchicalName(
-                studyOrdinal,
-                seriesIndex,
-                instanceNumber
-              )
-            } : file;
+            yield decorate(
+              hierarchical ? {
+                ...file,
+                ...hierarchicalName(
+                  studyOrdinal,
+                  seriesIndex,
+                  instanceNumber
+                )
+              } : file
+            );
             globalIndex++;
           }
         }
@@ -509,5 +561,6 @@ async function writeCollectionFromSpec(spec, outDir) {
 export {
   generateCollectionFromSpec,
   generateFile,
+  withResolvedSeed,
   writeCollectionFromSpec
 };

package/dist/esm/describe/describe.js

@@ -40,6 +40,12 @@ var VALID_LAYOUTS = {
   flat: true,
   hierarchical: true
 };
+var VALID_PATH_QUIRKS = {
+  "trailing-dot": true,
+  unicode: true,
+  "deep-nesting": true,
+  "long-name": true
+};
 var VALID_TRANSFER_SYNTAXES = {
   "explicit-vr-little-endian": true,
   "implicit-vr-little-endian": true
@@ -226,11 +232,20 @@ function validateDatasetSpec(raw) {
   if ("layout" in r) {
     validateEnum(r.layout, VALID_LAYOUTS, "DatasetSpec.layout");
   }
+  if ("pathQuirks" in r) {
+    if (!Array.isArray(r.pathQuirks)) {
+      throw new Error("DatasetSpec.pathQuirks: must be an array");
+    }
+    for (const [i, q] of r.pathQuirks.entries()) {
+      validateEnum(q, VALID_PATH_QUIRKS, `DatasetSpec.pathQuirks[${i}]`);
+    }
+  }
   return {
     ...entries.length > 0 ? { entries } : {},
     ...studies.length > 0 ? { studies } : {},
     ...r.seed !== void 0 ? { seed: r.seed } : {},
-    ...r.layout !== void 0 ? { layout: r.layout } : {}
+    ...r.layout !== void 0 ? { layout: r.layout } : {},
+    ...r.pathQuirks !== void 0 ? { pathQuirks: r.pathQuirks } : {}
   };
 }
 

package/dist/esm/index.js

@@ -1,4 +1,5 @@
 // src/collection/writer.ts
+import { randomBytes as randomBytes2 } from "node:crypto";
 import { mkdirSync as mkdirSync2 } from "node:fs";
 import { writeFile } from "node:fs/promises";
 import { dirname, resolve as resolve2 } from "node:path";
@@ -63,6 +64,12 @@ var VALID_LAYOUTS = {
   flat: true,
   hierarchical: true
 };
+var VALID_PATH_QUIRKS = {
+  "trailing-dot": true,
+  unicode: true,
+  "deep-nesting": true,
+  "long-name": true
+};
 var VALID_TRANSFER_SYNTAXES = {
   "explicit-vr-little-endian": true,
   "implicit-vr-little-endian": true
@@ -249,11 +256,20 @@ function validateDatasetSpec(raw) {
   if ("layout" in r) {
     validateEnum(r.layout, VALID_LAYOUTS, "DatasetSpec.layout");
   }
+  if ("pathQuirks" in r) {
+    if (!Array.isArray(r.pathQuirks)) {
+      throw new Error("DatasetSpec.pathQuirks: must be an array");
+    }
+    for (const [i, q] of r.pathQuirks.entries()) {
+      validateEnum(q, VALID_PATH_QUIRKS, `DatasetSpec.pathQuirks[${i}]`);
+    }
+  }
   return {
     ...entries.length > 0 ? { entries } : {},
     ...studies.length > 0 ? { studies } : {},
     ...r.seed !== void 0 ? { seed: r.seed } : {},
-    ...r.layout !== void 0 ? { layout: r.layout } : {}
+    ...r.layout !== void 0 ? { layout: r.layout } : {},
+    ...r.pathQuirks !== void 0 ? { pathQuirks: r.pathQuirks } : {}
   };
 }
 function validateRange(value, path) {
@@ -720,6 +736,48 @@ async function generateFile(spec, options) {
     index
   };
 }
+function hashString(s) {
+  let h = 2166136261;
+  for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return h >>> 0;
+}
+var UNICODE_TOKENS = ["\xE9", "\xFC", "\xF1", "\u65E5", "\u2122", "\u03A9"];
+var NEST_DEPTH = 8;
+var LONG_NAME_TARGET = 200;
+function applyPathQuirks(relativePath, quirks) {
+  const segments = relativePath.split("/");
+  let dirs = segments.slice(0, -1);
+  const leaf = segments[segments.length - 1];
+  const dot = leaf.lastIndexOf(".");
+  let stem = dot > 0 ? leaf.slice(0, dot) : leaf;
+  const ext = dot > 0 ? leaf.slice(dot) : "";
+  const unicode = (s) => `${s}${UNICODE_TOKENS[hashString(s) % UNICODE_TOKENS.length]}`;
+  const has = (q) => quirks.includes(q);
+  if (has("deep-nesting")) {
+    dirs = [...dirs, ...Array.from({ length: NEST_DEPTH }, (_, i) => `d${i}`)];
+  }
+  if (has("unicode")) {
+    dirs = dirs.map(unicode);
+    stem = unicode(stem);
+  }
+  if (has("long-name")) {
+    const pad = (s) => s.length < LONG_NAME_TARGET ? s + "x".repeat(LONG_NAME_TARGET - s.length) : s;
+    stem = pad(stem);
+    if (dirs.length > 0) {
+      const last = dirs.length - 1;
+      dirs = dirs.map((d, i) => i === last ? pad(d) : d);
+    }
+  }
+  let newLeaf = stem + ext;
+  if (has("trailing-dot")) {
+    if (dirs.length > 0) dirs = dirs.map((d) => `${d}.`);
+    else newLeaf += ".";
+  }
+  return { relativePath: [...dirs, newLeaf].join("/"), filename: newLeaf };
+}
 function hierarchicalName(studyOrdinal, seriesIndex, instanceNumber) {
   const pad3 = (n) => String(n).padStart(3, "0");
   const name = `${String(instanceNumber).padStart(5, "0")}.dcm`;
@@ -728,21 +786,28 @@ function hierarchicalName(studyOrdinal, seriesIndex, instanceNumber) {
     relativePath: `study-${pad3(studyOrdinal + 1)}/series-${pad3(seriesIndex + 1)}/${name}`
   };
 }
+function withResolvedSeed(spec) {
+  return spec.seed === void 0 ? { ...spec, seed: randomBytes2(4).readUInt32BE(0) } : spec;
+}
 async function* generateCollectionFromSpec(spec) {
   const flatEntries = spec.entries ?? [];
   const studies = spec.studies ?? [];
   const totalFiles = entryCount(flatEntries) + studyFileCount(studies);
   const padWidth = String(totalFiles).length;
   const hierarchical = spec.layout === "hierarchical";
+  const quirks = spec.pathQuirks ?? [];
+  const decorate = (file) => quirks.length === 0 ? file : { ...file, ...applyPathQuirks(file.relativePath, quirks) };
   let globalIndex = 0;
   for (const entry of flatEntries) {
     const { count = 1, ...fileSpec } = entry;
     for (let i = 0; i < count; i++) {
-      yield generateFile(fileSpec, {
-        index: globalIndex,
-        seed: spec.seed,
-        padWidth
-      });
+      yield decorate(
+        await generateFile(fileSpec, {
+          index: globalIndex,
+          seed: spec.seed,
+          padWidth
+        })
+      );
       globalIndex++;
     }
   }
@@ -774,14 +839,16 @@ async function* generateCollectionFromSpec(spec) {
                 uid: { study: studyUid, series: seriesUid }
               }
             );
-            yield hierarchical ? {
-              ...file,
-              ...hierarchicalName(
-                studyOrdinal,
-                seriesIndex,
-                instanceNumber
-              )
-            } : file;
+            yield decorate(
+              hierarchical ? {
+                ...file,
+                ...hierarchicalName(
+                  studyOrdinal,
+                  seriesIndex,
+                  instanceNumber
+                )
+              } : file
+            );
             globalIndex++;
           }
         }
@@ -1024,7 +1091,7 @@ async function fetchPublicCaseToCache(record, cacheRoot = DEFAULT_CACHE_ROOT) {
 }
 
 // src/schema/parametric.ts
-import { randomBytes as randomBytes2 } from "node:crypto";
+import { randomBytes as randomBytes3 } from "node:crypto";
 function sample(next, range) {
   if (typeof range === "number") return range;
   return range.min + next() % (range.max - range.min + 1);
@@ -1037,7 +1104,7 @@ function fraction(next) {
 }
 function resolveParametricSpec(spec) {
   const validated = validateParametricSpec(spec);
-  const seed = validated.seed ?? randomBytes2(4).readUInt32BE(0);
+  const seed = validated.seed ?? randomBytes3(4).readUInt32BE(0);
   const next = seededStream(seed, PARAMETRIC_STREAM_OFFSET, 0, 0);
   const params = validated.studies;
   const studies = [];
@@ -1110,5 +1177,6 @@ export {
   validateDatasetSpec,
   validateParametricSpec,
   verifySha256,
+  withResolvedSeed,
   writeCollectionFromSpec
 };

package/dist/esm/schema/validate.js

@@ -17,6 +17,12 @@ var VALID_LAYOUTS = {
   flat: true,
   hierarchical: true
 };
+var VALID_PATH_QUIRKS = {
+  "trailing-dot": true,
+  unicode: true,
+  "deep-nesting": true,
+  "long-name": true
+};
 var VALID_TRANSFER_SYNTAXES = {
   "explicit-vr-little-endian": true,
   "implicit-vr-little-endian": true
@@ -203,11 +209,20 @@ function validateDatasetSpec(raw) {
   if ("layout" in r) {
     validateEnum(r.layout, VALID_LAYOUTS, "DatasetSpec.layout");
   }
+  if ("pathQuirks" in r) {
+    if (!Array.isArray(r.pathQuirks)) {
+      throw new Error("DatasetSpec.pathQuirks: must be an array");
+    }
+    for (const [i, q] of r.pathQuirks.entries()) {
+      validateEnum(q, VALID_PATH_QUIRKS, `DatasetSpec.pathQuirks[${i}]`);
+    }
+  }
   return {
     ...entries.length > 0 ? { entries } : {},
     ...studies.length > 0 ? { studies } : {},
     ...r.seed !== void 0 ? { seed: r.seed } : {},
-    ...r.layout !== void 0 ? { layout: r.layout } : {}
+    ...r.layout !== void 0 ? { layout: r.layout } : {},
+    ...r.pathQuirks !== void 0 ? { pathQuirks: r.pathQuirks } : {}
   };
 }
 function validateRange(value, path) {

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

@@ -18,5 +18,6 @@ export declare function generateFile(spec: FileSpec, options?: {
     padWidth?: number;
     uid?: Partial<UidSet>;
 }): Promise<GeneratedFile>;
+export declare function withResolvedSeed(spec: DatasetSpec): DatasetSpec;
 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,7 +1,7 @@
-export { type CollectionManifest, type GeneratedFile, generateCollectionFromSpec, generateFile, writeCollectionFromSpec, } from './collection/writer.js';
+export { type CollectionManifest, type GeneratedFile, generateCollectionFromSpec, generateFile, withResolvedSeed, writeCollectionFromSpec, } from './collection/writer.js';
 export { type DescribeOptions, type DescribeResult, describeDirectory, } from './describe/describe.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 { resolveParametricSpec } from './schema/parametric.js';
-export type { DatasetLayout, DatasetSpec, DicomdirSpec, DicomTagOverrides, FakeSignatureSpec, FileSpec, ImageSpec, InvalidUidImageSpec, Modality, NonDicomSpec, ParametricEdgeCase, ParametricSpec, ParametricStudies, Range, SeriesEntrySpec, SeriesSpec, StudySpec, TransferSyntax, ValidImageSpec, VendorWarningsImageSpec, ViolationClass, } from './schema/types.js';
+export type { DatasetLayout, DatasetSpec, DicomdirSpec, DicomTagOverrides, FakeSignatureSpec, FileSpec, ImageSpec, InvalidUidImageSpec, Modality, NonDicomSpec, ParametricEdgeCase, ParametricSpec, ParametricStudies, PathQuirk, Range, SeriesEntrySpec, SeriesSpec, StudySpec, TransferSyntax, ValidImageSpec, VendorWarningsImageSpec, ViolationClass, } from './schema/types.js';
 export { validateDatasetSpec, validateParametricSpec, } from './schema/validate.js';

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

@@ -55,11 +55,13 @@ export type StudySpec = {
     count?: number;
 };
 export type DatasetLayout = 'flat' | 'hierarchical';
+export type PathQuirk = 'trailing-dot' | 'unicode' | 'deep-nesting' | 'long-name';
 export type DatasetSpec = {
     entries?: EntrySpec[];
     studies?: StudySpec[];
     seed?: number;
     layout?: DatasetLayout;
+    pathQuirks?: PathQuirk[];
 };
 export type Range = number | {
     min: number;

package/package.json

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