# Imageio’s user API

These functions represent imageio’s main interface for the user. They provide a common API to read and write image data for a large variety of formats. All read and write functions accept keyword arguments, which are passed on to the format that does the actual work. To see what keyword arguments are supported by a specific format, use the `help()` function.

Functions for reading:

> - `imread()` - read an image from the specified uri
> - `mimread()` - read a series of images from the specified uri
> - `volread()` - read a volume from the specified uri
> - `mvolread()` - read a series of volumes from the specified uri

Functions for saving:

> - `imwrite()` - write an image to the specified uri
> - `mimwrite()` - write a series of images to the specified uri
> - `volwrite()` - write a volume to the specified uri
> - `mvolwrite()` - write a series of volumes to the specified uri

More control:

For a larger degree of control, imageio provides functions `get_reader()` and `get_writer()`. They respectively return an `Reader` and an `Writer` object, which can be used to read/write data and meta data in a more controlled manner. This also allows specific scientific formats to be exposed in a way that best suits that file-format.

All read-functions return images as numpy arrays, and have a `meta` attribute; the meta-data dictionary can be accessed with `im.meta`. To make this work, imageio actually makes use of a subclass of `np.ndarray`. If needed, the image can be converted to a plain numpy array using `np.asarray(im)`.

Supported resource URI’s:

All functions described here accept a URI to describe the resource to read from or write to. These can be a wide range of things. (Imageio takes care of handling the URI so that plugins can access the data in an easy way.)

For reading and writing:

- a normal filename, e.g. `'c:\foo\bar.png'`
- a file in a zipfile, e.g. `'c:\foo\bar.zip\eggs.png'`
- a file object with a `read()` / `write()` method.

For reading:

- an http/ftp address, e.g. `'http://example.com/foo.png'`
- the raw bytes of an image file
- `get_reader("<video0>")` to grab images from a (web) camera.
- `imread("<screen>")` to grab a screenshot (on Windows or OS X).
- `imread("<clipboard>")` to grab an image from the clipboard (on Windows).

For writing one can also use `'<bytes>'` or `imageio.RETURN_BYTES` to make a write function return the bytes instead of writing to a file.

Note that reading from HTTP and zipfiles works for many formats including png and jpeg, but may not work for all formats (some plugins “seek” the file object, which HTTP/zip streams do not support). In such a case one can download/extract the file first. For HTTP one can use something like `imageio.imread(imageio.core.urlopen(url).read(), '.gif')`.

`imageio.``help`(name=None)

  Print the documentation of the format specified by name, or a list of supported formats if name is omitted.

  Parameters:

  name : str

  > Can be the name of a format, a filename extension, or a full filename. See also the formats page.

`imageio.``show_formats`()

  Show a nicely formatted list of available formats

