io
Module: io
Utilities to read and write images in various formats.
The following plug-ins are available:
Plugin | Description |
pil | Image reading via the Python Imaging 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 |
imread | Image reading and writing via imread |
imageio | Image reading via the ImageIO Library |
fits | FITS image reading via PyFITS |
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: 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: 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.See also
ImageCollection.concatenate
,MultiImage.concatenate
find_available_plugins
-
skimage.io.find_available_plugins(loaded=False)
[source] -
List available plugins.
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.
imread
-
skimage.io.imread(fname, as_grey=False, plugin=None, flatten=None, **plugin_args)
[source] -
Load an image from file.
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.
imread_collection
-
skimage.io.imread_collection(load_pattern, conserve_memory=True, plugin=None, **plugin_args)
[source] -
Load a collection of images.
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.
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: 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: 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: 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: 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: 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: 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: 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: img : ndarray
Image popped from the stack.
push
-
skimage.io.push(img)
[source] -
Push an image onto the shared image stack.
Parameters: 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 usingimshow
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: 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.
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_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
andload_func
. For an ImageCollectionic
,ic[5]
usesload_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 touint8
: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 argumentimg_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 toload_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: 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.See also
-
conserve_memory
-
files
-
reload(n=None)
[source] -
Clear the image cache.
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: 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.
-
filename
-
© 2011 the scikit-image team
Licensed under the BSD 3-clause License.
http://scikit-image.org/docs/0.12.x/api/skimage.io.html