ultrasound: extract unitToMm helper, document unit codes per spec

Per DICOM PS3.3 C.8.5.5.1.15, code 3 (cm) is the only spatial spacing
unit defined for PhysicalUnitsXDirection / YDirection — codes 0, 1, 2,
4–10 cover none / percent / dB / seconds / hertz / dB/sec / cm/sec /
cm² / cm²/sec / degrees. Replace the strict cm equality check with a
unitToMm helper that returns 10 for cm and null for everything else,
applied per axis. Functionally equivalent to the previous strict check,
but isolates the unit-to-spacing mapping in one tested place and adds a
clear extension point if a vendor exception ever needs to be honoured.

Author: PaulHax

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

@@ -5,6 +5,7 @@ import {
   encodeUltrasoundRegionMeta,
   getUltrasoundRegionFromMetadata,
   parseUltrasoundRegionFromBlob,
+  unitToMm,
   US_REGION_META_KEY,
   US_UNIT_CENTIMETERS,
 } from '@/src/core/streaming/dicom/ultrasoundRegion';
@@ -124,6 +125,20 @@ describe('decodeUltrasoundRegion', () => {
   });
 });
 
+describe('unitToMm', () => {
+  it('returns 10 for centimetres (code 3)', () => {
+    expect(unitToMm(US_UNIT_CENTIMETERS)).toBe(10);
+  });
+
+  it('returns null for non-spatial unit codes', () => {
+    // Per DICOM PS3.3 C.8.5.5.1.15: 0=none, 1=percent, 2=dB, 4=seconds,
+    // 5=hertz, 6=dB/sec, 7=cm/sec, 8=cm², 9=cm²/sec, 10=degrees.
+    [0, 1, 2, 4, 5, 6, 7, 8, 9, 10].forEach((code) => {
+      expect(unitToMm(code)).toBeNull();
+    });
+  });
+});
+
 describe('encodeUltrasoundRegionMeta / getUltrasoundRegionFromMetadata', () => {
   it('round-trips through the metadata tag array', () => {
     const region = {

src/core/streaming/dicom/ultrasoundRegion.ts

@@ -6,10 +6,21 @@ import { Tags, tagToGroupElement } from '@/src/core/dicomTags';
 
 export const US_REGION_META_KEY = '__volview_us_region';
 
-// DICOM unit codes for PhysicalUnitsXDirection / YDirection
-// 0x0003 = centimeters. See DICOM PS3.3 C.8.5.5.1.1.
+// 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,
+// 5=hertz, 6=dB/seconds, 7=cm/sec, 8=cm², 9=cm²/sec, A=degrees) are time,
+// frequency, velocity, area, or angle, so they are not converted to a VTK
+// image spacing.
 export const US_UNIT_CENTIMETERS = 3;
 
+// Returns the multiplier that converts a physical-delta value in the given
+// unit to millimetres, or null when the unit is not a spatial spacing.
+export const unitToMm = (code: number): number | null => {
+  if (code === US_UNIT_CENTIMETERS) return 10;
+  return null;
+};
+
 export type UltrasoundRegion = {
   physicalDeltaX: number;
   physicalDeltaY: number;

src/core/streaming/dicomChunkImage.ts

@@ -28,7 +28,7 @@ import { computed } from 'vue';
 import vtkITKHelper from '@kitware/vtk.js/Common/DataModel/ITKHelper';
 import {
   getUltrasoundRegionFromMetadata,
-  US_UNIT_CENTIMETERS,
+  unitToMm,
 } from '@/src/core/streaming/dicom/ultrasoundRegion';
 
 const { fastComputeRange } = vtkDataArray;
@@ -291,18 +291,15 @@ export default class DicomChunkImage
 
     const region = getUltrasoundRegionFromMetadata(this.getDicomMetadata());
     if (!region) return;
-    if (
-      region.physicalUnitsXDirection !== US_UNIT_CENTIMETERS ||
-      region.physicalUnitsYDirection !== US_UNIT_CENTIMETERS
-    ) {
-      return;
-    }
 
-    const CM_TO_MM = 10;
+    const xFactor = unitToMm(region.physicalUnitsXDirection);
+    const yFactor = unitToMm(region.physicalUnitsYDirection);
+    if (xFactor === null || yFactor === null) return;
+
     const [, , zSpacing] = this.vtkImageData.value.getSpacing();
     this.vtkImageData.value.setSpacing([
-      region.physicalDeltaX * CM_TO_MM,
-      region.physicalDeltaY * CM_TO_MM,
+      region.physicalDeltaX * xFactor,
+      region.physicalDeltaY * yFactor,
       zSpacing,
     ]);
   }