`imageio.``imread`(uri, format=None, **kwargs)

  Reads an image from the specified file. Returns a numpy array, which comes with a dict of meta data at its ‘meta’ attribute.

  Note that the image data is returned as-is, and may not always have a dtype of uint8 (and thus may differ from what e.g. PIL returns).

  Parameters:

  uri : {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.

  format : str

  > The format to use to read the file. By default imageio selects the appropriate for you based on the filename and its contents.

  kwargs : …

  > Further keyword arguments are passed to the reader. See `help()` to see what arguments are available for a particular format.

`imageio.``imwrite`(uri, im, format=None, **kwargs)

  Write an image to the specified file.

  Parameters:

  uri : {str, pathlib.Path, file}

  > The resource to write the image to, e.g. a filename, pathlib.Path or file object, see the docs for more info.

  im : numpy.ndarray

  > The image data. Must be NxM, NxMx3 or NxMx4.

  format : str

  > The format to use to read the file. By default imageio selects the appropriate for you based on the filename and its contents.

  kwargs : …

  > Further keyword arguments are passed to the writer. See `help()` to see what arguments are available for a particular format.

`imageio.``mimread`(uri, format=None, memtest=True, **kwargs)

  Reads multiple images from the specified file. Returns a list of numpy arrays, each with a dict of meta data at its ‘meta’ attribute.

  Parameters:

  uri : {str, pathlib.Path, bytes, file}

  > The resource to load the images from, e.g. a filename,pathlib.Path, http address or file object, see the docs for more info.

  format : str

  > The format to use to read the file. By default imageio selects the appropriate for you based on the filename and its contents.

  memtest : bool

  > If True (default), this function will raise an error if the resulting list of images consumes over 256 MB of memory. This is to protect the system using so much memory that it needs to resort to swapping, and thereby stall the computer. E.g. `mimread('hunger_games.avi')`.

  kwargs : …

  > Further keyword arguments are passed to the reader. See `help()` to see what arguments are available for a particular format.

`imageio.``mimwrite`(uri, ims, format=None, **kwargs)

  Write multiple images to the specified file.

  Parameters:

  uri : {str, pathlib.Path, file}

  > The resource to write the images to, e.g. a filename, pathlib.Path or file object, see the docs for more info.

  ims : sequence of numpy arrays

  > The image data. Each array must be NxM, NxMx3 or NxMx4.

  format : str

  > The format to use to read the file. By default imageio selects the appropriate for you based on the filename and its contents.

  kwargs : …

  > Further keyword arguments are passed to the writer. See `help()` to see what arguments are available for a particular format.

`imageio.``volread`(uri, format=None, **kwargs)

  Reads a volume from the specified file. Returns a numpy array, which comes with a dict of meta data at its ‘meta’ attribute.

  Parameters:

  uri : {str, pathlib.Path, bytes, file}

  > The resource to load the volume from, e.g. a filename, pathlib.Path, http address or file object, see the docs for more info.

  format : str

  > The format to use to read the file. By default imageio selects the appropriate for you based on the filename and its contents.

  kwargs : …

  > Further keyword arguments are passed to the reader. See `help()` to see what arguments are available for a particular format.

`imageio.``volwrite`(uri, vol, format=None, **kwargs)

  Write a volume to the specified file.

  Parameters:

  uri : {str, pathlib.Path, file}

  > The resource to write the image to, e.g. a filename, pathlib.Path or file object, see the docs for more info.

  vol : numpy.ndarray

  > The image data. Must be NxMxL (or NxMxLxK if each voxel is a tuple).

  format : str

  > The format to use to read the file. By default imageio selects the appropriate for you based on the filename and its contents.

  kwargs : …

  > Further keyword arguments are passed to the writer. See `help()` to see what arguments are available for a particular format.

`imageio.``mvolread`(uri, format=None, memtest=True, **kwargs)

  Reads multiple volumes from the specified file. Returns a list of numpy arrays, each with a dict of meta data at its ‘meta’ attribute.

  Parameters:

  uri : {str, pathlib.Path, bytes, file}

  > The resource to load the volumes from, e.g. a filename, pathlib.Path, http address or file object, see the docs for more info.

  format : str

  > The format to use to read the file. By default imageio selects the appropriate for you based on the filename and its contents.

  memtest : bool

  > If True (default), this function will raise an error if the resulting list of images consumes over 1 GB of memory. This is to protect the system using so much memory that it needs to resort to swapping, and thereby stall the computer. E.g. `mimread('hunger_games.avi')`.

  kwargs : …

  > Further keyword arguments are passed to the reader. See `help()` to see what arguments are available for a particular format.

`imageio.``mvolwrite`(uri, vols, format=None, **kwargs)

  Write multiple volumes to the specified file.

  Parameters:

  uri : {str, pathlib.Path, file}

  > The resource to write the volumes to, e.g. a filename, pathlib.Path or file object, see the docs for more info.

  ims : sequence of numpy arrays

  > The image data. Each array must be NxMxL (or NxMxLxK if each voxel is a tuple).

  format : str

  > The format to use to read the file. By default imageio selects the appropriate for you based on the filename and its contents.

  kwargs : …

  > Further keyword arguments are passed to the writer. See `help()` to see what arguments are available for a particular format.

`imageio.``get_reader`(uri, format=None, mode='?', **kwargs)

  Returns a `Reader` object which can be used to read data and meta data from the specified file.

  Parameters:

  uri : {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.

  format : str

  > The format to use to read the file. By default imageio selects the appropriate for you based on the filename and its contents.

  mode : {‘i’, ‘I’, ‘v’, ‘V’, ‘?’}

  > Used to give the reader a hint on what the user expects (default “?”): “i” for an image, “I” for multiple images, “v” for a volume, “V” for multiple volumes, “?” for don’t care.

  kwargs : …

  > Further keyword arguments are passed to the reader. See `help()` to see what arguments are available for a particular format.

`imageio.``get_writer`(uri, format=None, mode='?', **kwargs)

  Returns a `Writer` object which can be used to write data and meta data to the specified file.

  Parameters:

  uri : {str, pathlib.Path, file}

  > The resource to write the image to, e.g. a filename, pathlib.Path or file object, see the docs for more info.

  format : str

  > The format to use to write the file. By default imageio selects the appropriate for you based on the filename.

  mode : {‘i’, ‘I’, ‘v’, ‘V’, ‘?’}

  > Used to give the writer a hint on what the user expects (default ‘?’): “i” for an image, “I” for multiple images, “v” for a volume, “V” for multiple volumes, “?” for don’t care.

  kwargs : …

  > Further keyword arguments are passed to the writer. See `help()` to see what arguments are available for a particular format.

class `imageio.core.format.``Reader`(format, request)

  The purpose of a reader object is to read data from an image resource, and should be obtained by calling `get_reader()`.

  A reader can be used as an iterator to read multiple images, and (if the format permits) only reads data from the file when new data is requested (i.e. streaming). A reader can also be used as a context manager so that it is automatically closed.

  Plugins implement Reader’s for different formats. Though rare, plugins may provide additional functionality (beyond what is provided by the base reader class).

  `close`()

    Flush and close the reader/writer. This method has no effect if it is already closed.

  `closed`

    Whether the reader/writer is closed.

  `format`

    The `Format` object corresponding to the current read/write operation.

  `get_data`(index, **kwargs)

    Read image data from the file, using the image index. The returned image has a ‘meta’ attribute with the meta data.

    Some formats may support additional keyword arguments. These are listed in the documentation of those formats.

  `get_length`()

    Get the number of images in the file. (Note: you can also use `len(reader_object)`.)

    The result can be:
      - 0 for files that only have meta data
      - 1 for singleton images (e.g. in PNG, JPEG, etc.)
      - N for image series
      - inf for streams (series of unknown length)
  `get_meta_data`(index=None)

    Read meta data from the file. using the image index. If the index is omitted or None, return the file’s (global) meta data.

    Note that `get_data` also provides the meta data for the returned image as an atrribute of that image.

    The meta data is a dict, which shape depends on the format. E.g. for JPEG, the dict maps group names to subdicts and each group is a dict with name-value pairs. The groups represent the different metadata formats (EXIF, XMP, etc.).

  `get_next_data`(**kwargs)

    Read the next image from the series.

    Some formats may support additional keyword arguments. These are listed in the documentation of those formats.

  `iter_data`()

    Iterate over all images in the series. (Note: you can also iterate over the reader object.)

  `request`

    The `Request` object corresponding to the current read/write operation.

  `set_image_index`(index)

    Set the internal pointer such that the next call to get_next_data() returns the image specified by the index

class `imageio.core.format.``Writer`(format, request)

  The purpose of a writer object is to write data to an image resource, and should be obtained by calling `get_writer()`.

  A writer will (if the format permits) write data to the file as soon as new data is provided (i.e. streaming). A writer can also be used as a context manager so that it is automatically closed.

  Plugins implement Writer’s for different formats. Though rare, plugins may provide additional functionality (beyond what is provided by the base writer class).

  `append_data`(im, meta={})

    Append an image (and meta data) to the file. The final meta data that is used consists of the meta data on the given image (if applicable), updated with the given meta data.

  `close`()

    Flush and close the reader/writer. This method has no effect if it is already closed.

  `closed`

    Whether the reader/writer is closed.

  `format`

    The `Format` object corresponding to the current read/write operation.

  `request`

    The `Request` object corresponding to the current read/write operation.

  `set_meta_data`(meta)

    Sets the file’s (global) meta data. The meta data is a dict which shape depends on the format. E.g. for JPEG the dict maps group names to subdicts, and each group is a dict with name-value pairs. The groups represents the different metadata formats (EXIF, XMP, etc.).

    Note that some meta formats may not be supported for writing, and individual fields may be ignored without warning if they are invalid.