Module: io

Utilities to read and write images in various formats.

The following plug-ins are available:

Plugin

Description

imageio

Image reading via the ImageIO Library

qt

Fast image display using the Qt library

imread

Image reading and writing via imread

pil

Image reading via the Python Imaging Library

gdal

Image reading via the GDAL Library (www.gdal.org)

simpleitk

Image reading and writing via SimpleITK

tifffile

Load and save TIFF and TIFF-based images using tifffile.py

fits

FITS image reading via PyFITS

gtk

Fast image display using the GTK library

matplotlib

Display or save images using Matplotlib

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 a single multi-frame image.

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
ic: an iterable of images (including ImageCollection and MultiImage)

The images to be concatenated.

Returns
arnp.ndarray

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

Raises
ValueError

If images in ic don’t have identical shapes.

See also

ImageCollection.concatenate, MultiImage.concatenate

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
fnamestring

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

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

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
>>> for i in range(4):
...     ax_im = io.imshow(np.random.rand(50, 50))
>>> io.show() 

Examples using skimage.io.show

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.

See also

available_plugins

List of available plugins

Examples

To use Matplotlib as the default image reader, you would write:

>>> from skimage import io
>>> io.use_plugin('matplotlib', 'imread')

To see a list of available plugins run io.available_plugins. Note that this lists plugins that are defined, but the full list may not be usable if your system does not have the required libraries installed.

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.

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

Parameters
load_patternstr or list

Pattern glob or filenames to load. The path can be absolute or relative. Multiple patterns should be separated by os.pathsep, e.g. ‘/tmp/work/.png:/tmp/other/.jpg’. Also see implementation notes below.

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.

Other Parameters
load_funccallable

imread by default. See notes below.

Notes

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(file_pattern[5]) to load the image.

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

class AVILoader:
    video_file = 'myvideo.avi'

    def __call__(self, frame):
        return video_read(self.video_file, frame)

avi_load = AVILoader()

frames = range(0, 1000, 10) # 0, 10, 20, ...
ic = ImageCollection(frames, load_func=avi_load)

x = ic[5] # calls avi_load(frames[5]) or equivalently avi_load(50)

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)

For files with multiple images, the images will be flattened into a list and added to the list of available images. In this case, load_func should accept the keyword argument img_num.

Examples

>>> 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)
>>> ic = io.ImageCollection('/tmp/work/*.png:/tmp/other/*.jpg')
Attributes
fileslist of str

If a glob string is given for load_pattern, this attribute stores the expanded file list. Otherwise, this is simply equal to load_pattern.

__init__(self, load_pattern, conserve_memory=True, load_func=None, **load_func_kwargs)[source]

Load and manage a collection of images.

concatenate(self)[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.

property conserve_memory
property files
reload(self, n=None)[source]

Clear the image cache.

Parameters
nNone or int

Clear the cache for this image only. By default, the entire cache is erased.

MultiImage

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

Bases: skimage.io.collection.ImageCollection

A class containing a single multi-frame image.

Parameters
filenamestr

The complete path to the image file.

conserve_memorybool, optional

Whether to conserve memory by only caching a single frame. Default is True.

Notes

If conserve_memory=True the memory footprint can be reduced, however the performance can be affected because frames have to be read from file more often.

The last accessed frame is cached, all other frames will have to be read from file.

The current implementation makes use of tifffile for Tiff files and PIL otherwise.

Examples

>>> from skimage import data_dir
>>> img = MultiImage(data_dir + '/multipage.tif') 
>>> len(img) 
2
>>> for frame in img: 
...     print(frame.shape) 
(15, 10)
(15, 10)
__init__(self, filename, conserve_memory=True, dtype=None, **imread_kwargs)[source]

Load a multi-img.

property filename