LoadImage

class deeptrack.features.LoadImage(path: PropertyLike[str | list[str]], load_options: PropertyLike[dict] = None, as_list: PropertyLike[bool] = False, ndim: PropertyLike[int] = 3, to_grayscale: PropertyLike[bool] = False, get_one_random: PropertyLike[bool] = False, **kwargs: dict[str, Any])

Bases: Feature

Load an image from disk and preprocess it.

This feature 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 or 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, the first dimension of the image will be treated as a list. 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 stack of images. Only used when as_list is True. Defaults to False.

Attributes

__distributed__: bool

Indicates whether this feature distributes computation across inputs.

Methods

get(image: Any, path: str | list[str], load_options: dict[str, Any] | None, ndim: int, to_grayscale: bool, as_list: bool, get_one_random: bool, **kwargs: dict[str, Any]) -> np.ndarray

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.

Examples

>>> import deeptrack as dt
>>> import numpy as np
>>> from tempfile import NamedTemporaryFile

Create a temporary image file: >>> temp_file = NamedTemporaryFile(suffix=”.npy”, delete=False) >>> np.save(temp_file.name, np.random.rand(100, 100))

Load the image using LoadImage: >>> load_image_feature = dt.LoadImage(path=temp_file.name, to_grayscale=True) >>> loaded_image = load_image_feature.resolve()

Print image shape: >>> print(loaded_image.shape)

If to_grayscale=True, the image is converted to grayscale (single channel). If ndim=4, additional dimensions are added if necessary.

Cleanup the temporary file: >>> import os >>> os.remove(temp_file.name)

Methods Summary

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

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

Methods Documentation

get(*ign: Any, path: str | list[str], load_options: dict[str, Any] | None, ndim: int, to_grayscale: bool, as_list: bool, get_one_random: bool, **kwargs: dict[str, Any]) → np.ndarray

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.

Parameters

path: str or list of 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.

to_grayscale: bool

If True, converts the image to grayscale. Defaults to False.

as_list: bool

If True, treats the first dimension as a list of images instead of stacking them into a NumPy array.

get_one_random: bool

If True, selects a single random image from a multi-frame stack when as_list=True. Defaults to False.

**kwargs: dict[str, Any]

Additional keyword arguments.

Returns

np.ndarray

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

Raises

IOError

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