dicom-synth 1.8.0 → 1.10.0

package/dist/esm/describe/describe.js

@@ -1,5 +1,12 @@
 // src/describe/describe.ts
-import { readdirSync, readFileSync } from "node:fs";
+import {
+  closeSync,
+  openSync,
+  readdirSync,
+  readFileSync,
+  readSync,
+  statSync
+} from "node:fs";
 import { join } from "node:path";
 
 // src/loadDcmjs.ts
@@ -21,11 +28,35 @@ function loadDcmjs() {
 }
 var dcmjs = loadDcmjs();
 
+// src/schema/limits.ts
+var MAX_PIXEL_BYTES = 512 * 1024 * 1024;
+var MAX_STREAM_BYTES = 50 * 1024 * 1024 * 1024;
+
+// 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;
+}
+
 // src/schema/validate.ts
 var TYPE_CAPABILITIES = {
   "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 }
@@ -50,7 +81,6 @@ var VALID_TRANSFER_SYNTAXES = {
   "explicit-vr-little-endian": true,
   "implicit-vr-little-endian": true
 };
-var MAX_PIXEL_BYTES = 512 * 1024 * 1024;
 var VALID_VIOLATIONS = {
   "uid-too-long": true,
   "non-conformant-uid": true,
@@ -80,6 +110,43 @@ function validateSizeKbLimit(kb, path) {
     throw new Error(`${path}: exceeds the 512 MB limit`);
   }
 }
+function validateLargeTargetBytes(value, path) {
+  if (typeof value !== "number" || !Number.isInteger(value)) {
+    throw new Error(`${path}: must be an integer; got ${JSON.stringify(value)}`);
+  }
+  if (value <= MAX_PIXEL_BYTES) {
+    throw new Error(
+      `${path}: must exceed 512 MB \u2014 use targetSizeKb for smaller files`
+    );
+  }
+  if (value > MAX_STREAM_BYTES) {
+    throw new Error(`${path}: exceeds the 50 GB limit`);
+  }
+}
+function validateLargeImageEntry(e, path) {
+  for (const field of [
+    "rows",
+    "columns",
+    "frames",
+    "targetSizeKb",
+    "violations",
+    "transferSyntax"
+  ]) {
+    if (field in e) {
+      throw new Error(
+        `${path}.${field}: not supported for type "large-image" \u2014 use targetBytes`
+      );
+    }
+  }
+  if (!("targetBytes" in e)) {
+    throw new Error(`${path}.targetBytes: is required for type "large-image"`);
+  }
+  validateLargeTargetBytes(e.targetBytes, `${path}.targetBytes`);
+  if ("modality" in e) {
+    validateEnum(e.modality, VALID_MODALITIES, `${path}.modality`);
+  }
+  if ("tags" in e) validateTags(e.tags, `${path}.tags`);
+}
 function validateEnum(value, valid, path) {
   if (typeof value !== "string" || !Object.hasOwn(valid, value)) {
     throw new Error(
@@ -103,6 +170,15 @@ function validateEntry(entry, path) {
   const type = e.type;
   const caps = TYPE_CAPABILITIES[type];
   if ("count" in e) validatePositiveInt(e.count, `${path}.count`);
+  if (type === "large-image") {
+    validateLargeImageEntry(e, path);
+    return e;
+  }
+  if ("targetBytes" in e) {
+    throw new Error(
+      `${path}.targetBytes: only supported for type "large-image"`
+    );
+  }
   for (const field of [
     "modality",
     "rows",
@@ -162,12 +238,28 @@ function validateEntry(entry, path) {
   }
   return e;
 }
+var MODALITY_TAG = "00080060";
 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);
+    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 validateSeries(series, path) {
@@ -253,6 +345,13 @@ function validateDatasetSpec(raw) {
 var dcmjsAny = dcmjs;
 var HEX_TAG_RE2 = /^[0-9a-fA-F]{8}$/;
 var SUPPORTED_MODALITIES = /* @__PURE__ */ new Set(["CT", "PT", "MR", "CR"]);
+var RESERVED_KEEP_KEYWORDS = /* @__PURE__ */ new Set([
+  "Units",
+  "DecayCorrection",
+  "CorrectedImage",
+  "ScanningSequence",
+  "SequenceVariant"
+]);
 function buildHexToKeyword() {
   const map = /* @__PURE__ */ new Map();
   const nm = dcmjsAny.data.DicomMetaDictionary.nameMap;
@@ -268,20 +367,37 @@ function buildHexToKeyword() {
 function resolveKeepTags(keepTags) {
   const nameMap = dcmjsAny.data.DicomMetaDictionary.nameMap;
   let hexToKeyword;
-  return keepTags.map((tag) => {
+  const kept = [];
+  for (const tag of keepTags) {
+    let keyword;
     if (HEX_TAG_RE2.test(tag)) {
       hexToKeyword ?? (hexToKeyword = buildHexToKeyword());
-      const keyword = hexToKeyword.get(tag.toUpperCase());
-      if (!keyword) {
+      const mapped = hexToKeyword.get(tag.toUpperCase());
+      if (!mapped) {
         throw new Error(`describe: unknown hex tag "${tag}"`);
       }
-      return keyword;
+      keyword = mapped;
+    } else {
+      if (nameMap && !Object.hasOwn(nameMap, tag)) {
+        throw new Error(`describe: unknown tag keyword "${tag}"`);
+      }
+      keyword = tag;
+    }
+    if (RESERVED_KEEP_KEYWORDS.has(keyword)) {
+      console.warn(
+        `describe: ignoring keep-tag "${keyword}" \u2014 modality-coupled tags are reproduced from the modality field`
+      );
+      continue;
     }
-    if (nameMap && !Object.hasOwn(nameMap, tag)) {
-      throw new Error(`describe: unknown tag keyword "${tag}"`);
+    if (nameMap?.[keyword]?.vr === "UI") {
+      console.warn(
+        `describe: ignoring keep-tag "${keyword}" \u2014 UID-valued tags are not kept verbatim`
+      );
+      continue;
     }
-    return tag;
-  });
+    kept.push(keyword);
+  }
+  return kept;
 }
 function* walkFiles(dir) {
   for (const entry of readdirSync(dir, { withFileTypes: true })) {
@@ -293,18 +409,77 @@ function* walkFiles(dir) {
     }
   }
 }
-function parseFile(path) {
+function toArrayBuffer(buf) {
+  return buf.buffer.slice(
+    buf.byteOffset,
+    buf.byteOffset + buf.byteLength
+  );
+}
+function naturalize(ab) {
+  const parsed = dcmjsAny.data.DicomMessage.readFile(ab);
+  return dcmjsAny.data.DicomMetaDictionary.naturalizeDataset(parsed.dict);
+}
+function parseFull(path) {
   try {
-    const buf = readFileSync(path);
-    const ab = buf.buffer.slice(
-      buf.byteOffset,
-      buf.byteOffset + buf.byteLength
-    );
-    const parsed = dcmjsAny.data.DicomMessage.readFile(ab);
-    const record = dcmjsAny.data.DicomMetaDictionary.naturalizeDataset(
-      parsed.dict
-    );
-    return { record, size: buf.byteLength };
+    return naturalize(toArrayBuffer(readFileSync(path)));
+  } catch {
+    return null;
+  }
+}
+var PIXEL_DATA_OW = Buffer.from([224, 127, 16, 0, 79, 87]);
+var PIXEL_DATA_OB = Buffer.from([224, 127, 16, 0, 79, 66]);
+var EMPTY_OW_PIXEL_DATA = Buffer.from([
+  224,
+  127,
+  16,
+  0,
+  79,
+  87,
+  0,
+  0,
+  0,
+  0,
+  0,
+  0
+]);
+var HEADER_READ_BYTES = 2 * 1024 * 1024;
+function findPixelDataOffset(prefix) {
+  let best = -1;
+  for (const pattern of [PIXEL_DATA_OW, PIXEL_DATA_OB]) {
+    for (let from = 0; ; ) {
+      const i = prefix.indexOf(pattern, from);
+      if (i < 0) break;
+      if (prefix[i + 6] === 0 && prefix[i + 7] === 0) {
+        if (best < 0 || i < best) best = i;
+        break;
+      }
+      from = i + 1;
+    }
+  }
+  return best;
+}
+function readHeaderOnly(path) {
+  let prefix;
+  try {
+    const fd = openSync(path, "r");
+    try {
+      const buf = Buffer.alloc(HEADER_READ_BYTES);
+      const n = readSync(fd, buf, 0, HEADER_READ_BYTES, 0);
+      prefix = buf.subarray(0, n);
+    } finally {
+      closeSync(fd);
+    }
+  } catch {
+    return null;
+  }
+  const tagIdx = findPixelDataOffset(prefix);
+  if (tagIdx < 0) return null;
+  const headerOnly = Buffer.concat([
+    prefix.subarray(0, tagIdx),
+    EMPTY_OW_PIXEL_DATA
+  ]);
+  try {
+    return naturalize(toArrayBuffer(headerOnly));
   } catch {
     return null;
   }
@@ -314,10 +489,12 @@ function extractTags(record, keepKeywords) {
   let found = false;
   for (const keyword of keepKeywords) {
     const value = record[keyword];
-    if (value !== void 0) {
-      tags[keyword] = value;
-      found = true;
+    if (value === void 0) continue;
+    if (keyword === "Modality" && typeof value === "string" && SUPPORTED_MODALITIES.has(value)) {
+      continue;
     }
+    tags[keyword] = typeof value === "string" ? escapeTagTemplate(value) : value;
+    found = true;
   }
   return found ? tags : void 0;
 }
@@ -326,14 +503,25 @@ function describeDirectory(dir, options = {}) {
   const studies = /* @__PURE__ */ new Map();
   const stats = { dicomFiles: 0, skipped: 0, unknownModality: 0 };
   for (const path of [...walkFiles(dir)].sort()) {
-    const parsed = parseFile(path);
-    const studyUid = parsed?.record.StudyInstanceUID;
-    const seriesUid = parsed?.record.SeriesInstanceUID;
-    if (!parsed || typeof studyUid !== "string" || typeof seriesUid !== "string") {
+    let size;
+    try {
+      size = statSync(path).size;
+    } catch {
+      stats.skipped++;
+      continue;
+    }
+    if (size > MAX_STREAM_BYTES) {
+      stats.skipped++;
+      continue;
+    }
+    const large = size > MAX_PIXEL_BYTES;
+    const record = large ? readHeaderOnly(path) : parseFull(path);
+    const studyUid = record?.StudyInstanceUID;
+    const seriesUid = record?.SeriesInstanceUID;
+    if (!record || typeof studyUid !== "string" || typeof seriesUid !== "string") {
       stats.skipped++;
       continue;
     }
-    const { record } = parsed;
     stats.dicomFiles++;
     let modality;
     if (typeof record.Modality === "string") {
@@ -343,7 +531,7 @@ function describeDirectory(dir, options = {}) {
         stats.unknownModality++;
       }
     }
-    const sizeKb = Math.max(1, Math.round(parsed.size / 1024));
+    const sizeKb = Math.max(1, Math.round(size / 1024));
     const tags = keepKeywords.length ? extractTags(record, keepKeywords) : void 0;
     let study = studies.get(studyUid);
     if (!study) {
@@ -355,25 +543,27 @@ function describeDirectory(dir, options = {}) {
       series = /* @__PURE__ */ new Map();
       study.set(seriesUid, series);
     }
-    const collapseKey = JSON.stringify([modality ?? null, sizeKb, tags ?? null]);
+    const collapseKey = JSON.stringify([
+      large,
+      modality ?? null,
+      large ? size : sizeKb,
+      tags ?? null
+    ]);
     const existing = series.get(collapseKey);
     if (existing) {
       existing.count++;
     } else {
-      series.set(collapseKey, {
-        modality,
-        targetSizeKb: sizeKb,
-        tags,
-        count: 1
-      });
+      series.set(collapseKey, { modality, large, bytes: size, tags, count: 1 });
     }
   }
   const studySpecs = [...studies.values()].map((study) => {
     const seriesSpecs = [...study.values()].map((series) => {
       const entries = [...series.values()].map((acc) => ({
-        type: "valid-image",
         ...acc.modality !== void 0 ? { modality: acc.modality } : {},
-        targetSizeKb: acc.targetSizeKb,
+        ...acc.large ? { type: "large-image", targetBytes: acc.bytes } : {
+          type: "valid-image",
+          targetSizeKb: Math.max(1, Math.round(acc.bytes / 1024))
+        },
         ...acc.tags !== void 0 ? { tags: acc.tags } : {},
         ...acc.count > 1 ? { count: acc.count } : {}
       }));
@@ -389,5 +579,6 @@ function describeDirectory(dir, options = {}) {
   return { spec, stats };
 }
 export {
-  describeDirectory
+  describeDirectory,
+  readHeaderOnly
 };