dicom-synth 1.7.0 → 1.9.0

package/dist/esm/syntheticFixtures/streamWrite.js

@@ -0,0 +1,356 @@
+// src/syntheticFixtures/streamWrite.ts
+import { closeSync, mkdirSync as mkdirSync2, openSync, writeSync } from "node:fs";
+import { resolve as resolve2 } from "node:path";
+
+// src/schema/limits.ts
+var MAX_PIXEL_BYTES = 512 * 1024 * 1024;
+var MAX_STREAM_BYTES = 50 * 1024 * 1024 * 1024;
+
+// src/loadDcmjs.ts
+import dcmjsDefaultImport, * as dcmjsNamespace from "dcmjs";
+function loadDcmjs() {
+  if (dcmjsNamespace.data?.DicomDict) {
+    return dcmjsNamespace;
+  }
+  const d = dcmjsDefaultImport;
+  if (d?.data?.DicomDict) {
+    return d;
+  }
+  if (d?.default?.data?.DicomDict) {
+    return d.default;
+  }
+  throw new Error(
+    "dcmjs failed to load (missing data.DicomDict). Install dcmjs >= 0.29."
+  );
+}
+var dcmjs = loadDcmjs();
+
+// src/nonStandardDicom/dicomdir.ts
+import { mkdirSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+// src/schema/validate.ts
+var HEX_TAG_RE = /^[0-9a-fA-F]{8}$/;
+
+// src/syntheticFixtures/generator.ts
+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"
+};
+function buildTagToKeyword() {
+  const map = /* @__PURE__ */ new Map();
+  const nm = dcmjs.data?.DicomMetaDictionary?.nameMap;
+  if (!nm) return map;
+  for (const [keyword, info] of Object.entries(nm)) {
+    if (info?.tag) {
+      const hex = info.tag.replace(/[(,)]/g, "").toUpperCase();
+      if (hex.length === 8) map.set(hex, keyword);
+    }
+  }
+  return map;
+}
+var tagToKeyword = buildTagToKeyword();
+function applyTagOverrides(dataset, tags) {
+  if (!tags) return;
+  for (const [key, value] of Object.entries(tags)) {
+    if (HEX_TAG_RE.test(key)) {
+      const keyword = tagToKeyword.get(key.toUpperCase());
+      if (keyword) {
+        dataset[keyword] = value;
+      } else {
+        console.warn(`dicom-synth: unknown hex tag "${key}" \u2014 skipping`);
+      }
+    } else {
+      dataset[key] = value;
+    }
+  }
+}
+function buildMeta(uid, modality, transferSyntax = "explicit-vr-little-endian") {
+  return {
+    FileMetaInformationVersion: new Uint8Array([0, 1]).buffer,
+    MediaStorageSOPClassUID: MODALITY_PRESETS[modality].sopClassUid,
+    MediaStorageSOPInstanceUID: uid.sop,
+    TransferSyntaxUID: TRANSFER_SYNTAX_UID[transferSyntax],
+    ImplementationClassUID: "1.2.3.4",
+    ImplementationVersionName: "SYNTH"
+  };
+}
+function buildBaseImageDataset(uid, modality) {
+  const preset = MODALITY_PRESETS[modality];
+  return {
+    PatientName: "SYNTH^SUBJECT",
+    PatientID: "SYNTH_PID",
+    Modality: modality,
+    SOPClassUID: preset.sopClassUid,
+    SOPInstanceUID: uid.sop,
+    SeriesInstanceUID: uid.series,
+    StudyInstanceUID: uid.study,
+    StudyDescription: "Synthetic study",
+    SeriesDescription: "Synthetic series",
+    Rows: 1,
+    Columns: 1,
+    BitsAllocated: 16,
+    BitsStored: 16,
+    HighBit: 15,
+    SamplesPerPixel: 1,
+    PhotometricInterpretation: "MONOCHROME2",
+    PixelRepresentation: 0,
+    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" },
+    ...preset.attributes
+  };
+}
+function serializeDict(meta, dataset) {
+  const dicomDict = new dcmjs.data.DicomDict(
+    dcmjs.data.DicomMetaDictionary.denaturalizeDataset(
+      meta
+    )
+  );
+  dicomDict.dict = dcmjs.data.DicomMetaDictionary.denaturalizeDataset(
+    dataset
+  );
+  return Buffer.from(dicomDict.write({ allowInvalidVRLength: true }));
+}
+
+// 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]}`;
+}
+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);
+}
+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")
+    });
+  }
+  return (fileIndex) => {
+    const next = seededStream(seed, 0, fileIndex, 0);
+    return {
+      study: seededUid(next, "study"),
+      series: seededUid(next, "series"),
+      sop: seededUid(next, "sop")
+    };
+  };
+}
+
+// src/syntheticFixtures/streamWrite.ts
+var OW_MAX_BYTES = 4294967294;
+var FRAGMENT_MAX_BYTES = 4294967294;
+var DEFAULT_CHUNK_BYTES = 8 * 1024 * 1024;
+var RLE_TRANSFER_SYNTAX_UID = "1.2.840.10008.1.2.5";
+var PIXEL_DATA_OW_HEADER = Buffer.from([224, 127, 16, 0, 79, 87]);
+var PIXEL_DATA_OB_HEADER = Buffer.from([224, 127, 16, 0, 79, 66]);
+var ITEM_TAG_GROUP = 65534;
+var ITEM_TAG_ELEMENT = 57344;
+var SEQUENCE_DELIMITER_ELEMENT = 57565;
+function itemTag(element, byteLength = 0) {
+  const b = Buffer.alloc(8);
+  b.writeUInt16LE(ITEM_TAG_GROUP, 0);
+  b.writeUInt16LE(element, 2);
+  b.writeUInt32LE(byteLength, 4);
+  return b;
+}
+function nativeDimensions(pixelBytes) {
+  const cells = Math.max(1, Math.floor(pixelBytes / 2));
+  const rows = Math.min(65535, Math.max(1, Math.round(Math.sqrt(cells))));
+  const columns = Math.min(65535, Math.max(1, Math.floor(cells / rows)));
+  return { rows, columns, bytes: rows * columns * 2 };
+}
+function streamZeros(fd, totalBytes, zeroChunk) {
+  let remaining = totalBytes;
+  while (remaining > 0) {
+    const n = Math.min(zeroChunk.length, remaining);
+    writeSync(fd, zeroChunk, 0, n);
+    remaining -= n;
+  }
+}
+function writeNative(outPath, params, dims, zeroChunk) {
+  const { modality, uid, tags } = params;
+  const meta = buildMeta(uid, modality);
+  const dataset = buildBaseImageDataset(uid, modality);
+  applyTagOverrides(dataset, tags);
+  dataset.Rows = dims.rows;
+  dataset.Columns = dims.columns;
+  const minimalPixelBytes = dataset.PixelData.byteLength;
+  const probe = serializeDict(meta, dataset);
+  const pixelElement = Buffer.alloc(12);
+  PIXEL_DATA_OW_HEADER.copy(pixelElement);
+  pixelElement.writeUInt32LE(minimalPixelBytes, 8);
+  const owIdx = probe.indexOf(pixelElement);
+  if (owIdx < 0) {
+    throw new Error("failed to locate native PixelData element header");
+  }
+  const dataStart = owIdx + 12;
+  const header = Buffer.from(probe.subarray(0, dataStart));
+  header.writeUInt32LE(dims.bytes, owIdx + 8);
+  const trailing = probe.subarray(dataStart + minimalPixelBytes);
+  const fd = openSync(outPath, "w");
+  try {
+    writeSync(fd, header);
+    streamZeros(fd, dims.bytes, zeroChunk);
+    if (trailing.length > 0) writeSync(fd, trailing);
+  } finally {
+    closeSync(fd);
+  }
+  return header.length + dims.bytes + trailing.length;
+}
+function writeEncapsulated(outPath, params, pixelBytes, fragmentBytes, zeroChunk) {
+  const { modality, uid, tags } = params;
+  const meta = {
+    ...buildMeta(uid, modality),
+    TransferSyntaxUID: RLE_TRANSFER_SYNTAX_UID
+  };
+  const dataset = buildBaseImageDataset(uid, modality);
+  applyTagOverrides(dataset, tags);
+  dataset.PixelData = [new Uint8Array([]).buffer, new Uint8Array([0, 0]).buffer];
+  dataset._vrMap = { PixelData: "OB" };
+  const probe = serializeDict(meta, dataset);
+  const idx = probe.indexOf(PIXEL_DATA_OB_HEADER);
+  if (idx < 0 || probe.readUInt32LE(idx + 8) !== 4294967295) {
+    throw new Error("failed to locate encapsulated PixelData element header");
+  }
+  const prefix = Buffer.from(probe.subarray(0, idx + 12));
+  const fd = openSync(outPath, "w");
+  let bytesWritten = 0;
+  try {
+    writeSync(fd, prefix);
+    bytesWritten += prefix.length;
+    const bot = itemTag(ITEM_TAG_ELEMENT, 0);
+    writeSync(fd, bot);
+    bytesWritten += bot.length;
+    let remaining = pixelBytes;
+    while (remaining > 0) {
+      const fragLen = Math.min(fragmentBytes, remaining);
+      const fh = itemTag(ITEM_TAG_ELEMENT, fragLen);
+      writeSync(fd, fh);
+      streamZeros(fd, fragLen, zeroChunk);
+      bytesWritten += fh.length + fragLen;
+      remaining -= fragLen;
+    }
+    const delimiter = itemTag(SEQUENCE_DELIMITER_ELEMENT);
+    writeSync(fd, delimiter);
+    bytesWritten += delimiter.length;
+  } finally {
+    closeSync(fd);
+  }
+  return bytesWritten;
+}
+function streamLargeImage(outPath, options) {
+  const {
+    targetBytes,
+    chunkBytes = DEFAULT_CHUNK_BYTES,
+    owMaxBytes = OW_MAX_BYTES,
+    fragmentBytes = FRAGMENT_MAX_BYTES
+  } = options;
+  const modality = options.modality ?? "CT";
+  const uid = options.uid ?? makeUidGenerator(options.seed)(0);
+  const identity = { modality, uid, tags: options.tags };
+  mkdirSync2(resolve2(outPath, ".."), { recursive: true });
+  const zeroChunk = Buffer.alloc(Math.max(1, chunkBytes));
+  const probe = serializeDict(
+    buildMeta(uid, modality),
+    buildBaseImageDataset(uid, modality)
+  );
+  const nativeHeaderLen = probe.length - 2;
+  const requestedPixel = Math.max(2, targetBytes - nativeHeaderLen);
+  if (requestedPixel <= owMaxBytes) {
+    const dims = nativeDimensions(requestedPixel);
+    const bytesWritten2 = writeNative(outPath, identity, dims, zeroChunk);
+    return {
+      path: outPath,
+      bytesWritten: bytesWritten2,
+      encoding: "native",
+      pixelBytes: dims.bytes
+    };
+  }
+  const estimateFrags = Math.max(
+    1,
+    Math.ceil((targetBytes - nativeHeaderLen - 16) / fragmentBytes)
+  );
+  const overhead = nativeHeaderLen + 8 + estimateFrags * 8 + 8;
+  let pixelBytes = Math.max(2, targetBytes - overhead);
+  pixelBytes -= pixelBytes % 2;
+  const bytesWritten = writeEncapsulated(
+    outPath,
+    identity,
+    pixelBytes,
+    fragmentBytes - fragmentBytes % 2,
+    zeroChunk
+  );
+  return { path: outPath, bytesWritten, encoding: "encapsulated", pixelBytes };
+}
+function writeLargeImageFile(spec, outPath, options = {}) {
+  const { targetBytes } = spec;
+  if (!Number.isInteger(targetBytes)) {
+    throw new Error("writeLargeImageFile: targetBytes must be an integer");
+  }
+  if (targetBytes <= MAX_PIXEL_BYTES) {
+    throw new Error(
+      "writeLargeImageFile is for files above the 512 MB in-memory limit \u2014 use targetSizeKb for smaller files"
+    );
+  }
+  if (targetBytes > MAX_STREAM_BYTES) {
+    throw new Error("writeLargeImageFile: targetBytes exceeds the 50 GB limit");
+  }
+  return streamLargeImage(outPath, {
+    targetBytes,
+    modality: spec.modality,
+    seed: spec.seed,
+    chunkBytes: options.chunkBytes
+  });
+}
+export {
+  streamLargeImage,
+  writeLargeImageFile
+};

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

