Image formats#

RosettaSciIO can read and write data to all the image formats supported by imageio, which uses the Python Image Library (PIL/pillow). This includes .jpg, .gif, .png, .pdf, .tif, etc. It is important to note that these image formats only support 8-bit files, and therefore have an insufficient dynamic range for most scientific applications. It is therefore highly discouraged to use any general image format to store data for analysis purposes (with the exception of the Tagged image file format (TIFF), which uses the separate tiffile library).

Note

To read this format, the optional dependency imageio is required.

API functions#

rsciio.image.file_reader(filename, lazy=False, **kwds)#

Read data from any format supported by imageio (PIL/pillow).

The file format is defined by the file extension that is any one supported by imageio. For a list of formats see https://imageio.readthedocs.io/en/stable/formats/index.html.

Parameters:
filenamestr, pathlib.Path

Filename of the file to read or corresponding pathlib.Path.

lazybool, default=False

Whether to open the file lazily or not. The file will stay open until closed in compute() or closed manually. get_file_handle() can be used to access the file handler and close it manually.

**kwdsdict, optional

Allows to pass keyword arguments supported by the individual file readers as documented at https://imageio.readthedocs.io/en/stable/formats/index.html.

Returns:
list of dict

List of dictionaries containing the following fields:

  • ‘data’ – multidimensional numpy.ndarray or dask.array.Array

  • ‘axes’ – list of dictionaries describing the axes containing the fields ‘name’, ‘units’, ‘index_in_array’, and either ‘size’, ‘offset’, and ‘scale’ or a numpy array ‘axis’ containing the full axes vector

  • ‘metadata’ – dictionary containing the parsed metadata

  • ‘original_metadata’ – dictionary containing the full metadata tree from the input file

When the file contains several datasets, each dataset will be loaded as separate dictionary.

rsciio.image.file_writer(filename, signal, scalebar=False, scalebar_kwds=None, output_size=None, imshow_kwds=None, **kwds)#

Write data to any format supported by pillow.

The file format is defined by the file extension that is any one supported by imageio. When any of the parameters output_size, scalebar or imshow_kwds is given, imshow() is used to generate a figure.

Parameters:
filenamestr, pathlib.Path

Filename of the file to write to or corresponding pathlib.Path.

signaldict

Dictionary containing the signal object. Should contain the following fields:

  • ‘data’ – multidimensional numpy array

  • ‘axes’ – list of dictionaries describing the axes containing the fields ‘name’, ‘units’, ‘index_in_array’, and either ‘size’, ‘offset’, and ‘scale’ or a numpy array ‘axis’ containing the full axes vector

  • ‘metadata’ – dictionary containing the metadata tree

scalebarbool, Default=False

Export the image with a scalebar.

scalebar_kwdsdict, optional

Dictionary of keyword arguments for the scalebar. Useful to set formatting, location, etc. of the scalebar. See the documentation of the ‘matplotlib-scalebar’ library for more information.

output_size{2-tuple, int, None}, Default=None

The output size of the image in pixels (width, height):

  • if int, defines the width of the image, the height is determined from the aspect ratio of the image

  • if 2-tuple, defines the width and height of the image. Padding with white pixels is used to maintain the aspect ratio of the image.

  • if None, the size of the data is used.

For output sizes larger than the data size, “nearest” interpolation is used by default and this behaviour can be changed through the imshow_kwds dictionary.

imshow_kwdsdict, optional

Keyword arguments dictionary for imshow().

**kwdsdict, optional

Allows to pass keyword arguments supported by the individual file writers as documented at https://imageio.readthedocs.io/en/stable/formats/index.html when exporting an image without scalebar. When exporting with a scalebar, the keyword arguments are passed to the pil_kwargs dictionary of savefig().

Examples of saving arguments#

When saving an image, a scalebar can be added to the image and the formatting, location, etc. of the scalebar can be set using the scalebar_kwds arguments:

>>> from rsciio.image import file_writer
>>> file_writer('file.jpg', signal, scalebar=True)
>>> file_writer('file.jpg', signal, scalebar=True, scalebar_kwds={'location':'lower right'})

Note

To add scalebar, the optional dependency matplotlib-scalebar is required.

In the example above, the image is created using imshow(), and additional keyword arguments can be passed to this function using imshow_kwds. For example, this can be used to save an image displayed using the matplotlib colormap viridis:

>>> file_writer('file.jpg', signal, imshow_kwds=dict(cmap='viridis'))

The resolution of the exported image can be adjusted:

>>> file_writer('file.jpg', signal, output_size=512)