dicom-synth 1.10.0 → 1.12.0

package/dist/esm/schema/parametric.js

@@ -2,7 +2,7 @@
 import { randomBytes as randomBytes2 } from "node:crypto";
 
 // src/syntheticFixtures/uid.ts
-import { randomBytes } from "node:crypto";
+import { createHash, randomBytes } from "node:crypto";
 function lcg(seed) {
   let s = seed >>> 0;
   return () => {
@@ -90,6 +90,13 @@ function validateSeed(value, path) {
     );
   }
 }
+function validateUidSalt(value, path) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error(
+      `${path}: must be a non-empty string; got ${JSON.stringify(value)}`
+    );
+  }
+}
 function validateSizeKbLimit(kb, path) {
   if (kb * 1024 > MAX_PIXEL_BYTES) {
     throw new Error(`${path}: exceeds the 512 MB limit`);
@@ -224,27 +231,30 @@ 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, 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(", ")}`
-          );
-        }
-      }
-    }
+    validateTagValue(key, value, path);
   }
 }
 function validateRange(value, path, options = {}) {
@@ -358,6 +368,7 @@ function validateParametricSpec(raw) {
     }
   }
   if ("seed" in r) validateSeed(r.seed, "ParametricSpec.seed");
+  if ("uidSalt" in r) validateUidSalt(r.uidSalt, "ParametricSpec.uidSalt");
   if ("layout" in r) {
     validateEnum(r.layout, VALID_LAYOUTS, "ParametricSpec.layout");
   }
@@ -365,6 +376,7 @@ function validateParametricSpec(raw) {
     studies,
     ...edgeCases.length > 0 ? { edgeCases } : {},
     ...r.seed !== void 0 ? { seed: r.seed } : {},
+    ...r.uidSalt !== void 0 ? { uidSalt: r.uidSalt } : {},
     ...r.layout !== void 0 ? { layout: r.layout } : {}
   };
 }
@@ -468,6 +480,9 @@ function resolveParametricSpec(spec) {
     ...entries.length > 0 ? { entries } : {},
     studies,
     seed,
+    // Pass an explicit salt through; when absent, UIDs derive from `seed` so the
+    // resolved spec stays deterministic ("same seed → identical resolved spec").
+    ...validated.uidSalt !== void 0 ? { uidSalt: validated.uidSalt } : {},
     ...validated.layout !== void 0 ? { layout: validated.layout } : {}
   };
 }

package/dist/esm/schema/validate.js

@@ -79,6 +79,13 @@ function validateSeed(value, path) {
     );
   }
 }
+function validateUidSalt(value, path) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error(
+      `${path}: must be a non-empty string; got ${JSON.stringify(value)}`
+    );
+  }
+}
 function validateSizeKbLimit(kb, path) {
   if (kb * 1024 > MAX_PIXEL_BYTES) {
     throw new Error(`${path}: exceeds the 512 MB limit`);
@@ -213,26 +220,100 @@ 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, 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`
+    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 (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(", ")}`
-          );
+  }
+  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}]`);
         }
-      }
+      );
     }
   }
 }
@@ -241,16 +322,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;
@@ -295,6 +387,7 @@ function validateDatasetSpec(raw) {
     (study, i) => validateStudy(study, `studies[${i}]`)
   );
   if ("seed" in r) validateSeed(r.seed, "DatasetSpec.seed");
+  if ("uidSalt" in r) validateUidSalt(r.uidSalt, "DatasetSpec.uidSalt");
   if ("layout" in r) {
     validateEnum(r.layout, VALID_LAYOUTS, "DatasetSpec.layout");
   }
@@ -310,6 +403,7 @@ function validateDatasetSpec(raw) {
     ...entries.length > 0 ? { entries } : {},
     ...studies.length > 0 ? { studies } : {},
     ...r.seed !== void 0 ? { seed: r.seed } : {},
+    ...r.uidSalt !== void 0 ? { uidSalt: r.uidSalt } : {},
     ...r.layout !== void 0 ? { layout: r.layout } : {},
     ...r.pathQuirks !== void 0 ? { pathQuirks: r.pathQuirks } : {}
   };
