Module: `io`¶

Utilities to read and write images in various formats.

The following plug-ins are available:

Plugin	Description
gdal	Image reading via the GDAL Library (www.gdal.org)
tifffile	Load and save TIFF and TIFF-based images using tifffile.py
fits	FITS image reading via PyFITS
imread	Image reading and writing via imread
pil	Image reading via the Python Imaging Library
matplotlib	Display or save images using Matplotlib
imageio	Image reading via the ImageIO Library
simpleitk	Image reading and writing via SimpleITK

`skimage.io.call_plugin`(kind, args, *kwargs)	Find the appropriate plugin of 'kind' and execute it.
`skimage.io.concatenate_images`(ic)	Concatenate all images in the image collection into an array.
`skimage.io.find_available_plugins`([loaded])	List available plugins.
`skimage.io.imread`(fname[, as_gray, plugin])	Load an image from file.
`skimage.io.imread_collection`(load_pattern[, ...])	Load a collection of images.
`skimage.io.imread_collection_wrapper`(imread)
`skimage.io.imsave`(fname, arr[, plugin, ...])	Save an image to file.
`skimage.io.imshow`(arr[, plugin])	Display an image.
`skimage.io.imshow_collection`(ic[, plugin])	Display a collection of images.
`skimage.io.load_sift`(f)	Read SIFT or SURF features from externally generated file.
`skimage.io.load_surf`(f)	Read SIFT or SURF features from externally generated file.
`skimage.io.plugin_info`(plugin)	Return plugin meta-data.
`skimage.io.plugin_order`()	Return the currently preferred plugin order.
`skimage.io.pop`()	Pop an image from the shared image stack.
`skimage.io.push`(img)	Push an image onto the shared image stack.
`skimage.io.reset_plugins`()
`skimage.io.show`()	Display pending images.
`skimage.io.use_plugin`(name[, kind])	Set the default plugin for a specified operation.
`skimage.io.ImageCollection`(load_pattern[, ...])	Load and manage a collection of image files.
`skimage.io.MultiImage`(filename[, ...])	A class containing all frames from multi-frame TIFF images.
`skimage.io.collection`	Data structures to hold collections of images, with optional caching.
`skimage.io.manage_plugins`	Handle image reading, writing and plotting plugins.
`skimage.io.sift`
`skimage.io.util`

call_plugin¶

skimage.io.call_plugin(kind, *args, **kwargs)[source]¶

Find the appropriate plugin of ‘kind’ and execute it.

Parameters:

kind{‘imshow’, ‘imsave’, ‘imread’, ‘imread_collection’}: Function to look up.
pluginstr, optional: Plugin to load. Defaults to None, in which case the first matching plugin is used.
*args, **kwargsarguments and keyword arguments: Passed to the plugin function.

concatenate_images¶

skimage.io.concatenate_images(ic)[source]¶

Concatenate all images in the image collection into an array.

Parameters:

ican iterable of images: The images to be concatenated.

Returns:

array_catndarray: An array having one more dimension than the images in ic.

Raises:

ValueError: If images in ic don’t have identical shapes.

find_available_plugins¶

skimage.io.find_available_plugins(loaded=False)[source]¶

List available plugins.

Parameters:

loadedbool: If True, show only those plugins currently loaded. By default, all plugins are shown.

Returns:

pdict: Dictionary with plugin names as keys and exposed functions as values.

imread¶

skimage.io.imread(fname, as_gray=False, plugin=None, **plugin_args)[source]¶

Load an image from file.

Parameters:

fnamestr or pathlib.Path: Image file name, e.g. test.jpg or URL.
as_graybool, optional: If True, convert color images to gray-scale (64-bit floats). Images that are already in gray-scale format are not converted.
pluginstr, optional: Name of plugin to use. By default, the different plugins are tried (starting with imageio) until a suitable candidate is found. If not given and fname is a tiff file, the tifffile plugin will be used.

