dicom-synth 1.9.0 → 1.11.0

package/dist/esm/schema/validate.js

@@ -1,3 +1,19 @@
+// 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;
@@ -196,12 +212,102 @@ function validateEntry(entry, path) {
   }
   return e;
 }
+var MODALITY_TAG = "00080060";
+function validateTagValue(key, value, 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 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);
+    validateTagValue(key, value, path);
+  }
+}
+function validateArrayOfLength(value, count, path) {
+  if (!Array.isArray(value)) {
+    throw new Error(`${path}: must be an array`);
+  }
+  if (value.length !== count) {
+    throw new Error(
+      `${path}: length (${value.length}) must equal count (${count})`
+    );
+  }
+  return value;
+}
+function validateInstances(instances, path) {
+  if (typeof instances !== "object" || instances === null || Array.isArray(instances)) {
+    throw new Error(`${path}: must be an object`);
+  }
+  const inst = instances;
+  validatePositiveInt(inst.count, `${path}.count`);
+  const count = inst.count;
+  const hasKb = "targetSizeKb" in inst;
+  const hasBytes = "targetBytes" in inst;
+  if (hasKb === hasBytes) {
+    throw new Error(
+      `${path}: exactly one of "targetSizeKb" or "targetBytes" is required`
+    );
+  }
+  if (hasKb) {
+    const sizes = validateArrayOfLength(
+      inst.targetSizeKb,
+      count,
+      `${path}.targetSizeKb`
+    );
+    sizes.forEach((kb, i) => {
+      validatePositiveInt(kb, `${path}.targetSizeKb[${i}]`);
+      validateSizeKbLimit(kb, `${path}.targetSizeKb[${i}]`);
+    });
+  } else {
+    const sizes = validateArrayOfLength(
+      inst.targetBytes,
+      count,
+      `${path}.targetBytes`
+    );
+    sizes.forEach((b, i) => {
+      validateLargeTargetBytes(b, `${path}.targetBytes[${i}]`);
+    });
+  }
+  if ("modality" in inst) {
+    if (Array.isArray(inst.modality)) {
+      validateArrayOfLength(inst.modality, count, `${path}.modality`).forEach(
+        (m, i) => {
+          validateEnum(m, VALID_MODALITIES, `${path}.modality[${i}]`);
+        }
+      );
+    } else {
+      validateEnum(inst.modality, VALID_MODALITIES, `${path}.modality`);
+    }
+  }
+  if ("tags" in inst) {
+    const tags = inst.tags;
+    if (typeof tags !== "object" || tags === null || Array.isArray(tags)) {
+      throw new Error(`${path}.tags: must be an object`);
+    }
+    for (const [key, arr] of Object.entries(tags)) {
+      validateTagKey(key, `${path}.tags`);
+      validateArrayOfLength(arr, count, `${path}.tags.${key}`).forEach(
+        (value, i) => {
+          validateTagValue(key, value, `${path}.tags[${i}]`);
+        }
+      );
+    }
   }
 }
 function validateSeries(series, path) {
@@ -209,16 +315,27 @@ function validateSeries(series, path) {
     throw new Error(`${path}: must be an object`);
   }
   const s = series;
-  if (!Array.isArray(s.entries) || s.entries.length === 0) {
-    throw new Error(`${path}.entries: must be a non-empty array`);
+  const hasEntries = "entries" in s;
+  const hasInstances = "instances" in s;
+  if (hasEntries === hasInstances) {
+    throw new Error(
+      `${path}: must have exactly one of "entries" or "instances"`
+    );
   }
-  for (let i = 0; i < s.entries.length; i++) {
-    const e = validateEntry(s.entries[i], `${path}.entries[${i}]`);
-    if (!TYPE_CAPABILITIES[e.type].image) {
-      throw new Error(
-        `${path}.entries[${i}].type: "${e.type}" cannot be used inside a series \u2014 only image-generating types can be grouped`
-      );
+  if (hasEntries) {
+    if (!Array.isArray(s.entries) || s.entries.length === 0) {
+      throw new Error(`${path}.entries: must be a non-empty array`);
+    }
+    for (let i = 0; i < s.entries.length; i++) {
+      const e = validateEntry(s.entries[i], `${path}.entries[${i}]`);
+      if (!TYPE_CAPABILITIES[e.type].image) {
+        throw new Error(
+          `${path}.entries[${i}].type: "${e.type}" cannot be used inside a series \u2014 only image-generating types can be grouped`
+        );
+      }
     }
+  } else {
+    validateInstances(s.instances, `${path}.instances`);
   }
   if ("tags" in s) validateTags(s.tags, `${path}.tags`);
   return s;

package/dist/esm/syntheticFixtures/tagTemplate.js

@@ -0,0 +1,49 @@
+// src/syntheticFixtures/tagTemplate.ts
+var TEMPLATE_VOCAB = [
+  "index",
+  "studyIndex",
+  "seriesIndex",
+  "instanceNumber"
+];
+var TEMPLATE_PART_RE = /\{\{|\}\}|\{([a-zA-Z]+)\}/g;
+function escapeTagTemplate(value) {
+  return value.replace(/\{/g, "{{").replace(/\}/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;
+}
+function resolveTagTemplates(tags, context) {
+  if (!tags) return tags;
+  const resolved = {};
+  for (const [key, value] of Object.entries(tags)) {
+    resolved[key] = typeof value === "string" ? resolveString(value, context) : value;
+  }
+  return resolved;
+}
+function resolveString(value, context) {
+  return value.replace(TEMPLATE_PART_RE, (match, name) => {
+    if (name === void 0) return match === "{{" ? "{" : "}";
+    if (!TEMPLATE_VOCAB.includes(name)) {
+      throw new Error(
+        `tag template: unknown placeholder "{${name}}" \u2014 allowed: ${TEMPLATE_VOCAB.map((v) => `{${v}}`).join(", ")}`
+      );
+    }
+    const resolved = context[name];
+    if (resolved === void 0) {
+      throw new Error(
+        `tag template: placeholder "{${name}}" is not available here \u2014 it only applies inside grouped studies`
+      );
+    }
+    return String(resolved);
+  });
+}
+export {
+  TEMPLATE_VOCAB,
+  escapeTagTemplate,
+  findTemplateTokens,
+  resolveTagTemplates
+};

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

@@ -1,4 +1,5 @@
 import type { DatasetSpec, FileSpec } from '../schema/types.js';
+import { type TagContext } from '../syntheticFixtures/tagTemplate.js';
 import type { UidSet } from '../syntheticFixtures/uid.js';
 export type GeneratedFile = {
     filename: string;
@@ -17,6 +18,7 @@ export declare function generateFile(spec: FileSpec, options?: {
     seed?: number;
     padWidth?: number;
     uid?: Partial<UidSet>;
+    context?: Partial<TagContext>;
 }): Promise<GeneratedFile>;
 export declare function withResolvedSeed(spec: DatasetSpec): DatasetSpec;
 export declare function generateCollectionFromSpec(spec: DatasetSpec): AsyncGenerator<GeneratedFile>;

package/dist/types/describe/describe.d.ts

@@ -1,6 +1,7 @@
 import type { DatasetSpec } from '../schema/types.js';
 export type DescribeOptions = {
     keepTags?: string[];
+    sizeTolerance?: number;
 };
 export type DescribeResult = {
     spec: DatasetSpec;
@@ -11,4 +12,5 @@ export type DescribeResult = {
     };
 };
 export declare function readHeaderOnly(path: string): Record<string, unknown> | null;
+export declare function tagValuesEqual(a: unknown, b: unknown): boolean;
 export declare function describeDirectory(dir: string, options?: DescribeOptions): DescribeResult;

package/dist/types/index.d.ts

@@ -4,6 +4,7 @@ export { defaultPublicCasesPath, loadCaseById, loadCasesFromJson, loadDefaultCas
 export { caseCachePath, fetchPublicCaseToCache, verifySha256, } from './public-fixtures/fetch.js';
 export { MAX_PIXEL_BYTES, MAX_STREAM_BYTES } from './schema/limits.js';
 export { resolveParametricSpec } from './schema/parametric.js';
-export type { DatasetLayout, DatasetSpec, DicomdirSpec, DicomTagOverrides, FakeSignatureSpec, FileSpec, ImageSpec, InvalidUidImageSpec, LargeFileSpec, Modality, NonDicomSpec, ParametricEdgeCase, ParametricSpec, ParametricStudies, PathQuirk, Range, SeriesEntrySpec, SeriesSpec, StudySpec, TransferSyntax, ValidImageSpec, VendorWarningsImageSpec, ViolationClass, } from './schema/types.js';
+export type { DatasetLayout, DatasetSpec, DicomdirSpec, DicomTagOverrides, FakeSignatureSpec, FileSpec, ImageSpec, InvalidUidImageSpec, LargeFileSpec, Modality, NonDicomSpec, ParametricEdgeCase, ParametricSpec, ParametricStudies, PathQuirk, Range, SeriesEntrySpec, SeriesInstances, SeriesSpec, StudySpec, TransferSyntax, ValidImageSpec, VendorWarningsImageSpec, ViolationClass, } from './schema/types.js';
 export { validateDatasetSpec, validateParametricSpec, } from './schema/validate.js';
 export { type LargeFileEncoding, type LargeFileResult, type LargeImageSpec, type StreamLargeImageOptions, streamLargeImage, writeLargeImageFile, } from './syntheticFixtures/streamWrite.js';
+export { resolveTagTemplates, type TagContext, TEMPLATE_VOCAB, } from './syntheticFixtures/tagTemplate.js';

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

@@ -51,8 +51,16 @@ export type EntrySpec = FileSpec & {
 export type SeriesEntrySpec = (ImageSpec | LargeFileSpec) & {
     count?: number;
 };
+export type SeriesInstances = {
+    count: number;
+    targetSizeKb?: number[];
+    targetBytes?: number[];
+    modality?: Modality | Modality[];
+    tags?: Record<string, unknown[]>;
+};
 export type SeriesSpec = {
-    entries: SeriesEntrySpec[];
+    entries?: SeriesEntrySpec[];
+    instances?: SeriesInstances;
     tags?: DicomTagOverrides;
 };
 export type StudySpec = {

package/dist/types/syntheticFixtures/tagTemplate.d.ts

@@ -0,0 +1,11 @@
+import type { DicomTagOverrides } from '../schema/types.js';
+export type TagContext = {
+    index: number;
+    studyIndex?: number;
+    seriesIndex?: number;
+    instanceNumber?: number;
+};
+export declare const TEMPLATE_VOCAB: readonly ["index", "studyIndex", "seriesIndex", "instanceNumber"];
+export declare function escapeTagTemplate(value: string): string;
+export declare function findTemplateTokens(value: string): string[];
+export declare function resolveTagTemplates(tags: DicomTagOverrides | undefined, context: TagContext): DicomTagOverrides | undefined;

package/package.json

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