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.


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.


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(self)

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, bytes, file}

The resource to load the image from, e.g. a filename, 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, file}

The resource to write the image to, e.g. a filename 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, bytes, file}

The resource to load the images from, e.g. a filename, 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, file}

The resource to write the images to, e.g. a filename 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, bytes, file}

The resource to load the volume from, e.g. a filename, 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, file}

The resource to write the image to, e.g. a filename 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, bytes, file}

The resource to load the volumes from, e.g. a filename, 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, file}

The resource to write the volumes to, e.g. a filename 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, bytes, file}

The resource to load the image from, e.g. a filename, 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, file}

The resource to write the image to, e.g. a filename 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.

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.