Returns:

img_arrayndarray: The different color bands/channels are stored in the third dimension, such that a gray-image is MxN, an RGB-image MxNx3 and an RGBA-image MxNx4.

Other Parameters:

plugin_argskeywords: Passed to the given plugin.

imread_collection¶

skimage.io.imread_collection(load_pattern, conserve_memory=True, plugin=None, **plugin_args)[source]¶

Load a collection of images.

Parameters:

load_patternstr or list: List of objects to load. These are usually filenames, but may vary depending on the currently active plugin. See the docstring for ImageCollection for the default behaviour of this parameter.
conserve_memorybool, optional: If True, never keep more than one in memory at a specific time. Otherwise, images will be cached once they are loaded.

Returns:

icImageCollection: Collection of images.

Other Parameters:

plugin_argskeywords: Passed to the given plugin.

imread_collection_wrapper¶

skimage.io.imread_collection_wrapper(imread)[source]¶

imsave¶

skimage.io.imsave(fname, arr, plugin=None, check_contrast=True, **plugin_args)[source]¶

Save an image to file.

Parameters:

fnamestr or pathlib.Path: Target filename.
arrndarray of shape (M,N) or (M,N,3) or (M,N,4): Image data.
pluginstr, optional: Name of plugin to use. By default, the different plugins are tried (starting with imageio) until a suitable candidate is found. If not given and fname is a tiff file, the tifffile plugin will be used.
check_contrastbool, optional: Check for low contrast and print warning (default: True).

Other Parameters:

plugin_argskeywords: Passed to the given plugin.

Notes

When saving a JPEG, the compression ratio may be controlled using the quality keyword argument which is an integer with values in [1, 100] where 1 is worst quality and smallest file size, and 100 is best quality and largest file size (default 75). This is only available when using the PIL and imageio plugins.

imshow¶

skimage.io.imshow(arr, plugin=None, **plugin_args)[source]¶

Display an image.

Parameters:

arrndarray or str: Image data or name of image file.
pluginstr: Name of plugin to use. By default, the different plugins are tried (starting with imageio) until a suitable candidate is found.

Other Parameters:

plugin_argskeywords: Passed to the given plugin.

Examples using `skimage.io.imshow`¶

RAG Merging

imshow_collection¶

skimage.io.imshow_collection(ic, plugin=None, **plugin_args)[source]¶

Display a collection of images.

Parameters:

icImageCollection: Collection to display.
pluginstr: Name of plugin to use. By default, the different plugins are tried until a suitable candidate is found.

Other Parameters:

plugin_argskeywords: Passed to the given plugin.

load_sift¶

skimage.io.load_sift(f)[source]¶

Read SIFT or SURF features from externally generated file.

This routine reads SIFT or SURF files generated by binary utilities from http://people.cs.ubc.ca/~lowe/keypoints/ and http://www.vision.ee.ethz.ch/~surf/.

This routine does not generate SIFT/SURF features from an image. These algorithms are patent encumbered. Please use skimage.feature.CENSURE instead.

Parameters:

filelikestring or open file: Input file generated by the feature detectors from http://people.cs.ubc.ca/~lowe/keypoints/ or http://www.vision.ee.ethz.ch/~surf/ .
mode{‘SIFT’, ‘SURF’}, optional: Kind of descriptor used to generate filelike.

Returns:

datarecord array with fields

row: int
row position of feature
column: int
column position of feature
scale: float
feature scale
orientation: float
feature orientation
data: array
feature values

load_surf¶

skimage.io.load_surf(f)[source]¶

Read SIFT or SURF features from externally generated file.

This routine reads SIFT or SURF files generated by binary utilities from http://people.cs.ubc.ca/~lowe/keypoints/ and http://www.vision.ee.ethz.ch/~surf/.

This routine does not generate SIFT/SURF features from an image. These algorithms are patent encumbered. Please use skimage.feature.CENSURE instead.

