handle conveniences (#1390)

Author: casperdcl

src/Registration/pReg/Reg.py

@@ -30,7 +30,7 @@
 from sirf import SIRF
 from sirf.config import SIRF_HAS_SPM
 from sirf.SIRF import ContiguousError
-from sirf.Utilities import Handle, cpp_int_dtype, error, format_numpy_array_for_setter
+from sirf.Utilities import HANDLE, Handle, cpp_int_dtype, error, format_numpy_array_for_setter
 
 if sys.version_info[0] >= 3 and sys.version_info[1] >= 4:
     ABC = abc.ABC
@@ -145,9 +145,9 @@ def __init__(self, src=None):
         self.handle = None
         self.name = 'NiftiImageData'
         if src is None:
-            self.handle = Handle(None, -1).cReg_newObject(self.name)
+            self.handle = HANDLE.cReg_newObject(self.name)
         elif isinstance(src, str):
-            self.handle = Handle(None, -1).cReg_objectFromFile(self.name, src)
+            self.handle = HANDLE.cReg_objectFromFile(self.name, src)
         elif isinstance(src, SIRF.ImageData):
             # src is ImageData
             dim = src.dimensions()
@@ -508,9 +508,9 @@ def __init__(self, src=None):
         self.handle = None
         self.name = 'NiftiImageData3D'
         if src is None:
-            self.handle = Handle(None, -1).cReg_newObject(self.name)
+            self.handle = HANDLE.cReg_newObject(self.name)
         elif isinstance(src, str):
-            self.handle = Handle(None, -1).cReg_objectFromFile(self.name, src)
+            self.handle = HANDLE.cReg_objectFromFile(self.name, src)
         elif isinstance(src, SIRF.ImageData):
             # src is ImageData
             self.handle = src.handle.cReg_NiftiImageData_from_SIRFImageData(1)
@@ -529,12 +529,11 @@ def __init__(self, src1=None, src2=None, src3=None):
         self.handle = None
         self.name = 'NiftiImageData3DTensor'
         if src1 is None:
-            self.handle = Handle(None, -1).cReg_newObject(self.name)
+            self.handle = HANDLE.cReg_newObject(self.name)
         elif isinstance(src1, str):
-            self.handle = Handle(None, -1).cReg_objectFromFile(self.name, src1)
+            self.handle = HANDLE.cReg_objectFromFile(self.name, src1)
         elif all(isinstance(i, NiftiImageData3D) for i in (src1, src2, src3)):
-            self.handle = Handle(None, -1).cReg_NiftiImageData3DTensor_construct_from_3_components(
-                self.name, src1, src2, src3)
+            self.handle = HANDLE.cReg_NiftiImageData3DTensor_construct_from_3_components(self.name, src1, src2, src3)
         else:
             raise error('Wrong source in NiftiImageData3DTensor constructor')
 
@@ -574,12 +573,11 @@ def __init__(self, src1=None, src2=None, src3=None):
         self.handle = None
         self.name = 'NiftiImageData3DDisplacement'
         if src1 is None:
-            self.handle = Handle(None, -1).cReg_newObject(self.name)
+            self.handle = HANDLE.cReg_newObject(self.name)
         elif isinstance(src1, str):
-            self.handle = Handle(None, -1).cReg_objectFromFile(self.name, src1)
+            self.handle = HANDLE.cReg_objectFromFile(self.name, src1)
         elif all(isinstance(i, NiftiImageData3D) for i in (src1, src2, src3)):
-            self.handle = Handle(None, -1).cReg_NiftiImageData3DTensor_construct_from_3_components(
-                self.name, src1, src2, src3)
+            self.handle = HANDLE.cReg_NiftiImageData3DTensor_construct_from_3_components(self.name, src1, src2, src3)
         elif isinstance(src1, NiftiImageData3DDeformation):
             self.handle = src1.handle.cReg_NiftiImageData3DDisplacement_create_from_def()
         else:
@@ -600,12 +598,11 @@ def __init__(self, src1=None, src2=None, src3=None):
         self.handle = None
         self.name = 'NiftiImageData3DDeformation'
         if src1 is None:
-            self.handle = Handle(None, -1).cReg_newObject(self.name)
+            self.handle = HANDLE.cReg_newObject(self.name)
         elif isinstance(src1, str):
-            self.handle = Handle(None, -1).cReg_objectFromFile(self.name, src1)
+            self.handle = HANDLE.cReg_objectFromFile(self.name, src1)
         elif all(isinstance(i, NiftiImageData3D) for i in (src1, src2, src3)):
-            self.handle = Handle(None, -1).cReg_NiftiImageData3DTensor_construct_from_3_components(
-                self.name, src1, src2, src3)
+            self.handle = HANDLE.cReg_NiftiImageData3DTensor_construct_from_3_components(self.name, src1, src2, src3)
         elif isinstance(src1, NiftiImageData3DDisplacement):
             self.handle = src1.handle.cReg_NiftiImageData3DDeformation_create_from_disp()
         else:
@@ -790,7 +787,7 @@ def __init__(self):
         """init."""
         super().__init__()
         self.name = 'NiftyAladinSym'
-        self.handle = Handle(None, -1).cReg_newObject(self.name)
+        self.handle = HANDLE.cReg_newObject(self.name)
 
     def get_transformation_matrix_forward(self):
         """Get forward transformation matrix."""
@@ -809,7 +806,7 @@ def print_all_wrapped_methods():
         """Print all wrapped methods."""
         print("""In C++, this class is templated. \"dataType\"
               corresponds to \"float\" for Matlab and python.""")
-        Handle(None, -1).cReg_NiftyRegistration_print_all_wrapped_methods('NiftyAladinSym')
+        HANDLE.cReg_NiftyRegistration_print_all_wrapped_methods('NiftyAladinSym')
 
 
 class NiftyF3dSym(_NiftyRegistration):
@@ -818,7 +815,7 @@ def __init__(self):
         """init."""
         super().__init__()
         self.name = 'NiftyF3dSym'
-        self.handle = Handle(None, -1).cReg_newObject(self.name)
+        self.handle = HANDLE.cReg_newObject(self.name)
 
     def set_floating_time_point(self, floating_time_point):
         """Set floating time point."""
@@ -839,7 +836,7 @@ def print_all_wrapped_methods():
         """Print all wrapped methods."""
         print("""In C++, this class is templated. \"dataType\"
               corresponds to \"float\" for Matlab and python.""")
-        Handle(None, -1).cReg_NiftyRegistration_print_all_wrapped_methods('NiftyF3dSym')
+        HANDLE.cReg_NiftyRegistration_print_all_wrapped_methods('NiftyF3dSym')
 
 
 if SIRF_HAS_SPM:
@@ -850,7 +847,7 @@ def __init__(self):
             """init."""
             super().__init__()
             self.name = 'SPMRegistration'
-            self.handle = Handle(None, -1).cReg_newObject(self.name)
+            self.handle = HANDLE.cReg_newObject(self.name)
 
         def get_transformation_matrix_forward(self, idx=0):
             """Get forward transformation matrix."""
@@ -890,7 +887,7 @@ class NiftyResampler:
     def __init__(self):
         """init."""
         self.name = 'NiftyResampler'
-        self.handle = Handle(None, -1).cReg_newObject(self.name)
+        self.handle = HANDLE.cReg_newObject(self.name)
         self.reference_image = None
         self.floating_image = None
 
@@ -1071,7 +1068,7 @@ class ImageWeightedMean:
     def __init__(self):
         """init."""
         self.name = 'ImageWeightedMean'
-        self.handle = Handle(None, -1).cReg_newObject(self.name)
+        self.handle = HANDLE.cReg_newObject(self.name)
 
     def add_image(self, image, weight):
         """Add an image and its corresponding weight.
@@ -1104,9 +1101,9 @@ def __init__(self, src1=None, src2=None):
         self.handle = None
         self.name = 'AffineTransformation'
         if src1 is None:
-            self.handle = Handle(None, -1).cReg_newObject(self.name)
+            self.handle = HANDLE.cReg_newObject(self.name)
         elif isinstance(src1, str):
-            self.handle = Handle(None, -1).cReg_objectFromFile(self.name, src1)
+            self.handle = HANDLE.cReg_objectFromFile(self.name, src1)
         elif isinstance(src1, numpy.ndarray) and src2 is None:
             src1 = format_numpy_array_for_setter(src1)
             if src1.shape != (4, 4):
@@ -1116,15 +1113,15 @@ def __init__(self, src1=None, src2=None):
             for i in range(4):
                 for j in range(4):
                     trans[i, j] = src1[j, i]
-                self.handle = Handle(None, -1).cReg_AffineTransformation_construct_from_TM(trans)
+                self.handle = HANDLE.cReg_AffineTransformation_construct_from_TM(trans)
         elif isinstance(src1, numpy.ndarray) and src2 is not None and \
                 isinstance(src2, Quaternion):
             src1 = format_numpy_array_for_setter(src1)
             self.handle = src2.handle.cReg_AffineTransformation_construct_from_trans_and_quaternion(src1)
         elif isinstance(src1, numpy.ndarray) and isinstance(src2, numpy.ndarray):
             src1 = format_numpy_array_for_setter(src1)
             src2 = format_numpy_array_for_setter(src2)
-            self.handle = Handle(None, -1).cReg_AffineTransformation_construct_from_trans_and_euler(src1, src2)
+            self.handle = HANDLE.cReg_AffineTransformation_construct_from_trans_and_euler(src1, src2)
         else:
             raise error("""AffineTransformation accepts no args, filename,
                         4x4 array or translation with quaternion.""")
@@ -1191,7 +1188,7 @@ def get_quaternion(self):
     def get_identity():
         """Get identity matrix."""
         mat = AffineTransformation()
-        mat.handle = Handle(None, -1).cReg_AffineTransformation_get_identity()
+        mat.handle = HANDLE.cReg_AffineTransformation_get_identity()
         return mat
 
     @staticmethod
@@ -1221,7 +1218,7 @@ def __init__(self, src=None):
                                      array is wrong size.""")
             if src.dtype is not numpy.float32:
                 src = src.astype(numpy.float32)
