Module: io
¶
Utilities to read and write images in various formats.
The following plug-ins are available:
Plugin |
Description |
tifffile |
Load and save TIFF and TIFF-based images using tifffile.py |
imread |
Image reading and writing via imread |
qt |
Fast image display using the Qt library. Deprecated since 0.18. Will be removed in 0.20. |
pil |
Image reading via the Python Imaging Library |
gtk |
Fast image display using the GTK library |
simpleitk |
Image reading and writing via SimpleITK |
gdal |
Image reading via the GDAL Library (www.gdal.org) |
matplotlib |
Display or save images using Matplotlib |
fits |
FITS image reading via PyFITS |
imageio |
Image reading via the ImageIO Library |
|
Find the appropriate plugin of 'kind' and execute it. |
Concatenate all images in the image collection into an array. |
|
|
List available plugins. |
|
Load an image from file. |
|
Load a collection of images. |
|
Save an image to file. |
|
Display an image. |
|
Display a collection of images. |
Read SIFT or SURF features from externally generated file. |
|
Read SIFT or SURF features from externally generated file. |
|
|
Return plugin meta-data. |
Return the currently preferred plugin order. |
|
Pop an image from the shared image stack. |
|
|
Push an image onto the shared image stack. |
Display pending images. |
|
|
Set the default plugin for a specified operation. |
|
Load and manage a collection of image files. |
|
A class containing all frames from multi-frame images. |
|
Data structures to hold collections of images, with optional caching. |
|
Handle image reading, writing and plotting plugins. |
|
|
|
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.
See also
ImageCollection.concatenate
,MultiImage.concatenate
Notes
concatenate_images
receives any iterable object containing images, including ImageCollection and MultiImage, and returns a NumPy array.
find_available_plugins¶
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¶
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¶
plugin_order¶
pop¶
push¶
reset_plugins¶
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()
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.
- 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]
usesload_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)
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)
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 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.
See also
- property conserve_memory¶
- property files¶
MultiImage
¶
- class skimage.io.MultiImage(filename, conserve_memory=True, dtype=None, **imread_kwargs)[source]¶
Bases:
skimage.io.collection.ImageCollection
A class containing all frames from multi-frame 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 a single frame. Default is True.
- Other Parameters
- load_funccallable
imread
by default. See notes below.
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)
- property filename¶