ultrasound: replace JSON-in-tags sidecar with typed channel

Stop encoding UltrasoundRegions as a JSON string under a magic key on
the DICOM tag pair array and decoding it back. Expose it as a typed
property on MetaLoader, surface it on Chunk, and read it directly in
DicomChunkImage. The tag pair array now only contains DICOM tag/value
pairs.

Author: PaulHax

src/core/streaming/chunk.ts

@@ -86,6 +86,10 @@ export class Chunk {
     return this.metaLoader.metaBlob;
   }
 
+  get ultrasoundRegions() {
+    return this.metaLoader.ultrasoundRegions ?? null;
+  }
+
   get dataBlob() {
     return this.dataLoader.data;
   }

src/core/streaming/dicom/__tests__/ultrasoundRegion.spec.ts

@@ -2,11 +2,8 @@ import { describe, it, expect } from 'vitest';
 import type { DataElement } from '@/src/core/streaming/dicom/dicomParser';
 import {
   decodeUltrasoundRegion,
-  encodeUltrasoundRegionMeta,
-  getUltrasoundRegionFromMetadata,
   parseUltrasoundRegionFromBlob,
   unitToMm,
-  US_REGION_META_KEY,
   US_UNIT_CENTIMETERS,
 } from '@/src/core/streaming/dicom/ultrasoundRegion';
 
@@ -153,41 +150,6 @@ describe('unitToMm', () => {
   });
 });
 
-describe('encodeUltrasoundRegionMeta / getUltrasoundRegionFromMetadata', () => {
-  it('round-trips through the metadata tag array', () => {
-    const regions = {
-      region: {
-        physicalDeltaX: 0.05,
-        physicalDeltaY: 0.1,
-        physicalUnitsXDirection: US_UNIT_CENTIMETERS,
-        physicalUnitsYDirection: US_UNIT_CENTIMETERS,
-      },
-      regionCount: 2,
-    };
-    const entry = encodeUltrasoundRegionMeta(regions);
-    expect(entry[0]).toBe(US_REGION_META_KEY);
-
-    const meta: Array<[string, string]> = [
-      ['0008|0060', 'US'],
-      entry,
-      ['0010|0010', 'PATIENT^NAME'],
-    ];
-    expect(getUltrasoundRegionFromMetadata(meta)).toEqual(regions);
-  });
-
-  it('returns null when the entry is absent', () => {
-    expect(getUltrasoundRegionFromMetadata([])).toBeNull();
-    expect(getUltrasoundRegionFromMetadata(null)).toBeNull();
-    expect(getUltrasoundRegionFromMetadata(undefined)).toBeNull();
-  });
-
-  it('returns null when the entry value is unparseable', () => {
-    expect(
-      getUltrasoundRegionFromMetadata([[US_REGION_META_KEY, 'not-json']])
-    ).toBeNull();
-  });
-});
-
 // Builds a minimal DICOM P10 byte stream containing only what the ultrasound
 // parser needs: preamble, DICM magic, a TransferSyntaxUID (Explicit VR LE),
 // and a SequenceOfUltrasoundRegions with one populated item.

src/core/streaming/dicom/dicomFileMetaLoader.ts

