LoadImage#

Bases: Feature

Load an image from disk and preprocess it.

LoadImage loads an image file using multiple fallback file readers (ImageIO, NumPy, Pillow, and OpenCV) until a suitable reader is found. The image can be optionally converted to grayscale, reshaped to ensure a minimum number of dimensions, or treated as a list of images if multiple paths are provided.

Parameters#

path: PropertyLike[str | list[str]]: The path(s) to the image(s) to load. Can be a single string or a list of strings.
load_options: PropertyLike[dict[str, Any]], optional: Additional options passed to the file reader. Defaults to None.
as_list: PropertyLike[bool], optional: If True, returns a Python list of loaded images (one per path). Defaults to False.
ndim: PropertyLike[int], optional: Ensures the image has at least this many dimensions. Defaults to 3.
to_grayscale: PropertyLike[bool], optional: If True, converts the image to grayscale. Defaults to False.
get_one_random: PropertyLike[bool], optional: If True, extracts a single random image from a list of loaded images. Only used when as_list is True. Defaults to False.

Attributes#

__distributed__: bool: Set to False, indicating that this feature’s .get() method processes the entire input at once even if it is a list, rather than distributing calls for each item of the list.

Methods#

get(…) -> array or tensor or list of arrays/tensors: Load the image(s) from disk and process them.

Raises#

IOError: If no file reader could parse the file or the file does not exist.

Notes#

By default, LoadImage returns a NumPy array. If you want the output as a PyTorch tensor, convert the feature to torch by calling .torch() before resolving.

Examples#

>>> import deeptrack as dt

Create a temporary image file:

>>> import numpy as np
>>> import os, tempfile
>>>
>>> temp_file = tempfile.NamedTemporaryFile(suffix=".npy", delete=False)
>>> np.save(temp_file.name, np.random.rand(100, 100, 3))

Load the image using LoadImage:

>>> load_image_feature = dt.LoadImage(path=temp_file.name)
>>> loaded_image = load_image_feature()

Print image shape:

>>> loaded_image.shape
(100, 100, 3)

If to_grayscale=True, the image is converted to single channel:

>>> load_image_feature = dt.LoadImage(
...     path=temp_file.name,
...     to_grayscale=True,
... )
>>> loaded_image = load_image_feature()
>>> loaded_image.shape
(100, 100, 1)

If ndim=4, additional dimensions are added if necessary:

>>> load_image_feature = dt.LoadImage(
...     path=temp_file.name,
...     ndim=4,
... )
>>> loaded_image = load_image_feature()
>>> loaded_image.shape
(100, 100, 3, 1)

Load an image as a PyTorch tensor by setting the backend of the feature:

>>> load_image_feature = dt.LoadImage(path=temp_file.name)
>>> load_image_feature.torch()
>>> loaded_image = load_image_feature()
>>> type(loaded_image)
torch.Tensor

Cleanup the temporary file:

>>> os.remove(temp_file.name)

Methods Summary

get(*_, path, load_options, ndim, ...)

Load and process an image or a list of images from disk.

Methods Documentation

Load and process an image or a list of images from disk.

This method attempts to load an image using multiple file readers (ImageIO, NumPy, Pillow, and OpenCV) until a valid format is found. It supports optional processing steps such as ensuring a minimum number of dimensions, grayscale conversion, and treating multi-frame images as lists.

The output is returned as a NumPy array by default. If as_list=True, the result is a Python list of arrays. If the backend of the feature is “torch”, the image is returned as a PyTorch tensor.

Parameters#

path: str or list[str] or tuple[str, …]: The file path(s) to the image(s) to be loaded. A single string loads one image, while a list of paths loads multiple images.
load_options: dict of str to Any, optional: Additional options passed to the file reader (e.g., allow_pickle for NumPy, mode for OpenCV). Defaults to None.
ndim: int: Ensures the image has at least this many dimensions. If the loaded image has fewer dimensions, extra dimensions are added. Defaults to 3.
to_grayscale: bool: If True, converts the image to grayscale. Defaults to False.
as_list: bool: If True, returns a Python list of loaded images (one per path). Defaults to False.
get_one_random: bool: If True, selects a single random image from a list of loaded images when as_list=True. Defaults to False.
**kwargs: Any: Additional keyword arguments.

Returns#

array or list of arrays: The loaded and processed image(s). If as_list=True, returns a list of images; otherwise, returns a single NumPy array or PyTorch tensor.

Raises#

IOError: If no valid file reader is found or if the specified file does not exist.