dicom-synth 1.4.0 → 1.6.0

package/README.md

@@ -381,6 +381,71 @@ 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).
+
+---
+
+## 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
@@ -392,8 +457,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
@@ -406,6 +484,24 @@ dicom-synth-generate --schema examples/default.json --out /tmp/out
 
 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
+
+# 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
+```
+
+| Flag | Effect |
+|---|---|
+| `<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
@@ -471,7 +567,9 @@ 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/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 |
@@ -480,7 +578,10 @@ 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`) |
+| `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` |
 
 ---
 
@@ -506,9 +607,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
+- **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)
 

package/bin/dicom-synth-describe.mjs

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+import { writeFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { describeDirectory } from '../dist/esm/index.js'
+
+function usage() {
+  console.error(
+    'Usage: dicom-synth-describe <dir> [--out <spec.json>] [--keep-tags <a,b,...>]\n' +
+      '\n' +
+      'Scans a DICOM tree and emits a DatasetSpec describing its shape\n' +
+      '(studies/series, per-file size, modality).\n' +
+      '\n' +
+      'By default only the shape is reproduced — no tags are copied.\n' +
+      '--keep-tags copies the named tags (DICOM keywords or 8-hex tags)\n' +
+      "verbatim; if a kept tag holds PHI, handling it is the caller's\n" +
+      "responsibility, not this tool's.",
+  )
+  process.exit(1)
+}
+
+const args = process.argv.slice(2)
+if (args.length === 0) usage()
+
+let dir
+let outPath
+let keepTags
+
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === '--out' && args[i + 1]) {
+    outPath = resolve(args[++i])
+  } else if (args[i] === '--keep-tags' && args[i + 1]) {
+    keepTags = args[++i]
+      .split(',')
+      .map((t) => t.trim())
+      .filter(Boolean)
+  } else if (args[i].startsWith('--')) {
+    console.error(`Unknown argument: ${args[i]}`)
+    usage()
+  } else if (dir === undefined) {
+    dir = resolve(args[i])
+  } else {
+    console.error(`Unexpected argument: ${args[i]}`)
+    usage()
+  }
+}
+
+if (dir === undefined) usage()
+
+let result
+try {
+  result = describeDirectory(dir, keepTags ? { keepTags } : {})
+} catch (err) {
+  console.error(`Error: ${err.message}`)
+  process.exit(1)
+}
+
+const json = `${JSON.stringify(result.spec, null, 2)}\n`
+if (outPath) {
+  writeFileSync(outPath, json)
+  console.error(`Wrote DatasetSpec to ${outPath}`)
+} else {
+  process.stdout.write(json)
+}
+
+const { dicomFiles, skipped, unknownModality } = result.stats
+console.error(
+  `Described ${dicomFiles} DICOM file(s); skipped ${skipped} non-DICOM/ungroupable file(s)`,
+)
+if (unknownModality > 0) {
+  console.error(
+    `  ${unknownModality} file(s) had an unsupported Modality — emitted as default (CT)`,
+  )
+}

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)
 }