@@ -3,12 +3,13 @@ import { MetaLoader } from '@/src/core/streaming/types';
 import { Maybe } from '@/src/types';
 import { Tags } from '@/src/core/dicomTags';
 import {
-  encodeUltrasoundRegionMeta,
   parseUltrasoundRegionFromBlob,
+  UltrasoundRegions,
 } from '@/src/core/streaming/dicom/ultrasoundRegion';
 
 export class DicomFileMetaLoader implements MetaLoader {
   public tags: Maybe<Array<[string, string]>>;
+  public ultrasoundRegions: UltrasoundRegions | null = null;
   private file: File;
 
   constructor(
@@ -32,10 +33,7 @@ export class DicomFileMetaLoader implements MetaLoader {
 
     const modality = new Map(this.tags).get(Tags.Modality)?.trim();
     if (modality === 'US') {
-      const regions = await parseUltrasoundRegionFromBlob(this.file);
-      if (regions) {
-        this.tags.push(encodeUltrasoundRegionMeta(regions));
-      }
+      this.ultrasoundRegions = await parseUltrasoundRegionFromBlob(this.file);
     }
   }
 

src/core/streaming/dicom/dicomMetaLoader.ts

@@ -11,7 +11,6 @@ import { FILE_EXT_TO_MIME } from '@/src/io/mimeTypes';
 import { Tags } from '@/src/core/dicomTags';
 import {
   decodeUltrasoundRegion,
-  encodeUltrasoundRegionMeta,
   SEQUENCE_OF_ULTRASOUND_REGIONS,
   UltrasoundRegions,
 } from '@/src/core/streaming/dicom/ultrasoundRegion';
@@ -34,6 +33,7 @@ export class DicomMetaLoader implements MetaLoader {
   private fetcher: Fetcher;
   private readDicomTags: ReadDicomTagsFunction;
   private blob: Blob | null;
+  public ultrasoundRegions: UltrasoundRegions | null = null;
 
   constructor(fetcher: Fetcher, readDicomTags: ReadDicomTagsFunction) {
     this.fetcher = fetcher;
@@ -131,7 +131,7 @@ export class DicomMetaLoader implements MetaLoader {
     this.tags = await this.readDicomTags(metadataFile);
 
     if (modality === 'US' && ultrasoundRegions) {
-      this.tags.push(encodeUltrasoundRegionMeta(ultrasoundRegions));
+      this.ultrasoundRegions = ultrasoundRegions;
     }
   }
 

src/core/streaming/dicom/ultrasoundRegion.ts

@@ -4,8 +4,6 @@ import {
 } from '@/src/core/streaming/dicom/dicomParser';
 import { Tags, tagToGroupElement } from '@/src/core/dicomTags';
 
-export const US_REGION_META_KEY = '__volview_us_region';
-
 // DICOM unit codes for PhysicalUnitsXDirection / YDirection.
 // See DICOM PS3.3 C.8.5.5.1.15. The only spatial spacing code defined for
 // this field is 3 (cm). Other codes (0=none, 1=percent, 2=dB, 4=seconds,
@@ -144,22 +142,3 @@ export async function parseUltrasoundRegionFromBlob(
 
   return regions;
 }
-
-export function encodeUltrasoundRegionMeta(
-  regions: UltrasoundRegions
-): [string, string] {
-  return [US_REGION_META_KEY, JSON.stringify(regions)];
-}
-
-export function getUltrasoundRegionFromMetadata(
-  meta: ReadonlyArray<readonly [string, string]> | null | undefined
-): UltrasoundRegions | null {
-  if (!meta) return null;
-  const entry = meta.find(([key]) => key === US_REGION_META_KEY);
-  if (!entry) return null;
-  try {
-    return JSON.parse(entry[1]) as UltrasoundRegions;
-  } catch {
-    return null;
-  }
-}

src/core/streaming/dicomChunkImage.ts

@@ -26,10 +26,7 @@ import {
 import { ensureError } from '@/src/utils';
 import { computed } from 'vue';
 import vtkITKHelper from '@kitware/vtk.js/Common/DataModel/ITKHelper';
-import {
-  getUltrasoundRegionFromMetadata,
-  unitToMm,
-} from '@/src/core/streaming/dicom/ultrasoundRegion';
+import { unitToMm } from '@/src/core/streaming/dicom/ultrasoundRegion';
 
 const { fastComputeRange } = vtkDataArray;
 
@@ -289,7 +286,7 @@ export default class DicomChunkImage
   private applyUltrasoundSpacing() {
     if (this.getModality() !== 'US') return;
 
-    const regions = getUltrasoundRegionFromMetadata(this.getDicomMetadata());
+    const regions = this.chunks[0]?.ultrasoundRegions ?? null;
     if (!regions?.region) return;
 
     // VTK image data has a single global spacing, so multi-region images

src/core/streaming/types.ts

@@ -1,5 +1,6 @@
 import { Maybe } from '@/src/types';
 import { Awaitable } from '@vueuse/core';
+import type { UltrasoundRegions } from '@/src/core/streaming/dicom/ultrasoundRegion';
 
 export type LoaderEvents = {
   error: any;
@@ -17,6 +18,7 @@ interface Loader {
 export interface MetaLoader extends Loader {
   meta: Maybe<Array<[string, string]>>;
   metaBlob: Maybe<Blob>;
+  ultrasoundRegions?: UltrasoundRegions | null;
 }
 
 /**