dicom-synth 1.4.0 → 1.6.0

package/dist/esm/index.js

@@ -85,6 +85,25 @@ function validatePositiveInt(value, path) {
     );
   }
 }
+function validateSeed(value, path) {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw new Error(
+      `${path}: must be a finite number; got ${JSON.stringify(value)}`
+    );
+  }
+}
+function validateSizeKbLimit(kb, path) {
+  if (kb * 1024 > MAX_PIXEL_BYTES) {
+    throw new Error(`${path}: exceeds the 512 MB limit`);
+  }
+}
+function validateEnum(value, valid, path) {
+  if (typeof value !== "string" || !Object.hasOwn(valid, value)) {
+    throw new Error(
+      `${path}: must be one of ${Object.keys(valid).join(", ")}; got ${JSON.stringify(value)}`
+    );
+  }
+}
 function validateTagKey(key, path) {
   if (!HEX_TAG_RE.test(key) && !KEYWORD_RE.test(key)) {
     throw new Error(
@@ -97,11 +116,7 @@ function validateEntry(entry, path) {
     throw new Error(`${path}: must be an object`);
   }
   const e = entry;
-  if (typeof e.type !== "string" || !Object.hasOwn(TYPE_CAPABILITIES, e.type)) {
-    throw new Error(
-      `${path}.type: must be one of ${Object.keys(TYPE_CAPABILITIES).join(", ")}; got ${JSON.stringify(e.type)}`
-    );
-  }
+  validateEnum(e.type, TYPE_CAPABILITIES, `${path}.type`);
   const type = e.type;
   const caps = TYPE_CAPABILITIES[type];
   if ("count" in e) validatePositiveInt(e.count, `${path}.count`);
@@ -119,18 +134,14 @@ function validateEntry(entry, path) {
       throw new Error(`${path}.${field}: not supported for type "${type}"`);
   }
   if ("transferSyntax" in e) {
-    if (!Object.hasOwn(VALID_TRANSFER_SYNTAXES, e.transferSyntax)) {
-      throw new Error(
-        `${path}.transferSyntax: must be one of ${Object.keys(VALID_TRANSFER_SYNTAXES).join(", ")}`
-      );
-    }
+    validateEnum(
+      e.transferSyntax,
+      VALID_TRANSFER_SYNTAXES,
+      `${path}.transferSyntax`
+    );
   }
   if ("modality" in e) {
-    if (typeof e.modality !== "string" || !Object.hasOwn(VALID_MODALITIES, e.modality)) {
-      throw new Error(
-        `${path}.modality: must be one of ${Object.keys(VALID_MODALITIES).join(", ")}; got ${JSON.stringify(e.modality)}`
-      );
-    }
+    validateEnum(e.modality, VALID_MODALITIES, `${path}.modality`);
   }
   if ("tags" in e) validateTags(e.tags, `${path}.tags`);
   if ("violations" in e) {
@@ -138,11 +149,7 @@ function validateEntry(entry, path) {
       throw new Error(`${path}.violations: must be an array`);
     }
     for (const [i, v] of e.violations.entries()) {
-      if (typeof v !== "string" || !Object.hasOwn(VALID_VIOLATIONS, v)) {
-        throw new Error(
-          `${path}.violations[${i}]: must be one of ${Object.keys(VALID_VIOLATIONS).join(", ")}; got ${JSON.stringify(v)}`
-        );
-      }
+      validateEnum(v, VALID_VIOLATIONS, `${path}.violations[${i}]`);
     }
   }
   const hasDims = "rows" in e || "columns" in e || "frames" in e;
@@ -153,9 +160,7 @@ function validateEntry(entry, path) {
       );
     }
     validatePositiveInt(e.targetSizeKb, `${path}.targetSizeKb`);
-    if (e.targetSizeKb * 1024 > MAX_PIXEL_BYTES) {
-      throw new Error(`${path}.targetSizeKb: exceeds the 512 MB limit`);
-    }
+    validateSizeKbLimit(e.targetSizeKb, `${path}.targetSizeKb`);
   } else if (hasDims) {
     if (!("rows" in e) || !("columns" in e)) {
       throw new Error(`${path}: rows and columns must be provided together`);
@@ -240,23 +245,104 @@ function validateDatasetSpec(raw) {
   const studies = rawStudies.map(
     (study, i) => validateStudy(study, `studies[${i}]`)
   );
-  if ("seed" in r) {
-    if (typeof r.seed !== "number" || !Number.isFinite(r.seed)) {
+  if ("seed" in r) validateSeed(r.seed, "DatasetSpec.seed");
+  if ("layout" in r) {
+    validateEnum(r.layout, VALID_LAYOUTS, "DatasetSpec.layout");
+  }
+  return {
+    ...entries.length > 0 ? { entries } : {},
+    ...studies.length > 0 ? { studies } : {},
+    ...r.seed !== void 0 ? { seed: r.seed } : {},
+    ...r.layout !== void 0 ? { layout: r.layout } : {}
+  };
+}
+function validateRange(value, path) {
+  if (typeof value === "number") {
+    validatePositiveInt(value, path);
+    return value;
+  }
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error(
+      `${path}: must be a positive integer or { min, max }; got ${JSON.stringify(value)}`
+    );
+  }
+  const r = value;
+  validatePositiveInt(r.min, `${path}.min`);
+  validatePositiveInt(r.max, `${path}.max`);
+  if (r.min > r.max) {
+    throw new Error(`${path}: min (${r.min}) must be \u2264 max (${r.max})`);
+  }
+  return value;
+}
+function rangeMax(range) {
+  return typeof range === "number" ? range : range.max;
+}
+function validateParametricStudies(studies, path) {
+  if (typeof studies !== "object" || studies === null || Array.isArray(studies)) {
+    throw new Error(`${path}: must be an object`);
+  }
+  const s = studies;
+  for (const field of ["count", "seriesPerStudy", "filesPerSeries"]) {
+    if (!(field in s)) throw new Error(`${path}.${field}: is required`);
+    validateRange(s[field], `${path}.${field}`);
+  }
+  if ("fileSizeKb" in s) {
+    validateRange(s.fileSizeKb, `${path}.fileSizeKb`);
+    validateSizeKbLimit(rangeMax(s.fileSizeKb), `${path}.fileSizeKb`);
+  }
+  if ("modalities" in s) {
+    if (!Array.isArray(s.modalities) || s.modalities.length === 0) {
+      throw new Error(`${path}.modalities: must be a non-empty array`);
+    }
+    for (const [i, m] of s.modalities.entries()) {
+      validateEnum(m, VALID_MODALITIES, `${path}.modalities[${i}]`);
+    }
+  }
+  if ("tags" in s) validateTags(s.tags, `${path}.tags`);
+  return s;
+}
+function validateEdgeCase(edgeCase, path) {
+  const e = validateEntry(edgeCase, path);
+  if ("frequency" in e) {
+    if ("count" in e) {
       throw new Error(
-        `DatasetSpec.seed: must be a finite number; got ${JSON.stringify(r.seed)}`
+        `${path}: frequency cannot be combined with count \u2014 frequency draws the count at resolution time`
       );
     }
-  }
-  if ("layout" in r) {
-    if (typeof r.layout !== "string" || !Object.hasOwn(VALID_LAYOUTS, r.layout)) {
+    const f = e.frequency;
+    if (typeof f !== "number" || !(f >= 0 && f <= 1)) {
       throw new Error(
-        `DatasetSpec.layout: must be one of ${Object.keys(VALID_LAYOUTS).join(", ")}; got ${JSON.stringify(r.layout)}`
+        `${path}.frequency: must be a number between 0 and 1; got ${JSON.stringify(f)}`
       );
     }
   }
+  return e;
+}
+function validateParametricSpec(raw) {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    throw new Error("ParametricSpec: must be a JSON object");
+  }
+  const r = raw;
+  if (!("studies" in r)) {
+    throw new Error("ParametricSpec.studies: is required");
+  }
+  const studies = validateParametricStudies(r.studies, "studies");
+  const edgeCases = [];
+  if ("edgeCases" in r) {
+    if (!Array.isArray(r.edgeCases)) {
+      throw new Error("ParametricSpec.edgeCases: must be an array");
+    }
+    for (const [i, e] of r.edgeCases.entries()) {
+      edgeCases.push(validateEdgeCase(e, `edgeCases[${i}]`));
+    }
+  }
+  if ("seed" in r) validateSeed(r.seed, "ParametricSpec.seed");
+  if ("layout" in r) {
+    validateEnum(r.layout, VALID_LAYOUTS, "ParametricSpec.layout");
+  }
   return {
-    ...entries.length > 0 ? { entries } : {},
-    ...studies.length > 0 ? { studies } : {},
+    studies,
+    ...edgeCases.length > 0 ? { edgeCases } : {},
     ...r.seed !== void 0 ? { seed: r.seed } : {},
     ...r.layout !== void 0 ? { layout: r.layout } : {}
   };
@@ -457,6 +543,7 @@ function seededUid(next, role) {
   return formatUid(next(), next(), role);
 }
 var GROUP_STREAM_OFFSET = 2654435769;
+var PARAMETRIC_STREAM_OFFSET = 2246822507;
 function seededStream(seed, offset, a, b) {
   return lcg(seed * 999983 + offset + a * 1000003 + b * 7919 >>> 0);
 }
@@ -721,11 +808,153 @@ async function writeCollectionFromSpec(spec, outDir) {
   return manifest;
 }
 
+// src/describe/describe.ts
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+var dcmjsAny2 = dcmjs;
+var HEX_TAG_RE2 = /^[0-9a-fA-F]{8}$/;
+var SUPPORTED_MODALITIES = /* @__PURE__ */ new Set(["CT", "PT", "MR", "CR"]);
+function buildHexToKeyword() {
+  const map = /* @__PURE__ */ new Map();
+  const nm = dcmjsAny2.data.DicomMetaDictionary.nameMap;
+  if (!nm) return map;
+  for (const [keyword, info] of Object.entries(nm)) {
+    if (info?.tag) {
+      const hex = info.tag.replace(/[(,)]/g, "").toUpperCase();
+      if (hex.length === 8) map.set(hex, keyword);
+    }
+  }
+  return map;
+}
+function resolveKeepTags(keepTags) {
+  const nameMap = dcmjsAny2.data.DicomMetaDictionary.nameMap;
+  let hexToKeyword;
+  return keepTags.map((tag) => {
+    if (HEX_TAG_RE2.test(tag)) {
+      hexToKeyword ?? (hexToKeyword = buildHexToKeyword());
+      const keyword = hexToKeyword.get(tag.toUpperCase());
+      if (!keyword) {
+        throw new Error(`describe: unknown hex tag "${tag}"`);
+      }
+      return keyword;
+    }
+    if (nameMap && !Object.hasOwn(nameMap, tag)) {
+      throw new Error(`describe: unknown tag keyword "${tag}"`);
+    }
+    return tag;
+  });
+}
+function* walkFiles(dir) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      yield* walkFiles(path);
+    } else if (entry.isFile()) {
+      yield path;
+    }
+  }
+}
+function parseFile(path) {
+  try {
+    const buf = readFileSync(path);
+    const ab = buf.buffer.slice(
+      buf.byteOffset,
+      buf.byteOffset + buf.byteLength
+    );
+    const parsed = dcmjsAny2.data.DicomMessage.readFile(ab);
+    const record = dcmjsAny2.data.DicomMetaDictionary.naturalizeDataset(
+      parsed.dict
+    );
+    return { record, size: buf.byteLength };
+  } catch {
+    return null;
+  }
+}
+function extractTags(record, keepKeywords) {
+  const tags = {};
+  let found = false;
+  for (const keyword of keepKeywords) {
+    const value = record[keyword];
+    if (value !== void 0) {
+      tags[keyword] = value;
+      found = true;
+    }
+  }
+  return found ? tags : void 0;
+}
+function describeDirectory(dir, options = {}) {
+  const keepKeywords = options.keepTags ? resolveKeepTags(options.keepTags) : [];
+  const studies = /* @__PURE__ */ new Map();
+  const stats = { dicomFiles: 0, skipped: 0, unknownModality: 0 };
+  for (const path of [...walkFiles(dir)].sort()) {
+    const parsed = parseFile(path);
+    const studyUid = parsed?.record.StudyInstanceUID;
+    const seriesUid = parsed?.record.SeriesInstanceUID;
+    if (!parsed || typeof studyUid !== "string" || typeof seriesUid !== "string") {
+      stats.skipped++;
+      continue;
+    }
+    const { record } = parsed;
+    stats.dicomFiles++;
+    let modality;
+    if (typeof record.Modality === "string") {
+      if (SUPPORTED_MODALITIES.has(record.Modality)) {
+        modality = record.Modality;
+      } else {
+        stats.unknownModality++;
+      }
+    }
+    const sizeKb = Math.max(1, Math.round(parsed.size / 1024));
+    const tags = keepKeywords.length ? extractTags(record, keepKeywords) : void 0;
+    let study = studies.get(studyUid);
+    if (!study) {
+      study = /* @__PURE__ */ new Map();
+      studies.set(studyUid, study);
+    }
+    let series = study.get(seriesUid);
+    if (!series) {
+      series = /* @__PURE__ */ new Map();
+      study.set(seriesUid, series);
+    }
+    const collapseKey = JSON.stringify([modality ?? null, sizeKb, tags ?? null]);
+    const existing = series.get(collapseKey);
+    if (existing) {
+      existing.count++;
+    } else {
+      series.set(collapseKey, {
+        modality,
+        targetSizeKb: sizeKb,
+        tags,
+        count: 1
+      });
+    }
+  }
+  const studySpecs = [...studies.values()].map((study) => {
+    const seriesSpecs = [...study.values()].map((series) => {
+      const entries = [...series.values()].map((acc) => ({
+        type: "valid-image",
+        ...acc.modality !== void 0 ? { modality: acc.modality } : {},
+        targetSizeKb: acc.targetSizeKb,
+        ...acc.tags !== void 0 ? { tags: acc.tags } : {},
+        ...acc.count > 1 ? { count: acc.count } : {}
+      }));
+      return { entries };
+    });
+    return { series: seriesSpecs };
+  });
+  if (studySpecs.length === 0) {
+    throw new Error(`describe: no DICOM series found in ${dir}`);
+  }
+  const spec = { studies: studySpecs, layout: "hierarchical" };
+  validateDatasetSpec(spec);
+  return { spec, stats };
+}
+
 // src/public-fixtures/catalog.ts
-import { readFileSync } from "node:fs";
-import { dirname as dirname2, join } from "node:path";
+import { readFileSync as readFileSync2 } from "node:fs";
+import { dirname as dirname2, join as join2 } from "node:path";
 import { fileURLToPath } from "node:url";
-var bundledCatalogPath = join(
+var bundledCatalogPath = join2(
   dirname2(fileURLToPath(import.meta.url)),
   "../../data/public-cases.json"
 );
@@ -736,7 +965,7 @@ function loadDefaultCases() {
   return loadCasesFromJson(defaultPublicCasesPath());
 }
 function loadCasesFromJson(casesJsonPath) {
-  const j = JSON.parse(readFileSync(casesJsonPath, "utf8"));
+  const j = JSON.parse(readFileSync2(casesJsonPath, "utf8"));
   if (!Array.isArray(j.cases)) {
     throw new Error(
       `Invalid catalog in ${casesJsonPath}: expected "cases" array`
@@ -754,12 +983,12 @@ function loadCaseById(casesJsonPath, id) {
 
 // src/public-fixtures/fetch.ts
 import { createHash } from "node:crypto";
-import { existsSync, mkdirSync as mkdirSync3, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "node:fs";
+import { existsSync, mkdirSync as mkdirSync3, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "node:fs";
 import { homedir } from "node:os";
-import { join as join2 } from "node:path";
-var DEFAULT_CACHE_ROOT = join2(homedir(), ".cache", "dicom-synth-testcases");
+import { join as join3 } from "node:path";
+var DEFAULT_CACHE_ROOT = join3(homedir(), ".cache", "dicom-synth-testcases");
 function caseCachePath(sha256, root = DEFAULT_CACHE_ROOT) {
-  return join2(root, sha256, "file.dcm");
+  return join3(root, sha256, "file.dcm");
 }
 function verifySha256(buffer, expected) {
   const h = createHash("sha256").update(buffer).digest("hex");
@@ -777,11 +1006,11 @@ async function fetchPublicCaseToCache(record, cacheRoot = DEFAULT_CACHE_ROOT) {
   }
   const dest = caseCachePath(record.sha256, cacheRoot);
   if (existsSync(dest)) {
-    const buf2 = readFileSync2(dest);
+    const buf2 = readFileSync3(dest);
     verifySha256(buf2, record.sha256);
     return dest;
   }
-  mkdirSync3(join2(cacheRoot, record.sha256), { recursive: true });
+  mkdirSync3(join3(cacheRoot, record.sha256), { recursive: true });
   const res = await fetch(record.source.url);
   if (!res.ok) {
     throw new Error(
@@ -793,16 +1022,93 @@ async function fetchPublicCaseToCache(record, cacheRoot = DEFAULT_CACHE_ROOT) {
   writeFileSync2(dest, buf);
   return dest;
 }
+
+// src/schema/parametric.ts
+import { randomBytes as randomBytes2 } from "node:crypto";
+function sample(next, range) {
+  if (typeof range === "number") return range;
+  return range.min + next() % (range.max - range.min + 1);
+}
+function pick(next, items) {
+  return items[next() % items.length];
+}
+function fraction(next) {
+  return next() / 4294967296;
+}
+function resolveParametricSpec(spec) {
+  const validated = validateParametricSpec(spec);
+  const seed = validated.seed ?? randomBytes2(4).readUInt32BE(0);
+  const next = seededStream(seed, PARAMETRIC_STREAM_OFFSET, 0, 0);
+  const params = validated.studies;
+  const studies = [];
+  let totalFiles = 0;
+  const studyCount = sample(next, params.count);
+  for (let st = 0; st < studyCount; st++) {
+    const seriesCount = sample(next, params.seriesPerStudy);
+    const series = [];
+    for (let se = 0; se < seriesCount; se++) {
+      const fileCount = sample(next, params.filesPerSeries);
+      totalFiles += fileCount;
+      const modality = params.modalities ? pick(next, params.modalities) : void 0;
+      const base = {
+        type: "valid-image",
+        ...modality !== void 0 ? { modality } : {}
+      };
+      const entries2 = [];
+      if (params.fileSizeKb !== void 0 && typeof params.fileSizeKb !== "number") {
+        for (let f = 0; f < fileCount; f++) {
+          entries2.push({
+            ...base,
+            targetSizeKb: sample(next, params.fileSizeKb)
+          });
+        }
+      } else {
+        entries2.push({
+          ...base,
+          ...params.fileSizeKb !== void 0 ? { targetSizeKb: params.fileSizeKb } : {},
+          ...fileCount > 1 ? { count: fileCount } : {}
+        });
+      }
+      series.push({ entries: entries2 });
+    }
+    studies.push({
+      series,
+      ...params.tags !== void 0 ? { tags: params.tags } : {}
+    });
+  }
+  const entries = [];
+  for (const edgeCase of validated.edgeCases ?? []) {
+    const { frequency, ...entry } = edgeCase;
+    if (frequency === void 0) {
+      entries.push(entry);
+      continue;
+    }
+    let drawn = 0;
+    for (let i = 0; i < totalFiles; i++) {
+      if (fraction(next) < frequency) drawn++;
+    }
+    if (drawn > 0) entries.push({ ...entry, count: drawn });
+  }
+  return {
+    ...entries.length > 0 ? { entries } : {},
+    studies,
+    seed,
+    ...validated.layout !== void 0 ? { layout: validated.layout } : {}
+  };
+}
 export {
   caseCachePath,
   defaultPublicCasesPath,
+  describeDirectory,
   fetchPublicCaseToCache,
   generateCollectionFromSpec,
   generateFile,
   loadCaseById,
   loadCasesFromJson,
   loadDefaultCases,
+  resolveParametricSpec,
   validateDatasetSpec,
+  validateParametricSpec,
   verifySha256,
   writeCollectionFromSpec
 };