fix(ultrasound): tighten review follow-ups

- Correct PhysicalUnitsX/Y unit-code table per DICOM PS3.3 C.8.5.5
  (10=cm³, 11=cm³/sec, 12=degrees; previously labelled 10 as degrees)
  and extend the negative test to codes 11–12.
- Warn in the console when neither X nor Y direction is centimetres,
  parallel to the existing multi-region warning, so a 1mm fallback is
  no longer silent.
- Replace `null` with `undefined` for absent ultrasound regions so
  consumers handle a single absence state instead of three.

Author: PaulHax

src/core/streaming/chunk.ts

@@ -87,7 +87,7 @@ export class Chunk {
   }
 
   get ultrasoundRegions() {
-    return this.metaLoader.ultrasoundRegions ?? null;
+    return this.metaLoader.ultrasoundRegions;
   }
 
   get dataBlob() {

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

@@ -93,30 +93,22 @@ describe('decodeUltrasoundRegion', () => {
     });
   });
 
-  it('returns a null region with zero count when the sequence is empty', () => {
-    expect(decodeUltrasoundRegion([])).toEqual({
-      region: null,
-      regionCount: 0,
-    });
+  it('returns no region with zero count when the sequence is empty', () => {
+    expect(decodeUltrasoundRegion([])).toEqual({ regionCount: 0 });
   });
 
-  it('returns a null region with zero count when the data is not a sequence', () => {
-    expect(decodeUltrasoundRegion(undefined)).toEqual({
-      region: null,
-      regionCount: 0,
-    });
+  it('returns no region with zero count when the data is not a sequence', () => {
+    expect(decodeUltrasoundRegion(undefined)).toEqual({ regionCount: 0 });
     expect(decodeUltrasoundRegion(new Uint8Array(4))).toEqual({
-      region: null,
       regionCount: 0,
     });
   });
 
-  it('returns a null region but reports the count when a required field is missing', () => {
+  it('returns no region but reports the count when a required field is missing', () => {
     const missingDeltaY = wellFormedItem.filter(
       (e) => !(e.group === 0x0018 && e.element === 0x602e)
     );
     expect(decodeUltrasoundRegion(fakeSequenceData([missingDeltaY]))).toEqual({
-      region: null,
       regionCount: 1,
     });
   });
@@ -143,8 +135,9 @@ describe('unitToMm', () => {
 
   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) => {
+    // 5=hertz, 6=dB/sec, 7=cm/sec, 8=cm², 9=cm²/sec, 10=cm³,
+    // 11=cm³/sec, 12=degrees.
+    [0, 1, 2, 4, 5, 6, 7, 8, 9, 10, 11, 12].forEach((code) => {
       expect(unitToMm(code)).toBeNull();
     });
   });
@@ -210,7 +203,7 @@ describe('parseUltrasoundRegionFromBlob', () => {
     });
   });
 
-  it('returns null when the blob has no SequenceOfUltrasoundRegions', async () => {
+  it('returns undefined when the blob has no SequenceOfUltrasoundRegions', async () => {
     // Build a blob with only the TransferSyntaxUID + pixel data tag.
     const preamble = new Uint8Array(128);
     const magic = new TextEncoder().encode('DICM');
@@ -221,6 +214,6 @@ describe('parseUltrasoundRegionFromBlob', () => {
     new DataView(pixelDataTag.buffer).setUint16(2, 0x0010, true);
     const blob = new Blob([concat([preamble, magic, tsx, pixelDataTag])]);
 
-    expect(await parseUltrasoundRegionFromBlob(blob)).toBeNull();
+    expect(await parseUltrasoundRegionFromBlob(blob)).toBeUndefined();
   });
 });

src/core/streaming/dicom/dicomFileMetaLoader.ts

@@ -9,7 +9,7 @@ import {
 
 export class DicomFileMetaLoader implements MetaLoader {
   public tags: Maybe<Array<[string, string]>>;
-  public ultrasoundRegions: UltrasoundRegions | null = null;
+  public ultrasoundRegions: UltrasoundRegions | undefined;
   private file: File;
 
   constructor(

src/core/streaming/dicom/dicomMetaLoader.ts

@@ -33,7 +33,7 @@ export class DicomMetaLoader implements MetaLoader {
   private fetcher: Fetcher;
   private readDicomTags: ReadDicomTagsFunction;
   private blob: Blob | null;
-  public ultrasoundRegions: UltrasoundRegions | null = null;
+  public ultrasoundRegions: UltrasoundRegions | undefined;
 
   constructor(fetcher: Fetcher, readDicomTags: ReadDicomTagsFunction) {
     this.fetcher = fetcher;
@@ -57,7 +57,7 @@ export class DicomMetaLoader implements MetaLoader {
     let explicitVr = true;
     let dicomUpToPixelDataIdx = -1;
     let modality: string | undefined;
-    let ultrasoundRegions: UltrasoundRegions | null = null;
+    let ultrasoundRegions: UltrasoundRegions | undefined;
 
     const parse = createDicomParser({
       stopAtElement(group, element) {

src/core/streaming/dicom/ultrasoundRegion.ts

@@ -7,9 +7,9 @@ import { Tags, tagToGroupElement } from '@/src/core/dicomTags';
 // 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.
+// 5=hertz, 6=dB/seconds, 7=cm/sec, 8=cm², 9=cm²/sec, A=cm³, B=cm³/sec,
+// C=degrees) are time, frequency, velocity, area, volume, 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
@@ -31,7 +31,7 @@ export type UltrasoundRegion = {
 // Doppler) cannot be fully represented with a single VTK image spacing, so
 // we expose the count to let callers warn about partial support.
 export type UltrasoundRegions = {
-  region: UltrasoundRegion | null;
+  region?: UltrasoundRegion;
   regionCount: number;
 };
 
@@ -73,13 +73,13 @@ export function decodeUltrasoundRegion(
   sequenceData: DataElement['data']
 ): UltrasoundRegions {
   if (!Array.isArray(sequenceData) || sequenceData.length === 0) {
-    return { region: null, regionCount: 0 };
+    return { regionCount: 0 };
   }
   const [firstItem] = sequenceData;
 
   const findBytes = (target: [number, number]) => {
     const el = firstItem.find((inner) => isTag(inner, target));
-    if (!el || !(el.data instanceof Uint8Array)) return null;
+    if (!el || !(el.data instanceof Uint8Array)) return undefined;
     return el.data;
   };
 
@@ -90,7 +90,7 @@ export function decodeUltrasoundRegion(
 
   const regionCount = sequenceData.length;
   if (!deltaXBytes || !deltaYBytes || !unitsXBytes || !unitsYBytes) {
-    return { region: null, regionCount };
+    return { regionCount };
   }
 
   return {
@@ -110,8 +110,8 @@ export function decodeUltrasoundRegion(
  */
 export async function parseUltrasoundRegionFromBlob(
   blob: Blob
-): Promise<UltrasoundRegions | null> {
-  let regions: UltrasoundRegions | null = null;
+): Promise<UltrasoundRegions | undefined> {
+  let regions: UltrasoundRegions | undefined;
 
   const parse = createDicomParser({
     stopAtElement(group, element) {
@@ -136,7 +136,7 @@ export async function parseUltrasoundRegionFromBlob(
     }
   } catch (err) {
     console.warn('Failed to parse SequenceOfUltrasoundRegions:', err);
-    return null;
+    return undefined;
   } finally {
     reader.releaseLock();
   }

src/core/streaming/dicomChunkImage.ts

@@ -286,7 +286,7 @@ export default class DicomChunkImage
   private applyUltrasoundSpacing() {
     if (this.getModality() !== 'US') return;
 
-    const regions = this.chunks[0]?.ultrasoundRegions ?? null;
+    const regions = this.chunks[0]?.ultrasoundRegions;
     if (!regions?.region) return;
 
     // VTK image data has a single global spacing, so multi-region images
@@ -302,7 +302,15 @@ export default class DicomChunkImage
     const { region } = regions;
     const xFactor = unitToMm(region.physicalUnitsXDirection);
     const yFactor = unitToMm(region.physicalUnitsYDirection);
-    if (xFactor === null || yFactor === null) return;
+    // All-or-nothing: if either axis lacks a spatial unit (e.g. one axis is
+    // cm and the other is seconds, or unitless) the metadata can't be trusted
+    // as a 2D physical spacing, so leave the default 1mm fallback in place.
+    if (xFactor === null || yFactor === null) {
+      console.warn(
+        `Ultrasound spacing not applied: PhysicalUnitsXDirection=${region.physicalUnitsXDirection}, PhysicalUnitsYDirection=${region.physicalUnitsYDirection}; only code 3 (cm) is converted to mm.`
+      );
+      return;
+    }
 
     const [, , zSpacing] = this.vtkImageData.value.getSpacing();
     this.vtkImageData.value.setSpacing([

src/core/streaming/types.ts

@@ -18,7 +18,7 @@ interface Loader {
 export interface MetaLoader extends Loader {
   meta: Maybe<Array<[string, string]>>;
   metaBlob: Maybe<Blob>;
-  ultrasoundRegions?: UltrasoundRegions | null;
+  ultrasoundRegions?: UltrasoundRegions;
 }
 
 /**