RF: Factor SerializableImage

Author: effigies

nibabel/filebasedimages.py

@@ -260,21 +260,6 @@ def from_filename(klass, filename):
         file_map = klass.filespec_to_file_map(filename)
         return klass.from_file_map(file_map)
 
-    @classmethod
-    def from_bytes(klass, bstring):
-        """ Construct image from a byte string
-
-        Class method
-
-        Parameters
-        ----------
-        bstring : bytes
-            Byte string containing the on-disk representation of an image
-        """
-        bio = io.BytesIO(bstring)
-        file_map = self.make_file_map({'image': bio, 'header': bio})
-        return klass.from_file_map(file_map)
-
     @classmethod
     def from_file_map(klass, file_map):
         raise NotImplementedError
@@ -349,24 +334,6 @@ def to_filename(self, filename):
         self.file_map = self.filespec_to_file_map(filename)
         self.to_file_map()
 
-    def to_bytes(self):
-        """ Return a ``bytes`` object with the contents of the file that would
-        be written if the image were saved.
-
-        Parameters
-        ----------
-        None
-
-        Returns
-        -------
-        bytes
-            Serialized image
-        """
-        bio = io.BytesIO()
-        file_map = self.make_file_map({'image': bio, 'header': bio})
-        self.to_file_map(file_map)
-        return bio.getvalue()
-
     @deprecate_with_version('to_filespec method is deprecated.\n'
                             'Please use the "to_filename" method instead.',
                             '1.0', '3.0')
@@ -545,3 +512,79 @@ def path_maybe_image(klass, filename, sniff=None, sniff_max=1024):
         if sniff is None or len(sniff[0]) < klass._meta_sniff_len:
             return False, sniff
         return klass.header_class.may_contain_header(sniff[0]), sniff
+
+
+class SerializableImage(FileBasedImage):
+    '''
+    Abstract image class for (de)serializing images to/from byte strings.
+
+    The class doesn't define any image properties.
+
+    It has:
+
+    methods:
+
+       * .to_bytes() - serialize image to byte string
+
+    classmethods:
+
+       * from_bytes(bytestring) - make instance by deserializing a byte string
+
+    The following properties should hold:
+
+      * ``klass.from_bytes(bstr).to_bytes() == bstr``
+      * if ``img = orig.__class__.from_bytes(orig.to_bytes())``, then
+        ``img.header == orig.header`` and ``img.get_data() == orig.get_data()``
+
+    Further, for images that are single files on disk, the following methods of loading
+    the image must be equivalent:
+
+        img = klass.from_filename(fname)
+
+        with open(fname, 'rb') as fobj:
+            img = klass.from_bytes(fobj.read())
+
+    And the following methods of saving a file must be equivalent:
+
+        img.to_filename(fname)
+
+        with open(fname, 'wb') as fobj:
+            fobj.write(img.to_bytes())
+
+    Images that consist of separate header and data files will generally
+    place the header with the data, but if the header is not of fixed
+    size and does not define its own size, a new format may need to be
+    defined.
+    '''
+    @classmethod
+    def from_bytes(klass, bytestring):
+        """ Construct image from a byte string
+
+        Class method
+
+        Parameters
+        ----------
+        bstring : bytes
+            Byte string containing the on-disk representation of an image
+        """
+        bio = io.BytesIO(bstring)
+        file_map = klass.make_file_map({'image': bio, 'header': bio})
+        return klass.from_file_map(file_map)
+
+    def to_bytes(self):
+        """ Return a ``bytes`` object with the contents of the file that would
+        be written if the image were saved.
+
+        Parameters
+        ----------
+        None
+
+        Returns
+        -------
+        bytes
+            Serialized image
+        """
+        bio = io.BytesIO()
+        file_map = self.make_file_map({'image': bio, 'header': bio})
+        self.to_file_map(file_map)
+        return bio.getvalue()

nibabel/freesurfer/mghformat.py

@@ -16,6 +16,7 @@
 from ..affines import voxel_sizes, from_matvec
 from ..volumeutils import (array_to_file, array_from_file, endian_codes,
                            Recoder)
+from ..filebasedimages import SerializableImage
 from ..spatialimages import HeaderDataError, SpatialImage
 from ..fileholders import FileHolder
 from ..arrayproxy import ArrayProxy, reshape_dataobj
@@ -503,7 +504,7 @@ def __setitem__(self, item, value):
             super(MGHHeader, self).__setitem__(item, value)
 
 
-class MGHImage(SpatialImage):
+class MGHImage(SpatialImage, SerializableImage):
     """ Class for MGH format image
     """
     header_class = MGHHeader

nibabel/nifti1.py

@@ -19,6 +19,7 @@
 import numpy.linalg as npl
 
 from .py3k import asstr
+from .filebasedimages import SerializableImage
 from .volumeutils import Recoder, make_dt_codes, endian_codes
 from .spatialimages import HeaderDataError, ImageFileError
 from .batteryrunners import Report
@@ -1758,7 +1759,7 @@ class Nifti1PairHeader(Nifti1Header):
     is_single = False
 
 
-class Nifti1Pair(analyze.AnalyzeImage):
+class Nifti1Pair(analyze.AnalyzeImage, SerializableImage):
     """ Class for NIfTI1 format image, header pair
     """
     header_class = Nifti1PairHeader

nibabel/tests/test_image_api.py

@@ -494,17 +494,36 @@ def validate_affine_deprecated(self, imaker, params):
 
 
 class SerializeMixin(object):
-
-    def validate_serialize(self, imaker, params):
+    def validate_to_bytes(self, imaker, params):
         img = imaker()
-        serialized = img.serialize()
+        serialized = img.to_bytes()
         with InTemporaryDirectory():
             fname = 'img' + self.standard_extension
             img.to_filename(fname)
             with open(fname, 'rb') as fobj:
                 file_contents = fobj.read()
         assert serialized == file_contents
 
+    def validate_from_bytes(self, imaker, params):
+        for img_params in self.example_images:
+            img_a = self.klass.from_filename(img_params['fname'])
+            with open(img_params['fname'], 'rb') as fobj:
+                img_b = self.klass.from_bytes(fobj.read())
+
+            assert img_a.header == img_b.header
+            assert np.array_equal(img_a.get_data(), img_b.get_data())
+
+    def validate_round_trip(self, imaker, params):
+        for img_params in self.example_images:
+            img_a = self.klass.from_filename(img_params['fname'])
+            bytes_a = img_a.to_bytes()
+
+            img_b = self.klass.from_bytes(bytes_a)
+
+            assert img_b.to_bytes() == bytes_a
+            assert img_a.header == img_b.header
+            assert np.array_equal(img_a.get_data(), img_b.get_data())
+
 
 class LoadImageAPI(GenericImageAPI,
                    DataInterfaceMixin,