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
freeimage	Load images using the FreeImage library
gtk	Fast image display using the GTK library
matplotlib	Display or save images using Matplotlib
simpleitk	Image reading and writing via SimpleITK
fits	FITS image reading via PyFITS
pil	Image reading via the Python Imaging Library
imread	Image reading and writing via imread
tifffile	Load and save TIFF and TIFF-based images using tifffile.py
gdal	Image reading via the GDAL Library (www.gdal.org)

`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_grey, 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 a file.
`skimage.io.load_surf`(f)	Read SIFT or SURF features from a 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.

call_plugin¶

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

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

Parameters:

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

kind : {‘imshow’, ‘imsave’, ‘imread’, ‘imread_collection’}

Function to look up.

plugin : str, optional

Plugin to load. Defaults to None, in which case the first matching plugin is used.

*args, **kwargs : arguments 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:

Parameters:	ic: an iterable of images (including ImageCollection and MultiImage) The images to be concatenated.
Returns:	ar : np.ndarray An array having one more dimension than the images in ic.
Raises:	ValueError If images in ic don’t have identical shapes.

ic: an iterable of images (including ImageCollection and MultiImage)

The images to be concatenated.

Returns:

ar : np.ndarray

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:

Parameters:	loaded : bool If True, show only those plugins currently loaded. By default, all plugins are shown.
Returns:	p : dict Dictionary with plugin names as keys and exposed functions as values.

loaded : bool

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

Returns:

p : dict

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

imread¶

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

Load an image from file.

Parameters:

Parameters:	fname : string Image file name, e.g. `test.jpg` or URL. as_grey : bool If True, convert color images to grey-scale (32-bit floats). Images that are already in grey-scale format are not converted. plugin : str Name of plugin to use. By default, the different plugins are tried (starting with the Python Imaging Library) until a suitable candidate is found. If not given and fname is a tiff file, the tifffile plugin will be used.
Returns:	img_array : ndarray The different colour bands/channels are stored in the third dimension, such that a grey-image is MxN, an RGB-image MxNx3 and an RGBA-image MxNx4.
Other Parameters:
	plugin_args : keywords Passed to the given plugin.

fname : string

Image file name, e.g. test.jpg or URL.

as_grey : bool

If True, convert color images to grey-scale (32-bit floats). Images that are already in grey-scale format are not converted.

plugin : str

Name of plugin to use. By default, the different plugins are tried (starting with the Python Imaging Library) until a suitable candidate is found. If not given and fname is a tiff file, the tifffile plugin will be used.

Returns:

img_array : ndarray

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

Other Parameters:

plugin_args : keywords

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:

Parameters:	load_pattern : str 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_memory : bool, optional If True, never keep more than one in memory at a specific time. Otherwise, images will be cached once they are loaded.
Returns:	ic : ImageCollection Collection of images.
Other Parameters:
	plugin_args : keywords Passed to the given plugin.

load_pattern : str 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_memory : bool, optional

If True, never keep more than one in memory at a specific time. Otherwise, images will be cached once they are loaded.

Returns:

ic : ImageCollection

Collection of images.

Other Parameters:

plugin_args : keywords

Passed to the given plugin.

imread_collection_wrapper¶

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

imsave¶

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

Save an image to file.

Parameters:

Parameters:	fname : str Target filename. arr : ndarray of shape (M,N) or (M,N,3) or (M,N,4) Image data. plugin : str Name of plugin to use. By default, the different plugins are tried (starting with the Python Imaging Library) until a suitable candidate is found. If not given and fname is a tiff file, the tifffile plugin will be used.
Other Parameters:
	plugin_args : keywords Passed to the given plugin.

fname : str

Target filename.

arr : ndarray of shape (M,N) or (M,N,3) or (M,N,4)

Image data.

plugin : str

Name of plugin to use. By default, the different plugins are tried (starting with the Python Imaging Library) until a suitable candidate is found. If not given and fname is a tiff file, the tifffile plugin will be used.

Other Parameters:

plugin_args : keywords

Passed to the given plugin.

imshow¶

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

Display an image.

Parameters:

Parameters:	arr : ndarray or str Image data or name of image file. plugin : str Name of plugin to use. By default, the different plugins are tried (starting with the Python Imaging Library) until a suitable candidate is found.
Other Parameters:
	plugin_args : keywords Passed to the given plugin.

arr : ndarray or str

Image data or name of image file.

plugin : str

Name of plugin to use. By default, the different plugins are tried (starting with the Python Imaging Library) until a suitable candidate is found.

Other Parameters:

plugin_args : keywords

Passed to the given plugin.

imshow_collection¶

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

Display a collection of images.

Parameters:

Parameters:	ic : ImageCollection Collection to display. plugin : str Name of plugin to use. By default, the different plugins are tried until a suitable candidate is found.
Other Parameters:
	plugin_args : keywords Passed to the given plugin.

ic : ImageCollection

Collection to display.

plugin : str

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

Other Parameters:

plugin_args : keywords

Passed to the given plugin.

load_sift¶

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

Read SIFT or SURF features from a file.

Parameters:

Parameters:	f : string 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/
Returns:	data : record 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

f : string 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/

Returns:

data : record 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 a file.

Parameters:

Parameters:	f : string 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/
Returns:	data : record 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

f : string 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/

Returns:

data : record 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:

Parameters:	plugin : str Name of plugin.
Returns:	m : dict Meta data as specified in plugin `.ini`.

plugin : str

Name of plugin.

Returns:

m : dict

Meta data as specified in plugin .ini.

plugin_order¶

skimage.io.plugin_order()[source]¶

Return the currently preferred plugin order.

Returns:

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

p : dict

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:

Returns:	img : ndarray Image popped from the stack.

img : ndarray

Image popped from the stack.

push¶

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

Push an image onto the shared image stack.

Parameters:

Parameters:	img : ndarray Image to push.

img : ndarray

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

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:

Parameters:	name : str 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.

name : str

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.

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

Parameters:

Parameters:	load_pattern : str 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_memory : bool, 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_func : callable `imread` by default. See notes below.

load_pattern : str 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_memory : bool, 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_func : callable

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

files

(list 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__(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:

Returns:	ar : np.ndarray An array having one more dimension than the images in self.
Raises:	ValueError If images in the ImageCollection don’t have identical shapes.

ar : np.ndarray

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

Raises:

ValueError

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

Parameters:	n : None 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:

Parameters:	filename : str The complete path to the image file. conserve_memory : bool, optional Whether to conserve memory by only caching a single frame. Default is True.

filename : str

The complete path to the image file.

conserve_memory : bool, 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__(filename, conserve_memory=True, dtype=None, **imread_kwargs)[source]¶: Load a multi-img.

Module: `io`¶

call_plugin¶

concatenate_images¶

find_available_plugins¶

imread¶

imread_collection¶

imread_collection_wrapper¶

imsave¶

imshow¶

imshow_collection¶

load_sift¶

load_surf¶

plugin_info¶

plugin_order¶

pop¶

push¶

reset_plugins¶

show¶

use_plugin¶

`ImageCollection`¶

`MultiImage`¶

Navigation

Previous topic

Next topic

Contents

Versions

Module: io¶

call_plugin¶

concatenate_images¶

find_available_plugins¶

imread¶

imread_collection¶

imread_collection_wrapper¶

imsave¶

imshow¶

imshow_collection¶

load_sift¶

load_surf¶

plugin_info¶

plugin_order¶

pop¶

push¶

reset_plugins¶

show¶

use_plugin¶

ImageCollection¶

MultiImage¶

Navigation

Previous topic

Next topic

Contents

Versions

Module: `io`¶

`ImageCollection`¶

`MultiImage`¶