Expose smart transducer loading as util #380 #381

"Smart transducer loading" means reading via Transducer or
TransducerArray's serializer depending on the "type" field in the json
file. This functionality was stuck inside of Databse, but we expose it
as a general utility to support its use in SlicerOpenLIFU.

Author: ebrahimebrahim

src/openlifu/db/database.py

@@ -15,6 +15,7 @@
 from openlifu.plan import Protocol, Run, Solution
 from openlifu.util.json import PYFUSEncoder
 from openlifu.xdc import Transducer, TransducerArray
+from openlifu.xdc.util import load_transducer_from_file
 
 from .session import Session
 from .subject import Subject
@@ -861,18 +862,10 @@ def load_transducer(self, transducer_id, convert_array:bool = True) -> Transduce
         Returns:
             Corresponding Transducer object
         """
-        transducer_filename = self.get_transducer_filename(transducer_id)
-        with open(transducer_filename) as f:
-            if not f:
-                raise FileNotFoundError(f"Transducer file not found for ID: {transducer_id}")
-            d = json.load(f)
-        if "type"  in d and d["type"] == "TransducerArray":
-            transducer = TransducerArray.from_dict(d)
-            if convert_array:
-                transducer = transducer.to_transducer()
-        else:
-            transducer = Transducer.from_file(transducer_filename)
-        return transducer
+        return load_transducer_from_file(
+            transducer_filepath=self.get_transducer_filename(transducer_id),
+            convert_array=convert_array
+        )
 
     def load_transducer_standoff(self, trans, coords, options=None):
         raise NotImplementedError("Standoff is not yet implemented")

src/openlifu/xdc/util.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+import json
+import os
+from typing import Union
+
+from openlifu.xdc.transducer import Transducer
+from openlifu.xdc.transducerarray import TransducerArray
+
+PathLike = Union[str,os.PathLike]
+
+def load_transducer_from_file(transducer_filepath : PathLike, convert_array:bool = True) -> Transducer|TransducerArray:
+    """Load a Transducer or TransducerArray from file, depending on the "type" field in the file.
+    Note: the transducer object includes the relative path to the affiliated transducer model data. `get_transducer_absolute_filepaths`, should
+    be used to obtain the absolute data filepaths based on the Database directory path.
+    Args:
+        transducer_filepath: path to the transducer json file
+        convert_array: When enabled, if a TransducerArray is encountered then it is converted to a Transducer.
+    Returns: a Transducer if the json file defines a Transducer, or if the json file defines a TransducerArray and convert_array is enabled.
+        Otherwise a TransducerArray.
+    """
+    with open(transducer_filepath) as f:
+        if not f:
+            raise FileNotFoundError(f"Transducer file not found at: {transducer_filepath}")
+        d = json.load(f)
+    if "type"  in d and d["type"] == "TransducerArray":
+        transducer = TransducerArray.from_dict(d)
+        if convert_array:
+            transducer = transducer.to_transducer()
+    else:
+        transducer = Transducer.from_file(transducer_filepath)
+    return transducer