skimage2.io.ImageCollection#

class skimage2.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, skimage.io.ImageCollection does not keep more than one in memory at a specific time. Otherwise, images will be cached once they are loaded.

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.

Other Parameters:

load_funccallable: imread by default. See Notes below.
**load_func_kwargsdict: Any other keyword arguments are passed to load_func.

Notes

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

ImageCollection image loading can be customized through load_func. For an ImageCollection ic, ic[5] calls load_func(load_pattern[5]) to load that image.

For example, here is an ImageCollection that, for each video provided, loads every second frame:

import imageio.v3 as iio3
import itertools

def vidread_step(f, step):
    vid = iio3.imiter(f)
    return list(itertools.islice(vid, None, None, step)

video_file = 'no_time_for_that_tiny.gif'
ic = ImageCollection(video_file, load_func=vidread_step, step=2)

ic  # is an ImageCollection object of length 1 because 1 video is provided

x = ic[0]
x[5]  # the 10th frame of the first video

Alternatively, if load_func is provided and load_pattern is a sequence, an skimage.io.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 skimage.io.ImageCollection containing 500 images from a video:

class FrameReader:
    def __init__ (self, f):
        self.f = f
    def __call__ (self, index):
        return iio3.imread(self.f, index=index)

ic = ImageCollection(range(500), load_func=FrameReader('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

>>> from pathlib import Path
>>> import imageio.v3 as iio3
>>> import _skimage2.io as io
>>> from _skimage2 import data

# Where your images are located >>> data_dir = Path(data.__file__).parent

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

>>> image_col = io.ImageCollection([f'{data_dir}/*.png', '{data_dir}/*.jpg'])

>>> class MultiReader:
...     def __init__ (self, f):
...         self.f = f
...     def __call__ (self, index):
...         return iio3.imread(self.f, index=index)
...
>>> filename = data_dir / 'no_time_for_that_tiny.gif'
>>> ic = io.ImageCollection(range(24), load_func=MultiReader(filename))
>>> len(ic)
24
>>> isinstance(ic[0], np.ndarray)
True

__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 skimage.io.ImageCollection do not have identical shapes.