@@ -425,6 +519,7 @@ function validateParametricSpec(raw) {
     }
   }
   if ("seed" in r) validateSeed(r.seed, "ParametricSpec.seed");
+  if ("uidSalt" in r) validateUidSalt(r.uidSalt, "ParametricSpec.uidSalt");
   if ("layout" in r) {
     validateEnum(r.layout, VALID_LAYOUTS, "ParametricSpec.layout");
   }
@@ -432,6 +527,7 @@ function validateParametricSpec(raw) {
     studies,
     ...edgeCases.length > 0 ? { edgeCases } : {},
     ...r.seed !== void 0 ? { seed: r.seed } : {},
+    ...r.uidSalt !== void 0 ? { uidSalt: r.uidSalt } : {},
     ...r.layout !== void 0 ? { layout: r.layout } : {}
   };
 }

package/dist/esm/syntheticFixtures/streamWrite.js

@@ -144,44 +144,28 @@ function serializeDict(meta, dataset) {
 }
 
 // src/syntheticFixtures/uid.ts
-import { randomBytes } from "node:crypto";
-var ROLE_CODE = { study: 1, series: 2, sop: 3 };
-function lcg(seed) {
-  let s = seed >>> 0;
-  return () => {
-    s = Math.imul(1664525, s) + 1013904223 >>> 0;
-    return s;
-  };
-}
-function formatUid(a, b, role) {
-  return `2.25.${a}.${b}.${ROLE_CODE[role]}`;
+import { createHash, randomBytes } from "node:crypto";
+function hashUid(salt, key) {
+  const digest = createHash("sha256").update(salt).update(" ").update(key).digest();
+  const n = BigInt(`0x${digest.subarray(0, 16).toString("hex")}`);
+  return `2.25.${n.toString()}`;
 }
-function randomUid(role) {
-  const buf = randomBytes(8);
-  return formatUid(buf.readUInt32BE(0), buf.readUInt32BE(4), role);
+function randomUid() {
+  const n = BigInt(`0x${randomBytes(16).toString("hex")}`);
+  return `2.25.${n.toString()}`;
 }
-function seededUid(next, role) {
-  return formatUid(next(), next(), role);
+function seedToSalt(seed) {
+  return seed === void 0 ? void 0 : `seed:${seed}`;
 }
-function seededStream(seed, offset, a, b) {
-  return lcg(seed * 999983 + offset + a * 1000003 + b * 7919 >>> 0);
-}
-function makeUidGenerator(seed) {
-  if (seed === void 0) {
-    return () => ({
-      study: randomUid("study"),
-      series: randomUid("series"),
-      sop: randomUid("sop")
-    });
+function makeUidGenerator(salt) {
+  if (salt === void 0) {
+    return () => ({ study: randomUid(), series: randomUid(), sop: randomUid() });
   }
-  return (fileIndex) => {
-    const next = seededStream(seed, 0, fileIndex, 0);
-    return {
-      study: seededUid(next, "study"),
-      series: seededUid(next, "series"),
-      sop: seededUid(next, "sop")
-    };
-  };
+  return (fileIndex) => ({
+    study: hashUid(salt, `study:flat:${fileIndex}`),
+    series: hashUid(salt, `series:flat:${fileIndex}`),
+    sop: hashUid(salt, `sop:${fileIndex}`)
+  });
 }
 
 // src/syntheticFixtures/streamWrite.ts
@@ -294,7 +278,7 @@ function streamLargeImage(outPath, options) {
     fragmentBytes = FRAGMENT_MAX_BYTES
   } = options;
   const modality = options.modality ?? "CT";
-  const uid = options.uid ?? makeUidGenerator(options.seed)(0);
+  const uid = options.uid ?? makeUidGenerator(options.uidSalt ?? seedToSalt(options.seed))(0);
   const identity = { modality, uid, tags: options.tags };
   mkdirSync2(resolve2(outPath, ".."), { recursive: true });
   const zeroChunk = Buffer.alloc(Math.max(1, chunkBytes));
@@ -346,6 +330,7 @@ function writeLargeImageFile(spec, outPath, options = {}) {
   return streamLargeImage(outPath, {
     targetBytes,
     modality: spec.modality,
+    uidSalt: spec.uidSalt,
     seed: spec.seed,
     chunkBytes: options.chunkBytes
   });

package/dist/esm/syntheticFixtures/uid.js

@@ -1,6 +1,17 @@
 // src/syntheticFixtures/uid.ts
-import { randomBytes } from "node:crypto";
-var ROLE_CODE = { study: 1, series: 2, sop: 3 };
+import { createHash, randomBytes } from "node:crypto";
+function hashUid(salt, key) {
+  const digest = createHash("sha256").update(salt).update(" ").update(key).digest();
+  const n = BigInt(`0x${digest.subarray(0, 16).toString("hex")}`);
+  return `2.25.${n.toString()}`;
+}
+function randomUid() {
+  const n = BigInt(`0x${randomBytes(16).toString("hex")}`);
+  return `2.25.${n.toString()}`;
+}
+function seedToSalt(seed) {
+  return seed === void 0 ? void 0 : `seed:${seed}`;
+}
 function lcg(seed) {
   let s = seed >>> 0;
   return () => {
@@ -8,64 +19,34 @@ function lcg(seed) {
     return s;
   };
 }
-function formatUid(a, b, role) {
-  return `2.25.${a}.${b}.${ROLE_CODE[role]}`;
-}
-function randomUid(role) {
-  const buf = randomBytes(8);
-  return formatUid(buf.readUInt32BE(0), buf.readUInt32BE(4), role);
-}
-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);
 }
-function makeGroupUidGenerator(seed) {
-  if (seed === void 0) {
-    return {
-      study: () => randomUid("study"),
-      series: () => randomUid("series")
-    };
+function makeGroupUidGenerator(salt) {
+  if (salt === void 0) {
+    return { study: () => randomUid(), series: () => randomUid() };
   }
   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"
-    )
+    study: (studyIndex) => hashUid(salt, `study:${studyIndex}`),
+    series: (studyIndex, seriesIndex) => hashUid(salt, `series:${studyIndex}:${seriesIndex}`)
   };
 }
-function makeUidGenerator(seed) {
-  if (seed === void 0) {
-    return () => ({
-      study: randomUid("study"),
-      series: randomUid("series"),
-      sop: randomUid("sop")
-    });
+function makeUidGenerator(salt) {
+  if (salt === void 0) {
+    return () => ({ study: randomUid(), series: randomUid(), sop: randomUid() });
   }
-  return (fileIndex) => {
-    const next = seededStream(seed, 0, fileIndex, 0);
-    return {
-      study: seededUid(next, "study"),
-      series: seededUid(next, "series"),
-      sop: seededUid(next, "sop")
-    };
-  };
+  return (fileIndex) => ({
+    study: hashUid(salt, `study:flat:${fileIndex}`),
+    series: hashUid(salt, `series:flat:${fileIndex}`),
+    sop: hashUid(salt, `sop:${fileIndex}`)
+  });
 }
 export {
   PARAMETRIC_STREAM_OFFSET,
+  hashUid,
   makeGroupUidGenerator,
   makeUidGenerator,
+  seedToSalt,
   seededStream
 };

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

@@ -16,11 +16,13 @@ export type CollectionManifest = Array<{
 export declare function generateFile(spec: FileSpec, options?: {
     index?: number;
     seed?: number;
+    uidSalt?: string;
     padWidth?: number;
     uid?: Partial<UidSet>;
     context?: Partial<TagContext>;
 }): Promise<GeneratedFile>;
 export declare function withResolvedSeed(spec: DatasetSpec): DatasetSpec;
+export declare function withResolvedSalt(spec: DatasetSpec): DatasetSpec;
 export declare function generateCollectionFromSpec(spec: DatasetSpec): AsyncGenerator<GeneratedFile>;
 export type CollectionPreviewItem = {
     relativePath: string;

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

@@ -1,10 +1,11 @@
-export { type CollectionManifest, type CollectionPreviewItem, type GeneratedFile, generateCollectionFromSpec, generateFile, previewCollection, withResolvedSeed, writeCollectionFromSpec, } from './collection/writer.js';
+export { type CollectionManifest, type CollectionPreviewItem, type GeneratedFile, generateCollectionFromSpec, generateFile, previewCollection, withResolvedSalt, withResolvedSeed, writeCollectionFromSpec, } from './collection/writer.js';
 export { type DescribeOptions, type DescribeResult, describeDirectory, } from './describe/describe.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 { 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';
+export { hashUid, seedToSalt } from './syntheticFixtures/uid.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 = {
@@ -66,6 +74,7 @@ export type DatasetSpec = {
     entries?: EntrySpec[];
     studies?: StudySpec[];
     seed?: number;
+    uidSalt?: string;
     layout?: DatasetLayout;
     pathQuirks?: PathQuirk[];
 };
@@ -88,6 +97,7 @@ export type ParametricEdgeCase = EntrySpec & {
 };
 export type ParametricSpec = {
     seed?: number;
+    uidSalt?: string;
     studies: ParametricStudies;
     edgeCases?: ParametricEdgeCase[];
     layout?: DatasetLayout;

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

@@ -4,7 +4,9 @@ export type LargeImageSpec = {
     /** Approximate total file size in bytes (must exceed the 512 MB cap). */
     targetBytes: number;
     modality?: Modality;
-    /** Drawn when omitted; fixes the instance UIDs for reproducibility. */
+    /** UID namespace (hash-derived UIDs); random when both salt and seed omitted. */
+    uidSalt?: string;
+    /** Bridged to a salt when uidSalt is omitted; fixes the instance UIDs. */
     seed?: number;
 };
 export type LargeFileEncoding = 'native' | 'encapsulated';
@@ -18,7 +20,9 @@ export type StreamLargeImageOptions = {
     /** Approximate total file size in bytes (no floor — small values are valid). */
     targetBytes: number;
     modality?: Modality;
-    /** Drawn when omitted; fixes the instance UIDs for reproducibility. */
+    /** UID namespace (hash-derived UIDs); random when both salt and seed omitted. */
+    uidSalt?: string;
+    /** Bridged to a salt when uidSalt is omitted; fixes the instance UIDs. */
     seed?: number;
     /** Explicit UID set — used as-is (e.g. collection threading shared study/series UIDs). */
     uid?: UidSet;

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

@@ -3,12 +3,14 @@ export type UidSet = {
     series: string;
     sop: string;
 };
+export declare function hashUid(salt: string, key: string): string;
+export declare function seedToSalt(seed: number | undefined): string | undefined;
 export declare const PARAMETRIC_STREAM_OFFSET = 2246822507;
 export declare function seededStream(seed: number, offset: number, a: number, b: number): () => number;
 export type GroupUidGenerator = {
     study: (studyIndex: number) => string;
     series: (studyIndex: number, seriesIndex: number) => string;
 };
-export declare function makeGroupUidGenerator(seed?: number): GroupUidGenerator;
+export declare function makeGroupUidGenerator(salt?: string): GroupUidGenerator;
 export type UidGenerator = (fileIndex: number) => UidSet;
-export declare function makeUidGenerator(seed?: number): UidGenerator;
+export declare function makeUidGenerator(salt?: string): UidGenerator;

package/package.json

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