dicom-synth 1.10.0 → 1.11.0

package/bin/dicom-synth-describe.mjs

@@ -1,11 +1,12 @@
 #!/usr/bin/env node
 import { readFileSync, writeFileSync } from 'node:fs'
 import { resolve } from 'node:path'
+import { gzipSync } from 'node:zlib'
 import { describeDirectory } from '../dist/esm/index.js'
 
 function usage() {
   console.error(
-    'Usage: dicom-synth-describe <dir> [--out <spec.json>] [--keep-tags <a,b,...>] [--keep-tags-file <path>]\n' +
+    'Usage: dicom-synth-describe <dir> [--out <spec.json[.gz]>] [--keep-tags <a,b,...>] [--keep-tags-file <path>] [--size-tolerance <fraction>] [--gzip]\n' +
       '\n' +
       'Scans a DICOM tree and emits a DatasetSpec describing its shape\n' +
       '(studies/series, per-file size, modality).\n' +
@@ -15,7 +16,10 @@ function usage() {
       "verbatim; if a kept tag holds PHI, handling it is the caller's\n" +
       "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.',
+      'line, # comments); merged with any --keep-tags.\n' +
+      '--size-tolerance folds near-identical file sizes (fraction, e.g. 0.05\n' +
+      '= ±5%) into one entry; default exact.\n' +
+      '--gzip (or a .gz --out suffix) writes the spec gzip-compressed.',
   )
   process.exit(1)
 }
@@ -33,6 +37,8 @@ if (args.length === 0) usage()
 
 let dir
 let outPath
+let sizeTolerance
+let gzip = false
 const keepTags = []
 
 for (let i = 0; i < args.length; i++) {
@@ -52,6 +58,14 @@ for (let i = 0; i < args.length; i++) {
       console.error(`Error reading keep-tags file: ${err.message}`)
       process.exit(1)
     }
+  } else if (args[i] === '--size-tolerance' && args[i + 1]) {
+    sizeTolerance = Number(args[++i])
+    if (!Number.isFinite(sizeTolerance) || sizeTolerance < 0) {
+      console.error('--size-tolerance must be a non-negative number')
+      process.exit(1)
+    }
+  } else if (args[i] === '--gzip') {
+    gzip = true
   } else if (args[i].startsWith('--')) {
     console.error(`Unknown argument: ${args[i]}`)
     usage()
@@ -67,18 +81,22 @@ if (dir === undefined) usage()
 
 let result
 try {
-  result = describeDirectory(dir, keepTags.length ? { keepTags } : {})
+  result = describeDirectory(dir, {
+    ...(keepTags.length ? { keepTags } : {}),
+    ...(sizeTolerance !== undefined ? { sizeTolerance } : {}),
+  })
 } catch (err) {
   console.error(`Error: ${err.message}`)
   process.exit(1)
 }
 
 const json = `${JSON.stringify(result.spec, null, 2)}\n`
+const compress = gzip || outPath?.endsWith('.gz')
 if (outPath) {
-  writeFileSync(outPath, json)
+  writeFileSync(outPath, compress ? gzipSync(json) : json)
   console.error(`Wrote DatasetSpec to ${outPath}`)
 } else {
-  process.stdout.write(json)
+  process.stdout.write(compress ? gzipSync(json) : json)
 }
 
 const { dicomFiles, skipped, unknownModality } = result.stats

package/dist/esm/collection/writer.js

@@ -587,12 +587,41 @@ function filename(type, index, padWidth) {
 function entryCount(entries) {
   return entries.reduce((sum, e) => sum + (e.count ?? 1), 0);
 }
+function seriesFileCount(series) {
+  return series.instances ? series.instances.count : entryCount(series.entries ?? []);
+}
 function studyFileCount(studies) {
   return studies.reduce(
-    (sum, study) => sum + (study.count ?? 1) * study.series.reduce((s, series) => s + entryCount(series.entries), 0),
+    (sum, study) => sum + (study.count ?? 1) * study.series.reduce((s, series) => s + seriesFileCount(series), 0),
     0
   );
 }
+function* seriesFiles(series) {
+  if (series.instances) {
+    const inst = series.instances;
+    for (let i = 0; i < inst.count; i++) {
+      const modality = Array.isArray(inst.modality) ? inst.modality[i] : inst.modality;
+      const baseSpec = {
+        ...inst.targetBytes ? { type: "large-image", targetBytes: inst.targetBytes[i] } : { type: "valid-image", targetSizeKb: inst.targetSizeKb?.[i] },
+        ...modality !== void 0 ? { modality } : {}
+      };
+      const instanceTags = {};
+      if (inst.tags) {
+        for (const [key, values] of Object.entries(inst.tags)) {
+          instanceTags[key] = values[i];
+        }
+      }
+      yield { baseSpec, instanceTags };
+    }
+    return;
+  }
+  for (const entry of series.entries ?? []) {
+    const { count = 1, tags, ...baseSpec } = entry;
+    for (let i = 0; i < count; i++) {
+      yield { baseSpec, instanceTags: tags ?? {} };
+    }
+  }
+}
 function resolveUid(seed, index, override) {
   return { ...makeUidGenerator(seed)(index), ...override };
 }
@@ -720,36 +749,33 @@ function* planCollection(spec) {
       for (const [seriesIndex, series] of study.series.entries()) {
         const seriesUid = groupUids.series(studyOrdinal, seriesIndex);
         let instanceNumber = 0;
-        for (const entry of series.entries) {
-          const { count = 1, ...fileSpec } = entry;
-          for (let i = 0; i < count; i++) {
-            instanceNumber++;
-            const tags = {
-              InstanceNumber: instanceNumber,
-              ...study.tags,
-              ...series.tags,
-              ...fileSpec.tags
-            };
-            yield {
-              fileSpec: { ...fileSpec, tags },
+        for (const { baseSpec, instanceTags } of seriesFiles(series)) {
+          instanceNumber++;
+          const tags = {
+            InstanceNumber: instanceNumber,
+            ...study.tags,
+            ...series.tags,
+            ...instanceTags
+          };
+          yield {
+            fileSpec: { ...baseSpec, tags },
+            index: globalIndex,
+            uidOverride: { study: studyUid, series: seriesUid },
+            context: {
               index: globalIndex,
-              uidOverride: { study: studyUid, series: seriesUid },
-              context: {
-                index: globalIndex,
-                studyIndex: studyOrdinal,
-                seriesIndex,
-                instanceNumber
-              },
-              ...computeNames(
-                fileSpec.type,
-                globalIndex,
-                padWidth,
-                hierarchical ? { studyOrdinal, seriesIndex, instanceNumber } : void 0,
-                quirks
-              )
-            };
-            globalIndex++;
-          }
+              studyIndex: studyOrdinal,
+              seriesIndex,
+              instanceNumber
+            },
+            ...computeNames(
+              baseSpec.type,
+              globalIndex,
+              padWidth,
+              hierarchical ? { studyOrdinal, seriesIndex, instanceNumber } : void 0,
+              quirks
+            )
+          };
+          globalIndex++;
         }
       }
       studyOrdinal++;

package/dist/esm/describe/describe.js

@@ -239,26 +239,100 @@ function validateEntry(entry, path) {
   return e;
 }
 var MODALITY_TAG = "00080060";
+function validateTagValue(key, value, 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 validateTags(tags, path) {
   if (typeof tags !== "object" || tags === null || Array.isArray(tags)) {
     throw new Error(`${path}: must be an object`);
   }
   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`
+    validateTagValue(key, value, path);
+  }
+}
+function validateArrayOfLength(value, count, path) {
+  if (!Array.isArray(value)) {
+    throw new Error(`${path}: must be an array`);
+  }
+  if (value.length !== count) {
+    throw new Error(
+      `${path}: length (${value.length}) must equal count (${count})`
+    );
+  }
+  return value;
+}
+function validateInstances(instances, path) {
+  if (typeof instances !== "object" || instances === null || Array.isArray(instances)) {
+    throw new Error(`${path}: must be an object`);
+  }
+  const inst = instances;
+  validatePositiveInt(inst.count, `${path}.count`);
+  const count = inst.count;
+  const hasKb = "targetSizeKb" in inst;
+  const hasBytes = "targetBytes" in inst;
+  if (hasKb === hasBytes) {
+    throw new Error(
+      `${path}: exactly one of "targetSizeKb" or "targetBytes" is required`
+    );
+  }
+  if (hasKb) {
+    const sizes = validateArrayOfLength(
+      inst.targetSizeKb,
+      count,
+      `${path}.targetSizeKb`
+    );
+    sizes.forEach((kb, i) => {
+      validatePositiveInt(kb, `${path}.targetSizeKb[${i}]`);
+      validateSizeKbLimit(kb, `${path}.targetSizeKb[${i}]`);
+    });
+  } else {
+    const sizes = validateArrayOfLength(
+      inst.targetBytes,
+      count,
+      `${path}.targetBytes`
+    );
+    sizes.forEach((b, i) => {
+      validateLargeTargetBytes(b, `${path}.targetBytes[${i}]`);
+    });
+  }
+  if ("modality" in inst) {
+    if (Array.isArray(inst.modality)) {
+      validateArrayOfLength(inst.modality, count, `${path}.modality`).forEach(
+        (m, i) => {
+          validateEnum(m, VALID_MODALITIES, `${path}.modality[${i}]`);
+        }
       );
+    } else {
+      validateEnum(inst.modality, VALID_MODALITIES, `${path}.modality`);
+    }
+  }
+  if ("tags" in inst) {
+    const tags = inst.tags;
+    if (typeof tags !== "object" || tags === null || Array.isArray(tags)) {
+      throw new Error(`${path}.tags: must be an object`);
     }
-    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(", ")}`
-          );
+    for (const [key, arr] of Object.entries(tags)) {
+      validateTagKey(key, `${path}.tags`);
+      validateArrayOfLength(arr, count, `${path}.tags.${key}`).forEach(
+        (value, i) => {
+          validateTagValue(key, value, `${path}.tags[${i}]`);
         }
-      }
+      );
     }
   }
 }
@@ -267,16 +341,27 @@ function validateSeries(series, path) {
     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`);
+  const hasEntries = "entries" in s;
+  const hasInstances = "instances" in s;
+  if (hasEntries === hasInstances) {
+    throw new Error(
+      `${path}: must have exactly one of "entries" or "instances"`
+    );
   }
-  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 (hasEntries) {
+    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`
+        );
+      }
     }
+  } else {
+    validateInstances(s.instances, `${path}.instances`);
   }
   if ("tags" in s) validateTags(s.tags, `${path}.tags`);
   return s;