Parameters:

filelikestring or open file: Input file generated by the feature detectors from http://people.cs.ubc.ca/~lowe/keypoints/ or http://www.vision.ee.ethz.ch/~surf/ .
mode{‘SIFT’, ‘SURF’}, optional: Kind of descriptor used to generate filelike.

Returns:

datarecord array with fields

row: int
row position of feature
column: int
column position of feature
scale: float
feature scale
orientation: float
feature orientation
data: array
feature values

plugin_info¶

skimage.io.plugin_info(plugin)[source]¶

Return plugin meta-data.

Parameters:

pluginstr: Name of plugin.

Returns:

mdict: Meta data as specified in plugin .ini.

plugin_order¶

skimage.io.plugin_order()[source]¶

Return the currently preferred plugin order.

Returns:

pdict: Dictionary of preferred plugin order, with function name as key and plugins (in order of preference) as value.

pop¶

skimage.io.pop()[source]¶

Pop an image from the shared image stack.

Returns:

imgndarray: Image popped from the stack.

push¶

skimage.io.push(img)[source]¶

Push an image onto the shared image stack.

Parameters:

imgndarray: Image to push.

reset_plugins¶

skimage.io.reset_plugins()[source]¶

show¶

skimage.io.show()[source]¶

Display pending images.

Launch the event loop of the current gui plugin, and display all pending images, queued via imshow. This is required when using imshow from non-interactive scripts.

A call to show will block execution of code until all windows have been closed.

Examples

>>> import skimage.io as io

>>> rng = np.random.default_rng()
>>> for i in range(4):
...     ax_im = io.imshow(rng.random((50, 50)))
>>> io.show() 

Examples using `skimage.io.show`¶

Region Boundary based RAGs

RAG Merging

use_plugin¶

skimage.io.use_plugin(name, kind=None)[source]¶

Set the default plugin for a specified operation. The plugin will be loaded if it hasn’t been already.

Parameters:

namestr: Name of plugin.
kind{‘imsave’, ‘imread’, ‘imshow’, ‘imread_collection’, ‘imshow_collection’}, optional: Set the plugin for this function. By default, the plugin is set for all functions.

`ImageCollection`¶

class skimage.io.ImageCollection(load_pattern, conserve_memory=True, load_func=None, **load_func_kwargs)[source]¶

Bases: object

Load and manage a collection of image files.

Parameters:

load_patternstr or list of str: Pattern string or list of strings to load. The filename path can be absolute or relative.
conserve_memorybool, optional: If True, ImageCollection does not keep more than one in memory at a specific time. Otherwise, images will be cached once they are loaded.

Other Parameters:

load_funccallable: imread by default. See notes below.

Notes

Note that files are always returned in alphanumerical order. Also note that slicing returns a new ImageCollection, not a view into the data.

ImageCollection can be modified to load images from an arbitrary source by specifying a combination of load_pattern and load_func. For an ImageCollection ic, ic[5] uses load_func(load_pattern[5]) to load the image.

Imagine, for example, an ImageCollection that loads every third frame from a video file:

video_file = 'no_time_for_that_tiny.gif'

def vidread_step(f, step):
    vid = imageio.get_reader(f)
    seq = [v for v in vid.iter_data()]
    return seq[::step]

ic = ImageCollection(video_file, load_func=vidread_step, step=3)

ic  # is an ImageCollection object of length 1 because there is 1 file

x = ic[0]  # calls vidread_step(video_file, step=3)
x[5]  # is the sixth element of a list of length 8 (24 / 3)

Alternatively, if load_func is provided and load_pattern is a sequence, an ImageCollection of corresponding length will be created, and the individual images will be loaded by calling load_func with the matching element of the load_pattern as its first argument. In this case, the elements of the sequence do not need to be names of existing files (or strings at all). For example, to create an ImageCollection containing 500 images from a video:

