dicom-synth 1.1.0 → 1.3.0

package/dist/esm/schema/validate.js

@@ -1,12 +1,22 @@
 // src/schema/validate.ts
 var TYPE_CAPABILITIES = {
-  "valid-ct": { tags: true, violations: true, transferSyntax: true },
-  "invalid-uid-ct": { tags: true, violations: true, transferSyntax: true },
-  "vendor-warnings-ct": { tags: true, violations: true, transferSyntax: true },
-  "large-ct": { tags: true, violations: true, transferSyntax: true },
-  "fake-signature": { tags: false, violations: false, transferSyntax: false },
-  "non-dicom": { tags: false, violations: false, transferSyntax: false },
-  dicomdir: { tags: false, violations: false, transferSyntax: false }
+  "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 }
+};
+var VALID_MODALITIES = {
+  CT: true,
+  PT: true,
+  MR: true,
+  CR: true
+};
+var VALID_LAYOUTS = {
+  flat: true,
+  hierarchical: true
 };
 var VALID_TRANSFER_SYNTAXES = {
   "explicit-vr-little-endian": true,
@@ -23,6 +33,13 @@ var VALID_VIOLATIONS = {
 };
 var HEX_TAG_RE = /^[0-9a-fA-F]{8}$/;
 var KEYWORD_RE = /^[A-Z][A-Za-z0-9]*$/;
+function validatePositiveInt(value, path) {
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 1) {
+    throw new Error(
+      `${path}: must be a positive integer; got ${JSON.stringify(value)}`
+    );
+  }
+}
 function validateTagKey(key, path) {
   if (!HEX_TAG_RE.test(key) && !KEYWORD_RE.test(key)) {
     throw new Error(
@@ -42,37 +59,31 @@ function validateEntry(entry, path) {
   }
   const type = e.type;
   const caps = TYPE_CAPABILITIES[type];
-  if ("count" in e) {
-    if (typeof e.count !== "number" || !Number.isInteger(e.count) || e.count < 1) {
-      throw new Error(
-        `${path}.count: must be a positive integer; got ${JSON.stringify(e.count)}`
-      );
-    }
+  if ("count" in e) validatePositiveInt(e.count, `${path}.count`);
+  for (const field of [
+    "modality",
+    "tags",
+    "violations",
+    "transferSyntax"
+  ]) {
+    if (!caps.image && field in e)
+      throw new Error(`${path}.${field}: not supported for type "${type}"`);
   }
   if ("transferSyntax" in e) {
-    if (!caps.transferSyntax) {
-      throw new Error(
-        `${path}.transferSyntax: not supported for type "${type}"`
-      );
-    }
     if (!Object.hasOwn(VALID_TRANSFER_SYNTAXES, e.transferSyntax)) {
       throw new Error(
         `${path}.transferSyntax: must be one of ${Object.keys(VALID_TRANSFER_SYNTAXES).join(", ")}`
       );
     }
   }
-  if (!caps.tags && "tags" in e)
-    throw new Error(`${path}.tags: not supported for type "${type}"`);
-  if (!caps.violations && "violations" in e)
-    throw new Error(`${path}.violations: not supported for type "${type}"`);
-  if ("tags" in e) {
-    if (typeof e.tags !== "object" || e.tags === null || Array.isArray(e.tags)) {
-      throw new Error(`${path}.tags: must be an object`);
-    }
-    for (const key of Object.keys(e.tags)) {
-      validateTagKey(key, `${path}.tags`);
+  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)}`
+      );
     }
   }
+  if ("tags" in e) validateTags(e.tags, `${path}.tags`);
   if ("violations" in e) {
     if (!Array.isArray(e.violations)) {
       throw new Error(`${path}.violations: must be an array`);
@@ -85,18 +96,10 @@ function validateEntry(entry, path) {
       }
     }
   }
-  if (type === "large-ct") {
-    if (typeof e.rows !== "number" || !Number.isInteger(e.rows) || e.rows < 1) {
-      throw new Error(`${path}.rows: must be a positive integer`);
-    }
-    if (typeof e.columns !== "number" || !Number.isInteger(e.columns) || e.columns < 1) {
-      throw new Error(`${path}.columns: must be a positive integer`);
-    }
-    if ("frames" in e) {
-      if (typeof e.frames !== "number" || !Number.isInteger(e.frames) || e.frames < 1) {
-        throw new Error(`${path}.frames: must be a positive integer`);
-      }
-    }
+  if (type === "large-image") {
+    validatePositiveInt(e.rows, `${path}.rows`);
+    validatePositiveInt(e.columns, `${path}.columns`);
+    if ("frames" in e) validatePositiveInt(e.frames, `${path}.frames`);
     const rows = e.rows;
     const columns = e.columns;
     const frames = typeof e.frames === "number" ? e.frames : 1;
@@ -108,20 +111,72 @@ function validateEntry(entry, path) {
   }
   return e;
 }
+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)) {
+    validateTagKey(key, path);
+  }
+}
+function validateSeries(series, path) {
+  if (typeof series !== "object" || series === null || Array.isArray(series)) {
+    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`);
+  }
+  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 ("tags" in s) validateTags(s.tags, `${path}.tags`);
+  return s;
+}
+function validateStudy(study, path) {
+  if (typeof study !== "object" || study === null || Array.isArray(study)) {
+    throw new Error(`${path}: must be an object`);
+  }
+  const st = study;
+  if (!Array.isArray(st.series) || st.series.length === 0) {
+    throw new Error(`${path}.series: must be a non-empty array`);
+  }
+  for (let i = 0; i < st.series.length; i++) {
+    validateSeries(st.series[i], `${path}.series[${i}]`);
+  }
+  if ("count" in st) validatePositiveInt(st.count, `${path}.count`);
+  if ("tags" in st) validateTags(st.tags, `${path}.tags`);
+  return st;
+}
 function validateDatasetSpec(raw) {
   if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
     throw new Error("DatasetSpec: must be a JSON object");
   }
   const r = raw;
-  if (!Array.isArray(r.entries)) {
+  if ("entries" in r && !Array.isArray(r.entries)) {
     throw new Error("DatasetSpec.entries: must be an array");
   }
-  if (r.entries.length === 0) {
-    throw new Error("DatasetSpec.entries: must not be empty");
+  if ("studies" in r && !Array.isArray(r.studies)) {
+    throw new Error("DatasetSpec.studies: must be an array");
+  }
+  const rawEntries = r.entries ?? [];
+  const rawStudies = r.studies ?? [];
+  if (rawEntries.length === 0 && rawStudies.length === 0) {
+    throw new Error(
+      'DatasetSpec: must contain at least one of "entries" or "studies" (non-empty)'
+    );
   }
-  const entries = r.entries.map(
+  const entries = rawEntries.map(
     (entry, i) => validateEntry(entry, `entries[${i}]`)
   );
+  const studies = rawStudies.map(
+    (study, i) => validateStudy(study, `studies[${i}]`)
+  );
   if ("seed" in r) {
     if (typeof r.seed !== "number" || !Number.isFinite(r.seed)) {
       throw new Error(
@@ -129,9 +184,18 @@ function validateDatasetSpec(raw) {
       );
     }
   }
+  if ("layout" in r) {
+    if (typeof r.layout !== "string" || !Object.hasOwn(VALID_LAYOUTS, r.layout)) {
+      throw new Error(
+        `DatasetSpec.layout: must be one of ${Object.keys(VALID_LAYOUTS).join(", ")}; got ${JSON.stringify(r.layout)}`
+      );
+    }
+  }
   return {
-    entries,
-    ...r.seed !== void 0 ? { seed: r.seed } : {}
+    ...entries.length > 0 ? { entries } : {},
+    ...studies.length > 0 ? { studies } : {},
+    ...r.seed !== void 0 ? { seed: r.seed } : {},
+    ...r.layout !== void 0 ? { layout: r.layout } : {}
   };
 }
 export {

package/dist/esm/syntheticFixtures/generator.js

@@ -44,7 +44,35 @@ var MAX_PIXEL_BYTES = 512 * 1024 * 1024;
 var HEX_TAG_RE = /^[0-9a-fA-F]{8}$/;
 
 // src/syntheticFixtures/generator.ts
-var CT_SOP_CLASS = "1.2.840.10008.5.1.4.1.1.2";
+var MODALITY_PRESETS = {
+  CT: {
+    sopClassUid: "1.2.840.10008.5.1.4.1.1.2",
+    // CT Image Storage
+    attributes: {}
+  },
+  PT: {
+    sopClassUid: "1.2.840.10008.5.1.4.1.1.128",
+    // PET Image Storage
+    attributes: {
+      Units: "BQML",
+      DecayCorrection: "NONE",
+      CorrectedImage: ["ATTN", "DECY"]
+    }
+  },
+  MR: {
+    sopClassUid: "1.2.840.10008.5.1.4.1.1.4",
+    // MR Image Storage
+    attributes: {
+      ScanningSequence: "SE",
+      SequenceVariant: "NONE"
+    }
+  },
+  CR: {
+    sopClassUid: "1.2.840.10008.5.1.4.1.1.1",
+    // CR Image Storage
+    attributes: {}
+  }
+};
 var TRANSFER_SYNTAX_UID = {
   "explicit-vr-little-endian": "1.2.840.10008.1.2.1",
   "implicit-vr-little-endian": "1.2.840.10008.1.2"
@@ -77,22 +105,23 @@ function applyTagOverrides(dataset, tags) {
     }
   }
 }
-function buildMeta(uid, transferSyntax = "explicit-vr-little-endian") {
+function buildMeta(uid, modality, transferSyntax = "explicit-vr-little-endian") {
   return {
     FileMetaInformationVersion: new Uint8Array([0, 1]).buffer,
-    MediaStorageSOPClassUID: CT_SOP_CLASS,
+    MediaStorageSOPClassUID: MODALITY_PRESETS[modality].sopClassUid,
     MediaStorageSOPInstanceUID: uid.sop,
     TransferSyntaxUID: TRANSFER_SYNTAX_UID[transferSyntax],
     ImplementationClassUID: "1.2.3.4",
     ImplementationVersionName: "SYNTH"
   };
 }
-function buildBaseCtDataset(uid) {
+function buildBaseImageDataset(uid, modality) {
+  const preset = MODALITY_PRESETS[modality];
   return {
     PatientName: "SYNTH^SUBJECT",
     PatientID: "SYNTH_PID",
-    Modality: "CT",
-    SOPClassUID: CT_SOP_CLASS,
+    Modality: modality,
+    SOPClassUID: preset.sopClassUid,
     SOPInstanceUID: uid.sop,
     SeriesInstanceUID: uid.series,
     StudyInstanceUID: uid.study,
@@ -109,7 +138,8 @@ function buildBaseCtDataset(uid) {
     PixelData: new Uint8Array([0, 0]).buffer,
     // Declares PixelData's VR explicitly — without it dcmjs logs
     // "No value representation given for PixelData" and falls back to OW anyway.
-    _vrMap: { PixelData: "OW" }
+    _vrMap: { PixelData: "OW" },
+    ...preset.attributes
   };
 }
 function serializeDict(meta, dataset) {
@@ -123,36 +153,36 @@ function serializeDict(meta, dataset) {
   );
   return Buffer.from(dicomDict.write({ allowInvalidVRLength: true }));
 }
-function buildValidCtBuffer(uid, tags, transferSyntax) {
-  const dataset = buildBaseCtDataset(uid);
+function buildValidImageBuffer(uid, modality, tags, transferSyntax) {
+  const dataset = buildBaseImageDataset(uid, modality);
   applyTagOverrides(dataset, tags);
-  return serializeDict(buildMeta(uid, transferSyntax), dataset);
+  return serializeDict(buildMeta(uid, modality, transferSyntax), dataset);
 }
-function buildInvalidUidCtBuffer(uid, tags, transferSyntax) {
+function buildInvalidUidImageBuffer(uid, modality, tags, transferSyntax) {
   const invalidUid = {
     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 = buildBaseCtDataset(invalidUid);
+  const dataset = buildBaseImageDataset(invalidUid, modality);
   applyTagOverrides(dataset, tags);
-  return serializeDict(buildMeta(invalidUid, transferSyntax), dataset);
+  return serializeDict(buildMeta(invalidUid, modality, transferSyntax), dataset);
 }
-function buildVendorCtBuffer(uid, tags, transferSyntax) {
-  const dataset = buildBaseCtDataset(uid);
+function buildVendorWarningsImageBuffer(uid, modality, tags, transferSyntax) {
+  const dataset = buildBaseImageDataset(uid, modality);
   dataset.Laterality = "";
   dataset.PatientWeight = "0";
   applyTagOverrides(dataset, tags);
-  return serializeDict(buildMeta(uid, transferSyntax), dataset);
+  return serializeDict(buildMeta(uid, modality, transferSyntax), dataset);
 }
-function buildLargeCtBuffer(uid, rows, columns, frames, tags, transferSyntax) {
-  const dataset = buildBaseCtDataset(uid);
+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, transferSyntax), dataset);
+  return serializeDict(buildMeta(uid, modality, transferSyntax), dataset);
 }
 function buildFakeSignatureBuffer() {
   const buf = Buffer.alloc(200, 0);
@@ -164,15 +194,31 @@ function buildNonDicomBuffer(content = "not dicom") {
 }
 function buildBufferForSpec(spec, uid) {
   switch (spec.type) {
-    case "valid-ct":
-      return buildValidCtBuffer(uid, spec.tags, spec.transferSyntax);
-    case "invalid-uid-ct":
-      return buildInvalidUidCtBuffer(uid, spec.tags, spec.transferSyntax);
-    case "vendor-warnings-ct":
-      return buildVendorCtBuffer(uid, spec.tags, spec.transferSyntax);
-    case "large-ct":
-      return buildLargeCtBuffer(
+    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,

package/dist/esm/syntheticFixtures/uid.js

@@ -18,6 +18,33 @@ function randomUid(role) {
 function seededUid(next, role) {
   return formatUid(next(), next(), role);
 }
+var GROUP_STREAM_OFFSET = 2654435769;
+function seededStream(seed, offset, a, b) {
+  return lcg(seed * 999983 + offset + a * 1000003 + b * 7919 >>> 0);
+}
+function makeGroupUidGenerator(seed) {
+  if (seed === void 0) {
+    return {
+      study: () => randomUid("study"),
+      series: () => randomUid("series")
+    };
+  }
+  return {
+    study: (studyIndex) => seededUid(
+      seededStream(seed, GROUP_STREAM_OFFSET, studyIndex + 1, 0),
+      "study"
+    ),
+    series: (studyIndex, seriesIndex) => seededUid(
+      seededStream(
+        seed,
+        GROUP_STREAM_OFFSET,
+        studyIndex + 1,
+        seriesIndex + 1
+      ),
+      "series"
+    )
+  };
+}
 function makeUidGenerator(seed) {
   if (seed === void 0) {
     return () => ({
@@ -27,7 +54,7 @@ function makeUidGenerator(seed) {
     });
   }
   return (fileIndex) => {
-    const next = lcg(seed * 999983 + fileIndex * 1000003 >>> 0);
+    const next = seededStream(seed, 0, fileIndex, 0);
     return {
       study: seededUid(next, "study"),
       series: seededUid(next, "series"),
@@ -36,5 +63,6 @@ function makeUidGenerator(seed) {
   };
 }
 export {
+  makeGroupUidGenerator,
   makeUidGenerator
 };

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

@@ -1,6 +1,8 @@
 import type { DatasetSpec, FileSpec } from '../schema/types.js';
+import type { UidSet } from '../syntheticFixtures/uid.js';
 export type GeneratedFile = {
     filename: string;
+    relativePath: string;
     buffer: Buffer;
     type: FileSpec['type'];
     index: number;
@@ -14,6 +16,7 @@ export declare function generateFile(spec: FileSpec, options?: {
     index?: number;
     seed?: number;
     padWidth?: number;
+    uid?: Partial<UidSet>;
 }): Promise<GeneratedFile>;
 export declare function generateCollectionFromSpec(spec: DatasetSpec): AsyncGenerator<GeneratedFile>;
 export declare function writeCollectionFromSpec(spec: DatasetSpec, outDir: string): Promise<CollectionManifest>;

package/dist/types/index.d.ts

@@ -1,5 +1,5 @@
 export { type CollectionManifest, type GeneratedFile, generateCollectionFromSpec, generateFile, writeCollectionFromSpec, } from './collection/writer.js';
 export { defaultPublicCasesPath, loadCaseById, loadCasesFromJson, loadDefaultCases, type PublicCaseRecord, type PublicCaseSource, } from './public-fixtures/catalog.js';
 export { caseCachePath, fetchPublicCaseToCache, verifySha256, } from './public-fixtures/fetch.js';
-export type { DatasetSpec, DicomdirSpec, DicomTagOverrides, FakeSignatureSpec, FileSpec, InvalidUidCtSpec, LargeCtSpec, NonDicomSpec, TransferSyntax, ValidCtSpec, VendorCtSpec, ViolationClass, } from './schema/types.js';
+export type { DatasetLayout, DatasetSpec, DicomdirSpec, DicomTagOverrides, FakeSignatureSpec, FileSpec, ImageSpec, InvalidUidImageSpec, LargeImageSpec, Modality, NonDicomSpec, SeriesEntrySpec, SeriesSpec, StudySpec, TransferSyntax, ValidImageSpec, VendorWarningsImageSpec, ViolationClass, } from './schema/types.js';
 export { validateDatasetSpec } from './schema/validate.js';

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

@@ -7,22 +7,24 @@ export type DicomTagOverrides = {
     [tag: string]: unknown;
 };
 export type ViolationClass = 'uid-too-long' | 'non-conformant-uid' | 'missing-meta-header' | 'malformed-sq-delimiter' | 'vr-max-length-exceeded' | 'missing-type1-tag';
-type BaseCtSpec = {
+export type Modality = 'CT' | 'PT' | 'MR' | 'CR';
+type BaseImageSpec = {
+    modality?: Modality;
     tags?: DicomTagOverrides;
     transferSyntax?: TransferSyntax;
     violations?: ViolationClass[];
 };
-export type ValidCtSpec = BaseCtSpec & {
-    type: 'valid-ct';
+export type ValidImageSpec = BaseImageSpec & {
+    type: 'valid-image';
 };
-export type InvalidUidCtSpec = BaseCtSpec & {
-    type: 'invalid-uid-ct';
+export type InvalidUidImageSpec = BaseImageSpec & {
+    type: 'invalid-uid-image';
 };
-export type VendorCtSpec = BaseCtSpec & {
-    type: 'vendor-warnings-ct';
+export type VendorWarningsImageSpec = BaseImageSpec & {
+    type: 'vendor-warnings-image';
 };
-export type LargeCtSpec = BaseCtSpec & {
-    type: 'large-ct';
+export type LargeImageSpec = BaseImageSpec & {
+    type: 'large-image';
     rows: number;
     columns: number;
     frames?: number;
@@ -37,12 +39,28 @@ export type NonDicomSpec = {
 export type DicomdirSpec = {
     type: 'dicomdir';
 };
-export type FileSpec = ValidCtSpec | InvalidUidCtSpec | VendorCtSpec | LargeCtSpec | FakeSignatureSpec | NonDicomSpec | DicomdirSpec;
+export type ImageSpec = ValidImageSpec | InvalidUidImageSpec | VendorWarningsImageSpec | LargeImageSpec;
+export type FileSpec = ImageSpec | FakeSignatureSpec | NonDicomSpec | DicomdirSpec;
 export type EntrySpec = FileSpec & {
     count?: number;
 };
+export type SeriesEntrySpec = ImageSpec & {
+    count?: number;
+};
+export type SeriesSpec = {
+    entries: SeriesEntrySpec[];
+    tags?: DicomTagOverrides;
+};
+export type StudySpec = {
+    series: SeriesSpec[];
+    tags?: DicomTagOverrides;
+    count?: number;
+};
+export type DatasetLayout = 'flat' | 'hierarchical';
 export type DatasetSpec = {
-    entries: EntrySpec[];
+    entries?: EntrySpec[];
+    studies?: StudySpec[];
     seed?: number;
+    layout?: DatasetLayout;
 };
 export {};

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

@@ -3,5 +3,10 @@ export type UidSet = {
     series: string;
     sop: string;
 };
+export type GroupUidGenerator = {
+    study: (studyIndex: number) => string;
+    series: (studyIndex: number, seriesIndex: number) => string;
+};
+export declare function makeGroupUidGenerator(seed?: number): GroupUidGenerator;
 export type UidGenerator = (fileIndex: number) => UidSet;
 export declare function makeUidGenerator(seed?: number): UidGenerator;

package/package.json

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