@@ -498,8 +583,117 @@ function extractTags(record, keepKeywords) {
   }
   return found ? tags : void 0;
 }
+function sizeKbOf(bytes) {
+  return Math.max(1, Math.round(bytes / 1024));
+}
+function bucketBytes(bytes, tolerance) {
+  if (tolerance <= 0 || bytes < 1) return bytes;
+  const factor = 1 + tolerance;
+  const bucket = Math.floor(Math.log(bytes) / Math.log(factor));
+  return Math.max(1, Math.round(factor ** (bucket + 0.5)));
+}
+function collapseKeyOf(r) {
+  return JSON.stringify([
+    r.large,
+    r.modality ?? null,
+    r.large ? r.bytes : sizeKbOf(r.bytes),
+    r.tags ?? null
+  ]);
+}
+function accumulate(byKey, r) {
+  const key = collapseKeyOf(r);
+  const existing = byKey.get(key);
+  if (existing) {
+    existing.count++;
+  } else {
+    byKey.set(key, {
+      modality: r.modality,
+      large: r.large,
+      bytes: r.bytes,
+      tags: r.tags,
+      count: 1
+    });
+  }
+}
+function entryOf(acc) {
+  return {
+    ...acc.modality !== void 0 ? { modality: acc.modality } : {},
+    ...acc.large ? { type: "large-image", targetBytes: acc.bytes } : { type: "valid-image", targetSizeKb: sizeKbOf(acc.bytes) },
+    ...acc.tags !== void 0 ? { tags: acc.tags } : {},
+    ...acc.count > 1 ? { count: acc.count } : {}
+  };
+}
+function collapseEntries(records) {
+  const byKey = /* @__PURE__ */ new Map();
+  for (const r of records) accumulate(byKey, r);
+  return [...byKey.values()].map(entryOf);
+}
+function tagValuesEqual(a, b) {
+  if (a === b) return true;
+  if (typeof a === "object" && a !== null && typeof b === "object" && b !== null)
+    return JSON.stringify(a) === JSON.stringify(b);
+  return false;
+}
+function tryInstancesForm(records) {
+  const count = records.length;
+  if (count === 0) return null;
+  const large = records[0]?.large ?? false;
+  const modality = records[0]?.modality;
+  const columns = /* @__PURE__ */ new Map();
+  for (let i = 0; i < count; i++) {
+    const r = records[i];
+    if (r.large !== large || r.modality !== modality) return null;
+    if (!r.tags) continue;
+    for (const [k, v] of Object.entries(r.tags)) {
+      let col = columns.get(k);
+      if (!col) {
+        col = { values: new Array(count), present: 0 };
+        columns.set(k, col);
+      }
+      col.values[i] = v;
+      col.present++;
+    }
+  }
+  if (columns.size === 0) return null;
+  const sharedTags = {};
+  const perInstanceTags = {};
+  for (const [k, col] of columns) {
+    if (col.present !== count) return null;
+    const first = col.values[0];
+    if (col.values.every((v) => tagValuesEqual(v, first))) {
+      sharedTags[k] = first;
+    } else {
+      perInstanceTags[k] = col.values;
+    }
+  }
+  if (Object.keys(perInstanceTags).length === 0) return null;
+  const instances = {
+    count,
+    ...large ? { targetBytes: records.map((r) => r.bytes) } : { targetSizeKb: records.map((r) => sizeKbOf(r.bytes)) },
+    ...modality !== void 0 ? { modality } : {},
+    // perInstanceTags is non-empty here (we returned null above otherwise).
+    tags: perInstanceTags
+  };
+  return {
+    instances,
+    ...Object.keys(sharedTags).length ? { tags: sharedTags } : {}
+  };
+}
+function buildSeriesSpec(records) {
+  return tryInstancesForm(records) ?? { entries: collapseEntries(records) };
+}
+function seriesSpecFromAccum(accum) {
+  return Array.isArray(accum) ? buildSeriesSpec(accum) : { entries: [...accum.values()].map(entryOf) };
+}
 function describeDirectory(dir, options = {}) {
   const keepKeywords = options.keepTags ? resolveKeepTags(options.keepTags) : [];
+  const keepTags = keepKeywords.length > 0;
+  const tolerance = options.sizeTolerance ?? 0;
+  if (!Number.isFinite(tolerance) || tolerance < 0) {
+    throw new Error(
+      `describe: sizeTolerance must be a non-negative fraction; got ${JSON.stringify(options.sizeTolerance)}`
+    );
+  }
   const studies = /* @__PURE__ */ new Map();
   const stats = { dicomFiles: 0, skipped: 0, unknownModality: 0 };
   for (const path of [...walkFiles(dir)].sort()) {
@@ -531,8 +725,9 @@ function describeDirectory(dir, options = {}) {
         stats.unknownModality++;
       }
     }
-    const sizeKb = Math.max(1, Math.round(size / 1024));
-    const tags = keepKeywords.length ? extractTags(record, keepKeywords) : void 0;
+    const tags = keepTags ? extractTags(record, keepKeywords) : void 0;
+    const bytes = large ? size : Math.min(bucketBytes(size, tolerance), MAX_PIXEL_BYTES);
+    const fileRecord = { large, bytes, modality, tags };
     let study = studies.get(studyUid);
     if (!study) {
       study = /* @__PURE__ */ new Map();
@@ -540,37 +735,18 @@ function describeDirectory(dir, options = {}) {
     }
     let series = study.get(seriesUid);
     if (!series) {
-      series = /* @__PURE__ */ new Map();
+      series = keepTags ? [] : /* @__PURE__ */ new Map();
       study.set(seriesUid, series);
     }
-    const collapseKey = JSON.stringify([
-      large,
-      modality ?? null,
-      large ? size : sizeKb,
-      tags ?? null
-    ]);
-    const existing = series.get(collapseKey);
-    if (existing) {
-      existing.count++;
+    if (Array.isArray(series)) {
+      series.push(fileRecord);
     } else {
-      series.set(collapseKey, { modality, large, bytes: size, tags, count: 1 });
+      accumulate(series, fileRecord);
     }
   }
-  const studySpecs = [...studies.values()].map((study) => {
-    const seriesSpecs = [...study.values()].map((series) => {
-      const entries = [...series.values()].map((acc) => ({
-        ...acc.modality !== void 0 ? { modality: acc.modality } : {},
-        ...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 } : {}
-      }));
-      return { entries };
-    });
-    return { series: seriesSpecs };
-  });
+  const studySpecs = [...studies.values()].map((study) => ({
+    series: [...study.values()].map(seriesSpecFromAccum)
+  }));
   if (studySpecs.length === 0) {
     throw new Error(`describe: no DICOM series found in ${dir}`);
   }
@@ -580,5 +756,6 @@ function describeDirectory(dir, options = {}) {
 }
 export {
   describeDirectory,
-  readHeaderOnly
+  readHeaderOnly,
+  tagValuesEqual
 };

package/dist/esm/index.js

@@ -288,26 +288,100 @@ function validateEntry(entry, path) {
   return e;
 }
 var MODALITY_TAG = "00080060";
+function validateTagValue(key, value, 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 validateTags(tags, path) {
   if (typeof tags !== "object" || tags === null || Array.isArray(tags)) {
     throw new Error(`${path}: must be an object`);
   }
   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`
+    validateTagValue(key, value, path);
+  }
+}
+function validateArrayOfLength(value, count, path) {
+  if (!Array.isArray(value)) {
+    throw new Error(`${path}: must be an array`);
+  }
+  if (value.length !== count) {
+    throw new Error(
+      `${path}: length (${value.length}) must equal count (${count})`
+    );
+  }
+  return value;
+}
+function validateInstances(instances, path) {
+  if (typeof instances !== "object" || instances === null || Array.isArray(instances)) {
+    throw new Error(`${path}: must be an object`);
+  }
+  const inst = instances;
+  validatePositiveInt(inst.count, `${path}.count`);
+  const count = inst.count;
+  const hasKb = "targetSizeKb" in inst;
+  const hasBytes = "targetBytes" in inst;
+  if (hasKb === hasBytes) {
+    throw new Error(
+      `${path}: exactly one of "targetSizeKb" or "targetBytes" is required`
+    );
+  }
+  if (hasKb) {
+    const sizes = validateArrayOfLength(
+      inst.targetSizeKb,
+      count,
+      `${path}.targetSizeKb`
+    );
+    sizes.forEach((kb, i) => {
+      validatePositiveInt(kb, `${path}.targetSizeKb[${i}]`);
+      validateSizeKbLimit(kb, `${path}.targetSizeKb[${i}]`);
+    });
+  } else {
+    const sizes = validateArrayOfLength(
+      inst.targetBytes,
+      count,
+      `${path}.targetBytes`
+    );
+    sizes.forEach((b, i) => {
+      validateLargeTargetBytes(b, `${path}.targetBytes[${i}]`);
+    });
+  }
+  if ("modality" in inst) {
+    if (Array.isArray(inst.modality)) {
+      validateArrayOfLength(inst.modality, count, `${path}.modality`).forEach(
+        (m, i) => {
+          validateEnum(m, VALID_MODALITIES, `${path}.modality[${i}]`);
+        }
       );
+    } else {
+      validateEnum(inst.modality, VALID_MODALITIES, `${path}.modality`);
     }
-    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(", ")}`
-          );
+  }
+  if ("tags" in inst) {
+    const tags = inst.tags;
+    if (typeof tags !== "object" || tags === null || Array.isArray(tags)) {
+      throw new Error(`${path}.tags: must be an object`);
+    }
+    for (const [key, arr] of Object.entries(tags)) {
+      validateTagKey(key, `${path}.tags`);
+      validateArrayOfLength(arr, count, `${path}.tags.${key}`).forEach(
+        (value, i) => {
+          validateTagValue(key, value, `${path}.tags[${i}]`);
         }
-      }
+      );
     }
   }
 }
