dicom-synth 1.3.0 → 1.5.0

package/dist/esm/index.js

@@ -49,7 +49,6 @@ var TYPE_CAPABILITIES = {
   "valid-image": { image: true },
   "invalid-uid-image": { image: true },
   "vendor-warnings-image": { image: true },
-  "large-image": { image: true },
   "fake-signature": { image: false },
   "non-dicom": { image: false },
   dicomdir: { image: false }
@@ -86,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(
@@ -98,16 +116,16 @@ 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`);
   for (const field of [
     "modality",
+    "rows",
+    "columns",
+    "frames",
+    "targetSizeKb",
     "tags",
     "violations",
     "transferSyntax"
@@ -116,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) {
@@ -135,14 +149,22 @@ 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}]`);
     }
   }
-  if (type === "large-image") {
+  const hasDims = "rows" in e || "columns" in e || "frames" in e;
+  if ("targetSizeKb" in e) {
+    if (hasDims) {
+      throw new Error(
+        `${path}: targetSizeKb cannot be combined with rows/columns/frames \u2014 use one sizing mechanism`
+      );
+    }
+    validatePositiveInt(e.targetSizeKb, `${path}.targetSizeKb`);
+    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`);
+    }
     validatePositiveInt(e.rows, `${path}.rows`);
     validatePositiveInt(e.columns, `${path}.columns`);
     if ("frames" in e) validatePositiveInt(e.frames, `${path}.frames`);
@@ -223,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 } : {}
   };
@@ -355,36 +458,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);
@@ -397,36 +510,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":
@@ -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);
 }
@@ -793,6 +880,80 @@ 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,
@@ -802,7 +963,9 @@ export {
   loadCaseById,
   loadCasesFromJson,
   loadDefaultCases,
+  resolveParametricSpec,
   validateDatasetSpec,
+  validateParametricSpec,
   verifySha256,
   writeCollectionFromSpec
 };