dicom-synth 1.14.0 → 1.16.0

package/dist/esm/schema/parametric.js

@@ -97,11 +97,14 @@ function validateUidSalt(value, path) {
     );
   }
 }
-function validateSizeKbLimit(kb, path) {
-  if (kb * 1024 > MAX_PIXEL_BYTES) {
+function validateInMemoryByteLimit(bytes, path) {
+  if (bytes > MAX_PIXEL_BYTES) {
     throw new Error(`${path}: exceeds the 512 MB limit`);
   }
 }
+function validateSizeKbLimit(kb, path) {
+  validateInMemoryByteLimit(kb * 1024, path);
+}
 function validateLargeTargetBytes(value, path) {
   if (typeof value !== "number" || !Number.isInteger(value)) {
     throw new Error(`${path}: must be an integer; got ${JSON.stringify(value)}`);
@@ -139,6 +142,29 @@ function validateLargeImageEntry(e, path) {
   }
   if ("tags" in e) validateTags(e.tags, `${path}.tags`);
 }
+function validateNonDicomEntry(e, path) {
+  const sizing = ["content", "targetSizeKb", "targetBytes"].filter(
+    (f) => f in e
+  );
+  if (sizing.length > 1) {
+    throw new Error(
+      `${path}: "content", "targetSizeKb" and "targetBytes" are mutually exclusive`
+    );
+  }
+  if ("content" in e && typeof e.content !== "string") {
+    throw new Error(
+      `${path}.content: must be a string; got ${JSON.stringify(e.content)}`
+    );
+  }
+  if ("targetSizeKb" in e) {
+    validatePositiveInt(e.targetSizeKb, `${path}.targetSizeKb`);
+    validateSizeKbLimit(e.targetSizeKb, `${path}.targetSizeKb`);
+  }
+  if ("targetBytes" in e) {
+    validatePositiveInt(e.targetBytes, `${path}.targetBytes`);
+    validateInMemoryByteLimit(e.targetBytes, `${path}.targetBytes`);
+  }
+}
 function validateEnum(value, valid, path) {
   if (typeof value !== "string" || !Object.hasOwn(valid, value)) {
     throw new Error(
@@ -166,6 +192,22 @@ function validateEntry(entry, path) {
     validateLargeImageEntry(e, path);
     return e;
   }
+  if (type === "non-dicom") {
+    for (const field of [
+      "modality",
+      "rows",
+      "columns",
+      "frames",
+      "tags",
+      "violations",
+      "transferSyntax"
+    ]) {
+      if (field in e)
+        throw new Error(`${path}.${field}: not supported for type "${type}"`);
+    }
+    validateNonDicomEntry(e, path);
+    return e;
+  }
   if ("targetBytes" in e) {
     throw new Error(
       `${path}.targetBytes: only supported for type "large-image"`

package/dist/esm/schema/validate.js

@@ -28,6 +28,9 @@ var TYPE_CAPABILITIES = {
   "non-dicom": { image: false },
   dicomdir: { image: false }
 };
+function isImageType(type) {
+  return TYPE_CAPABILITIES[type].image;
+}
 var VALID_MODALITIES = {
   CT: true,
   PT: true,
@@ -86,11 +89,14 @@ function validateUidSalt(value, path) {
     );
   }
 }
-function validateSizeKbLimit(kb, path) {
-  if (kb * 1024 > MAX_PIXEL_BYTES) {
+function validateInMemoryByteLimit(bytes, path) {
+  if (bytes > MAX_PIXEL_BYTES) {
     throw new Error(`${path}: exceeds the 512 MB limit`);
   }
 }
+function validateSizeKbLimit(kb, path) {
+  validateInMemoryByteLimit(kb * 1024, path);
+}
 function validateLargeTargetBytes(value, path) {
   if (typeof value !== "number" || !Number.isInteger(value)) {
     throw new Error(`${path}: must be an integer; got ${JSON.stringify(value)}`);
@@ -128,6 +134,29 @@ function validateLargeImageEntry(e, path) {
   }
   if ("tags" in e) validateTags(e.tags, `${path}.tags`);
 }
+function validateNonDicomEntry(e, path) {
+  const sizing = ["content", "targetSizeKb", "targetBytes"].filter(
+    (f) => f in e
+  );
+  if (sizing.length > 1) {
+    throw new Error(
+      `${path}: "content", "targetSizeKb" and "targetBytes" are mutually exclusive`
+    );
+  }
+  if ("content" in e && typeof e.content !== "string") {
+    throw new Error(
+      `${path}.content: must be a string; got ${JSON.stringify(e.content)}`
+    );
+  }
+  if ("targetSizeKb" in e) {
+    validatePositiveInt(e.targetSizeKb, `${path}.targetSizeKb`);
+    validateSizeKbLimit(e.targetSizeKb, `${path}.targetSizeKb`);
+  }
+  if ("targetBytes" in e) {
+    validatePositiveInt(e.targetBytes, `${path}.targetBytes`);
+    validateInMemoryByteLimit(e.targetBytes, `${path}.targetBytes`);
+  }
+}
 function validateEnum(value, valid, path) {
   if (typeof value !== "string" || !Object.hasOwn(valid, value)) {
     throw new Error(
@@ -155,6 +184,22 @@ function validateEntry(entry, path) {
     validateLargeImageEntry(e, path);
     return e;
   }
+  if (type === "non-dicom") {
+    for (const field of [
+      "modality",
+      "rows",
+      "columns",
+      "frames",
+      "tags",
+      "violations",
+      "transferSyntax"
+    ]) {
+      if (field in e)
+        throw new Error(`${path}.${field}: not supported for type "${type}"`);
+    }
+    validateNonDicomEntry(e, path);
+    return e;
+  }
   if ("targetBytes" in e) {
     throw new Error(
       `${path}.targetBytes: only supported for type "large-image"`
@@ -362,6 +407,101 @@ function validateStudy(study, path) {
   if ("tags" in st) validateTags(st.tags, `${path}.tags`);
   return st;
 }
+function positionalName(prefix, ordinal) {
+  return `${prefix}-${String(ordinal).padStart(3, "0")}`;
+}
+var VALID_TREE_ROLES = {
+  study: true,
+  series: true
+};
+function validateNodeName(value, path) {
+  if (typeof value !== "string" || value.length === 0 || value === "." || value === ".." || /[/\\]/.test(value)) {
+    throw new Error(
+      `${path}: must be a non-empty name without path separators; got ${JSON.stringify(value)}`
+    );
+  }
+}
+function validateTreeNode(node, path, inStudy, inSeries) {
+  if (typeof node !== "object" || node === null || Array.isArray(node)) {
+    throw new Error(`${path}: must be an object`);
+  }
+  const n = node;
+  if ("children" in n) {
+    if ("type" in n) {
+      throw new Error(
+        `${path}: a node cannot have both "children" (directory) and "type" (file)`
+      );
+    }
+    if ("name" in n) validateNodeName(n.name, `${path}.name`);
+    if ("tags" in n) validateTags(n.tags, `${path}.tags`);
+    let childStudy = inStudy;
+    let childSeries = inSeries;
+    if ("role" in n) {
+      validateEnum(n.role, VALID_TREE_ROLES, `${path}.role`);
+      if (n.role === "study") {
+        if (inStudy) {
+          throw new Error(
+            `${path}.role: a study directory cannot nest inside another study`
+          );
+        }
+        childStudy = true;
+      } else {
+        if (!inStudy) {
+          throw new Error(
+            `${path}.role: a series directory requires an enclosing study-role directory`
+          );
+        }
+        if (inSeries) {
+          throw new Error(
+            `${path}.role: a series directory cannot nest inside another series`
+          );
+        }
+        childSeries = true;
+      }
+    }
+    if (!Array.isArray(n.children) || n.children.length === 0) {
+      throw new Error(`${path}.children: must be a non-empty array`);
+    }
+    validateTreeChildren(
+      n.children,
+      `${path}.children`,
+      childStudy,
+      childSeries
+    );
+    return;
+  }
+  const e = validateEntry(node, path);
+  if ("name" in n) {
+    validateNodeName(n.name, `${path}.name`);
+    if ((e.count ?? 1) > 1) {
+      throw new Error(
+        `${path}: "name" cannot be combined with count > 1 \u2014 the copies would collide on one path`
+      );
+    }
+  }
+}
+function validateTreeChildren(children, basePath, inStudy, inSeries) {
+  const claimed = /* @__PURE__ */ new Map();
+  let dirOrdinal = 0;
+  children.forEach((child, i) => {
+    const path = `${basePath}[${i}]`;
+    validateTreeNode(child, path, inStudy, inSeries);
+    const n = child;
+    let name = "name" in n ? n.name : void 0;
+    if ("children" in n) {
+      dirOrdinal++;
+      name ?? (name = positionalName("dir", dirOrdinal));
+    }
+    if (name === void 0) return;
+    const prior = claimed.get(name);
+    if (prior !== void 0) {
+      throw new Error(
+        `${path}: name "${name}" collides with ${prior} \u2014 siblings must resolve to distinct paths`
+      );
+    }
+    claimed.set(name, path);
+  });
+}
 function validateDatasetSpec(raw) {
   if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
     throw new Error("DatasetSpec: must be a JSON object");
@@ -373,11 +513,15 @@ function validateDatasetSpec(raw) {
   if ("studies" in r && !Array.isArray(r.studies)) {
     throw new Error("DatasetSpec.studies: must be an array");
   }
+  if ("tree" in r && !Array.isArray(r.tree)) {
+    throw new Error("DatasetSpec.tree: must be an array");
+  }
   const rawEntries = r.entries ?? [];
   const rawStudies = r.studies ?? [];
-  if (rawEntries.length === 0 && rawStudies.length === 0) {
+  const rawTree = r.tree ?? [];
+  if (rawEntries.length === 0 && rawStudies.length === 0 && rawTree.length === 0) {
     throw new Error(
-      'DatasetSpec: must contain at least one of "entries" or "studies" (non-empty)'
+      'DatasetSpec: must contain at least one of "entries", "studies" or "tree" (non-empty)'
     );
   }
   const entries = rawEntries.map(
@@ -386,6 +530,9 @@ function validateDatasetSpec(raw) {
   const studies = rawStudies.map(
     (study, i) => validateStudy(study, `studies[${i}]`)
   );
+  if (rawTree.length > 0) {
+    validateTreeChildren(rawTree, "tree", false, false);
+  }
   if ("seed" in r) validateSeed(r.seed, "DatasetSpec.seed");
   if ("uidSalt" in r) validateUidSalt(r.uidSalt, "DatasetSpec.uidSalt");
   if ("layout" in r) {
@@ -402,6 +549,7 @@ function validateDatasetSpec(raw) {
   return {
     ...entries.length > 0 ? { entries } : {},
     ...studies.length > 0 ? { studies } : {},
+    ...rawTree.length > 0 ? { tree: r.tree } : {},
     ...r.seed !== void 0 ? { seed: r.seed } : {},
     ...r.uidSalt !== void 0 ? { uidSalt: r.uidSalt } : {},
     ...r.layout !== void 0 ? { layout: r.layout } : {},
@@ -533,6 +681,8 @@ function validateParametricSpec(raw) {
 }
 export {
   HEX_TAG_RE,
+  isImageType,
+  positionalName,
   validateDatasetSpec,
   validateParametricSpec
 };

package/dist/esm/syntheticFixtures/generator.js

@@ -108,6 +108,14 @@ function applyTagOverrides(dataset, tags) {
     }
   }
 }
+function syncMetaWithDataset(meta, dataset) {
+  if (typeof dataset.SOPInstanceUID === "string") {
+    meta.MediaStorageSOPInstanceUID = dataset.SOPInstanceUID;
+  }
+  if (typeof dataset.SOPClassUID === "string") {
+    meta.MediaStorageSOPClassUID = dataset.SOPClassUID;
+  }
+}
 function buildMeta(uid, modality, transferSyntax = "explicit-vr-little-endian") {
   return {
     FileMetaInformationVersion: new Uint8Array([0, 1]).buffer,
@@ -194,6 +202,7 @@ function buildImageBuffer(spec, uid) {
   }
   applyTagOverrides(dataset, spec.tags);
   const meta = buildMeta(effectiveUid, modality, spec.transferSyntax);
+  syncMetaWithDataset(meta, dataset);
   applySizing(dataset, meta, spec);
   return serializeDict(meta, dataset);
 }
@@ -202,8 +211,13 @@ function buildFakeSignatureBuffer() {
   buf.write("XXXX", 128, 4, "ascii");
   return buf;
 }
-function buildNonDicomBuffer(content = "not dicom") {
-  return Buffer.from(content, "utf8");
+function sizedNonDicomBytes(spec) {
+  return spec.targetBytes ?? (spec.targetSizeKb !== void 0 ? spec.targetSizeKb * 1024 : void 0);
+}
+function buildNonDicomBuffer(spec) {
+  const bytes = sizedNonDicomBytes(spec);
+  if (bytes !== void 0) return Buffer.alloc(bytes, "not dicom ");
+  return Buffer.from(spec.content ?? "not dicom", "utf8");
 }
 function buildBufferForSpec(spec, uid) {
   switch (spec.type) {
@@ -214,7 +228,7 @@ function buildBufferForSpec(spec, uid) {
     case "fake-signature":
       return buildFakeSignatureBuffer();
     case "non-dicom":
-      return buildNonDicomBuffer(spec.content);
+      return buildNonDicomBuffer(spec);
     case "dicomdir":
       return buildDicomdirBuffer();
     case "large-image":
@@ -228,5 +242,7 @@ export {
   buildBaseImageDataset,
   buildBufferForSpec,
   buildMeta,
-  serializeDict
+  serializeDict,
+  sizedNonDicomBytes,
+  syncMetaWithDataset
 };

package/dist/esm/syntheticFixtures/streamWrite.js

@@ -94,6 +94,14 @@ function applyTagOverrides(dataset, tags) {
     }
   }
 }
+function syncMetaWithDataset(meta, dataset) {
+  if (typeof dataset.SOPInstanceUID === "string") {
+    meta.MediaStorageSOPInstanceUID = dataset.SOPInstanceUID;
+  }
+  if (typeof dataset.SOPClassUID === "string") {
+    meta.MediaStorageSOPClassUID = dataset.SOPClassUID;
+  }
+}
 function buildMeta(uid, modality, transferSyntax = "explicit-vr-little-endian") {
   return {
     FileMetaInformationVersion: new Uint8Array([0, 1]).buffer,
@@ -204,6 +212,7 @@ function writeNative(outPath, params, dims, zeroChunk) {
   const meta = buildMeta(uid, modality);
   const dataset = buildBaseImageDataset(uid, modality);
   applyTagOverrides(dataset, tags);
+  syncMetaWithDataset(meta, dataset);
   dataset.Rows = dims.rows;
   dataset.Columns = dims.columns;
   const minimalPixelBytes = dataset.PixelData.byteLength;
@@ -237,6 +246,7 @@ function writeEncapsulated(outPath, params, pixelBytes, fragmentBytes, zeroChunk
   };
   const dataset = buildBaseImageDataset(uid, modality);
   applyTagOverrides(dataset, tags);
+  syncMetaWithDataset(meta, dataset);
   dataset.PixelData = [new Uint8Array([]).buffer, new Uint8Array([0, 0]).buffer];
   dataset._vrMap = { PixelData: "OB" };
   const probe = serializeDict(meta, dataset);

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

@@ -4,6 +4,7 @@ export type DescribeOptions = {
     sizeTolerance?: number;
     preserveUids?: boolean;
     uidSalt?: string;
+    captureTree?: boolean;
 };
 export type DescribeResult = {
     spec: DatasetSpec;
@@ -11,6 +12,7 @@ export type DescribeResult = {
         dicomFiles: number;
         skipped: number;
         unknownModality: number;
+        nonDicomFiles: number;
     };
 };
 export declare function readHeaderOnly(path: string): Record<string, unknown> | null;

package/dist/types/index.d.ts

@@ -4,7 +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, SeriesInstances, SeriesSpec, StudySpec, TransferSyntax, ValidImageSpec, VendorWarningsImageSpec, ViolationClass, } from './schema/types.js';
+export type { DatasetLayout, DatasetSpec, DicomdirSpec, DicomTagOverrides, EntrySpec, FakeSignatureSpec, FileSpec, ImageSpec, InvalidUidImageSpec, LargeFileSpec, Modality, NonDicomSpec, ParametricEdgeCase, ParametricSpec, ParametricStudies, PathQuirk, Range, SeriesEntrySpec, SeriesInstances, SeriesSpec, StudySpec, TransferSyntax, TreeDirNode, TreeFileNode, TreeNode, 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

@@ -33,6 +33,8 @@ export type FakeSignatureSpec = {
 export type NonDicomSpec = {
     type: 'non-dicom';
     content?: string;
+    targetSizeKb?: number;
+    targetBytes?: number;
 };
 export type DicomdirSpec = {
     type: 'dicomdir';
@@ -68,11 +70,22 @@ export type StudySpec = {
     tags?: DicomTagOverrides;
     count?: number;
 };
+export type TreeFileNode = EntrySpec & {
+    name?: string;
+};
+export type TreeDirNode = {
+    name?: string;
+    role?: 'study' | 'series';
+    tags?: DicomTagOverrides;
+    children: TreeNode[];
+};
+export type TreeNode = TreeDirNode | TreeFileNode;
 export type DatasetLayout = 'flat' | 'hierarchical';
 export type PathQuirk = 'trailing-dot' | 'unicode' | 'deep-nesting' | 'long-name';
 export type DatasetSpec = {
     entries?: EntrySpec[];
     studies?: StudySpec[];
+    tree?: TreeNode[];
     seed?: number;
     uidSalt?: string;
     layout?: DatasetLayout;

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

@@ -1,4 +1,6 @@
-import type { DatasetSpec, ParametricSpec } from './types.js';
+import type { DatasetSpec, FileSpec, ParametricSpec } from './types.js';
+export declare function isImageType(type: FileSpec['type']): boolean;
 export declare const HEX_TAG_RE: RegExp;
+export declare function positionalName(prefix: string, ordinal: number): string;
 export declare function validateDatasetSpec(raw: unknown): DatasetSpec;
 export declare function validateParametricSpec(raw: unknown): ParametricSpec;

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

@@ -1,7 +1,9 @@
-import type { DicomTagOverrides, FileSpec, Modality, TransferSyntax } from '../schema/types.js';
+import type { DicomTagOverrides, FileSpec, Modality, NonDicomSpec, TransferSyntax } from '../schema/types.js';
 import type { UidSet } from './uid.js';
 export declare function applyTagOverrides(dataset: Record<string, unknown>, tags: DicomTagOverrides | undefined): void;
+export declare function syncMetaWithDataset(meta: Record<string, unknown>, dataset: Record<string, unknown>): void;
 export declare function buildMeta(uid: UidSet, modality: Modality, transferSyntax?: TransferSyntax): Record<string, unknown>;
 export declare function buildBaseImageDataset(uid: UidSet, modality: Modality): Record<string, unknown>;
 export declare function serializeDict(meta: Record<string, unknown>, dataset: Record<string, unknown>): Buffer;
+export declare function sizedNonDicomBytes(spec: NonDicomSpec): number | undefined;
 export declare function buildBufferForSpec(spec: FileSpec, uid: UidSet): Buffer;

package/package.json

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