dicom-synth 1.16.0 → 1.18.0

package/bin/dicom-synth-describe.mjs

@@ -6,7 +6,7 @@ import { describeDirectory } from '../dist/esm/index.js'
 
 function usage() {
   console.error(
-    'Usage: dicom-synth-describe <dir> [--out <spec.json[.gz]>] [--tree] [--keep-tags <a,b,...>] [--keep-tags-file <path>] [--size-tolerance <fraction>] [--no-preserve-uids] [--uid-salt <hex>] [--gzip]\n' +
+    'Usage: dicom-synth-describe <dir> [--out <spec.json[.gz]>] [--tree] [--keep-tags <a,b,...>] [--keep-tags-file <path>] [--keep-private-tags] [--size-tolerance <fraction>] [--no-preserve-uids] [--uid-salt <hex>] [--gzip]\n' +
       '\n' +
       'Scans a DICOM tree and emits a DatasetSpec describing its shape\n' +
       '(studies/series, per-file size, modality).\n' +
@@ -22,6 +22,13 @@ function usage() {
       "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.\n' +
+      '--keep-private-tags captures ALL private (odd-group) elements as-is as\n' +
+      'raw { vr, value } tag forms — creators, scalars, nested private\n' +
+      'sequences. Private blocks routinely carry PHI/device detail: handling\n' +
+      "that is the caller's responsibility. UID-valued leaves are still\n" +
+      'hashed unless --no-preserve-uids. Individual private tags can instead\n' +
+      'be named (8-hex) in --keep-tags. Binary/unparseable payloads are\n' +
+      'skipped and counted.\n' +
       '--size-tolerance folds near-identical file sizes (fraction, e.g. 0.05\n' +
       '= ±5%) into one entry; default exact.\n' +
       '--no-preserve-uids emits shape only with freshly minted UIDs (no link\n' +
@@ -52,6 +59,7 @@ let preserveUids = true
 let uidSalt
 let gzip = false
 let captureTree = false
+let keepPrivateTags = false
 const keepTags = []
 
 for (let i = 0; i < args.length; i++) {
@@ -77,6 +85,8 @@ for (let i = 0; i < args.length; i++) {
       console.error('--size-tolerance must be a non-negative number')
       process.exit(1)
     }
+  } else if (args[i] === '--keep-private-tags') {
+    keepPrivateTags = true
   } else if (args[i] === '--no-preserve-uids') {
     preserveUids = false
   } else if (args[i] === '--tree') {
@@ -107,6 +117,7 @@ let result
 try {
   result = describeDirectory(dir, {
     ...(keepTags.length ? { keepTags } : {}),
+    ...(keepPrivateTags ? { keepPrivateTags: true } : {}),
     ...(sizeTolerance !== undefined ? { sizeTolerance } : {}),
     preserveUids,
     ...(uidSalt !== undefined ? { uidSalt } : {}),

package/dist/esm/collection/writer.js

@@ -56,6 +56,9 @@ function isImageType(type) {
   return TYPE_CAPABILITIES[type].image;
 }
 var HEX_TAG_RE = /^[0-9a-fA-F]{8}$/;
+function isRawTagValue(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) && typeof value.vr === "string";
+}
 function positionalName(prefix, ordinal) {
   return `${prefix}-${String(ordinal).padStart(3, "0")}`;
 }
@@ -148,27 +151,50 @@ function buildTagToKeyword() {
   return map;
 }
 var tagToKeyword = buildTagToKeyword();
+function toRawElement(raw) {
+  const value = raw.vr === "SQ" ? raw.value.map(
+    (item) => Object.fromEntries(
+      Object.entries(item).map(([tag, nested]) => [
+        tag.toUpperCase(),
+        toRawElement(nested)
+      ])
+    )
+  ) : raw.value;
+  return { vr: raw.vr, Value: Array.isArray(value) ? value : [value] };
+}
 function applyTagOverrides(dataset, tags) {
-  if (!tags) return;
+  if (!tags) return void 0;
+  let raw;
   for (const [key, value] of Object.entries(tags)) {
-    if (HEX_TAG_RE.test(key)) {
+    if (isRawTagValue(value)) {
+      raw ?? (raw = {});
+      raw[key.toUpperCase()] = toRawElement(value);
+    } else if (HEX_TAG_RE.test(key)) {
       const keyword = tagToKeyword.get(key.toUpperCase());
-      if (keyword) {
-        dataset[keyword] = value;
-      } else {
-        console.warn(`dicom-synth: unknown hex tag "${key}" \u2014 skipping`);
+      if (!keyword) {
+        throw new Error(
+          `dicom-synth: unknown hex tag "${key}" \u2014 dictionary tags take plain values; private/unknown tags require the raw { vr, value } form`
+        );
       }
+      dataset[keyword] = value;
     } else {
       dataset[key] = value;
     }
   }
+  return raw;
 }
-function syncMetaWithDataset(meta, dataset) {
-  if (typeof dataset.SOPInstanceUID === "string") {
-    meta.MediaStorageSOPInstanceUID = dataset.SOPInstanceUID;
+function rawScalarString(rawElements, tag) {
+  const value = rawElements?.[tag]?.Value;
+  return value?.length === 1 && typeof value[0] === "string" ? value[0] : void 0;
+}
+function syncMetaWithDataset(meta, dataset, rawElements) {
+  const sopInstance = rawScalarString(rawElements, "00080018") ?? (typeof dataset.SOPInstanceUID === "string" ? dataset.SOPInstanceUID : void 0);
+  if (sopInstance !== void 0) {
+    meta.MediaStorageSOPInstanceUID = sopInstance;
   }
-  if (typeof dataset.SOPClassUID === "string") {
-    meta.MediaStorageSOPClassUID = dataset.SOPClassUID;
+  const sopClass = rawScalarString(rawElements, "00080016") ?? (typeof dataset.SOPClassUID === "string" ? dataset.SOPClassUID : void 0);
+  if (sopClass !== void 0) {
+    meta.MediaStorageSOPClassUID = sopClass;
   }
 }
 function buildMeta(uid, modality, transferSyntax = "explicit-vr-little-endian") {
@@ -208,7 +234,7 @@ function buildBaseImageDataset(uid, modality) {
     ...preset.attributes
   };
 }
-function serializeDict(meta, dataset) {
+function serializeDict(meta, dataset, rawElements) {
   const dicomDict = new dcmjs.data.DicomDict(
     dcmjs.data.DicomMetaDictionary.denaturalizeDataset(
       meta
@@ -217,14 +243,17 @@ function serializeDict(meta, dataset) {
   dicomDict.dict = dcmjs.data.DicomMetaDictionary.denaturalizeDataset(
     dataset
   );
+  if (rawElements) {
+    Object.assign(dicomDict.dict, rawElements);
+  }
   return Buffer.from(dicomDict.write({ allowInvalidVRLength: true }));
 }
 var MAX_DIMENSION = 65535;
-function applySizing(dataset, meta, spec) {
+function applySizing(dataset, meta, spec, rawElements) {
   if (spec.targetSizeKb !== void 0) {
     const clampDim = (n) => Math.min(MAX_DIMENSION, Math.max(1, Math.round(n)));
     const minimalPixelBytes = dataset.PixelData.byteLength;
-    const overhead = serializeDict(meta, dataset).length - minimalPixelBytes;
+    const overhead = serializeDict(meta, dataset, rawElements).length - minimalPixelBytes;
     const cells = Math.max(
       1,
       Math.round((spec.targetSizeKb * 1024 - overhead) / 2)
@@ -255,11 +284,11 @@ function buildImageBuffer(spec, uid) {
     dataset.Laterality = "";
     dataset.PatientWeight = "0";
   }
-  applyTagOverrides(dataset, spec.tags);
+  const rawElements = applyTagOverrides(dataset, spec.tags);
   const meta = buildMeta(effectiveUid, modality, spec.transferSyntax);
-  syncMetaWithDataset(meta, dataset);
-  applySizing(dataset, meta, spec);
-  return serializeDict(meta, dataset);
+  syncMetaWithDataset(meta, dataset, rawElements);
+  applySizing(dataset, meta, spec, rawElements);
+  return { buffer: serializeDict(meta, dataset, rawElements), rawElements };
 }
 function buildFakeSignatureBuffer() {
   const buf = Buffer.alloc(200, 0);
@@ -281,11 +310,11 @@ function buildBufferForSpec(spec, uid) {
     case "vendor-warnings-image":
       return buildImageBuffer(spec, uid);
     case "fake-signature":
-      return buildFakeSignatureBuffer();
+      return { buffer: buildFakeSignatureBuffer() };
     case "non-dicom":
-      return buildNonDicomBuffer(spec);
+      return { buffer: buildNonDicomBuffer(spec) };
     case "dicomdir":
-      return buildDicomdirBuffer();
+      return { buffer: buildDicomdirBuffer() };
     case "large-image":
       throw new Error(
         "large-image cannot be generated in memory \u2014 use writeCollectionFromSpec (disk-only streaming)"
@@ -366,12 +395,12 @@ function writeNative(outPath, params, dims, zeroChunk) {
   const { modality, uid, tags } = params;
   const meta = buildMeta(uid, modality);
   const dataset = buildBaseImageDataset(uid, modality);
-  applyTagOverrides(dataset, tags);
-  syncMetaWithDataset(meta, dataset);
+  const rawElements = applyTagOverrides(dataset, tags);
+  syncMetaWithDataset(meta, dataset, rawElements);
   dataset.Rows = dims.rows;
   dataset.Columns = dims.columns;
   const minimalPixelBytes = dataset.PixelData.byteLength;
-  const probe = serializeDict(meta, dataset);
+  const probe = serializeDict(meta, dataset, rawElements);
   const pixelElement = Buffer.alloc(12);
   PIXEL_DATA_OW_HEADER.copy(pixelElement);
   pixelElement.writeUInt32LE(minimalPixelBytes, 8);
@@ -400,11 +429,11 @@ function writeEncapsulated(outPath, params, pixelBytes, fragmentBytes, zeroChunk
     TransferSyntaxUID: RLE_TRANSFER_SYNTAX_UID
   };
   const dataset = buildBaseImageDataset(uid, modality);
-  applyTagOverrides(dataset, tags);
-  syncMetaWithDataset(meta, dataset);
+  const rawElements = applyTagOverrides(dataset, tags);
+  syncMetaWithDataset(meta, dataset, rawElements);
   dataset.PixelData = [new Uint8Array([]).buffer, new Uint8Array([0, 0]).buffer];
   dataset._vrMap = { PixelData: "OB" };
-  const probe = serializeDict(meta, dataset);
+  const probe = serializeDict(meta, dataset, rawElements);
   const idx = probe.indexOf(PIXEL_DATA_OB_HEADER);
   if (idx < 0 || probe.readUInt32LE(idx + 8) !== 4294967295) {
     throw new Error("failed to locate encapsulated PixelData element header");
@@ -501,7 +530,7 @@ var VIOLATION_LEVEL = {
   "missing-meta-header": "byte",
   "malformed-sq-delimiter": "byte"
 };
-function applyTagLevel(buffer, violations) {
+function applyTagLevel(buffer, violations, rawElements) {
   if (violations.length === 0) return buffer;
   let parsed;
   try {
@@ -535,6 +564,9 @@ function applyTagLevel(buffer, violations) {
     }
   }
   parsed.dict = dcmjsAny.data.DicomMetaDictionary.denaturalizeDataset(natural);
+  if (rawElements) {
+    Object.assign(parsed.dict, rawElements);
+  }
   if (violations.includes("uid-too-long")) {
     ;
     parsed.dict["00080018"] = {
@@ -567,11 +599,14 @@ function applyByteLevel(buffer, violations) {
   }
   return result;
 }
-function applyViolations(buffer, violations) {
+function applyViolations(buffer, violations, rawElements) {
   if (violations.length === 0) return buffer;
   const tagViolations = violations.filter((v) => VIOLATION_LEVEL[v] === "tag");
   const byteViolations = violations.filter((v) => VIOLATION_LEVEL[v] === "byte");
-  return applyByteLevel(applyTagLevel(buffer, tagViolations), byteViolations);
+  return applyByteLevel(
+    applyTagLevel(buffer, tagViolations, rawElements),
+    byteViolations
+  );
 }
 
 // src/collection/writer.ts
@@ -645,10 +680,11 @@ async function generateFile(spec, options) {
     ...spec,
     tags: resolveTagTemplates(spec.tags, { index, ...options?.context })
   } : spec;
-  let buffer = buildBufferForSpec(resolvedSpec, uid);
+  const built = buildBufferForSpec(resolvedSpec, uid);
+  let buffer = built.buffer;
   const violations = "violations" in spec ? spec.violations : void 0;
   if (violations?.length) {
-    buffer = applyViolations(buffer, violations);
+    buffer = applyViolations(buffer, violations, built.rawElements);
   }
   const name = filename(spec.type, index, padWidth);
   return {