Skip to main content
`Ctrl`+`K`

# 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:
    filename `python:str`, `pathlib.Path`

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

    lazy bool, 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.

    **kwds `python:dict`, 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:
    `python:list` of `python: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:
    filename `python:str`, `pathlib.Path`

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

    signal `python:dict`

      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

    scalebar bool, Default=False

      Export the image with a scalebar.

    scalebar_kwds `python:dict`, 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, `python:int`, `python: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_kwds `python:dict`, optional

      Keyword arguments dictionary for `imshow()`.

    **kwds `python:dict`, 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)