Add standoff transform to Transducer (OpenwaterHealth#166)

Author: ebrahimebrahim

src/openlifu/virtual_fit.py

@@ -106,22 +106,24 @@ def from_dict(parameter_dict:Dict[str,Any]) -> VirtualFitOptions: # Override Dic
 # (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
-    standoff_transform : np.ndarray,
     volume_array : np.ndarray,
     volume_affine_RAS : np.ndarray,
     units: str,
     target_RAS : Sequence[float],
+    standoff_transform : np.ndarray,
     options : VirtualFitOptions,
 ) -> List[np.ndarray]:
     """Run patient-specific "virtual fitting" algorithm, suggesting a series of candidate transducer
     transforms for optimal sonicaiton of a given target.
 
     Args:
-        standoff_transform: See `create_standoff_transform` documentation for the meaning of this
         volume_array: A 3D volume MRI
         volume_affine_RAS: A 4x4 affine transform that maps `volume_array` into RAS space with certain units
         units: The spatial units of the RAS space into which volume_affine_RAS maps
         target_RAS: A 3D point, in the coordinates and units of `volume_affine_RAS` (the `units` argument)
+        standoff_transform: See the documentation of `create_standoff_transform` or
+            `Transducer.standoff_transform` for the meaning of this. Here it should be provided in the
+            units `units`. The method `Transducer.get_standoff_transform_in_units` is useful for getting this.
         options : Virtual fitting algorithm configuration. See the `VirtualFitOptions` documentation.
 
     Returns: A list of transducer transform candidates sorted starting from the best-scoring one. The transforms map transducer space

src/openlifu/xdc/transducer.py

@@ -22,11 +22,26 @@ class Transducer:
     frequency: float = 400.6e3
     units: str = "m"
     attrs: Dict[str, Any] = field(default_factory= dict)
+
     registration_surface_filename: str | None = None
     """Relative path to an open surface of the transducer to be used for registration"""
+
     transducer_body_filename: str | None = None
     """Relative path to the closed surface mesh for visualizing the transducer body"""
 
+    standoff_transform: np.ndarray = field(default_factory=lambda: np.eye(4, dtype=float))
+    """Affine transform representing the way in which the standoff for this transducer displaces the transducer.
+
+    A "standoff transform" applies a displacement in transducer space that moves a transducer to where it would
+    be situated with the standoff in place. The idea is that if you start with a transform that places a transducer
+    directly against skin, then pre-composing that transform by a "standoff transform" serves to nudge the transducer
+    such that there is space for the standoff to be between it and the skin.
+
+    See also `openlifu.geo.create_standoff_transform`.
+
+    The units of this transform are assumed to be the native units of the transducer, the `Transducer.units` field.
+    """
+
     def __post_init__(self):
         logging.info("Initializing transducer array")
         if self.name == "":
@@ -155,6 +170,12 @@ def convert_transform(self, matrix:np.ndarray, units:str) -> np.ndarray:
         matrix[0:3, 3] *= getunitconversion(units, self.units)
         return matrix
 
+    def get_standoff_transform_in_units(self, units:str) -> np.ndarray:
+        """Get the transducer's standoff transform in the desired units."""
+        matrix = self.standoff_transform.copy()
+        matrix[0:3, 3] *= getunitconversion(self.units, units)
+        return matrix
+
     @staticmethod
     def merge(list_of_transducers:List[Transducer]) -> Transducer:
         merged_array = list_of_transducers[0].copy()
@@ -175,6 +196,7 @@ def rescale(self, units):
     def to_dict(self):
         d = self.__dict__.copy()
         d["elements"] = [element.to_dict() for element in d["elements"]]
+        d["standoff_transform"] =  d["standoff_transform"].tolist()
         return d
 
     def to_file(self, filename):
@@ -197,6 +219,8 @@ def from_file(filename):
     def from_dict(d, **kwargs):
         d = d.copy()
         d["elements"] = Element.from_dict(d["elements"])
+        if "standoff_transform" in d:
+            d["standoff_transform"] = np.array(d["standoff_transform"])
         return Transducer(**d, **kwargs)
 
     @staticmethod

tests/resources/example_db/transducers/example_transducer/example_transducer.json

@@ -965,5 +965,11 @@
   ],
   "frequency": 400600,
   "units": "mm",
-  "attrs": {}
+  "attrs": {},
+  "standoff_transform": [
+    [0.9, 0.1, 0, 0],
+    [-0.1, 0.9, 0, 0],
+    [0, 0, 1, 2.6],
+    [0, 0, 0, 1]
+  ]
 }

tests/test_transducer.py

@@ -6,7 +6,7 @@
 import pytest
 from helpers import dataclasses_are_equal
 
-from openlifu import Transducer
+from openlifu.xdc import Element, Transducer
 
 
 @pytest.fixture()
@@ -64,3 +64,28 @@ def test_get_effective_origin():
         transducer.get_effective_origin(apodizations = apodizations_with_just_one_element, units = "um"),
         transducer.get_positions(units="um")[element_index_to_turn_on],
     )
+
+def test_get_standoff_transform_in_units():
+    standoff_transform_in_mm = np.array([
+            [-0.1,0.9,0,20],
+            [0.9,0.1,0,30],
+            [0,0,1,40],
+            [0,0,0,1],
+    ])
+    standoff_transform_in_cm = np.array([
+            [-0.1,0.9,0,2],
+            [0.9,0.1,0,3],
+            [0,0,1,4],
+            [0,0,0,1],
+    ])
+    transducer = Transducer(units='mm')
+    transducer.standoff_transform = standoff_transform_in_mm
+    assert np.allclose(
+        transducer.get_standoff_transform_in_units("cm"),
+        standoff_transform_in_cm,
+    )
+
+def test_read_data_types(example_transducer:Transducer):
+    assert isinstance(example_transducer.standoff_transform, np.ndarray)
+    if len(example_transducer.elements) > 0:
+        assert isinstance(example_transducer.elements[0], Element)