@@ -316,16 +390,27 @@ function validateSeries(series, path) {
     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`);
+  const hasEntries = "entries" in s;
+  const hasInstances = "instances" in s;
+  if (hasEntries === hasInstances) {
+    throw new Error(
+      `${path}: must have exactly one of "entries" or "instances"`
+    );
   }
-  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 (hasEntries) {
+    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`
+        );
+      }
     }
+  } else {
+    validateInstances(s.instances, `${path}.instances`);
   }
   if ("tags" in s) validateTags(s.tags, `${path}.tags`);
   return s;
@@ -1033,12 +1118,41 @@ function filename(type, index, padWidth) {
 function entryCount(entries) {
   return entries.reduce((sum, e) => sum + (e.count ?? 1), 0);
 }
+function seriesFileCount(series) {
+  return series.instances ? series.instances.count : entryCount(series.entries ?? []);
+}
 function studyFileCount(studies) {
   return studies.reduce(
-    (sum, study) => sum + (study.count ?? 1) * study.series.reduce((s, series) => s + entryCount(series.entries), 0),
+    (sum, study) => sum + (study.count ?? 1) * study.series.reduce((s, series) => s + seriesFileCount(series), 0),
     0
   );
 }
+function* seriesFiles(series) {
+  if (series.instances) {
+    const inst = series.instances;
+    for (let i = 0; i < inst.count; i++) {
+      const modality = Array.isArray(inst.modality) ? inst.modality[i] : inst.modality;
+      const baseSpec = {
+        ...inst.targetBytes ? { type: "large-image", targetBytes: inst.targetBytes[i] } : { type: "valid-image", targetSizeKb: inst.targetSizeKb?.[i] },
+        ...modality !== void 0 ? { modality } : {}
+      };
+      const instanceTags = {};
+      if (inst.tags) {
+        for (const [key, values] of Object.entries(inst.tags)) {
+          instanceTags[key] = values[i];
+        }
+      }
+      yield { baseSpec, instanceTags };
+    }
+    return;
+  }
+  for (const entry of series.entries ?? []) {
+    const { count = 1, tags, ...baseSpec } = entry;
+    for (let i = 0; i < count; i++) {
+      yield { baseSpec, instanceTags: tags ?? {} };
+    }
+  }
+}
 function resolveUid(seed, index, override) {
   return { ...makeUidGenerator(seed)(index), ...override };
 }
@@ -1166,36 +1280,33 @@ function* planCollection(spec) {
       for (const [seriesIndex, series] of study.series.entries()) {
         const seriesUid = groupUids.series(studyOrdinal, seriesIndex);
         let instanceNumber = 0;
-        for (const entry of series.entries) {
-          const { count = 1, ...fileSpec } = entry;
-          for (let i = 0; i < count; i++) {
-            instanceNumber++;
-            const tags = {
-              InstanceNumber: instanceNumber,
-              ...study.tags,
-              ...series.tags,
-              ...fileSpec.tags
-            };
-            yield {
-              fileSpec: { ...fileSpec, tags },
+        for (const { baseSpec, instanceTags } of seriesFiles(series)) {
+          instanceNumber++;
+          const tags = {
+            InstanceNumber: instanceNumber,
+            ...study.tags,
+            ...series.tags,
+            ...instanceTags
+          };
+          yield {
+            fileSpec: { ...baseSpec, tags },
+            index: globalIndex,
+            uidOverride: { study: studyUid, series: seriesUid },
+            context: {
               index: globalIndex,
-              uidOverride: { study: studyUid, series: seriesUid },
-              context: {
-                index: globalIndex,
-                studyIndex: studyOrdinal,
-                seriesIndex,
-                instanceNumber
-              },
-              ...computeNames(
-                fileSpec.type,
-                globalIndex,
-                padWidth,
-                hierarchical ? { studyOrdinal, seriesIndex, instanceNumber } : void 0,
-                quirks
-              )
-            };
-            globalIndex++;
-          }
+              studyIndex: studyOrdinal,
+              seriesIndex,
+              instanceNumber
+            },
+            ...computeNames(
+              baseSpec.type,
+              globalIndex,
+              padWidth,
+              hierarchical ? { studyOrdinal, seriesIndex, instanceNumber } : void 0,
+              quirks
+            )
+          };
+          globalIndex++;
         }
       }
       studyOrdinal++;
@@ -1444,8 +1555,117 @@ function extractTags(record, keepKeywords) {
   }
   return found ? tags : void 0;
 }
+function sizeKbOf(bytes) {
+  return Math.max(1, Math.round(bytes / 1024));
+}
+function bucketBytes(bytes, tolerance) {
+  if (tolerance <= 0 || bytes < 1) return bytes;
+  const factor = 1 + tolerance;
+  const bucket = Math.floor(Math.log(bytes) / Math.log(factor));
+  return Math.max(1, Math.round(factor ** (bucket + 0.5)));
+}
+function collapseKeyOf(r) {
+  return JSON.stringify([
+    r.large,
+    r.modality ?? null,
+    r.large ? r.bytes : sizeKbOf(r.bytes),
+    r.tags ?? null
+  ]);
+}
+function accumulate(byKey, r) {
+  const key = collapseKeyOf(r);
+  const existing = byKey.get(key);
+  if (existing) {
+    existing.count++;
+  } else {
+    byKey.set(key, {
+      modality: r.modality,
+      large: r.large,
+      bytes: r.bytes,
+      tags: r.tags,
+      count: 1
+    });
+  }
+}
+function entryOf(acc) {
+  return {
+    ...acc.modality !== void 0 ? { modality: acc.modality } : {},
+    ...acc.large ? { type: "large-image", targetBytes: acc.bytes } : { type: "valid-image", targetSizeKb: sizeKbOf(acc.bytes) },
+    ...acc.tags !== void 0 ? { tags: acc.tags } : {},
+    ...acc.count > 1 ? { count: acc.count } : {}
+  };
+}
+function collapseEntries(records) {
+  const byKey = /* @__PURE__ */ new Map();
+  for (const r of records) accumulate(byKey, r);
+  return [...byKey.values()].map(entryOf);
+}
+function tagValuesEqual(a, b) {
+  if (a === b) return true;
+  if (typeof a === "object" && a !== null && typeof b === "object" && b !== null)
+    return JSON.stringify(a) === JSON.stringify(b);
+  return false;
+}
+function tryInstancesForm(records) {
+  const count = records.length;
+  if (count === 0) return null;
+  const large = records[0]?.large ?? false;
+  const modality = records[0]?.modality;
+  const columns = /* @__PURE__ */ new Map();
+  for (let i = 0; i < count; i++) {
+    const r = records[i];
+    if (r.large !== large || r.modality !== modality) return null;
+    if (!r.tags) continue;
+    for (const [k, v] of Object.entries(r.tags)) {
+      let col = columns.get(k);
+      if (!col) {
+        col = { values: new Array(count), present: 0 };
+        columns.set(k, col);
+      }
+      col.values[i] = v;
+      col.present++;
+    }
+  }
+  if (columns.size === 0) return null;
+  const sharedTags = {};
+  const perInstanceTags = {};
+  for (const [k, col] of columns) {
+    if (col.present !== count) return null;
+    const first = col.values[0];
+    if (col.values.every((v) => tagValuesEqual(v, first))) {
+      sharedTags[k] = first;
+    } else {
+      perInstanceTags[k] = col.values;
+    }
+  }
+  if (Object.keys(perInstanceTags).length === 0) return null;
+  const instances = {
+    count,
+    ...large ? { targetBytes: records.map((r) => r.bytes) } : { targetSizeKb: records.map((r) => sizeKbOf(r.bytes)) },
+    ...modality !== void 0 ? { modality } : {},
+    // perInstanceTags is non-empty here (we returned null above otherwise).
+    tags: perInstanceTags
+  };
+  return {
+    instances,
+    ...Object.keys(sharedTags).length ? { tags: sharedTags } : {}
+  };
+}
+function buildSeriesSpec(records) {
+  return tryInstancesForm(records) ?? { entries: collapseEntries(records) };
+}
+function seriesSpecFromAccum(accum) {
+  return Array.isArray(accum) ? buildSeriesSpec(accum) : { entries: [...accum.values()].map(entryOf) };
+}
 function describeDirectory(dir, options = {}) {
   const keepKeywords = options.keepTags ? resolveKeepTags(options.keepTags) : [];
+  const keepTags = keepKeywords.length > 0;
+  const tolerance = options.sizeTolerance ?? 0;
+  if (!Number.isFinite(tolerance) || tolerance < 0) {
+    throw new Error(
+      `describe: sizeTolerance must be a non-negative fraction; got ${JSON.stringify(options.sizeTolerance)}`
+    );
+  }
   const studies = /* @__PURE__ */ new Map();
   const stats = { dicomFiles: 0, skipped: 0, unknownModality: 0 };
   for (const path of [...walkFiles(dir)].sort()) {
@@ -1477,8 +1697,9 @@ function describeDirectory(dir, options = {}) {
         stats.unknownModality++;
       }
     }
-    const sizeKb = Math.max(1, Math.round(size / 1024));
-    const tags = keepKeywords.length ? extractTags(record, keepKeywords) : void 0;
+    const tags = keepTags ? extractTags(record, keepKeywords) : void 0;
+    const bytes = large ? size : Math.min(bucketBytes(size, tolerance), MAX_PIXEL_BYTES);
+    const fileRecord = { large, bytes, modality, tags };
     let study = studies.get(studyUid);
     if (!study) {
       study = /* @__PURE__ */ new Map();
@@ -1486,37 +1707,18 @@ function describeDirectory(dir, options = {}) {
     }
     let series = study.get(seriesUid);
     if (!series) {
-      series = /* @__PURE__ */ new Map();
+      series = keepTags ? [] : /* @__PURE__ */ new Map();
       study.set(seriesUid, series);
     }
-    const collapseKey = JSON.stringify([
-      large,
-      modality ?? null,
-      large ? size : sizeKb,
-      tags ?? null
-    ]);
-    const existing = series.get(collapseKey);
-    if (existing) {
-      existing.count++;
+    if (Array.isArray(series)) {
+      series.push(fileRecord);
     } else {
-      series.set(collapseKey, { modality, large, bytes: size, tags, count: 1 });
+      accumulate(series, fileRecord);
     }
   }
-  const studySpecs = [...studies.values()].map((study) => {
-    const seriesSpecs = [...study.values()].map((series) => {
-      const entries = [...series.values()].map((acc) => ({
-        ...acc.modality !== void 0 ? { modality: acc.modality } : {},
-        ...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 } : {}
-      }));
-      return { entries };
-    });
-    return { series: seriesSpecs };
-  });
+  const studySpecs = [...studies.values()].map((study) => ({
+    series: [...study.values()].map(seriesSpecFromAccum)
+  }));
   if (studySpecs.length === 0) {
     throw new Error(`describe: no DICOM series found in ${dir}`);
   }

package/dist/esm/schema/parametric.js

@@ -224,27 +224,30 @@ function validateEntry(entry, path) {
   return e;
 }
 var MODALITY_TAG = "00080060";
+function validateTagValue(key, value, 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 validateTags(tags, path) {
   if (typeof tags !== "object" || tags === null || Array.isArray(tags)) {
     throw new Error(`${path}: must be an object`);
   }
   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(", ")}`
-          );
-        }
-      }
-    }
+    validateTagValue(key, value, path);
   }
 }
 function validateRange(value, path, options = {}) {

package/dist/esm/schema/validate.js

@@ -213,26 +213,100 @@ function validateEntry(entry, path) {
   return e;
 }
 var MODALITY_TAG = "00080060";
+function validateTagValue(key, value, 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 validateTags(tags, path) {
   if (typeof tags !== "object" || tags === null || Array.isArray(tags)) {
     throw new Error(`${path}: must be an object`);
   }
   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`
+    validateTagValue(key, value, path);
+  }
+}
+function validateArrayOfLength(value, count, path) {
+  if (!Array.isArray(value)) {
+    throw new Error(`${path}: must be an array`);
+  }
+  if (value.length !== count) {
+    throw new Error(
+      `${path}: length (${value.length}) must equal count (${count})`
+    );
+  }
+  return value;
+}
+function validateInstances(instances, path) {
+  if (typeof instances !== "object" || instances === null || Array.isArray(instances)) {
+    throw new Error(`${path}: must be an object`);
+  }
+  const inst = instances;
+  validatePositiveInt(inst.count, `${path}.count`);
+  const count = inst.count;
+  const hasKb = "targetSizeKb" in inst;
+  const hasBytes = "targetBytes" in inst;
+  if (hasKb === hasBytes) {
+    throw new Error(
+      `${path}: exactly one of "targetSizeKb" or "targetBytes" is required`
+    );
+  }
+  if (hasKb) {
+    const sizes = validateArrayOfLength(
+      inst.targetSizeKb,
+      count,
+      `${path}.targetSizeKb`
+    );
+    sizes.forEach((kb, i) => {
+      validatePositiveInt(kb, `${path}.targetSizeKb[${i}]`);
+      validateSizeKbLimit(kb, `${path}.targetSizeKb[${i}]`);
+    });
+  } else {
+    const sizes = validateArrayOfLength(
+      inst.targetBytes,
+      count,
+      `${path}.targetBytes`
+    );
+    sizes.forEach((b, i) => {
+      validateLargeTargetBytes(b, `${path}.targetBytes[${i}]`);
+    });
+  }
+  if ("modality" in inst) {
+    if (Array.isArray(inst.modality)) {
+      validateArrayOfLength(inst.modality, count, `${path}.modality`).forEach(
+        (m, i) => {
+          validateEnum(m, VALID_MODALITIES, `${path}.modality[${i}]`);
+        }
       );
+    } else {
+      validateEnum(inst.modality, VALID_MODALITIES, `${path}.modality`);
+    }
+  }
+  if ("tags" in inst) {
+    const tags = inst.tags;
+    if (typeof tags !== "object" || tags === null || Array.isArray(tags)) {
+      throw new Error(`${path}.tags: must be an object`);
     }
-    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(", ")}`
-          );
+    for (const [key, arr] of Object.entries(tags)) {
+      validateTagKey(key, `${path}.tags`);
+      validateArrayOfLength(arr, count, `${path}.tags.${key}`).forEach(
+        (value, i) => {
+          validateTagValue(key, value, `${path}.tags[${i}]`);
         }
-      }
+      );
     }
   }
 }
@@ -241,16 +315,27 @@ function validateSeries(series, path) {
     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`);
+  const hasEntries = "entries" in s;
+  const hasInstances = "instances" in s;
+  if (hasEntries === hasInstances) {
+    throw new Error(
+      `${path}: must have exactly one of "entries" or "instances"`
+    );
   }
-  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 (hasEntries) {
+    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`
+        );
+      }
     }
+  } else {
+    validateInstances(s.instances, `${path}.instances`);
   }
   if ("tags" in s) validateTags(s.tags, `${path}.tags`);
   return s;

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

@@ -1,6 +1,7 @@
 import type { DatasetSpec } from '../schema/types.js';
 export type DescribeOptions = {
     keepTags?: string[];
+    sizeTolerance?: number;
 };
 export type DescribeResult = {
     spec: DatasetSpec;
@@ -11,4 +12,5 @@ export type DescribeResult = {
     };
 };
 export declare function readHeaderOnly(path: string): Record<string, unknown> | null;
+export declare function tagValuesEqual(a: unknown, b: unknown): boolean;
 export declare function describeDirectory(dir: string, options?: DescribeOptions): DescribeResult;

package/dist/types/index.d.ts

@@ -4,7 +4,7 @@ export { defaultPublicCasesPath, loadCaseById, loadCasesFromJson, loadDefaultCas
 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, LargeFileSpec, 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, SeriesInstances, 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/schema/types.d.ts

@@ -51,8 +51,16 @@ export type EntrySpec = FileSpec & {
 export type SeriesEntrySpec = (ImageSpec | LargeFileSpec) & {
     count?: number;
 };
+export type SeriesInstances = {
+    count: number;
+    targetSizeKb?: number[];
+    targetBytes?: number[];
+    modality?: Modality | Modality[];
+    tags?: Record<string, unknown[]>;
+};
 export type SeriesSpec = {
-    entries: SeriesEntrySpec[];
+    entries?: SeriesEntrySpec[];
+    instances?: SeriesInstances;
     tags?: DicomTagOverrides;
 };
 export type StudySpec = {

package/package.json

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