-            self.handle = Handle(None, -1).cReg_Quaternion_construct_from_array(src)
+            self.handle = HANDLE.cReg_Quaternion_construct_from_array(src)
         elif isinstance(src, AffineTransformation):
             self.handle = src.handle.cReg_Quaternion_construct_from_AffineTransformation()
         else:

src/common/SIRF.py

@@ -35,7 +35,7 @@
 
 import deprecation
 
-from sirf.Utilities import Handle, assert_validities, assert_validity, cpp_int_dtype
+from sirf.Utilities import HANDLE, assert_validities, assert_validity, cpp_int_dtype
 
 if sys.version_info[0] >= 3 and sys.version_info[1] >= 4:
     ABC = abc.ABC
@@ -679,7 +679,7 @@ def __ne__(self, other):
         return not (self == other)
 
     def read(self, file, engine, verb):
-        self.handle = Handle(None, -1).cSIRF_readImageData(file, engine, verb)
+        self.handle = HANDLE.cSIRF_readImageData(file, engine, verb)
 
     def fill(self, image):
         self.handle.cSIRF_fillImageFromImage(image)
@@ -713,7 +713,7 @@ class DataHandleVector:
     """
     def __init__(self):
         self.name = 'DataHandleVector'
-        self.handle = Handle(None, -1).cSIRF_newObject(self.name)
+        self.handle = HANDLE.cSIRF_newObject(self.name)
 
     def push_back(self, handle):
         """Push back new data handle."""

src/common/Utilities.py

@@ -1,5 +1,6 @@
 '''Utilities used by all engines
 '''
+import functools
 import inspect
 import os
 import re
@@ -34,13 +35,19 @@
 
 
 class Handle:
+    """
+    Convenience class for:
+    - calling SWIG backend functions
+      + routing to correct backend based on function name prefix
+      + auto-unwrapping function arguments from:
+        * numpy data arrays (via `.ctypes.data`)
+        * handle pointers (via `._handle`)
+    - casting return types
+    - pointer destrunction on deletion
+    """
     def __init__(self, handle, check_stack: int | None = None):
         self._handle = handle
         if (check_stack is None or check_stack >= 0) and pyiutil.executionStatus(handle) != 0:
-            check_stack = inspect.stack()[1 if check_stack is None else check_stack]
-            #print('\nFile: %s' % check_stack[1])
-            #print('Line: %d' % check_stack[2])
-            #print('check_status found the following message sent from the engine:')
             msg = pyiutil.executionError(handle)
             file = pyiutil.executionErrorFile(handle)
             line = pyiutil.executionErrorLine(handle)
@@ -91,9 +98,11 @@ def __getattr__(self, name):
         func = getattr(backend, name)
         match name:
             case 'cSIRF_axpby' | 'cSIRF_axpbyAlt' | 'cReg_AffineTransformation_construct_from_trans_and_quaternion': # 2nd arg=self
+                @functools.wraps(func)
                 def wrapped(one, *args):
                     return Handle(func(self._toarg(one), self._handle, *map(self._toarg, args)))
             case _:
+                @functools.wraps(func)
                 def wrapped(*args):
                     if self.valid: # 1st arg=self
                         return Handle(func(self._handle, *map(self._toarg, args)))
@@ -113,6 +122,9 @@ def _toarg(cls, obj):
         return obj
 
 
+HANDLE = Handle(None, -1) # for calling backend functions which do not require a handle argument
+
+
 def cpp_int_bits():
     """Returns the number of bits in a C++ integer."""
     return pyiutil.intBits()
@@ -152,7 +164,7 @@ def examples_data_path(data_type):
     Returns the path to PET/MR/Registration data used by SIRF/examples demos.
     data_type: either 'PET' or 'MR' or 'Registration'
     '''
-    path = Handle(None, -1).cSIRF_examples_data_path(data_type)
+    path = HANDLE.cSIRF_examples_data_path(data_type)
     return str(path)