dicom-synth 1.9.0 → 1.10.0

package/bin/dicom-synth-describe.mjs

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
-import { writeFileSync } from 'node:fs'
+import { readFileSync, writeFileSync } from 'node:fs'
 import { resolve } from 'node:path'
 import { describeDirectory } from '../dist/esm/index.js'
 
 function usage() {
   console.error(
-    'Usage: dicom-synth-describe <dir> [--out <spec.json>] [--keep-tags <a,b,...>]\n' +
+    'Usage: dicom-synth-describe <dir> [--out <spec.json>] [--keep-tags <a,b,...>] [--keep-tags-file <path>]\n' +
       '\n' +
       'Scans a DICOM tree and emits a DatasetSpec describing its shape\n' +
       '(studies/series, per-file size, modality).\n' +
@@ -13,26 +13,45 @@ function usage() {
       'By default only the shape is reproduced — no tags are copied.\n' +
       '--keep-tags copies the named tags (DICOM keywords or 8-hex tags)\n' +
       "verbatim; if a kept tag holds PHI, handling it is the caller's\n" +
-      "responsibility, not this tool's.",
+      "responsibility, not this tool's.\n" +
+      '--keep-tags-file reads the same allow-list from a file (one tag per\n' +
+      'line, # comments); merged with any --keep-tags.',
   )
   process.exit(1)
 }
 
+// Parse a keep-tags file: one tag per line, blank lines and # comments ignored.
+function parseKeepTagsFile(path) {
+  return readFileSync(path, 'utf8')
+    .split(/\r?\n/)
+    .map((line) => line.replace(/#.*$/, '').trim())
+    .filter(Boolean)
+}
+
 const args = process.argv.slice(2)
 if (args.length === 0) usage()
 
 let dir
 let outPath
-let keepTags
+const keepTags = []
 
 for (let i = 0; i < args.length; i++) {
   if (args[i] === '--out' && args[i + 1]) {
     outPath = resolve(args[++i])
   } else if (args[i] === '--keep-tags' && args[i + 1]) {
-    keepTags = args[++i]
-      .split(',')
-      .map((t) => t.trim())
-      .filter(Boolean)
+    keepTags.push(
+      ...args[++i]
+        .split(',')
+        .map((t) => t.trim())
+        .filter(Boolean),
+    )
+  } else if (args[i] === '--keep-tags-file' && args[i + 1]) {
+    try {
+      keepTags.push(...parseKeepTagsFile(resolve(args[++i])))
+    } catch (err) {
+      console.error(`Error reading keep-tags file: ${err.message}`)
+      process.exit(1)
+    }
   } else if (args[i].startsWith('--')) {
     console.error(`Unknown argument: ${args[i]}`)
     usage()
@@ -48,7 +67,7 @@ if (dir === undefined) usage()
 
 let result
 try {
-  result = describeDirectory(dir, keepTags ? { keepTags } : {})
+  result = describeDirectory(dir, keepTags.length ? { keepTags } : {})
 } catch (err) {
   console.error(`Error: ${err.message}`)
   process.exit(1)

package/dist/esm/collection/writer.js

@@ -49,6 +49,40 @@ 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}$/;
 
@@ -566,7 +600,11 @@ async function generateFile(spec, options) {
   const index = options?.index ?? 0;
   const padWidth = options?.padWidth ?? 3;
   const uid = resolveUid(options?.seed, index, options?.uid);
-  let buffer = buildBufferForSpec(spec, uid);
+  const resolvedSpec = "tags" in spec && spec.tags ? {
+    ...spec,
+    tags: resolveTagTemplates(spec.tags, { index, ...options?.context })
+  } : spec;
+  let buffer = buildBufferForSpec(resolvedSpec, uid);
   const violations = "violations" in spec ? spec.violations : void 0;
   if (violations?.length) {
     buffer = applyViolations(buffer, violations);
@@ -661,6 +699,7 @@ function* planCollection(spec) {
       yield {
         fileSpec,
         index: globalIndex,
+        context: { index: globalIndex },
         ...computeNames(
           fileSpec.type,
           globalIndex,
@@ -695,6 +734,12 @@ function* planCollection(spec) {
               fileSpec: { ...fileSpec, tags },
               index: globalIndex,
               uidOverride: { study: studyUid, series: seriesUid },
+              context: {
+                index: globalIndex,
+                studyIndex: studyOrdinal,
+                seriesIndex,
+                instanceNumber
+              },
               ...computeNames(
                 fileSpec.type,
                 globalIndex,
@@ -715,7 +760,8 @@ async function materialisePlan(plan, seed) {
   const file = await generateFile(plan.fileSpec, {
     index: plan.index,
     seed,
-    uid: plan.uidOverride
+    uid: plan.uidOverride,
+    context: plan.context
   });
   return { ...file, filename: plan.filename, relativePath: plan.relativePath };
 }
@@ -771,7 +817,7 @@ async function writeCollectionFromSpec(spec, outDir) {
         targetBytes: large.targetBytes,
         modality: large.modality,
         uid,
-        tags: large.tags
+        tags: resolveTagTemplates(large.tags, plan.context)
       });
     } else {
       const file = await materialisePlan(plan, spec.seed);

package/dist/esm/describe/describe.js

@@ -32,6 +32,25 @@ var dcmjs = loadDcmjs();
 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 },
@@ -219,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) {
@@ -310,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;
@@ -325,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 (nameMap && !Object.hasOwn(nameMap, tag)) {
-      throw new Error(`describe: unknown 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;
     }
-    return tag;
-  });
+    if (nameMap?.[keyword]?.vr === "UI") {
+      console.warn(
+        `describe: ignoring keep-tag "${keyword}" \u2014 UID-valued tags are not kept verbatim`
+      );
+      continue;
+    }
+    kept.push(keyword);
+  }
+  return kept;
 }
 function* walkFiles(dir) {
   for (const entry of readdirSync(dir, { withFileTypes: true })) {
@@ -430,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;
 }

package/dist/esm/index.js

@@ -49,6 +49,50 @@ 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 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;
+}
+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 },
@@ -243,12 +287,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) {
@@ -986,7 +1046,11 @@ async function generateFile(spec, options) {
   const index = options?.index ?? 0;
   const padWidth = options?.padWidth ?? 3;
   const uid = resolveUid(options?.seed, index, options?.uid);
-  let buffer = buildBufferForSpec(spec, uid);
+  const resolvedSpec = "tags" in spec && spec.tags ? {
+    ...spec,
+    tags: resolveTagTemplates(spec.tags, { index, ...options?.context })
+  } : spec;
+  let buffer = buildBufferForSpec(resolvedSpec, uid);
   const violations = "violations" in spec ? spec.violations : void 0;
   if (violations?.length) {
     buffer = applyViolations(buffer, violations);
@@ -1081,6 +1145,7 @@ function* planCollection(spec) {
       yield {
         fileSpec,
         index: globalIndex,
+        context: { index: globalIndex },
         ...computeNames(
           fileSpec.type,
           globalIndex,
@@ -1115,6 +1180,12 @@ function* planCollection(spec) {
               fileSpec: { ...fileSpec, tags },
               index: globalIndex,
               uidOverride: { study: studyUid, series: seriesUid },
+              context: {
+                index: globalIndex,
+                studyIndex: studyOrdinal,
+                seriesIndex,
+                instanceNumber
+              },
               ...computeNames(
                 fileSpec.type,
                 globalIndex,
@@ -1135,7 +1206,8 @@ async function materialisePlan(plan, seed) {
   const file = await generateFile(plan.fileSpec, {
     index: plan.index,
     seed,
-    uid: plan.uidOverride
+    uid: plan.uidOverride,
+    context: plan.context
   });
   return { ...file, filename: plan.filename, relativePath: plan.relativePath };
 }
@@ -1191,7 +1263,7 @@ async function writeCollectionFromSpec(spec, outDir) {
         targetBytes: large.targetBytes,
         modality: large.modality,
         uid,
-        tags: large.tags
+        tags: resolveTagTemplates(large.tags, plan.context)
       });
     } else {
       const file = await materialisePlan(plan, spec.seed);
@@ -1219,6 +1291,13 @@ import { join } from "node:path";
 var dcmjsAny2 = 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 = dcmjsAny2.data.DicomMetaDictionary.nameMap;
@@ -1234,20 +1313,37 @@ function buildHexToKeyword() {
 function resolveKeepTags(keepTags) {
   const nameMap = dcmjsAny2.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 (nameMap && !Object.hasOwn(nameMap, tag)) {
-      throw new Error(`describe: unknown 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;
     }
-    return tag;
-  });
+    if (nameMap?.[keyword]?.vr === "UI") {
+      console.warn(
+        `describe: ignoring keep-tag "${keyword}" \u2014 UID-valued tags are not kept verbatim`
+      );
+      continue;
+    }
+    kept.push(keyword);
+  }
+  return kept;
 }
 function* walkFiles(dir) {
   for (const entry of readdirSync(dir, { withFileTypes: true })) {
@@ -1339,10 +1435,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;
 }
@@ -1606,6 +1704,7 @@ function resolveParametricSpec(spec) {
 export {
   MAX_PIXEL_BYTES,
   MAX_STREAM_BYTES,
+  TEMPLATE_VOCAB,
   caseCachePath,
   defaultPublicCasesPath,
   describeDirectory,
@@ -1617,6 +1716,7 @@ export {
   loadDefaultCases,
   previewCollection,
   resolveParametricSpec,
+  resolveTagTemplates,
   streamLargeImage,
   validateDatasetSpec,
   validateParametricSpec,

package/dist/esm/schema/parametric.js

@@ -15,6 +15,22 @@ function seededStream(seed, offset, a, b) {
   return lcg(seed * 999983 + offset + a * 1000003 + b * 7919 >>> 0);
 }
 
+// src/syntheticFixtures/tagTemplate.ts
+var TEMPLATE_VOCAB = [
+  "index",
+  "studyIndex",
+  "seriesIndex",
+  "instanceNumber"
+];
+var TEMPLATE_PART_RE = /\{\{|\}\}|\{([a-zA-Z]+)\}/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/limits.ts
 var MAX_PIXEL_BYTES = 512 * 1024 * 1024;
 var MAX_STREAM_BYTES = 50 * 1024 * 1024 * 1024;
@@ -207,12 +223,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 validateRange(value, path, options = {}) {

package/dist/esm/schema/validate.js

@@ -1,3 +1,19 @@
+// src/syntheticFixtures/tagTemplate.ts
+var TEMPLATE_VOCAB = [
+  "index",
+  "studyIndex",
+  "seriesIndex",
+  "instanceNumber"
+];
+var TEMPLATE_PART_RE = /\{\{|\}\}|\{([a-zA-Z]+)\}/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/limits.ts
 var MAX_PIXEL_BYTES = 512 * 1024 * 1024;
 var MAX_STREAM_BYTES = 50 * 1024 * 1024 * 1024;
@@ -196,12 +212,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) {

package/dist/esm/syntheticFixtures/tagTemplate.js

@@ -0,0 +1,49 @@
+// 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;
+}
+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);
+  });
+}
+export {
+  TEMPLATE_VOCAB,
+  escapeTagTemplate,
+  findTemplateTokens,
+  resolveTagTemplates
+};

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

@@ -1,4 +1,5 @@
 import type { DatasetSpec, FileSpec } from '../schema/types.js';
+import { type TagContext } from '../syntheticFixtures/tagTemplate.js';
 import type { UidSet } from '../syntheticFixtures/uid.js';
 export type GeneratedFile = {
     filename: string;
@@ -17,6 +18,7 @@ export declare function generateFile(spec: FileSpec, options?: {
     seed?: number;
     padWidth?: number;
     uid?: Partial<UidSet>;
+    context?: Partial<TagContext>;
 }): Promise<GeneratedFile>;
 export declare function withResolvedSeed(spec: DatasetSpec): DatasetSpec;
 export declare function generateCollectionFromSpec(spec: DatasetSpec): AsyncGenerator<GeneratedFile>;

package/dist/types/index.d.ts

@@ -7,3 +7,4 @@ 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 { 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';

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

@@ -0,0 +1,11 @@
+import type { DicomTagOverrides } from '../schema/types.js';
+export type TagContext = {
+    index: number;
+    studyIndex?: number;
+    seriesIndex?: number;
+    instanceNumber?: number;
+};
+export declare const TEMPLATE_VOCAB: readonly ["index", "studyIndex", "seriesIndex", "instanceNumber"];
+export declare function escapeTagTemplate(value: string): string;
+export declare function findTemplateTokens(value: string): string[];
+export declare function resolveTagTemplates(tags: DicomTagOverrides | undefined, context: TagContext): DicomTagOverrides | undefined;

package/package.json

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