ENH,RF: Deprecated Image.resample. New convenience wrappers -

resampleToPixdims and resampleToReference

fsl/data/image.py

@@ -1165,12 +1165,10 @@ class Image(Nifti):
         self.notify(topic='saveState')
 
 
+    @deprecated.deprecated('2.2.0', '3.0.0',
+                           'Use fsl.utils.image.resample instead.')
     def resample(self, *args, **kwargs):
-        """Returns a copy of the data in this ``Image``, resampled to the
-        specified ``newShape``.
-
-        See the :mod:`.image.resample` module for more details.
-        """
+        """Deprecated - use :func:`.image.resample` instead. """
         from fsl.utils.image.resample import resample
         return resample(self, *args, **kwargs)
 

fsl/utils/image/resample.py

@@ -7,6 +7,9 @@
 """This module defines the :func:`resample` function, which can be used
 to resample an :class:`.Image` object to a different resolution.
 
+The :func:`resampleToPixdims` and :func:`resampleToReference` functions
+are convenience wrappers around :func:`resample`.
+
 The :func:`applySmoothing` and :func:`calculateMatrix` functions are
 sub-functions of :func:`resample`.
 """
@@ -20,6 +23,40 @@ import scipy.ndimage       as ndimage
 import fsl.utils.transform as transform
 
 
+def resampleToPixdims(image, newPixdims, **kwargs):
+    """Resample ``image`` so that it has the specified voxel dimensions.
+
+    This is a wrapper around :func:`resample` - refer to its documenttion
+    for details on the other arguments and the return values.
+
+    :arg image:   :class:`.Image` to resample
+    :arg pixdims: New voxel dimensions to resample ``image`` to.
+    """
+    oldShape   = image.shape
+    oldPixdims = image.pixdim
+    fac        = [o / float(n) for o, n in zip(oldPixdims, newPixdims)]
+    newShape   = [p * f        for p, f in zip(oldShape,   fac)]
+    return resample(image, newShape, **kwargs)
+
+
+def resampleToReference(image, reference, **kwargs):
+    """Resample ``image`` into the space of the ``reference``.
+
+    This is a wrapper around :func:`resample` - refer to its documenttion
+    for details on the other arguments and the return values.
+
+    :arg image:     :class:`.Image` to resample
+    :arg reference: :class:`.Nifti` defining the space to resample ``image``
+                    into
+    """
+
+    kwargs['mode']     = kwargs.get('mode', 'constant')
+    kwargs['newShape'] = reference.shape
+    kwargs['matrix']   = transform.concat(image.worldToVoxMat,
+                                          reference.voxToWorldMat)
+    return resample(image, **kwargs)
+
+
 def resample(image,
              newShape,
              sliceobj=None,