dicom-synth 1.13.0 → 1.15.0

package/dist/esm/collection/writer.js

@@ -8,6 +8,55 @@ import { dirname, resolve as resolve3 } from "node:path";
 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 resolveTagTemplates(tags, context) {
+  if (!tags) return tags;
+  const resolved = {};
+  for (const [key, value] of Object.entries(tags)) {
+    resolved[key] = typeof value === "string" ? resolveString(value, context) : value;
+  }
+  return resolved;
+}
+function resolveString(value, context) {
+  return value.replace(TEMPLATE_PART_RE, (match, name) => {
+    if (name === void 0) return match === "{{" ? "{" : "}";
+    if (!TEMPLATE_VOCAB.includes(name)) {
+      throw new Error(
+        `tag template: unknown placeholder "{${name}}" \u2014 allowed: ${TEMPLATE_VOCAB.map((v) => `{${v}}`).join(", ")}`
+      );
+    }
+    const resolved = context[name];
+    if (resolved === void 0) {
+      throw new Error(
+        `tag template: placeholder "{${name}}" is not available here \u2014 it only applies inside grouped studies`
+      );
+    }
+    return String(resolved);
+  });
+}
+
+// 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 }
+};
+function isImageType(type) {
+  return TYPE_CAPABILITIES[type].image;
+}
+var HEX_TAG_RE = /^[0-9a-fA-F]{8}$/;
+
 // src/loadDcmjs.ts
 import dcmjsDefaultImport, * as dcmjsNamespace from "dcmjs";
 function loadDcmjs() {
@@ -49,43 +98,6 @@ function buildDicomdirBuffer() {
   return buf.subarray(0, off);
 }
 
-// src/syntheticFixtures/tagTemplate.ts
-var TEMPLATE_VOCAB = [
-  "index",
-  "studyIndex",
-  "seriesIndex",
-  "instanceNumber"
-];
-var TEMPLATE_PART_RE = /\{\{|\}\}|\{([a-zA-Z]+)\}/g;
-function resolveTagTemplates(tags, context) {
-  if (!tags) return tags;
-  const resolved = {};
-  for (const [key, value] of Object.entries(tags)) {
-    resolved[key] = typeof value === "string" ? resolveString(value, context) : value;
-  }
-  return resolved;
-}
-function resolveString(value, context) {
-  return value.replace(TEMPLATE_PART_RE, (match, name) => {
-    if (name === void 0) return match === "{{" ? "{" : "}";
-    if (!TEMPLATE_VOCAB.includes(name)) {
-      throw new Error(
-        `tag template: unknown placeholder "{${name}}" \u2014 allowed: ${TEMPLATE_VOCAB.map((v) => `{${v}}`).join(", ")}`
-      );
-    }
-    const resolved = context[name];
-    if (resolved === void 0) {
-      throw new Error(
-        `tag template: placeholder "{${name}}" is not available here \u2014 it only applies inside grouped studies`
-      );
-    }
-    return String(resolved);
-  });
-}
-
-// src/schema/validate.ts
-var HEX_TAG_RE = /^[0-9a-fA-F]{8}$/;
-
 // src/syntheticFixtures/generator.ts
 var MODALITY_PRESETS = {
   CT: {
@@ -242,8 +254,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) {
@@ -254,7 +271,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":
@@ -565,6 +582,15 @@ function studyFileCount(studies) {
     0
   );
 }
+function isDirNode(node) {
+  return "children" in node;
+}
+function treeFileCount(nodes) {
+  return nodes.reduce(
+    (sum, node) => sum + (isDirNode(node) ? treeFileCount(node.children) : node.count ?? 1),
+    0
+  );
+}
 function* seriesFiles(series) {
   if (series.instances) {
     const inst = series.instances;
@@ -661,6 +687,9 @@ function applyPathQuirks(relativePath, quirks) {
   }
   return { relativePath: [...dirs, newLeaf].join("/"), filename: newLeaf };
 }
+function decorateNames(names, quirks) {
+  return quirks.length === 0 ? names : applyPathQuirks(names.relativePath, quirks);
+}
 function hierarchicalName(studyOrdinal, seriesIndex, instanceNumber) {
   const pad3 = (n) => String(n).padStart(3, "0");
   const name = `${String(instanceNumber).padStart(5, "0")}.dcm`;
@@ -687,12 +716,78 @@ function computeNames(type, index, padWidth, grouped, quirks) {
     const name = filename(type, index, padWidth);
     names = { filename: name, relativePath: name };
   }
-  return quirks.length === 0 ? names : applyPathQuirks(names.relativePath, quirks);
+  return decorateNames(names, quirks);
+}
+function* planTree(nodes, scope, env) {
+  let dirOrdinal = 0;
+  for (const node of nodes) {
+    if (isDirNode(node)) {
+      dirOrdinal++;
+      const dirName = node.name ?? `dir-${String(dirOrdinal).padStart(3, "0")}`;
+      const child = {
+        ...scope,
+        dirs: [...scope.dirs, dirName],
+        tags: { ...scope.tags, ...node.tags }
+      };
+      if (node.role === "study") {
+        const ordinal = env.counters.study++;
+        child.study = {
+          ordinal,
+          uid: env.groupUids.study(ordinal),
+          seriesCount: 0
+        };
+      } else if (node.role === "series" && child.study) {
+        const index = child.study.seriesCount++;
+        child.series = {
+          index,
+          uid: env.groupUids.series(child.study.ordinal, index),
+          instanceCount: 0
+        };
+      }
+      yield* planTree(node.children, child, env);
+      continue;
+    }
+    const { count = 1, name, ...fileSpec } = node;
+    const image = isImageType(fileSpec.type);
+    for (let i = 0; i < count; i++) {
+      const index = env.counters.file++;
+      const instanceNumber = image && scope.series ? ++scope.series.instanceCount : void 0;
+      const leaf = name ?? filename(fileSpec.type, index, env.padWidth);
+      const names = decorateNames(
+        { filename: leaf, relativePath: [...scope.dirs, leaf].join("/") },
+        env.quirks
+      );
+      const tags = image ? {
+        ...instanceNumber !== void 0 ? { InstanceNumber: instanceNumber } : {},
+        ...scope.tags,
+        ..."tags" in fileSpec ? fileSpec.tags : void 0
+      } : void 0;
+      yield {
+        fileSpec: tags ? { ...fileSpec, tags } : fileSpec,
+        index,
+        ...image && scope.study ? {
+          uidOverride: {
+            study: scope.study.uid,
+            ...scope.series ? { series: scope.series.uid } : {}
+          }
+        } : {},
+        context: {
+          index,
+          ...scope.study ? { studyIndex: scope.study.ordinal } : {},
+          ...scope.series ? { seriesIndex: scope.series.index } : {},
+          ...instanceNumber !== void 0 ? { instanceNumber } : {}
+        },
+        filename: names.filename,
+        relativePath: names.relativePath
+      };
+    }
+  }
 }
 function* planCollection(spec) {
   const flatEntries = spec.entries ?? [];
   const studies = spec.studies ?? [];
-  const totalFiles = entryCount(flatEntries) + studyFileCount(studies);
+  const tree = spec.tree ?? [];
+  const totalFiles = entryCount(flatEntries) + studyFileCount(studies) + treeFileCount(tree);
   const padWidth = String(totalFiles).length;
   const hierarchical = spec.layout === "hierarchical";
   const quirks = spec.pathQuirks ?? [];
@@ -756,6 +851,18 @@ function* planCollection(spec) {
       studyOrdinal++;
     }
   }
+  if (tree.length > 0) {
+    yield* planTree(
+      tree,
+      { dirs: [], tags: {} },
+      {
+        groupUids,
+        padWidth,
+        quirks,
+        counters: { file: globalIndex, study: studyOrdinal }
+      }
+    );
+  }
 }
 async function materialisePlan(plan, salt) {
   const file = await generateFile(plan.fileSpec, {
@@ -775,12 +882,13 @@ async function* generateCollectionFromSpec(spec) {
 async function* previewCollection(spec) {
   const salt = effectiveSalt(spec);
   for (const plan of planCollection(spec)) {
-    if (plan.fileSpec.type === "large-image") {
+    const knownBytes = plan.fileSpec.type === "large-image" ? plan.fileSpec.targetBytes : plan.fileSpec.type === "non-dicom" ? sizedNonDicomBytes(plan.fileSpec) : void 0;
+    if (knownBytes !== void 0) {
       yield {
         relativePath: plan.relativePath,
-        type: "large-image",
+        type: plan.fileSpec.type,
         index: plan.index,
-        approxBytes: plan.fileSpec.targetBytes
+        approxBytes: knownBytes
       };
     } else {
       const file = await materialisePlan(plan, salt);

package/dist/esm/describe/describe.js

@@ -113,11 +113,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)}`);
@@ -155,6 +158,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(
@@ -182,6 +208,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"`
@@ -389,6 +431,98 @@ function validateStudy(study, path) {
   if ("tags" in st) validateTags(st.tags, `${path}.tags`);
   return st;
 }
+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 = `dir-${String(dirOrdinal).padStart(3, "0")}`);
+    }
+    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");
@@ -400,11 +534,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(
@@ -413,6 +551,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) {
@@ -429,6 +570,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 } : {},
@@ -607,9 +749,13 @@ var UID_SWEEP_EXCLUDE = /* @__PURE__ */ new Set([
   "SeriesInstanceUID",
   "SOPClassUID"
 ]);
+var vrCache = /* @__PURE__ */ new Map();
 function vrOf(keyword) {
+  if (vrCache.has(keyword)) return vrCache.get(keyword);
   const nm = dcmjsAny.data.DicomMetaDictionary.nameMap;
-  return (nm?.[keyword] ?? nm?.[`RETIRED_${keyword}`])?.vr;
+  const vr = (nm?.[keyword] ?? nm?.[`RETIRED_${keyword}`])?.vr;
+  vrCache.set(keyword, vr);
+  return vr;
 }
 function hashUidVia(map, salt, original) {
   let synthetic = map.get(original);
@@ -619,22 +765,78 @@ function hashUidVia(map, salt, original) {
   }
   return synthetic;
 }
+function isUidLeaf(value) {
+  return typeof value === "string" || Array.isArray(value) && value.every((v) => typeof v === "string");
+}
+function hasHashableUid(value) {
+  const uids = typeof value === "string" ? [value] : value;
+  return uids.some((v) => !v.startsWith(DICOM_ORG_ROOT));
+}
+function pruneUidSequence(value) {
+  const items = Array.isArray(value) ? value : [value];
+  const pruned = [];
+  for (const item of items) {
+    if (typeof item !== "object" || item === null || Array.isArray(item))
+      continue;
+    const skeleton = {};
+    let hashable = false;
+    for (const [keyword, v] of Object.entries(item)) {
+      if (keyword === "_vrMap") continue;
+      const vr = vrOf(keyword);
+      if (vr === "UI") {
+        if (isUidLeaf(v)) {
+          skeleton[keyword] = v;
+          if (hasHashableUid(v)) hashable = true;
+        }
+      } else if (vr === "SQ") {
+        const nested = pruneUidSequence(v);
+        if (nested) {
+          skeleton[keyword] = nested;
+          hashable = true;
+        }
+      }
+    }
+    if (hashable) pruned.push(skeleton);
+  }
+  return pruned.length > 0 ? pruned : void 0;
+}
 function collectUidOriginals(record) {
   const uids = {};
   let found = false;
   for (const [keyword, value] of Object.entries(record)) {
     if (UID_SWEEP_EXCLUDE.has(keyword)) continue;
-    if (typeof value !== "string" || value.startsWith(DICOM_ORG_ROOT)) continue;
-    if (vrOf(keyword) !== "UI") continue;
-    uids[keyword] = value;
-    found = true;
+    const vr = vrOf(keyword);
+    if (vr === "UI") {
+      if (isUidLeaf(value) && hasHashableUid(value)) {
+        uids[keyword] = value;
+        found = true;
+      }
+    } else if (vr === "SQ") {
+      const pruned = pruneUidSequence(value);
+      if (pruned) {
+        uids[keyword] = pruned;
+        found = true;
+      }
+    }
   }
   return found ? uids : void 0;
 }
+function hashUidValue(value, salt, map) {
+  if (typeof value === "string") {
+    return value.startsWith(DICOM_ORG_ROOT) ? value : hashUidVia(map, salt, value);
+  }
+  if (Array.isArray(value)) return value.map((v) => hashUidValue(v, salt, map));
+  return Object.fromEntries(
+    Object.entries(value).map(([k, v]) => [
+      k,
+      hashUidValue(v, salt, map)
+    ])
+  );
+}
 function hashUidTags(uids, salt, map) {
   const tags = {};
   for (const [keyword, original] of Object.entries(uids)) {
-    tags[keyword] = hashUidVia(map, salt, original);
+    tags[keyword] = hashUidValue(original, salt, map);
   }
   return tags;
 }
@@ -820,11 +1022,17 @@ function describeDirectory(dir, options = {}) {
   }
   const salt = preserveUids ? options.uidSalt ?? deriveSalt([...studies.keys()]) : void 0;
   if (salt !== void 0) {
+    const sweptKeepTags = /* @__PURE__ */ new Set();
     for (const study of studies.values()) {
       for (const series of study.values()) {
         if (!Array.isArray(series)) continue;
         for (const rec of series) {
           if (rec.uidOriginals) {
+            if (rec.tags) {
+              for (const keyword of Object.keys(rec.uidOriginals)) {
+                if (keyword in rec.tags) sweptKeepTags.add(keyword);
+              }
+            }
             rec.tags = mergeTags(
               rec.tags,
               hashUidTags(rec.uidOriginals, salt, uidMap)
@@ -833,6 +1041,11 @@ function describeDirectory(dir, options = {}) {
         }
       }
     }
+    for (const keyword of sweptKeepTags) {
+      console.warn(
+        `describe: keep-tag "${keyword}" contains UID references \u2014 kept as its hashed UID skeleton, not verbatim (disable with preserveUids: false)`
+      );
+    }
   }
   const withGroupUid = (spec2, seriesUid) => salt === void 0 ? spec2 : {
     ...spec2,