Merge pull request #644 from effigies/enh/serialize

ENH: Add SerializableImage class with to/from_bytes methods

Author: effigies

nibabel/__init__.py

@@ -65,6 +65,7 @@ def setup_test():
 from .minc1 import Minc1Image
 from .minc2 import Minc2Image
 from .cifti2 import Cifti2Header, Cifti2Image
+from .gifti import GiftiImage
 # Deprecated backwards compatiblity for MINC1
 from .deprecated import ModuleProxy as _ModuleProxy
 minc = _ModuleProxy('nibabel.minc')

nibabel/filebasedimages.py

@@ -8,6 +8,7 @@
 ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ##
 ''' Common interface for any image format--volume or surface, binary or xml.'''
 
+import io
 from copy import deepcopy
 from six import string_types
 from .fileholders import FileHolder
@@ -78,8 +79,8 @@ class FileBasedImage(object):
 
     methods:
 
-       * .get_header() (deprecated, use header property instead)
-       * .to_filename(fname) - writes data to filename(s) derived from
+       * get_header() (deprecated, use header property instead)
+       * to_filename(fname) - writes data to filename(s) derived from
          ``fname``, where the derivation may differ between formats.
        * to_file_map() - save image to files with which the image is already
          associated.
@@ -511,3 +512,92 @@ 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
+
+    Loading from byte strings should provide round-trip equivalence:
+
+    .. code:: python
+
+        img_a = klass.from_bytes(bstr)
+        img_b = klass.from_bytes(img_a.to_bytes())
+
+        np.allclose(img_a.get_fdata(), img_b.get_fdata())
+        np.allclose(img_a.affine, img_b.affine)
+
+    Further, for images that are single files on disk, the following methods of loading
+    the image must be equivalent:
+
+    .. code:: python
+
+        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:
+
+    .. code:: python
+
+        img.to_filename(fname)
+
+        with open(fname, 'wb') as fobj:
+            fobj.write(img.to_bytes())
+
+    Images that consist of separate header and data files (e.g., Analyze
+    images) currently do not support this interface.
+    For multi-file images, ``to_bytes()`` and ``from_bytes()`` must be
+    overridden, and any encoding details should be documented.
+    '''
+
+    @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
+        """
+        if len(klass.files_types) > 1:
+            raise NotImplementedError("from_bytes is undefined for multi-file images")
+        bio = io.BytesIO(bytestring)
+        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
+        """
+        if len(self.__class__.files_types) > 1:
+            raise NotImplementedError("to_bytes() is undefined for multi-file images")
+        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/gifti/gifti.py

@@ -18,7 +18,7 @@
 import numpy as np
 
 from .. import xmlutils as xml
-from ..filebasedimages import FileBasedImage
+from ..filebasedimages import SerializableImage
 from ..nifti1 import data_type_codes, xform_codes, intent_codes
 from .util import (array_index_order_codes, gifti_encoding_codes,
                    gifti_endian_codes, KIND2FMT)
@@ -534,7 +534,7 @@ def metadata(self):
         return self.meta.metadata
 
 
-class GiftiImage(xml.XmlSerializable, FileBasedImage):
+class GiftiImage(xml.XmlSerializable, SerializableImage):
     """ GIFTI image object
 
     The Gifti spec suggests using the following suffixes to your
@@ -724,6 +724,9 @@ def to_xml(self, enc='utf-8'):
 <!DOCTYPE GIFTI SYSTEM "http://www.nitrc.org/frs/download.php/115/gifti.dtd">
 """ + xml.XmlSerializable.to_xml(self, enc)
 
+    # Avoid the indirection of going through to_file_map
+    to_bytes = to_xml
+
     def to_file_map(self, file_map=None):
         """ Save the current image to the specified file_map
 

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
@@ -2025,7 +2026,7 @@ def as_reoriented(self, ornt):
         return img
 
 
-class Nifti1Image(Nifti1Pair):
+class Nifti1Image(Nifti1Pair, SerializableImage):
     """ Class for single file NIfTI1 format image
     """
     header_class = Nifti1Header

nibabel/tests/test_filebasedimages.py

@@ -5,9 +5,9 @@
 
 import numpy as np
 
-from nibabel.filebasedimages import FileBasedHeader, FileBasedImage
+from ..filebasedimages import FileBasedHeader, FileBasedImage, SerializableImage
 
-from nibabel.tests.test_image_api import GenericImageAPI
+from .test_image_api import GenericImageAPI, SerializeMixin
 
 from nose.tools import (assert_true, assert_false, assert_equal,
                         assert_not_equal)
@@ -50,6 +50,10 @@ def set_data_dtype(self, dtype):
         self.arr = self.arr.astype(dtype)
 
 
+class SerializableNumpyImage(FBNumpyImage, SerializableImage):
+    pass
+
+
 class TestFBImageAPI(GenericImageAPI):
     """ Validation for FileBasedImage instances
     """
@@ -80,6 +84,16 @@ def obj_params(self):
             yield func, params
 
 
+class TestSerializableImageAPI(TestFBImageAPI, SerializeMixin):
+    image_maker = SerializableNumpyImage
+
+    @staticmethod
+    def _header_eq(header_a, header_b):
+        """ FileBasedHeader is an abstract class, so __eq__ is undefined.
+        Checking for the same header type is sufficient, here. """
+        return type(header_a) == type(header_b) == FileBasedHeader
+
+
 def test_filebased_header():
     # Test stuff about the default FileBasedHeader
 

nibabel/tests/test_image_api.py

@@ -38,6 +38,7 @@
 
 from .. import (AnalyzeImage, Spm99AnalyzeImage, Spm2AnalyzeImage,
                 Nifti1Pair, Nifti1Image, Nifti2Pair, Nifti2Image,
+                GiftiImage,
                 MGHImage, Minc1Image, Minc2Image, is_proxy)
 from ..spatialimages import SpatialImage
 from .. import minc1, minc2, parrec, brikhead
@@ -493,6 +494,67 @@ def validate_affine_deprecated(self, imaker, params):
             assert_true(aff is img.get_affine())
 
 
+class SerializeMixin(object):
+    def validate_to_bytes(self, imaker, params):
+        img = imaker()
+        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):
+        img = imaker()
+        klass = getattr(self, 'klass', img.__class__)
+        with InTemporaryDirectory():
+            fname = 'img' + self.standard_extension
+            img.to_filename(fname)
+
+            all_images = list(getattr(self, 'example_images', [])) + [{'fname': fname}]
+            for img_params in all_images:
+                img_a = klass.from_filename(img_params['fname'])
+                with open(img_params['fname'], 'rb') as fobj:
+                    img_b = klass.from_bytes(fobj.read())
+
+                assert self._header_eq(img_a.header, img_b.header)
+                assert np.array_equal(img_a.get_data(), img_b.get_data())
+                del img_a
+                del img_b
+
+    def validate_to_from_bytes(self, imaker, params):
+        img = imaker()
+        klass = getattr(self, 'klass', img.__class__)
+        with InTemporaryDirectory():
+            fname = 'img' + self.standard_extension
+            img.to_filename(fname)
+
+            all_images = list(getattr(self, 'example_images', [])) + [{'fname': fname}]
+            for img_params in all_images:
+                img_a = klass.from_filename(img_params['fname'])
+                bytes_a = img_a.to_bytes()
+
+                img_b = klass.from_bytes(bytes_a)
+
+                assert img_b.to_bytes() == bytes_a
+                assert self._header_eq(img_a.header, img_b.header)
+                assert np.array_equal(img_a.get_data(), img_b.get_data())
+                del img_a
+                del img_b
+
+    @staticmethod
+    def _header_eq(header_a, header_b):
+        """ Header equality check that can be overridden by a subclass of this test
+
+        This allows us to retain the same tests above when testing an image that uses an
+        abstract class as a header, namely when testing the FileBasedImage API, which
+        raises a NotImplementedError for __eq__
+        """
+        return header_a == header_b
+
+
+
 class LoadImageAPI(GenericImageAPI,
                    DataInterfaceMixin,
                    AffineMixin,
@@ -613,7 +675,7 @@ class TestNifti1PairAPI(TestSpm99AnalyzeAPI):
     can_save = True
 
 
-class TestNifti1API(TestNifti1PairAPI):
+class TestNifti1API(TestNifti1PairAPI, SerializeMixin):
     klass = image_maker = Nifti1Image
     standard_extension = '.nii'
 
@@ -660,14 +722,20 @@ def loader(self, fname):
 #    standard_extension = '.v'
 
 
-class TestMGHAPI(ImageHeaderAPI):
+class TestMGHAPI(ImageHeaderAPI, SerializeMixin):
     klass = image_maker = MGHImage
     example_shapes = ((2, 3, 4), (2, 3, 4, 5))  # MGH can only do >= 3D
     has_scaling = True
     can_save = True
     standard_extension = '.mgh'
 
 
+class TestGiftiAPI(LoadImageAPI, SerializeMixin):
+    klass = image_maker = GiftiImage
+    can_save = True
+    standard_extension = '.gii'
+
+
 class TestAFNIAPI(LoadImageAPI):
     loader = brikhead.load
     klass = image_maker = brikhead.AFNIImage