dicom-synth 1.8.0 → 1.10.0

package/dist/esm/schema/limits.js

@@ -0,0 +1,7 @@
+// src/schema/limits.ts
+var MAX_PIXEL_BYTES = 512 * 1024 * 1024;
+var MAX_STREAM_BYTES = 50 * 1024 * 1024 * 1024;
+export {
+  MAX_PIXEL_BYTES,
+  MAX_STREAM_BYTES
+};

package/dist/esm/schema/parametric.js

@@ -15,11 +15,32 @@ function seededStream(seed, offset, a, b) {
   return lcg(seed * 999983 + offset + a * 1000003 + b * 7919 >>> 0);
 }
 
+// src/syntheticFixtures/tagTemplate.ts
+var TEMPLATE_VOCAB = [
+  "index",
+  "studyIndex",
+  "seriesIndex",
+  "instanceNumber"
+];
+var TEMPLATE_PART_RE = /\{\{|\}\}|\{([a-zA-Z]+)\}/g;
+function findTemplateTokens(value) {
+  const names = [];
+  for (const m of value.matchAll(TEMPLATE_PART_RE)) {
+    if (m[1] !== void 0) names.push(m[1]);
+  }
+  return names;
+}
+
+// src/schema/limits.ts
+var MAX_PIXEL_BYTES = 512 * 1024 * 1024;
+var MAX_STREAM_BYTES = 50 * 1024 * 1024 * 1024;
+
 // src/schema/validate.ts
 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 }
@@ -38,7 +59,6 @@ var VALID_TRANSFER_SYNTAXES = {
   "explicit-vr-little-endian": true,
   "implicit-vr-little-endian": true
 };
-var MAX_PIXEL_BYTES = 512 * 1024 * 1024;
 var VALID_VIOLATIONS = {
   "uid-too-long": true,
   "non-conformant-uid": true,
@@ -56,6 +76,13 @@ function validatePositiveInt(value, path) {
     );
   }
 }