class vidread_random:
    def __init__ (self, f):
        self.vid = imageio.get_reader(f)
    def __call__ (self, frameno):
        return self.vid.get_data(frameno)
ic = ImageCollection(range(500), load_func=vidread_random('movie.mp4'))

ic  # is an ImageCollection object of length 500

Another use of load_func would be to convert all images to uint8:

def imread_convert(f):
    return imread(f).astype(np.uint8)

ic = ImageCollection('/tmp/*.png', load_func=imread_convert)

Examples

>>> import imageio
>>> import skimage.io as io
>>> from skimage import data_dir

>>> coll = io.ImageCollection(data_dir + '/chess*.png')
>>> len(coll)
2
>>> coll[0].shape
(200, 200)

>>> image_col = io.ImageCollection(['/tmp/work/*.png', '/tmp/other/*.jpg'])

>>> class multiread:
...     def __init__ (self, f):
...         self.vid = imageio.get_reader(f)
...     def __call__ (self, frameno):
...         return self.vid.get_data(frameno)
...
>>> filename = data_dir + '/no_time_for_that_tiny.gif'
>>> image_col = io.ImageCollection(range(24), load_func=multiread(filename))
>>> len(image_col)
24

Attributes:

fileslist of str: If a pattern string is given for load_pattern, this attribute stores the expanded file list. Otherwise, this is equal to load_pattern.

__init__(load_pattern, conserve_memory=True, load_func=None, **load_func_kwargs)[source]¶: Load and manage a collection of images.

concatenate()[source]¶

Concatenate all images in the collection into an array.

Returns:

arnp.ndarray: An array having one more dimension than the images in self.

Raises:

ValueError: If images in the ImageCollection don’t have identical shapes.

`MultiImage`¶

class skimage.io.MultiImage(filename, conserve_memory=True, dtype=None, **imread_kwargs)[source]¶

Bases: ImageCollection

A class containing all frames from multi-frame TIFF images.

Parameters:

load_patternstr or list of str: Pattern glob or filenames to load. The path can be absolute or relative.
conserve_memorybool, optional: Whether to conserve memory by only caching the frames of a single image. Default is True.

Notes

MultiImage returns a list of image-data arrays. In this regard, it is very similar to ImageCollection, but the two differ in their treatment of multi-frame images.

For a TIFF image containing N frames of size WxH, MultiImage stores all frames of that image as a single element of shape (N, W, H) in the list. ImageCollection instead creates N elements of shape (W, H).

For an animated GIF image, MultiImage reads only the first frame, while ImageCollection reads all frames by default.

Examples

>>> from skimage import data_dir

>>> multipage_tiff = data_dir + '/multipage.tif'
>>> multi_img = MultiImage(multipage_tiff)
>>> len(multi_img)  # multi_img contains one element
1
>>> multi_img[0].shape  # this element is a two-frame image of shape:
(2, 15, 10)

>>> image_col = ImageCollection(multipage_tiff)
>>> len(image_col)  # image_col contains two elements
2
>>> for frame in image_col:
...     print(frame.shape)  # each element is a frame of shape (15, 10)
...
(15, 10)
(15, 10)

__init__(filename, conserve_memory=True, dtype=None, **imread_kwargs)[source]¶: Load a multi-img.

property filename¶

Module: io¶

call_plugin¶

concatenate_images¶

find_available_plugins¶

imread¶

imread_collection¶

imread_collection_wrapper¶

imsave¶

imshow¶

Examples using skimage.io.imshow¶

imshow_collection¶

load_sift¶

load_surf¶

plugin_info¶

plugin_order¶

pop¶

push¶

reset_plugins¶

show¶

Examples using skimage.io.show¶

use_plugin¶

ImageCollection¶

MultiImage¶

Module: `io`¶

Examples using `skimage.io.imshow`¶

Examples using `skimage.io.show`¶

`ImageCollection`¶

`MultiImage`¶