Add VF options dataclass (OpenwaterHealth#165)

Author: ebrahimebrahim

src/openlifu/virtual_fit.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import logging
+from dataclasses import dataclass
 from typing import List, Sequence, Tuple
 
 import numpy as np
@@ -17,12 +18,83 @@
     spherical_interpolator_from_mesh,
     vtk_img_from_array_and_affine,
 )
+from openlifu.util.dict_conversion import DictMixin
+from openlifu.util.units import getunitconversion
 
 log = logging.getLogger("VirtualFit")
 
 ras2asl_3x3 = np.array([[0,1,0],[0,0,1],[-1,0,0]], dtype=float) # ASL means Anterior-Superior-Left coordinates
 asl2ras_3x3 = ras2asl_3x3.transpose()
 
+@dataclass
+class VirtualFitOptions(DictMixin):
+    """Parameters to configure the `virtual_fit` algorithm.
+
+    The terms 'pitch' and 'yaw' used here refer to the following target-centric angular coordinates in patient space:
+        pitch: The angle between the anterior axis through the target and the ray from from the target to the projection of
+            a given point into the anterior-superior plane.
+        yaw: The angle between the anterior-superior plane through the target and the ray from the target to a given point.
+
+    Another way to describe them in terms of standard spherical coordinates centered at the target in ASL (anterior-superior-left) space:
+        pitch: The azimuthal spherical coordinate.
+        yaw: 90 degrees minus the polar spherical coordinate.
+    """
+
+    units:float = "mm"
+    """The units of length used in the length attributes of this class"""
+
+    transducer_steering_center_distance:float = 50.
+    """Distance from the transducer origin axially to the center of the steering zone in the units `units`"""
+
+    steering_limits:Tuple[Tuple[float,float],Tuple[float,float],Tuple[float,float]] = ((-50,50),(-50,50),(-50,50))
+    """Distance from the transducer origin axially to the center of the steering zone in the units `units`"""
+
+    pitch_range : Tuple[float,float] = (-10,150)
+    """Range of pitches to include in the transducer fitting search grid, in degrees"""
+
+    pitch_step : float = 5
+    """Pitch step size when forming the transducer fitting search grid, in degrees"""
+
+    yaw_range : Tuple[float, float] = (-65, 65)
+    """Range of yaws to include in the transducer fitting search grid, in degrees"""
+
+    yaw_step : float = 5
+    """Yaw step size when forming the transducer fitting search grid, in degrees"""
+
+    planefit_dyaw_extent:float = 15
+    """Left and right extents of the point grid to be used for plane fitting along the local yaw axes,
+    in units of `units`. The plane fitting point grid will be twice this size, since this is left
+    and right extents. (Note that this has units of length, not angle!)"""
+
+    planefit_dyaw_step:float = 3
+    """Local yaw axis step size to use when constructing plane fitting grids. In spatial units of `units`."""
+
+    planefit_dpitch_extent:float = 15
+    """Left and right extents of the point grid to be used for plane fitting along the local pitch axes,
+    in spatial units of `units`. The plane fitting point grid will be twice this size, since this is left
+    and right extents."""
+
+    planefit_dpitch_step:float = 3
+    """Local pitch axis step size to use when constructing plane fitting grids. In spatial units of `units`."""
+
+    def to_units(self, target_units:str) -> VirtualFitOptions:
+        """Do unit conversion and return a version of this VirtualFitOptions that uses
+        `target_units` as the units for all attributes that have units of length."""
+        conversion_factor = getunitconversion(from_unit = self.units, to_unit=target_units)
+        return VirtualFitOptions(
+            units = target_units,
+            transducer_steering_center_distance = conversion_factor * self.transducer_steering_center_distance,
+            steering_limits = tuple(map(tuple,conversion_factor*np.array(self.steering_limits))),
+            pitch_range = self.pitch_range,
+            pitch_step = self.pitch_step,
+            yaw_range = self.yaw_range,
+            yaw_step = self.yaw_step,
+            planefit_dyaw_extent = conversion_factor * self.planefit_dyaw_extent,
+            planefit_dyaw_step = conversion_factor * self.planefit_dyaw_step,
+            planefit_dpitch_extent = conversion_factor * self.planefit_dpitch_extent,
+            planefit_dpitch_step = conversion_factor * self.planefit_dpitch_step,
+        )
+
 # (Currently we disable pylint E1121 because it is a temporary issue
 # which should be resolved by #165 and #166)
 def virtual_fit( # pylint: disable=E1121
@@ -49,7 +121,7 @@ def virtual_fit( # pylint: disable=E1121
         volume_array: A 3D volume MRI
         volume_affine_RAS: A 4x4 affine transform that maps `volume_array` into RAS space with certain units
         target_RAS: A 3D point, in the coordinates and units of `volume_affine_RAS`
-        pitch_range: Range of pitches to include in the transducer fitting search grid, in degrees
+        pitch_range:
         pitch_step: Pitch step size when forming the transducer fitting search grid, in degrees
         yaw_range: Range of yaws to include in the transducer fitting search grid, in degrees
         yaw_step: Yaw step size when forming the transducer fitting search grid, in degrees
@@ -68,16 +140,7 @@ def virtual_fit( # pylint: disable=E1121
             In spatial units of `volume_affine_RAS`.
 
     Returns: A list of transducer transform candidates sorted starting from the best-scoring one. The transforms map transducer space
-        into LPS space, and they are in the same units as `volume_affine_RAS`.
-
-    The terms 'pitch' and 'yaw' used here refer to the following target-centric angular coordinates in patient space:
-        pitch: The angle between the anterior axis through the target and the ray from from the target to the projection of
-            a given point into the anterior-superior plane.
-        yaw: The angle between the anterior-superior plane through the target and the ray from the target to a given point.
-
-    Another way to describe them in terms of standard spherical coordinates centered at the target in ASL (anterior-superior-left) space:
-        pitch: The azimuthal spherical coordinate.
-        yaw: 90 degrees minus the polar spherical coordinate.
+        into LPS space, and they are in the same units as the RAS space of `volume_affine_RAS`.
     """
 
     log.info("Computing foreground mask...")

tests/test_virtual_fit.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from openlifu.virtual_fit import VirtualFitOptions
+
+
+def test_unit_conversion():
+    vfo = VirtualFitOptions(
+        units="cm",
+        transducer_steering_center_distance=45.,
+        pitch_range=(-12,14),
+        yaw_range=(-13,15),
+        pitch_step = 9,
+        yaw_step = 10,
+        planefit_dyaw_extent = 2.3,
+        steering_limits=((-10,11),(-12,13),(-14,15)),
+    )
+    vfo_converted = vfo.to_units("mm")
+    assert vfo_converted.transducer_steering_center_distance == 10*vfo.transducer_steering_center_distance
+    assert vfo_converted.planefit_dyaw_extent == 10*vfo.planefit_dyaw_extent
+    assert vfo_converted.yaw_step == vfo.yaw_step
+    assert vfo_converted.pitch_range == vfo.pitch_range
+    assert isinstance(vfo_converted.steering_limits, tuple)
+    assert all(isinstance(sl, tuple) for sl in vfo_converted.steering_limits)
+    assert vfo_converted.steering_limits[2][0] == 10*vfo.steering_limits[2][0]