deeptrack.image Module

Image class and relative functions.

This module defines the Image class and related utility functions for managing array-like structures and their associated properties. The Image class is central to DeepTrack2, acting as a container for numerical data (such as images, tensors, and scalars) while maintaining the properties generated by features during pipeline processing.

Key Features

• Enhanced Array-Like Interface

  The Image class provides an interface similar to NumPy arrays, enabling mathematical operations, slicing, and indexing, while preserving additional metadata as properties.

• Property Management

  Image objects store properties that describe the transformations and features applied during their creation, ensuring traceability and enabling advanced functionality.

• Interoperability

  Includes seamless integration with NumPy, CuPy, and PyTorch arrays, allowing for GPU acceleration and deep learning compatibility.

• Utility Functions

  Includes helper functions (coerce, strip, etc.) for managing and manipulating Image objects efficiently within pipelines.

Module Structure

Classes:

• Image: Core class for managing array-like data and their properties.

Utility Functions:

• def strip(element)

  def strip(

  element: Union[Image, List, Tuple, Any],

  ) -> Any

  Recursively extract the underlying value from an Image object.

• coerce(images)

  coerce(

  images: List[Union[Image, np.ndarray]],

  ) -> List[Image]

  Coerce a list of images to a consistent type.

• pad_image_to_fft(image, axes)

  pad_image_to_fft(

  image: Union[Image, np.ndarray], axes: Iterable[int] = (0, 1),

  ) -> Union[Image, np.ndarray]

  Pads an image to optimize Fast Fourier Transform (FFT) performance.

• maybe_cupy(array)

  maybe_cupy(

  array: Union[np.ndarray, List, Tuple],

  ) -> Union[‘cupy.ndarray’, np.ndarray]

  Convert an array to a CuPy array if GPU is available and enabled.

Examples

Basic usage of the Image class:

>>> import numpy as np
>>> from deeptrack.image import Image

>>> img = Image(np.array([[1, 2], [3, 4]]))
>>> print(img + 1)
Image([[2, 3],
       [4, 5]])

Property tracking:

>>> from deeptrack.properties import Property

>>> img.append({"feature": "example", "value": 42})
>>> print(img.properties)
[{'feature': 'example', 'value': 42}]

Functions

coerce(images)	Coerce a list of images to a consistent type.
maybe_cupy(array)	Convert an array to a CuPy array if GPU is available and enabled.
pad_image_to_fft(image[, axes])	Pads an image to optimize Fast Fourier Transform (FFT) performance.
strip(element)	Recursively extract the underlying value from an Image object.

Classes

Image(value[, copy])	Wrapper for array-like values with property tracking.
Property(sampling_rule, **kwargs)	Property of a feature in the DeepTrack2 framework.