Core API v2.9¶

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 backend that does the actual work. To see what keyword arguments are supported by a specific format, use the help() function.

Note

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

imageio.help(name=None)¶

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

Parameters

namestr: 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

Functions for reading¶

`imageio.imread`(uri[, format])	Reads an image from the specified file.
`imageio.mimread`(uri[, format, memtest])	Reads multiple images from the specified file.
`imageio.volread`(uri[, format])	Reads a volume from the specified file.
`imageio.mvolread`(uri[, format, memtest])	Reads multiple volumes from the specified file.

Functions for writing¶

`imageio.imwrite`(uri, im[, format])	Write an image to the specified file.
`imageio.mimwrite`(uri, ims[, format])	Write multiple images to the specified file.
`imageio.volwrite`(uri, vol[, format])	Write a volume to the specified file.
`imageio.mvolwrite`(uri, vols[, format])	Write multiple volumes to the specified file.

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.

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.
formatstr: 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.
formatstr: 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.

property closed¶: Whether the reader/writer is closed.

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

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

property closed¶: Whether the reader/writer is closed.

property format¶: The Format object corresponding to the current read/write operation.

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

API Reference

imageio.imread