IO documentation

doc/user_guide/io.rst

@@ -492,7 +492,7 @@ EMSA/MSA
 --------
 
 This `open standard format
-<http://www.amc.anl.gov/ANLSoftwareLibrary/02-MMSLib/XEDS/EMMFF/EMMFF.IBM/Emmff.Total>`__
+<https://www.microscopy.org/resources/scientific_data/index.cfm>`__
 is widely used to exchange single spectrum data, but it does not support
 multidimensional data. It can be used to exchange single spectra with Gatan's
 Digital Micrograph.
@@ -529,12 +529,12 @@ using the `encoding` argument, e.g.:
 Ripple
 ------
 
-This `open standard format
-<http://www.nist.gov/lispix/doc/image-file-formats/raw-file-format.htm>`__ is
-widely used to exchange multidimensional data. However, it only supports data of
-up to three dimensions. It can be used to exchange data with Bruker and `Lispix
-<http://www.nist.gov/lispix/>`_. Used in combination with the :ref:`import-rpl`
-it is very useful for exporting data to Gatan's Digital Micrograph.
+This *open standard format* developed at NIST as native format for
+`Lispix <http://www.nist.gov/lispix/>`_ is widely used to exchange
+multidimensional data. However, it only supports data of up to three
+dimensions. It can also be used to exchange data with Bruker and used in
+combination with the :ref:`import-rpl` it is very useful for exporting data
+to Gatan's Digital Micrograph.
 
 The default encoding is latin-1. It is possible to set a different encoding
 using the encoding argument, e.g.:
@@ -554,8 +554,9 @@ the "r+" mode are incompatible).
 Images
 ------
 
-HyperSpy is able to read and write data too all the image formats supported by
-`the Python Image Library <http://www.pythonware.com/products/pil/>`_ (PIL).
+HyperSpy is able to read and write data too `all the image formats 
+<https://imageio.readthedocs.io/en/stable/formats.html>`_ supported by
+`imageio`, which used the Python Image Library  (PIL/pillow).
 This includes png, pdf, gif etc.
 
 It is important to note that these image formats only support 8-bit files, and
@@ -633,7 +634,8 @@ Gatan Digital Micrograph
 
 HyperSpy can read both dm3 and dm4 files but the reading features are not
 complete (and probably they will be unless Gatan releases the specifications of
-the format). That said, we understand that this is an important feature and if
+the format and creates a more consistent metadata-structure). That said, we
+understand that this is an important feature and if
 loading a particular Digital Micrograph file fails for you, please report it as
 an issue in the `issues tracker <https://github.com/hyperspy/hyperspy/issues>`__ to make
 us aware of the problem.
@@ -659,11 +661,11 @@ Extra loading arguments
 
 .. _edax-format:
 
-EDAX TEAM SPD and SPC
----------------------
+EDAX TEAM/Genesis SPD and SPC
+-----------------------------
 
 HyperSpy can read both ``.spd`` (spectrum image) and ``.spc`` (single spectra)
-files from the EDAX TEAM software.
+files from the EDAX TEAM software and its predecessor EDAX Genesis.
 If reading an ``.spd`` file, the calibration of the
 spectrum image is loaded from the corresponding ``.ipr`` and ``.spc`` files
 stored in the same directory, or from specific files indicated by the user.

hyperspy/io_plugins/image.py

@@ -37,32 +37,50 @@
 
 
 # TODO Extend it to support SI
-def file_writer(filename, signal, file_format='png', **kwds):
-    """Writes data to any format supported by PIL
+def file_writer(filename, signal, **kwds):
+    """Writes data to any format supported by imageio (PIL/pillow).
+    For a list of formats see https://imageio.readthedocs.io/en/stable/formats.html
 
-        Parameters
-        ----------
-        filename: str
-        signal: a Signal instance
-        file_format : str
-            The fileformat defined by its extension that is any one supported by
-            PIL.
+    Parameters
+    ----------
+    filename: {str, pathlib.Path, bytes, file}
+        The resource to write the image to, e.g. a filename, pathlib.Path or
+        file object, see the docs for more info. The file format is defined by 
+        the file extension that is any one supported by imageio.
+    signal: a Signal instance
+    format: str, optional
+        The format to use to read the file. By default imageio selects the
+        appropriate for you based on the filename and its contents.
+    **kwds: keyword arguments
+        Allows to pass keyword arguments supported by the individual file
+        writers as documented at https://imageio.readthedocs.io/en/stable/formats.html
+
     """
     data = signal.data
     if rgb_tools.is_rgbx(data):
         data = rgb_tools.rgbx2regular_array(data)
-    imwrite(filename, data)
+    imwrite(filename, data, **kwds)
 
 
 def file_reader(filename, **kwds):
-    """Read data from any format supported by PIL.
+    """Read data from any format supported by imageio (PIL/pillow).
+    For a list of formats see https://imageio.readthedocs.io/en/stable/formats.html
 
     Parameters
     ----------
-    filename: str
+    filename: {str, pathlib.Path, bytes, file}
+        The resource to load the image from, e.g. a filename, pathlib.Path,
+        http address or file object, see the docs for more info. The file format
+        is defined by the file extension that is any one supported by imageio.
+    format: str, optional
+        The format to use to read the file. By default imageio selects the
+        appropriate for you based on the filename and its contents.
+    **kwds: keyword arguments
+        Allows to pass keyword arguments supported by the individual file
+        readers as documented at https://imageio.readthedocs.io/en/stable/formats.html
 
     """
-    dc = _read_data(filename)
+    dc = _read_data(filename, **kwds)
     lazy = kwds.pop('lazy', False)
     if lazy:
         # load the image fully to check the dtype and shape, should be cheap.
@@ -81,7 +99,7 @@ def file_reader(filename, **kwds):
              }]
 
 
-def _read_data(filename):
+def _read_data(filename, **kwds):
     dc = imread(filename)
     if len(dc.shape) > 2:
         # It may be a grayscale image that was saved in the RGB or RGBA

hyperspy/tests/io/test_image.py

@@ -52,3 +52,25 @@ def test_save_load_cycle_color(color, ext):
         filename = os.path.join(tmpdir, 'test_image.'+ext)
         s.save(filename)
         hs.load(filename)
+
+
+@pytest.mark.parametrize(("dtype"), ['uint8', 'uint32'])
+@pytest.mark.parametrize(("ext"), ['png', 'bmp', 'gif', 'jpg'])
+def test_save_load_cycle_kwds(dtype, ext):
+    s = hs.signals.Signal2D(np.arange(128*128).reshape(128, 128).astype(dtype))
+    with tempfile.TemporaryDirectory() as tmpdir:
+        print('Saving-loading cycle for the extension:', ext)
+        filename = os.path.join(tmpdir, 'test_image.'+ext)
+        if ext == 'png':
+            if dtype == 'uint32':
+                kwds = {'bits': 32}
+            else:
+                kwds = {'optimize': True}
+        elif ext == 'jpg':
+            kwds = {'quality': 100, 'optimize': True}
+        elif ext == 'gif':
+            kwds = {'subrectangles': 'True', 'palettesize': 128}
+        else:
+            kwds = {}
+        s.save(filename, **kwds)
+        hs.load(filename, pilmode='L', as_grey=True)