@@ -18,5 +18,13 @@ export declare function generateFile(spec: FileSpec, options?: {
     padWidth?: number;
     uid?: Partial<UidSet>;
 }): Promise<GeneratedFile>;
+export declare function withResolvedSeed(spec: DatasetSpec): DatasetSpec;
 export declare function generateCollectionFromSpec(spec: DatasetSpec): AsyncGenerator<GeneratedFile>;
+export type CollectionPreviewItem = {
+    relativePath: string;
+    type: FileSpec['type'];
+    index: number;
+    approxBytes: number;
+};
+export declare function previewCollection(spec: DatasetSpec): AsyncGenerator<CollectionPreviewItem>;
 export declare function writeCollectionFromSpec(spec: DatasetSpec, outDir: string): Promise<CollectionManifest>;

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

@@ -10,4 +10,5 @@ export type DescribeResult = {
         unknownModality: number;
     };
 };
+export declare function readHeaderOnly(path: string): Record<string, unknown> | null;
 export declare function describeDirectory(dir: string, options?: DescribeOptions): DescribeResult;

package/dist/types/index.d.ts

@@ -1,7 +1,9 @@
-export { type CollectionManifest, type GeneratedFile, generateCollectionFromSpec, generateFile, writeCollectionFromSpec, } from './collection/writer.js';
+export { type CollectionManifest, type CollectionPreviewItem, type GeneratedFile, generateCollectionFromSpec, generateFile, previewCollection, 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, 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, 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';

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

@@ -0,0 +1,2 @@
+export declare const MAX_PIXEL_BYTES: number;
+export declare const MAX_STREAM_BYTES: number;

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

@@ -37,12 +37,18 @@ export type NonDicomSpec = {
 export type DicomdirSpec = {
     type: 'dicomdir';
 };
+export type LargeFileSpec = {
+    type: 'large-image';
+    targetBytes: number;
+    modality?: Modality;
+    tags?: DicomTagOverrides;
+};
 export type ImageSpec = ValidImageSpec | InvalidUidImageSpec | VendorWarningsImageSpec;
-export type FileSpec = ImageSpec | FakeSignatureSpec | NonDicomSpec | DicomdirSpec;
+export type FileSpec = ImageSpec | FakeSignatureSpec | NonDicomSpec | DicomdirSpec | LargeFileSpec;
 export type EntrySpec = FileSpec & {
     count?: number;
 };
-export type SeriesEntrySpec = ImageSpec & {
+export type SeriesEntrySpec = (ImageSpec | LargeFileSpec) & {
     count?: number;
 };
 export type SeriesSpec = {
@@ -74,6 +80,8 @@ export type ParametricStudies = {
     fileSizeKb?: Range;
     modalities?: Modality[];
     tags?: DicomTagOverrides;
+    largeFilesPerSeries?: Range;
+    largeFileBytes?: Range;
 };
 export type ParametricEdgeCase = EntrySpec & {
     frequency?: number;

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

@@ -1,3 +1,7 @@
-import type { FileSpec } from '../schema/types.js';
+import type { DicomTagOverrides, FileSpec, Modality, 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 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 buildBufferForSpec(spec: FileSpec, uid: UidSet): Buffer;

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

@@ -0,0 +1,49 @@
+import type { DicomTagOverrides, Modality } from '../schema/types.js';
+import { type UidSet } from './uid.js';
+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. */
+    seed?: number;
+};
+export type LargeFileEncoding = 'native' | 'encapsulated';
+export type LargeFileResult = {
+    path: string;
+    bytesWritten: number;
+    encoding: LargeFileEncoding;
+    pixelBytes: number;
+};
+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. */
+    seed?: number;
+    /** Explicit UID set — used as-is (e.g. collection threading shared study/series UIDs). */
+    uid?: UidSet;
+    /** Tag overrides applied to the dataset (e.g. InstanceNumber, study/series tags). */
+    tags?: DicomTagOverrides;
+    chunkBytes?: number;
+    owMaxBytes?: number;
+    fragmentBytes?: number;
+};
+/**
+ * Low-level streaming writer: chooses the encoding from the requested size and
+ * the (overridable) ceilings, and applies **no policy bounds** — `targetBytes`
+ * may be tiny. This is the entry point for exercising the streamed path inline
+ * in tests/CI: override `owMaxBytes`/`fragmentBytes` to force either encoding at
+ * KB scale. Normal callers want {@link writeLargeImageFile}, which adds the
+ * 512 MB–50 GB policy bounds.
+ */
+export declare function streamLargeImage(outPath: string, options: StreamLargeImageOptions): LargeFileResult;
+/**
+ * Stream a single DICOM image of approximately `targetBytes` to disk without
+ * holding it in memory. Disk-only: the in-memory `generateFile` path keeps the
+ * 512 MB cap. Files up to ~4 GB use a conformant native (OW) encoding; larger
+ * files (to 50 GB) use encapsulated fragments — a valid container with
+ * non-conformant zero pixel content.
+ */
+export declare function writeLargeImageFile(spec: LargeImageSpec, outPath: string, options?: {
+    chunkBytes?: number;
+}): LargeFileResult;

package/package.json

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