FileCollection#

class FileCollection(filename: str | None = None, loop: bool = False, **kwargs: Any)[source]#

Iterate images from a collection of files

Parameters:

  • filename (str) – wildcard path to image files

  • loop (bool, optional) – Endlessly loop over the files, defaults to False

  • kwargs – options applied to image frames, see convert

The resulting object is an iterator over the image files that match the wildcard description. The iterator returns Image objects where the name attribute is the name of the image file.

Eager mode (default): All images are decoded at construction time. This makes random access (files[i]), slicing, and len(files) fast but can be slow and memory-intensive for large collections.

from machinevisiontoolbox import FileCollection
images = FileCollection('campus/*.png')
len(images)                      # fast
img = images[5]                  # fast, in-memory
for image in images:             # iterate in-memory
    pass

Lazy mode (via context manager): Files are decoded on-demand during iteration. This avoids the startup cost of decoding all images upfront. Trade-off: random access (__getitem__) is not available; use only for sequential iteration.

from machinevisiontoolbox import FileCollection
with FileCollection('campus/*.png') as images:
    for image in images:         # decode on-demand
        pass

If the path is not absolute, the file is first searched for relative to the current directory, and if not found, it is searched for in the images folder of the mvtb-data package, installed as a Toolbox dependency.

Example:

from machinevisiontoolbox import FileCollection
images = FileCollection('campus/*.png')
len(images)
for image in images:  # iterate over images
    # do a thing

alternatively:

img = files[i]  # load i'th file from the collection

or using a context manager for memory-efficient streaming:

with FileCollection('campus/*.png') as images:
    for image in images:
        # process image
References:
Seealso:

convert cv2.imread

Base constructor for image sources.

Parameters:

kwargs (Any) – source-specific keyword arguments

Methods

disp

Display images from the source interactively.

tensor

Convert all images from this source into a single 4D PyTorch tensor.

Attributes

args

i

images

loop

names