+function validateNonNegativeInt(value, path) {
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
+    throw new Error(
+      `${path}: must be a non-negative integer; got ${JSON.stringify(value)}`
+    );
+  }
+}
 function validateSeed(value, path) {
   if (typeof value !== "number" || !Number.isFinite(value)) {
     throw new Error(
@@ -68,6 +95,43 @@ function validateSizeKbLimit(kb, path) {
     throw new Error(`${path}: exceeds the 512 MB limit`);
   }
 }
+function validateLargeTargetBytes(value, path) {
+  if (typeof value !== "number" || !Number.isInteger(value)) {
+    throw new Error(`${path}: must be an integer; got ${JSON.stringify(value)}`);
+  }
+  if (value <= MAX_PIXEL_BYTES) {
+    throw new Error(
+      `${path}: must exceed 512 MB \u2014 use targetSizeKb for smaller files`
+    );
+  }
+  if (value > MAX_STREAM_BYTES) {
+    throw new Error(`${path}: exceeds the 50 GB limit`);
+  }
+}
+function validateLargeImageEntry(e, path) {
+  for (const field of [
+    "rows",
+    "columns",
+    "frames",
+    "targetSizeKb",
+    "violations",
+    "transferSyntax"
+  ]) {
+    if (field in e) {
+      throw new Error(
+        `${path}.${field}: not supported for type "large-image" \u2014 use targetBytes`
+      );
+    }
+  }
+  if (!("targetBytes" in e)) {
+    throw new Error(`${path}.targetBytes: is required for type "large-image"`);
+  }
+  validateLargeTargetBytes(e.targetBytes, `${path}.targetBytes`);
+  if ("modality" in e) {
+    validateEnum(e.modality, VALID_MODALITIES, `${path}.modality`);
+  }
+  if ("tags" in e) validateTags(e.tags, `${path}.tags`);
+}
 function validateEnum(value, valid, path) {
   if (typeof value !== "string" || !Object.hasOwn(valid, value)) {
     throw new Error(
@@ -91,6 +155,15 @@ function validateEntry(entry, path) {
   const type = e.type;
   const caps = TYPE_CAPABILITIES[type];
   if ("count" in e) validatePositiveInt(e.count, `${path}.count`);
+  if (type === "large-image") {
+    validateLargeImageEntry(e, path);
+    return e;
+  }
+  if ("targetBytes" in e) {
+    throw new Error(
+      `${path}.targetBytes: only supported for type "large-image"`
+    );
+  }
   for (const field of [
     "modality",
     "rows",
@@ -150,27 +223,44 @@ function validateEntry(entry, path) {
   }
   return e;
 }
+var MODALITY_TAG = "00080060";
 function validateTags(tags, path) {
   if (typeof tags !== "object" || tags === null || Array.isArray(tags)) {
     throw new Error(`${path}: must be an object`);
   }
-  for (const key of Object.keys(tags)) {
+  for (const [key, value] of Object.entries(tags)) {
     validateTagKey(key, path);
+    const isModalityKey = key === "Modality" || key.toUpperCase() === MODALITY_TAG;
+    if (isModalityKey && typeof value === "string" && Object.hasOwn(VALID_MODALITIES, value)) {
+      throw new Error(
+        `${path}.${key}: set a preset modality (${Object.keys(VALID_MODALITIES).join("/")}) via the "modality" field, not tags \u2014 it is coupled to SOPClassUID and type-1 attributes`
+      );
+    }
+    if (typeof value === "string") {
+      for (const name of findTemplateTokens(value)) {
+        if (!TEMPLATE_VOCAB.includes(name)) {
+          throw new Error(
+            `${path}.${key}: unknown placeholder "{${name}}" \u2014 allowed: ${TEMPLATE_VOCAB.map((v) => `{${v}}`).join(", ")}`
+          );
+        }
+      }
+    }
   }
 }
-function validateRange(value, path) {
+function validateRange(value, path, options = {}) {
+  const checkInt = options.allowZero ? validateNonNegativeInt : validatePositiveInt;
   if (typeof value === "number") {
-    validatePositiveInt(value, path);
+    checkInt(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)}`
+      `${path}: must be an integer or { min, max }; got ${JSON.stringify(value)}`
     );
   }
   const r = value;
-  validatePositiveInt(r.min, `${path}.min`);
-  validatePositiveInt(r.max, `${path}.max`);
+  checkInt(r.min, `${path}.min`);
+  checkInt(r.max, `${path}.max`);
   if (r.min > r.max) {
     throw new Error(`${path}: min (${r.min}) must be \u2264 max (${r.max})`);
   }
@@ -179,6 +269,9 @@ function validateRange(value, path) {
 function rangeMax(range) {
   return typeof range === "number" ? range : range.max;
 }
+function rangeMin(range) {
+  return typeof range === "number" ? range : range.min;
+}
 function validateParametricStudies(studies, path) {
   if (typeof studies !== "object" || studies === null || Array.isArray(studies)) {
     throw new Error(`${path}: must be an object`);
@@ -192,6 +285,32 @@ function validateParametricStudies(studies, path) {
     validateRange(s.fileSizeKb, `${path}.fileSizeKb`);
     validateSizeKbLimit(rangeMax(s.fileSizeKb), `${path}.fileSizeKb`);
   }
+  if ("largeFilesPerSeries" in s) {
+    validateRange(s.largeFilesPerSeries, `${path}.largeFilesPerSeries`, {
+      allowZero: true
+    });
+    if (!("largeFileBytes" in s)) {
+      throw new Error(
+        `${path}.largeFileBytes: is required when largeFilesPerSeries is set`
+      );
+    }
+  }
+  if ("largeFileBytes" in s) {
+    if (!("largeFilesPerSeries" in s)) {
+      throw new Error(
+        `${path}.largeFilesPerSeries: is required when largeFileBytes is set`
+      );
+    }
+    validateRange(s.largeFileBytes, `${path}.largeFileBytes`);
+    validateLargeTargetBytes(
+      rangeMin(s.largeFileBytes),
+      `${path}.largeFileBytes (min)`
+    );
+    validateLargeTargetBytes(
+      rangeMax(s.largeFileBytes),
+      `${path}.largeFileBytes (max)`
+    );
+  }
   if ("modalities" in s) {
     if (!Array.isArray(s.modalities) || s.modalities.length === 0) {
       throw new Error(`${path}.modalities: must be a non-empty array`);
@@ -255,6 +374,12 @@ function sample(next, range) {
   if (typeof range === "number") return range;
   return range.min + next() % (range.max - range.min + 1);
 }
+var BYTES_PER_MB = 1024 * 1024;
+function sampleBytes(next, range) {
+  if (typeof range === "number") return range;
+  const spanMb = Math.floor((range.max - range.min) / BYTES_PER_MB) + 1;
+  return range.min + next() % spanMb * BYTES_PER_MB;
+}
 function pick(next, items) {
   return items[next() % items.length];
 }
@@ -295,6 +420,30 @@ function resolveParametricSpec(spec) {
           ...fileCount > 1 ? { count: fileCount } : {}
         });
       }
+      if (params.largeFilesPerSeries !== void 0 && params.largeFileBytes !== void 0) {
+        const largeCount = sample(next, params.largeFilesPerSeries);
+        const largeBase = {
+          type: "large-image",
+          targetBytes: 0,
+          ...modality !== void 0 ? { modality } : {}
+        };
+        if (typeof params.largeFileBytes === "number") {
+          if (largeCount > 0) {
+            entries2.push({
+              ...largeBase,
+              targetBytes: params.largeFileBytes,
+              ...largeCount > 1 ? { count: largeCount } : {}
+            });
+          }
+        } else {
+          for (let lf = 0; lf < largeCount; lf++) {
+            entries2.push({
+              ...largeBase,
+              targetBytes: sampleBytes(next, params.largeFileBytes)
+            });
+          }
+        }
+      }
       series.push({ entries: entries2 });
     }
     studies.push({

package/dist/esm/schema/validate.js

@@ -1,8 +1,29 @@
+// src/syntheticFixtures/tagTemplate.ts
+var TEMPLATE_VOCAB = [
+  "index",
+  "studyIndex",
+  "seriesIndex",
+  "instanceNumber"
+];
+var TEMPLATE_PART_RE = /\{\{|\}\}|\{([a-zA-Z]+)\}/g;
+function findTemplateTokens(value) {
+  const names = [];
+  for (const m of value.matchAll(TEMPLATE_PART_RE)) {
+    if (m[1] !== void 0) names.push(m[1]);
+  }
+  return names;
+}
+
+// src/schema/limits.ts
+var MAX_PIXEL_BYTES = 512 * 1024 * 1024;
+var MAX_STREAM_BYTES = 50 * 1024 * 1024 * 1024;
+
 // src/schema/validate.ts
 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 }
@@ -27,7 +48,6 @@ var VALID_TRANSFER_SYNTAXES = {
   "explicit-vr-little-endian": true,
   "implicit-vr-little-endian": true
 };
-var MAX_PIXEL_BYTES = 512 * 1024 * 1024;
 var VALID_VIOLATIONS = {
   "uid-too-long": true,
   "non-conformant-uid": true,
@@ -45,6 +65,13 @@ function validatePositiveInt(value, path) {
     );
   }
 }
+function validateNonNegativeInt(value, path) {
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
+    throw new Error(
+      `${path}: must be a non-negative integer; got ${JSON.stringify(value)}`
+    );
+  }
+}
 function validateSeed(value, path) {
   if (typeof value !== "number" || !Number.isFinite(value)) {
     throw new Error(
@@ -57,6 +84,43 @@ function validateSizeKbLimit(kb, path) {
     throw new Error(`${path}: exceeds the 512 MB limit`);
   }
 }
+function validateLargeTargetBytes(value, path) {
+  if (typeof value !== "number" || !Number.isInteger(value)) {
+    throw new Error(`${path}: must be an integer; got ${JSON.stringify(value)}`);
+  }
+  if (value <= MAX_PIXEL_BYTES) {
+    throw new Error(
+      `${path}: must exceed 512 MB \u2014 use targetSizeKb for smaller files`
+    );
+  }
+  if (value > MAX_STREAM_BYTES) {
+    throw new Error(`${path}: exceeds the 50 GB limit`);
+  }
+}
+function validateLargeImageEntry(e, path) {
+  for (const field of [
+    "rows",
+    "columns",
+    "frames",
+    "targetSizeKb",
+    "violations",
+    "transferSyntax"
+  ]) {
+    if (field in e) {
+      throw new Error(
+        `${path}.${field}: not supported for type "large-image" \u2014 use targetBytes`
+      );
+    }
+  }
+  if (!("targetBytes" in e)) {
+    throw new Error(`${path}.targetBytes: is required for type "large-image"`);
+  }
+  validateLargeTargetBytes(e.targetBytes, `${path}.targetBytes`);
+  if ("modality" in e) {
+    validateEnum(e.modality, VALID_MODALITIES, `${path}.modality`);
+  }
+  if ("tags" in e) validateTags(e.tags, `${path}.tags`);
+}
 function validateEnum(value, valid, path) {
   if (typeof value !== "string" || !Object.hasOwn(valid, value)) {
     throw new Error(
@@ -80,6 +144,15 @@ function validateEntry(entry, path) {
   const type = e.type;
   const caps = TYPE_CAPABILITIES[type];
   if ("count" in e) validatePositiveInt(e.count, `${path}.count`);
+  if (type === "large-image") {
+    validateLargeImageEntry(e, path);
+    return e;
+  }
+  if ("targetBytes" in e) {
+    throw new Error(
+      `${path}.targetBytes: only supported for type "large-image"`
+    );
+  }
   for (const field of [
     "modality",
     "rows",
@@ -139,12 +212,28 @@ function validateEntry(entry, path) {
   }
   return e;
 }
+var MODALITY_TAG = "00080060";
 function validateTags(tags, path) {
   if (typeof tags !== "object" || tags === null || Array.isArray(tags)) {
     throw new Error(`${path}: must be an object`);
   }
-  for (const key of Object.keys(tags)) {
+  for (const [key, value] of Object.entries(tags)) {
     validateTagKey(key, path);
+    const isModalityKey = key === "Modality" || key.toUpperCase() === MODALITY_TAG;
+    if (isModalityKey && typeof value === "string" && Object.hasOwn(VALID_MODALITIES, value)) {
+      throw new Error(
+        `${path}.${key}: set a preset modality (${Object.keys(VALID_MODALITIES).join("/")}) via the "modality" field, not tags \u2014 it is coupled to SOPClassUID and type-1 attributes`
+      );
+    }
+    if (typeof value === "string") {
+      for (const name of findTemplateTokens(value)) {
+        if (!TEMPLATE_VOCAB.includes(name)) {
+          throw new Error(
+            `${path}.${key}: unknown placeholder "{${name}}" \u2014 allowed: ${TEMPLATE_VOCAB.map((v) => `{${v}}`).join(", ")}`
+          );
+        }
+      }
+    }
   }
 }
 function validateSeries(series, path) {
@@ -225,19 +314,20 @@ function validateDatasetSpec(raw) {
     ...r.pathQuirks !== void 0 ? { pathQuirks: r.pathQuirks } : {}
   };
 }
-function validateRange(value, path) {
+function validateRange(value, path, options = {}) {
+  const checkInt = options.allowZero ? validateNonNegativeInt : validatePositiveInt;
   if (typeof value === "number") {
-    validatePositiveInt(value, path);
+    checkInt(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)}`
+      `${path}: must be an integer or { min, max }; got ${JSON.stringify(value)}`
     );
   }
   const r = value;
-  validatePositiveInt(r.min, `${path}.min`);
-  validatePositiveInt(r.max, `${path}.max`);
+  checkInt(r.min, `${path}.min`);
+  checkInt(r.max, `${path}.max`);
   if (r.min > r.max) {
     throw new Error(`${path}: min (${r.min}) must be \u2264 max (${r.max})`);
   }
@@ -246,6 +336,9 @@ function validateRange(value, path) {
 function rangeMax(range) {
   return typeof range === "number" ? range : range.max;
 }
+function rangeMin(range) {
+  return typeof range === "number" ? range : range.min;
+}
 function validateParametricStudies(studies, path) {
   if (typeof studies !== "object" || studies === null || Array.isArray(studies)) {
     throw new Error(`${path}: must be an object`);
@@ -259,6 +352,32 @@ function validateParametricStudies(studies, path) {
     validateRange(s.fileSizeKb, `${path}.fileSizeKb`);
     validateSizeKbLimit(rangeMax(s.fileSizeKb), `${path}.fileSizeKb`);
   }
+  if ("largeFilesPerSeries" in s) {
+    validateRange(s.largeFilesPerSeries, `${path}.largeFilesPerSeries`, {
+      allowZero: true
+    });
+    if (!("largeFileBytes" in s)) {
+      throw new Error(
+        `${path}.largeFileBytes: is required when largeFilesPerSeries is set`
+      );
+    }
+  }
+  if ("largeFileBytes" in s) {
+    if (!("largeFilesPerSeries" in s)) {
+      throw new Error(
+        `${path}.largeFilesPerSeries: is required when largeFileBytes is set`
+      );
+    }
+    validateRange(s.largeFileBytes, `${path}.largeFileBytes`);
+    validateLargeTargetBytes(
+      rangeMin(s.largeFileBytes),
+      `${path}.largeFileBytes (min)`
+    );
+    validateLargeTargetBytes(
+      rangeMax(s.largeFileBytes),
+      `${path}.largeFileBytes (max)`
+    );
+  }
   if ("modalities" in s) {
     if (!Array.isArray(s.modalities) || s.modalities.length === 0) {
       throw new Error(`${path}.modalities: must be a non-empty array`);

package/dist/esm/syntheticFixtures/generator.js

@@ -39,8 +39,11 @@ function buildDicomdirBuffer() {
   return buf.subarray(0, off);
 }
 
-// src/schema/validate.ts
+// src/schema/limits.ts
 var MAX_PIXEL_BYTES = 512 * 1024 * 1024;
+var MAX_STREAM_BYTES = 50 * 1024 * 1024 * 1024;
+
+// src/schema/validate.ts
 var HEX_TAG_RE = /^[0-9a-fA-F]{8}$/;
 
 // src/syntheticFixtures/generator.ts
@@ -214,8 +217,16 @@ function buildBufferForSpec(spec, uid) {
       return buildNonDicomBuffer(spec.content);
     case "dicomdir":
       return buildDicomdirBuffer();
+    case "large-image":
+      throw new Error(
+        "large-image cannot be generated in memory \u2014 use writeCollectionFromSpec (disk-only streaming)"
+      );
   }
 }
 export {
-  buildBufferForSpec
+  applyTagOverrides,
+  buildBaseImageDataset,
+  buildBufferForSpec,
+  buildMeta,
+  serializeDict
 };