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="256MB", **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, int, float, str}

If truthy, this function will raise an error if the resulting list of images consumes greater than the amount of memory specified. This is to protect the system from using so much memory that it needs to resort to swapping, and thereby stall the computer. E.g. mimread('hunger_games.avi').

If the argument is a number, that will be used as the threshold number of bytes.

If the argument is a string, it will be interpreted as a number of bytes with SI/IEC prefixed units (e.g. ‘1kB’, ‘250MiB’, ‘80.3YB’).

Units are case sensitive
k, M etc. represent a 1000-fold change, where Ki, Mi etc. represent 1024-fold
The “B” is optional, but if present, must be capitalised

If the argument is True, the default will be used, for compatibility reasons.

Default: ‘256MB’

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='1GB', **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, int, float, str}

If truthy, this function will raise an error if the resulting list of images consumes greater than the amount of memory specified. This is to protect the system from using so much memory that it needs to resort to swapping, and thereby stall the computer. E.g. mimread('hunger_games.avi').

If the argument is a number, that will be used as the threshold number of bytes.

If the argument is a string, it will be interpreted as a number of bytes with SI/IEC prefixed units (e.g. ‘1kB’, ‘250MiB’, ‘80.3YB’).

Units are case sensitive
k, M etc. represent a 1000-fold change, where Ki, Mi etc. represent 1024-fold
The “B” is optional, but if present, must be capitalised

If the argument is True, the default will be used, for compatibility reasons.

Default: ‘1GB’

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).

Attributes:	`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.

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. Raises IndexError if the index is out of range.

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).

Attributes:	`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.

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.