dicom-synth 1.4.0 → 1.6.0

package/dist/esm/describe/describe.js

@@ -0,0 +1,378 @@
+// src/describe/describe.ts
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+// 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/schema/validate.ts
+var TYPE_CAPABILITIES = {
+  "valid-image": { image: true },
+  "invalid-uid-image": { image: true },
+  "vendor-warnings-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,
+  "implicit-vr-little-endian": true
+};
+var MAX_PIXEL_BYTES = 512 * 1024 * 1024;
+var VALID_VIOLATIONS = {
+  "uid-too-long": true,
+  "non-conformant-uid": true,
+  "missing-meta-header": true,
+  "malformed-sq-delimiter": true,
+  "vr-max-length-exceeded": true,
+  "missing-type1-tag": true
+};
+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 validateSeed(value, path) {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw new Error(
+      `${path}: must be a finite number; got ${JSON.stringify(value)}`
+    );
+  }
+}
+function validateSizeKbLimit(kb, path) {
+  if (kb * 1024 > MAX_PIXEL_BYTES) {
+    throw new Error(`${path}: exceeds the 512 MB limit`);
+  }
+}
+function validateEnum(value, valid, path) {
+  if (typeof value !== "string" || !Object.hasOwn(valid, value)) {
+    throw new Error(
+      `${path}: must be one of ${Object.keys(valid).join(", ")}; got ${JSON.stringify(value)}`
+    );
+  }
+}
+function validateTagKey(key, path) {
+  if (!HEX_TAG_RE.test(key) && !KEYWORD_RE.test(key)) {
+    throw new Error(
+      `${path}: invalid tag key "${key}" \u2014 must be a DICOM keyword name (e.g. "Modality") or an 8-hex-char tag (e.g. "00080060")`
+    );
+  }
+}
+function validateEntry(entry, path) {
+  if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+    throw new Error(`${path}: must be an object`);
+  }
+  const e = entry;
+  validateEnum(e.type, TYPE_CAPABILITIES, `${path}.type`);
+  const type = e.type;
+  const caps = TYPE_CAPABILITIES[type];
+  if ("count" in e) validatePositiveInt(e.count, `${path}.count`);
+  for (const field of [
+    "modality",
+    "rows",
+    "columns",
+    "frames",
+    "targetSizeKb",
+    "tags",
+    "violations",
+    "transferSyntax"
+  ]) {
+    if (!caps.image && field in e)
+      throw new Error(`${path}.${field}: not supported for type "${type}"`);
+  }
+  if ("transferSyntax" in e) {
+    validateEnum(
+      e.transferSyntax,
+      VALID_TRANSFER_SYNTAXES,
+      `${path}.transferSyntax`
+    );
+  }
+  if ("modality" in e) {
+    validateEnum(e.modality, VALID_MODALITIES, `${path}.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`);
+    }
+    for (const [i, v] of e.violations.entries()) {
+      validateEnum(v, VALID_VIOLATIONS, `${path}.violations[${i}]`);
+    }
+  }
+  const hasDims = "rows" in e || "columns" in e || "frames" in e;
+  if ("targetSizeKb" in e) {
+    if (hasDims) {
+      throw new Error(
+        `${path}: targetSizeKb cannot be combined with rows/columns/frames \u2014 use one sizing mechanism`
+      );
+    }
+    validatePositiveInt(e.targetSizeKb, `${path}.targetSizeKb`);
+    validateSizeKbLimit(e.targetSizeKb, `${path}.targetSizeKb`);
+  } else if (hasDims) {
+    if (!("rows" in e) || !("columns" in e)) {
+      throw new Error(`${path}: rows and columns must be provided together`);
+    }
+    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;
+    if (rows * columns * frames * 2 > MAX_PIXEL_BYTES) {
+      throw new Error(
+        `${path}: pixel data (${rows}\xD7${columns}\xD7${frames}\xD72 bytes) exceeds the 512 MB limit`
+      );
+    }
+  }
+  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 ("entries" in r && !Array.isArray(r.entries)) {
+    throw new Error("DatasetSpec.entries: must be an array");
+  }
+  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 = rawEntries.map(
+    (entry, i) => validateEntry(entry, `entries[${i}]`)
+  );
+  const studies = rawStudies.map(
+    (study, i) => validateStudy(study, `studies[${i}]`)
+  );
+  if ("seed" in r) validateSeed(r.seed, "DatasetSpec.seed");
+  if ("layout" in r) {
+    validateEnum(r.layout, VALID_LAYOUTS, "DatasetSpec.layout");
+  }
+  return {
+    ...entries.length > 0 ? { entries } : {},
+    ...studies.length > 0 ? { studies } : {},
+    ...r.seed !== void 0 ? { seed: r.seed } : {},
+    ...r.layout !== void 0 ? { layout: r.layout } : {}
+  };
+}
+
+// src/describe/describe.ts
+var dcmjsAny = dcmjs;
+var HEX_TAG_RE2 = /^[0-9a-fA-F]{8}$/;
+var SUPPORTED_MODALITIES = /* @__PURE__ */ new Set(["CT", "PT", "MR", "CR"]);
+function buildHexToKeyword() {
+  const map = /* @__PURE__ */ new Map();
+  const nm = dcmjsAny.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;
+}
+function resolveKeepTags(keepTags) {
+  const nameMap = dcmjsAny.data.DicomMetaDictionary.nameMap;
+  let hexToKeyword;
+  return keepTags.map((tag) => {
+    if (HEX_TAG_RE2.test(tag)) {
+      hexToKeyword ?? (hexToKeyword = buildHexToKeyword());
+      const keyword = hexToKeyword.get(tag.toUpperCase());
+      if (!keyword) {
+        throw new Error(`describe: unknown hex tag "${tag}"`);
+      }
+      return keyword;
+    }
+    if (nameMap && !Object.hasOwn(nameMap, tag)) {
+      throw new Error(`describe: unknown tag keyword "${tag}"`);
+    }
+    return tag;
+  });
+}
+function* walkFiles(dir) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      yield* walkFiles(path);
+    } else if (entry.isFile()) {
+      yield path;
+    }
+  }
+}
+function parseFile(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 };
+  } catch {
+    return null;
+  }
+}
+function extractTags(record, keepKeywords) {
+  const tags = {};
+  let found = false;
+  for (const keyword of keepKeywords) {
+    const value = record[keyword];
+    if (value !== void 0) {
+      tags[keyword] = value;
+      found = true;
+    }
+  }
+  return found ? tags : void 0;
+}
+function describeDirectory(dir, options = {}) {
+  const keepKeywords = options.keepTags ? resolveKeepTags(options.keepTags) : [];
+  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") {
+      stats.skipped++;
+      continue;
+    }
+    const { record } = parsed;
+    stats.dicomFiles++;
+    let modality;
+    if (typeof record.Modality === "string") {
+      if (SUPPORTED_MODALITIES.has(record.Modality)) {
+        modality = record.Modality;
+      } else {
+        stats.unknownModality++;
+      }
+    }
+    const sizeKb = Math.max(1, Math.round(parsed.size / 1024));
+    const tags = keepKeywords.length ? extractTags(record, keepKeywords) : void 0;
+    let study = studies.get(studyUid);
+    if (!study) {
+      study = /* @__PURE__ */ new Map();
+      studies.set(studyUid, study);
+    }
+    let series = study.get(seriesUid);
+    if (!series) {
+      series = /* @__PURE__ */ new Map();
+      study.set(seriesUid, series);
+    }
+    const collapseKey = JSON.stringify([modality ?? null, sizeKb, tags ?? null]);
+    const existing = series.get(collapseKey);
+    if (existing) {
+      existing.count++;
+    } else {
+      series.set(collapseKey, {
+        modality,
+        targetSizeKb: sizeKb,
+        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.tags !== void 0 ? { tags: acc.tags } : {},
+        ...acc.count > 1 ? { count: acc.count } : {}
+      }));
+      return { entries };
+    });
+    return { series: seriesSpecs };
+  });
+  if (studySpecs.length === 0) {
+    throw new Error(`describe: no DICOM series found in ${dir}`);
+  }
+  const spec = { studies: studySpecs, layout: "hierarchical" };
+  validateDatasetSpec(spec);
+  return { spec, stats };
+}
+export {
+  describeDirectory
+};