image.py

"""Containers for array-like structures.

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.

Key Classes
-----------
- `Image`: Core class for managing array-like data and their properties.

    Encapsulates array-like data structures (e.g., NumPy arrays, lists, 
    Torch tensors) while providing a unified interface for array operations and
    property management.

Methods
-------
- `strip(element)`

    strip(
        element: Image | np.ndarray | list | tuple | Any,
    ) -> Any
    
    Recursively extract the underlying value from an Image object.

- `coerce(images)`

    coerce(
        images: list[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: Image | np.ndarray,
        axes: Iterable[int] = (0, 1),
    ) -> Image | np.ndarray
    
    Pads an image to optimize Fast Fourier Transform (FFT) performance.

- `maybe_cupy(array)`

    maybe_cupy(
        array: np.ndarray | list | tuple,
    ) -> 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}]

"""

from __future__ import annotations
import operator as ops
from typing import Any, Callable, Iterable

import numpy as np

from deeptrack.backend._config import cupy
from deeptrack.properties import Property
from deeptrack.types import NumberLike


def _binary_method(
    op: Callable[[NumberLike, NumberLike], NumberLike],
) -> Callable[[Image, Image | NumberLike], Image]:
    """Implement a binary operator for the Image class.

    This function generates a binary method (e.g., `__add__`, `__sub__`) for
    the `Image` class, enabling operations like addition, subtraction, or
    comparison between `Image` objects or between an `Image` object and a
    scalar/array. It operates between the operands `self`and `other`.

    The resulting method applies the specified operator (`op`) to the `_value`
    attribute of the `Image` object, preserving the `Image` structure and its
    properties.

    If the `other` operand is also an `Image` object, the resulting `Image`
    merges the properties of both operands.

    If the `other` operand is not an `Image`, it is treated as a scalar or
    array, and only the properties of `self` are preserved in the resulting
    `Image`.

    Parameters
    ----------
    op: Callable[[NumberLike, NumberLike], NumberLike]
        The operator function (e.g., `operator.add`, `operator.sub`) that 
        defines the binary operation.

    Returns
    -------
    Callable[[Image, Image | NumberLike], Image]
        A method that can be assigned to a binary operator (e.g., `__add__`) 
        of the `Image` class.

    Examples
    --------
    >>> import operator
    >>> import numpy as np
    >>> from deeptrack.image import _binary_method, Image

    Define __add__ for the Image class:
    
    >>> Image.__add__ = _binary_method(operator.add)

    Create two images and add them:

    >>> img1 = Image(np.array([1, 2, 3]))
    >>> img2 = Image(np.array([4, 5, 6]))
    >>> result = img1 + img2
    >>> print(result)
    Image(array([5, 7, 9]))

    Add a scalar to an Image:

    >>> result = img1 + 10
    >>> print(result)
    Image(array([11, 12, 13]))

    """

    def func(
        self: Image | np.ndarray,
        other: Image | np.ndarray | NumberLike,
    ) -> Image:

        # Coerce inputs to compatible types.
        self, other = coerce([self, other])

        if isinstance(other, Image):
            # Perform operation and merge properties from both Images.
            return Image(
                op(self._value, other._value),
                copy=False,
            ).merge_properties_from([self, other])
        else:
            # Perform operation and retain properties from `self`.
            return Image(
                op(self._value, other),
                copy=False,
            ).merge_properties_from(self)

    func.__name__ = f"__{op.__name__}__"

    return func


def _reflected_binary_method(
    op: Callable[[NumberLike, NumberLike], NumberLike],
) -> Callable[[Image | NumberLike, Image], Image]:
    """Implement a reflected binary operator for the Image class.

    This function generates a reflected binary method (e.g., `__radd__`,
    `__rsub__`) for the `Image` class, enabling operations like reverse
    addition or subtraction between an `Image` object and another operand
    (scalar, array, or `Image`). This method is invoked when the left-hand
    operand does not implement the operation for the provided types.

    The resulting method applies the specified operator (`op`) in reverse
    order, where the `other` operand is treated as the left-hand operand and
    `self` is treated as the right-hand operand.

    If the `other` operand is also an `Image` object, the resulting `Image` 
    merges the properties of both operands.

    If the `other` operand is not an `Image`, it is treated as a scalar or
    array, and only the properties of `self` are preserved in the resulting
    `Image`.

    Parameters
    ----------
    op: Callable[[NumberLike, NumberLike], NumberLike]
        The operator function (e.g., `operator.add`, `operator.sub`) that 
        defines the reflected binary operation.

    Returns
    -------
    Callable[[Image, Image | NumberLike], Image]
        A method that can be assigned to a reflected binary operator (e.g.,
        `__radd__`) of the `Image` class.

    Examples
    --------
    >>> import operator
    >>> import numpy as np
    >>> from deeptrack.image import _reflected_binary_method, Image

    Define __radd__ for the Image class:

    >>> Image.__radd__ = _reflected_binary_method(operator.add)

    Add an Image to a scalar (reflected operation):

    >>> img = Image(np.array([1, 2, 3]))
    >>> result = 10 + img
    >>> print(result)
    Image(array([11, 12, 13]))

    Add two Images (reflected operation):

    >>> img2 = Image(np.array([4, 5, 6]))
    >>> result = img2 + img
    >>> print(result)
    Image(array([5, 7, 9]))

    """

    def func(
        self: Image | np.ndarray,
        other: Image | np.ndarray | NumberLike,
    ) -> Image:

        # Coerce inputs to compatible types.
        self, other = coerce([self, other])

        if isinstance(other, Image):
            # Perform operation and merge properties from both Images.
            return Image(
                op(other._value, self._value),
                copy=False,
            ).merge_properties_from([other, self])
        else:
            # Perform operation and retain properties from `self`.
            return Image(
                op(other, self._value),
                copy=False,
            ).merge_properties_from(self)

    func.__name__ = f"__r{op.__name__}__"

    return func


def _inplace_binary_method(
    op: Callable[[NumberLike, NumberLike], NumberLike]
) -> Callable[[Image, Image | NumberLike], Image]:
    """Implement an in-place binary operator for the Image class.

    This function generates an in-place binary method (e.g., `__iadd__`,
    `__imul__`) for the `Image` class, enabling operations like in-place
    addition, multiplication, or other modifications to an `Image` object. The
    operation updates the `_value` of the current `Image` instance (`self`)
    rather than creating a new one.

    The resulting method applies the specified operator (`op`) to the `_value`
    attribute of the `Image` object, preserving the `Image` structure and its
    properties.

    If the `other` operand is also an `Image` object, the properties of `other`
    are merged into `self`.

    Parameters
    ----------
    op: Callable[[NumberLike, NumberLike], NumberLike]
        The operator function (e.g., `operator.iadd`, `operator.imul`) that 
        defines the in-place binary operation.

    Returns
    -------
    Callable[[Image, Image | NumberLike], None]
        A method that can be assigned to an in-place binary operator (e.g.,
        `__iadd__`) of the `Image` class.

    Examples
    --------
    >>> import operator
    >>> import numpy as np
    >>> from deeptrack.image import _inplace_binary_method, Image

    Define __iadd__ for the Image class:
    
    >>> Image.__iadd__ = _inplace_binary_method(operator.iadd)

    Create two images and perform in-place addition:

    >>> img1 = Image(np.array([1, 2, 3]))
    >>> img2 = Image(np.array([4, 5, 6]))
    >>> img1 += img2
    >>> print(img1)
    Image(array([5, 7, 9]))

    Add a scalar to an Image in-place:

    >>> img1 += 10
    >>> print(img1)
    Image(array([15, 17, 19]))

    """

    def func(
        self: Image | np.ndarray,
        other: Image | np.ndarray | NumberLike,
    ) -> Image:

        # Coerce inputs to compatible types.
        self, other = coerce([self, other])

        if isinstance(other, Image):
            # Perform in-place operation and merge properties from `other`.
            self._value = op(self._value, other._value)
            self.merge_properties_from(other)
        else:
            # Perform in-place operation without merging properties.
            self._value = op(self._value, other)

        return self

    func.__name__ = f"__i{op.__name__}__"

    return func


def _numeric_methods(
    op: Callable[[NumberLike, NumberLike], NumberLike],
) -> tuple[
    Callable[[Image, Image | NumberLike], Image],
    Callable[[Image | NumberLike, Image], Image],
    Callable[[Image, Image | NumberLike], Image]
]:
    """Generate forward, reflected, and in-place binary methods.

    This utility function returns a tuple of three methods that implement
    forward (e.g., `__add__`), reflected (e.g., `__radd__`), and in-place
    (e.g., `__iadd__`) binary operations for a given numeric operator.

    These methods are generated using `_binary_method`,
    `_reflected_binary_method`, and `_inplace_binary_method` respectively,
    which handle the specific semantics of each type of operation.

    Parameters
    ----------
    op: Callable[[NumberLike, NumberLike], NumberLike]
        A callable representing the numeric operator (e.g., `operator.add`, 
        `operator.mul`) to implement the methods for.

    Returns
    -------
    tuple[
        Callable[[Image, Image | NumberLike], Image],
        Callable[[Image | NumberLike, Image], Image],
        Callable[[Image, Image | NumberLike], Image]
    ]
        A tuple containing three callables:
        (1) The forward binary method (`_binary_method`).
        (2) The reflected binary method (`_reflected_binary_method`).
        (3) The in-place binary method (`_inplace_binary_method`).

    Examples
    --------
    >>> import operator
    >>> from deeptrack.image import _numeric_methods, Image

    Define addition methods for the Image class:

    >>> Image.__add__, Image.__radd__, Image.__iadd__ = \
    ...     _numeric_methods(operator.add)

    Perform forward, reflected, and in-place addition:

    >>> img1 = Image([1, 2, 3])
    >>> img2 = Image([4, 5, 6])

    Forward addition:
    >>> result = img1 + img2
    >>> print(result)
    Image(array([5, 7, 9]))

    Reflected addition:
    >>> result = [10, 20, 30] + img1
    >>> print(result)
    Image(array([11, 22, 33]))

    In-place addition:
    >>> img1 += img2
    >>> print(img1)
    Image(array([5, 7, 9]))

    """

    return (
        _binary_method(op),
        _reflected_binary_method(op),
        _inplace_binary_method(op),
    )


def _unary_method(
    op: Callable[[NumberLike], NumberLike],
) -> Callable[[Image], Image]:
    """Implement a unary special method for the Image class.

    This function generates a unary method (e.g., `__neg__`, `__abs__`) for
    the `Image` class. It applies the specified unary operator (`op`) to the
    `_value` attribute of the `Image` instance while preserving the `Image`
    structure and its properties.

    Parameters
    ----------
    op: Callable[[NumberLike], NumberLike]
        A callable representing the unary operation (e.g., `operator.neg`, 
        `operator.abs`).

    Returns
    -------
    Callable[[Image], Image]
        A method that can be assigned to a unary operator (e.g., `__neg__`) 
        of the `Image` class.

    Examples
    --------
    >>> import operator
    >>> import numpy as np
    >>> from deeptrack.image import _unary_method, Image

    Define negation for the Image class:

    >>> Image.__neg__ = _unary_method(operator.neg)

    Create an image and apply negation:

    >>> img = Image(np.array([1, 2, 3]))
    >>> result = -img
    >>> print(result)
    Image(array([-1, -2, -3]))

    """

    def func(
        self: Image | np.ndarray,
    ) -> Image:

        # Apply the unary operator to the Image instance.
        return Image(
            op(self._value)
        ).merge_properties_from(self)

    func.__name__ = f"__{op}__"

    return func


class Image:
    """Wrapper for array-like values with property tracking.

    This class encapsulates array-like values (e.g., NumPy arrays, lists, 
    tensors) while providing a unified interface for array operations and
    property management.
    
    It serves two primary purposes:

    1. **Unified Interface**

        Offers compatibility with NumPy and CuPy operations regardless of the
        underlying data type. This allows for seamless integration with NumPy
        functions and universal function calls (`ufuncs`).

    2. **Property Tracking**

        Stores and manages properties associated with features used in creating
        or modifying the image. This makes it possible to track metadata and
        ensure consistency across operations.

    Attributes
    ----------
    _value: np.ndarray
        The underlying data stored in the Image object as NumPy.
    properties: list[dict[str, Property]]
        A list of property dictionaries associated with the Image.

    Parameters
    ----------
    value: np.ndarray | list | int | float | bool | Image
        The array-like object to be converted to a NumPy array and stored in 
        the Image object. If it is an Image, the value and properties of the 
        image are copied or referenced depening on the value of the `copy` 
        parameter.
    copy: bool, optional
        If `True`, the `value` is copied to ensure independence (default).
        If `False`, a reference to the original value is maintained.

    Methods
    -------
    **Property Management**
    
    `append(
        property_dict: dict
    ) -> Image`
        Add a dictionary of properties to the `Image`.

    `get_property(
        key: str,
        get_one: bool = True,
        default: Any = None
    ) -> Any | list[Any]`
        Retrieve a property by key. If `get_one` is `True`, returns the first
        match; otherwise, returns a list of matches.

    `merge_properties_from(
        other: Image | list[Image] | np.ndarray | list[np.ndarray]
    ) -> Image`  
        Merge properties from another `Image`, list of `Image`s, or a NumPy
        array.

    **Conversion Utilities**

    `to_cupy() -> Image`
      Convert the `Image` to a CuPy array if the underlying value is a NumPy
      array.
    `to_numpy() -> Image`
      Convert the `Image` to a numpy array if the underlying value is a CuPy
      array.
    `__array__(*args: tuple[Any, ...], **kwargs: dict[str, Any]) -> np.ndarray`  
      Convert the `Image` to a numpy array. Used implicitly by numpy functions.

    **NumPy Compatibility
    
    `__array_ufunc__(
        ufunc: Callable,
        method: str,
        *inputs: tuple[Any],
        **kwargs: dict[str, Any]
    ) -> Image | tuple[Image, ...] | None`
        Enable compatibility with numpy's universal functions (ufuncs).
        Examples include `np.add`, `np.multiply`, and `np.sin`.
        
    The following NumPy universal functions (ufuncs) are supported:

    - Arithmetic: 
        `np.add`, `np.subtract`, `np.multiply`, `np.divide`, `np.power`,
        `np.mod`, etc.
    - Trigonometric:
        `np.sin`, `np.cos`, `np.tan`, `np.arcsin`, `np.arccos`,
        `np.arctan`, etc.
    - Exponential and logarithmic:
        `np.exp`, `np.log`, `np.log10`, etc.
    - Comparison:
        `np.equal`, `np.not_equal`, `np.less`, `np.less_equal`,
        `np.greater`, `np.greater_equal`, etc.
    - Bitwise:
        `np.bitwise_and`, `np.bitwise_or`, `np.bitwise_xor`, etc.

    `__array_function__(
        func: Callable[..., Any],
        types: tuple[type, ...],
        args: tuple[Any, ...],
        kwargs: dict[str, Any]
    ) -> Image | tuple[Image, ...] | Any`
        Enable compatibility with numpy's general functions, such as `np.mean`,
        `np.dot`, and `np.concatenate`.
        
        The following numpy general functions are supported:

        - Array manipulation:
            `np.reshape`, `np.transpose`, `np.concatenate`, etc.
        - Statistical:
            `np.mean`, `np.sum`, `np.std`, etc.
        - Linear algebra:
            `np.dot`, `np.cross`, etc.

    **Indexing and Assignment**
    
    `__getitem__(
        idx: Any
    ) -> Image | Any`
        Access array elements using standard indexing or slicing. If the result
        is scalar, returns it; otherwise, returns an `Image`.
    `__setitem__(
        key: Any,
        value: Any
    ) -> None` 
        Assign values to specific array elements. Updates the properties of the
        `Image` accordingly.

    **Special Methods**

    `__repr__() -> str`  
        Return a string representation of the `Image` object.

    Examples
    --------
    Create an `Image` instance from a NumPy array:

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

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

    Access NumPy attributes and methods:

    >>> print(img.shape)
    (2, 2)
    >>> print(img.sum())
    10

    Manage properties:

    >>> img.append({"property_name": "example"})
    >>> print(img.properties)
    [{'property_name': 'example'}]

    Compatibility with NumPy ufuncs:

    >>> print(img + 10)
    Image(array([[11, 12],
                 [13, 14]]))

    Conversion between NumPy and CuPy arrays:

    >>> import cupy

    >>> gpu_img = img.to_cupy()
    >>> print(type(gpu_img._value))
    <class cupy.ndarray>

    >>> converted_back = gpu_img.to_numpy()
    >>> print(type(converted_back._value))
    <class 'numpy.ndarray'>

    """

    # Attributes.
    _value: np.ndarray
    properties: list[dict[str, Property]]

    def __init__(
        self: Image | np.ndarray,
        value: Image | np.ndarray | list | int | float |  bool,
        copy: bool = True,
    ):
        """Initialize an Image object.

        The `Image` class wraps an array-like object, providing enhanced 
        functionality such as property tracking and compatibility with NumPy 
        and CuPy operations.

        Parameters
        ----------
        value: np.ndarray | list | int | float | bool | Image
            The array-like object to be converted to a NumPy array and stored 
            in the Image object. If it is an Image, the value and properties of
            the image are copied or referenced depening on the value of the 
            `copy` parameter.
        copy: bool, optional
            If `True`, the `value` is copied to ensure independence (default).
            If `False`, a reference to the original value is maintained.

        Attributes
        ----------
        _value: np.ndarray
            The underlying data stored in the Image object as NumPy.
        properties: list[dict[str, Property]]
            A list of property dictionaries associated with the Image.

        """

        super().__init__()

        # Copy the value if requested, otherwise use a reference.
        if copy:
            self._value = self._view(value)
        else:
            if isinstance(value, Image):
                self._value = value._value
            else:
                self._value = value

        # Copy properties from the input Image if applicable,
        # otherwise initialize an empty list
        if isinstance(value, Image):
            self.properties = list(value.properties)
        else:
            self.properties = []

    def append(
        self: Image | np.ndarray,
        property_dict: dict[str, Property],
    ) -> Image:
        """Append a dictionary to the properties list.

        This method adds a dictionary of property values to the `properties`
        list of the `Image` instance.

        This method does not ensure uniqueness of properties within the
        `properties` list. Duplicate entries may be added if the same
        dictionary is appended multiple times.

        Parameters
        ----------
        property_dict: dict[str, Property]
            A dictionary to append to the property list.

        Returns
        -------
        Image
            Returns itself.

        Examples
        --------
        >>> import numpy as np
        >>> from deeptrack import Feature, Image

        Define the feature and enable property storage:

        >>> class SimpleParticle(Feature):
        ...     def get(self, image, position=None, **kwargs):
        ...         return image

        >>> particle = SimpleParticle(position=(128, 128))
        >>> particle.store_properties()  # Return Image instead of NumPy array.

        Create an input image and resolve the feature:

        >>> input_image = Image(np.zeros((256, 256)))
        >>> output_image = particle.resolve(input_image)
        >>> print(output_image.properties)
        [{'position': (128, 128), 'name': 'SimpleParticle'}]

        Append new properties to the image:

        >>> output_image.append({"key1": 1, "key2": 2})
        >>> print(output_image.properties)
        [{'position': (128, 128), 'name': 'SimpleParticle'},
        {'key1': 1, 'key2': 2}]

        """

        #TODO: Check if we still need to make a copy of the list.

        self.properties = [*self.properties, property_dict]

        return self

    def get_property(
        self: Image | np.ndarray,
        key: str,
        get_one: bool = True,
        default: Any = None,
    ) -> Any | list[Any]:
        """Retrieve the value of a property of the Image.

        If the feature has the property defined by `key`, the method returns
        its current_value. Otherwise, it returns the `default` value.

        If `get_one` is `True`, the first instance is returned; otherwise, all
        instances are returned as a list.

        Parameters
        ----------
        key: str
            The name of the property.
        get_one: bool, optional
            Whether to return only the first instance of the property (default
            behavior for `True`) or all instances of the property (`False`).           
        default: Any, optional
            The value to be returned as default, which is by default `None`.

        Returns
        -------
        Any | list[Any]
            The value of the property (if `get_one` is `True`) or all instances
            as a list (if `get_one` is `True`). If the property is not found,
            it returns `default`.

        Examples
        --------
        >>> import numpy as np
        >>> from deeptrack import Feature, Image

        Define the feature and enable property storage:

        >>> class SimpleParticle(Feature):
        ...     def get(self, image, position=None, **kwargs):
        ...         return image

        >>> particle = SimpleParticle(position=(128, 128))
        >>> particle.store_properties()  # Return Image instead of NumPy array.

        Create an input image and resolve the feature:

        >>> input_image = Image(np.zeros((256, 256)))
        >>> output_image = particle.resolve(input_image)

        Retrieve the properties:
        
        >>> print(output_image.get_property("position"))
        >>> print(output_image.get_property("name"))


        """

        # If get_one = True, return the first instance of the property.
        if get_one:
            for prop in self.properties:
                if key in prop:
                    return prop[key]

            # If no instance, return the default.
            return default

        # If get_one = False, return all instances of the property,
        # or default if no instance of the property.
        return [
            prop[key]
            for prop
            in self.properties
            if key in prop
        ] or default

    def merge_properties_from(
        self: Image | np.ndarray,
        other: np.ndarray | Image | Iterable,
    ) -> Image:
        """Merge properties with those from another Image.

        Appends properties from another images without duplicating properties.
        The uniqueness of a dictionary of properties is determined from the
        property `hash_key`.

        Most functions involving two images should automatically output an
        image with merged properties. However, since each property is
        guaranteed to be unique, it is safe to manually call this function if
        there is any uncertainty.

        Parameters
        ----------
        other: Image | np.ndarray | Iterable
            The data to retrieve properties from. It can be an Image, a NumPy
            array (which has no properties), or an iterable object.

        Returns
        -------
        Image
            Returns itself.

        Examples
        --------
        >>> import numpy as np
        >>> from deeptrack import Feature, Image

        Define the feature and enable property storage:

        >>> class SimpleParticle(Feature):
        ...     def get(self, image, position=None, **kwargs):
        ...         return image

        >>> particle = SimpleParticle(position=(128, 128))
        >>> particle.store_properties()  # To return an Image and not an array.

        Create an input image:
    
        >>> input_image = Image(np.zeros((256, 256)))

        Resolve the feature twice without update and verify that only one set
        of properties is stored:

        >>> output_image1 = particle.resolve(input_image)
        >>> output_image2 = particle.resolve(input_image)
        >>> output_image1.merge_properties_from(output_image2)
        >>> print(output_image1.properties)
        [{'position': (128, 128), 'name': 'SimpleParticle'}]

        Update the feature, resolve it, and verify that now two sets of
        properties are stored:

        >>> particle.update()
        >>> output_image3 = particle.resolve(input_image)
        >>> output_image1.merge_properties_from(output_image3)
        >>> print(output_image1.properties)
        [{'position': (128, 128), 'name': 'SimpleParticle'},
        {'position': (128, 128), 'name': 'SimpleParticle'}]

        Now, call the method with a list including a previously merged feature
        and a NumPy array that are not merged:

        >>> particle.update()
        >>> output_image4 = particle.resolve(input_image)
        >>> output_image1.merge_properties_from(
        ...     [output_image3, output_image4, np.zeros((10, 10))]
        ... )
        >>> print(output_image1.properties)
        [{'position': (128, 128), 'name': 'SimpleParticle'},
        {'position': (128, 128), 'name': 'SimpleParticle'},
        {'position': (128, 128), 'name': 'SimpleParticle'}]

        """

        # If other is a NumPy array, return the image itself,
        # because arrays can not contain properties.
        if isinstance(other, np.ndarray):
            return self

        # If other is an Image, add the properties without duplication.
        if isinstance(other, Image):
            for new_prop in other.properties:

                # Check if the property is already in the list.
                should_append = True
                for my_prop in self.properties:
                    if my_prop is new_prop:
                        # Prop already present.
                        should_append = False
                        break

                # Append new property if not duplicated.
                if should_append:
                    self.append(new_prop)

            return self

        # Ensure that the recursion is not infinite.
        if not isinstance(other, str):
            # If other is iterable, recurse.
            if hasattr(other, "__iter__"):
                for item in other:
                    self.merge_properties_from(item)

            return self

        # Return the Image itself unaltered.
        return self

    def _view(
        self: Image | np.ndarray,
        value: Image | np.ndarray | list | int | float | bool,
    ) -> np.ndarray:
        """Convert the value to NumPy array for storage in the Image object.

        This method converts the value to a NumPy array to ensure that the 
        stored value is compatible with the `Image` class. 

        If the input is a list or scalar type, it is converted into a NumPy 
        array.
        
        If the input is another `Image` object, it recursively retrieves the 
        underlying value to avoid nesting.
        
        If the input is not compatible with NumPy array conversion, the
        original value is returned.
        
        Parameters
        ----------
        value: np.ndarray | list | int | float | bool | Image
            The input value to be transformed to a NumPy array.

        Returns
        -------
        np.ndarray
            A NumPy array representation of the input value. If the input is
            not compatible with NumPy array conversion, the original value is
            returned.

        """

        # Ensure not to create nested Image objects.
        if isinstance(value, Image):
            return self._view(value._value)

        # Convert compatible types to NumPy arrays.
        if isinstance(value, (np.ndarray, list, int, float, bool)):
            return np.array(value)

        # Return value if it cannot be converted.
        return value

    def __array_ufunc__(
        self: Image | np.ndarray,
        ufunc: np.ufunc,
        method: str,
        *inputs: tuple[Any, ...],
        **kwargs: dict[str, Any],
    ) -> Image | tuple[Image, ...] | None:
        """Enable Image objects to use NumPy ufuncs.

        This method integrates the Image class with NumPy's universal functions 
        (`ufuncs`), enabling operations like addition, multiplication, or 
        trigonometric functions directly on Image objects.

        Parameters
        ----------
        ufunc: np.ufunc
            The NumPy ufunc being called.
        method: str
            The method of the ufunc being called (e.g., "__call__", "reduce").
        *inputs: tuple[Any, ...]
            Positional arguments passed to the ufunc.
        **kwargs: dict[str, Any]
            Keyword arguments passed to the ufunc.

        Returns
        -------
        Image | tuple[Image, ...] | None]
            The result of the ufunc applied to the Image object(s). If the
            ufunc returns a tuple, each element is wrapped in an Image. For the
            `at` method, returns `None`.

        Raises
        ------
        TypeError
            If the input types are not compatible.

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

        >>> img1 = Image(np.array([1, 2, 3]))
        >>> img2 = Image(np.array([4, 5, 6]))

        Use np.add ufunc:

        >>> result = np.add(img1, img2)
        >>> print(result)
        Image([5, 7, 9])

        Apply a unary ufunc:

        >>> result = np.sin(img1)
        >>> print(result)
        Image([0.84147, 0.909297, 0.14112])

        Use an 'at' method with ufuncs:

        >>> img = Image(np.array([1, 2, 3]))
        >>> np.add.at(img, [0, 2], 10)
        >>> print(img)
        Image([11, 2, 13])

        """

        # Ensures all inputs are the same type.
        args = coerce(inputs)

        # Strips the Image object from the inputs.
        args = tuple(strip(arg) for arg in args)

        # If an output array is defined and is an Image,
        # redirect the output to the value of that image.
        out = kwargs.get("out", ())
        if out:
            kwargs["out"] = tuple(x._value if isinstance(x, Image)
                                  else x
                                  for x in out)

        # Call the ufunc.
        results = getattr(ufunc, method)(*args, **kwargs)

        if type(results) is tuple:

            # If the ufunc returns a tuple, return a tuple of Image objects.
            outputs = []
            for result in results:
                out = Image(result, copy=False)
                out.merge_properties_from(inputs)
                outputs.append(out)

            return tuple(outputs)
        elif method == "at":  #TODO: check whether not implemented on purpose?

            # Does not have an output.
            return None
        else:

            # If the ufunc returns a single value, return an Image object.
            result = Image(results, copy=False)
            result.merge_properties_from(inputs)
            return result

    def __array_function__(
        self: Image | np.ndarray,
        func: Callable[..., Any],
        types: tuple[type, ...],
        args: tuple[Any, ...],
        kwargs: dict[str, Any],
    ) -> Image | tuple[Image, ...] | Any:
        """Handle NumPy functions for Image objects.

        This method integrates Image objects with NumPy functions, allowing
        them to be used transparently in standard NumPy operations while
        preserving their structure and properties.

        Parameters
        ----------
        func: Callable
            The NumPy function being called (e.g., `np.mean`, `np.dot`).
        types: tuple[type, ...]
            The types of the arguments involved in the function.
        args: tuple[Any, ...]
            The positional arguments for the function.
        kwargs: dict[str, Any]
            The keyword arguments for the function.

        Returns
        -------
        Image | tuple[Image, ...] | Any
            The result of the NumPy function. If the function returns a single
            value, it may be wrapped as an Image object. If it returns a tuple,
            each element is wrapped as an Image. Constants remain unwrapped.

        Raises
        ------
        NotImplementedError
            If the function is not supported.

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

        >>> img = Image(np.array([1, 2, 3]))

        Use np.sum function:

        >>> result = np.sum(img)
        >>> print(result)
        6  # Not wrapped as Image since it's a scalar.

        Use np.mean function:

        >>> result = np.mean(img)
        >>> print(result)
        2.0  # Scalar result.

        Use np.reshape to modify the shape:

        >>> reshaped = np.reshape(img, (3, 1))
        >>> print(reshaped)
        Image([[1], [2], [3]])

        """

        # Allows to use NumPy functions on Image objects.

        # Ensures all inputs are the same type.
        values = coerce(args)

        # Strips the Image object from the inputs.
        values = [strip(arg) for arg in values]

        # Check if the function is supported.
        if not (
            isinstance(self._value, (np.ndarray, tuple, list))
            or np.isscalar(self._value)
        ) and not hasattr(self._value, "__array_function__"):
            return NotImplemented

        out = func(*values, **kwargs)

        # Constants are not wrapped as Image objects.
        if isinstance(out, (bool, int, float, complex, np.generic)):
            return out

        # If the function returns a tuple, return a tuple of Image objects.
        if isinstance(out, tuple):
            outputs = []
            for result in out:
                out = Image(result, copy=False)
                out.merge_properties_from(args)
                outputs.append(out)

            return tuple(outputs)
        else:
            # If the function returns a single value, return an Image object.
            result = Image(out, copy=False)
            result.merge_properties_from(args)
            return result

    def __array__(
        self: Image | np.ndarray,
        *args: tuple[Any, ...],
        **kwargs: dict[str, Any],
    ) -> np.ndarray:
        """Convert the Image object to a NumPy array.

        This method allows an Image object to be seamlessly used with NumPy 
        functions by converting its `_value` attribute (assumed to be the 
        underlying array) into a NumPy array.

        If the `_value` attribute is already a NumPy array, it is returned 
        as-is. Otherwise, `self.to_numpy()` is called to convert `_value` to a 
        NumPy array-compatible representation.

        Parameters
        ----------
        *args: tuple[Any, ...]
            Positional arguments passed to `numpy.array`.
        **kwargs: dict[str, Any]
            Keyword arguments passed to `numpy.array`.

        Returns
        -------
        np.ndarray
            The underlying `_value` attribute of the Image object as a NumPy
            array.

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

        >>> img = Image(np.array([1, 2, 3]))
        >>> np_array = np.array(img)  # This triggers __array__
        >>> print(np_array)
        [1 2 3]

        >>> img2 = Image(cupy.array([1, 2, 3]))
        >>> np_array2 = np.array(img2)  # This triggers __array__
        >>> print(np_array2)
        [1 2 3]

        """

        return np.array(self.to_numpy()._value, *args)

    def to_cupy(
        self: Image | np.ndarray,
    ) -> Image:
        """Convert the image's underlying value to a CuPy array.

        This method converts the `_value` of the `Image` object to a CuPy array 
        if it is currently a NumPy array. If the conversion is performed, the 
        method returns a new `Image` object with the converted value while 
        preserving the properties of the original `Image`.

        If the `_value` is already a CuPy array or an unsupported type, the 
        method returns the `Image` object unchanged.

        Returns
        -------
        Image
            A new `Image` object with the `_value` as a CuPy array, or the 
            unchanged `Image` object if conversion is not applicable.

        Examples
        --------
        Convert a NumPy array to CuPy:
    
        >>> import numpy as np
        >>> from deeptrack.image import Image
    
        >>> img = Image(np.array([1, 2, 3]))
        >>> cupy_img = img.to_cupy()
        >>> print(cupy_img)
        Image(array([1, 2, 3]))

        If the `_value` is already a CuPy array, no conversion occurs:

        >>> import cupy

        >>> cupy_img = Image(cupy.array([1, 2, 3]))
        >>> print(cupy_img.to_cupy() is cupy_img)
        True

        """

        if isinstance(self._value, np.ndarray):
            return Image(
                cupy.array(self._value),
                copy=False,
            ).merge_properties_from(self)

        return self

    def to_numpy(
        self: Image | np.ndarray,
    ) -> Image:
        """Convert the image's underlying value to a NumPy array.

        This method converts the `_value` of the `Image` object to a NumPy
        array if it is currently a CuPy array. If the conversion is performed,
        the method returns a new `Image` object with the converted value while 
        preserving the properties of the original `Image`.

        If the `_value` is already a NumPy array or an unsupported type, the 
        method returns the `Image` object unchanged.

        Returns
        -------
        Image
            A new `Image` object with the `_value` as a NumPy array, or the 
            unchanged `Image` object if conversion is not applicable.

        Examples
        --------
        Convert a CuPy array to NumPy:

        >>> import cupy
        >>> from deeptrack.image import Image

        >>> img = Image(cupy.array([1, 2, 3]))
        >>> numpy_img = img.to_numpy()
        >>> print(numpy_img)
        Image(array([1, 2, 3]))

        If the `_value` is already a NumPy array, no conversion occurs:

        >>> import numpy as np

        >>> numpy_img = Image(np.array([1, 2, 3]))
        >>> print(numpy_img.to_numpy() is numpy_img)
        True

        """

        if isinstance(self._value, np.ndarray):
            return self

        if isinstance(self._value, cupy.ndarray):
            return Image(
                self._value.get(),
                copy=False,
            ).merge_properties_from(self)

        return self

    def __getattr__(
        self: Image | np.ndarray,
        key: str,
    ) -> Any:
        """Access attributes of the underlying value.

        This method intercepts attribute access for the `Image` instance and 
        delegates it to the underlying `_value` attribute if the requested 
        attribute is not explicitly defined on the `Image` object.

        Parameters
        ----------
        key: str
            The name of the attribute to access.

        Returns
        -------
        Any
            The value of the attribute from the `_value` object.

        Raises
        ------
        AttributeError
            If the attribute does not exist on the `_value` object.
        """

        # Delegate attribute access to the `_value` object.
        return getattr(self._value, key)

    def __getitem__(
        self: Image | np.ndarray,
        idx: int | slice | tuple[int | slice, ...] | Any,
    ) -> Image | int | float | bool | complex | np.ndarray:
        """Access and return an item or a slice from the Image.

        This method allows indexing into the wrapped `_value` of the Image, 
        supporting both scalar and slice-based indexing. If the result is an 
        array-like object, it is returned as an Image. If it is a scalar, the 
        scalar value is returned.

        Parameters
        ----------
        idx: int | slice | tuple[int | slice, ...] | Any
            The index or indices used to access elements of the Image.

        Returns
        -------
        Image | int | float | bool | complex | np.ndarray
            The accessed value, either as an Image (for array-like results) or 
            as a scalar for single-element results.

        Examples
        --------
        >>> from deeptrack.image import Image
        
        >>> img = Image(np.array([[1, 2], [3, 4]]))
        >>> img[0, 0]
        Image(1)

        >>> img[:, 0]
        Image(array([1, 3]))

        """

        # Strip any `Image` wrappers from the index to ensure compatibility.
        idx = strip(idx)

        # Retrieve the indexed result from `_value`.
        out = self._value.__getitem__(idx)

        # Return the result directly if it is a scalar type.
        if isinstance(out, (bool, int, float, complex, np.generic)):
            return out

        # Wrap the result in a new `Image` object and merge properties.
        out = Image(out, copy=False)
        out.merge_properties_from([self, idx])
        return out

    def __setitem__(
        self: Image | np.ndarray,
        key: int | slice | tuple[int | slice, ...] | list[int],
        value: int | slice | tuple[int | slice, ...] | list[int],
    ) -> None:
        """Assign a value to a specific index or slice of the image.

        Modifies the underlying `_value` attribute of the `Image` object via
        indexing or slicing. It also updates the properties of the `Image`
        object by merging any associated properties from the key or value.

        Parameters
        ----------
        key: int | slice | tuple[int | slice, ...] | list[int]
            The index or slice to update. It can be a single integer to update
            a specific position, a slice to update a range of positions, a
            tuple of integers or slices for multi-dimensional indexing, or a
            list of integers for advanced indexing.
        value: Image | numpy.ndarray | int | float | bool | complex
            The value to assign to the specified index or slice. If `value` is
            an `Image`, its `_value` attribute is extracted before assignment.
            Other types are assigned directly after being stripped if
            necessary.

        Returns
        -------
        None

        Examples
        --------
        Assign a scalar to a specific index:
        
        >>> import numpy as np
        >>> from deeptrack.image import Image

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

        Assign an array to a slice:

        >>> img[:, 1] = [10, 20]
        >>> print(img)
        Image(array([[ 1, 10],
                    [ 3, 20]]))

        Assign an Image to a specific index:

        >>> other_img = Image(50)
        >>> img[1, 0] = other_img
        >>> print(img)
        Image(array([[ 1, 10],
                    [50, 20]]))        

        """

        # Strip away `Image` wrappers or nested elements from key and value.
        key = strip(key)
        value = strip(value)

        # Perform the assignment on the underlying `_value` attribute.
        self._value.__setitem__(key, value)

        # Merge properties from the key and value into the current Image.
        self.merge_properties_from([key, value])

    def __int__(
        self: Image,
    )-> int:
        """Convert the Image's value to an integer.

        Returns
        -------
        int
            The integer representation of the Image's `_value` attribute.

        """

        return int(self._value)

    def __float__(
        self: Image | np.ndarray,
    ) -> float:
        """Convert the Image's value to a float.

        Returns
        -------
        float
            The float representation of the Image's `_value` attribute.

        """

        return float(self._value)

    def __bool__(
        self: Image | np.ndarray,
    ) -> bool:
        """Check if the Image's value is truthy.

        Returns
        -------
        bool
            `True` if the `_value` is truthy, otherwise `False`.

        """

        return bool(self._value)

    def __round__(
        self: Image | np.ndarray,
        ndigits: int = 0,
    ) -> float:
        """Round the Image's value to a specified number of digits.

        Parameters
        ----------
        ndigits: int, optional
            The number of decimal places to round to (default is 0).

        Returns
        -------
        Image
            The rounded `_value`.

        """

        return round(self._value, ndigits)

    def __len__(
        self: Image | np.ndarray,
    ) -> int:
        """Return the length of the Image's value.

        Returns
        -------
        int
            The length of the `_value` attribute.

        """

        return len(self._value)

    def __repr__(
        self: Image | np.ndarray,
    ) -> str:
        """Return the string representation of the Image.

        Returns
        -------
        str
            A string representing the Image, including its `_value` attribute.

        """

        return f"Image({repr(self._value)})"

    # Comparison methods.
    __lt__ = _binary_method(ops.lt)
    __le__ = _binary_method(ops.le)
    __eq__ = _binary_method(ops.eq)
    __ne__ = _binary_method(ops.ne)
    __gt__ = _binary_method(ops.gt)
    __ge__ = _binary_method(ops.ge)

    # Numeric methods.
    __add__, __radd__, __iadd__ = _numeric_methods(ops.add)
    __sub__, __rsub__, __isub__ = _numeric_methods(ops.sub)
    __mul__, __rmul__, __imul__ = _numeric_methods(ops.mul)
    __matmul__, __rmatmul__, __imatmul__ = _numeric_methods(ops.matmul)

    # Python 3 does not use __div__, __rdiv__, or __idiv__
    __truediv__, __rtruediv__, __itruediv__ = _numeric_methods(ops.truediv)
    __floordiv__, __rfloordiv__, __ifloordiv__ = _numeric_methods(ops.floordiv)
    __mod__, __rmod__, __imod__ = _numeric_methods(ops.mod)
    __divmod__ = _binary_method(divmod)
    __rdivmod__ = _reflected_binary_method(divmod)

    # __idivmod__ does not exist
    #TODO: handle the optional third argument for __pow__?
    __pow__, __rpow__, __ipow__ = _numeric_methods(ops.pow)
    __lshift__, __rlshift__, __ilshift__ = _numeric_methods(ops.lshift)
    __rshift__, __rrshift__, __irshift__ = _numeric_methods(ops.rshift)
    __and__, __rand__, __iand__ = _numeric_methods(ops.and_)
    __xor__, __rxor__, __ixor__ = _numeric_methods(ops.xor)
    __or__, __ror__, __ior__ = _numeric_methods(ops.or_)

    # Unary methods.
    __neg__ = _unary_method(ops.neg)
    __pos__ = _unary_method(ops.pos)
    __abs__ = _unary_method(ops.abs)
    __invert__ = _unary_method(ops.invert)


def strip(
    element: Image | np.ndarray | list | tuple | Any,
) -> Any:
    """Recursively extract the underlying value from an Image object.

    This function strips away the `Image` wrapper to return the underlying 
    `_value` attribute. If the input is a list or tuple, it recursively 
    processes each element, preserving the original structure. For other types, 
    the input is returned unchanged.

    Parameters
    ----------
    element: Image | np.ndarray | list | tuple | Any
        The input to process.

    Returns
    -------
    Any
        The stripped value. If `element` is an `Image`, its `_value` is
        returned. If `element` is a list or tuple, the corresponding stripped
        structure is returned. Otherwise, `element` is returned unchanged.

    Examples
    --------
    >>> from deeptrack.image import Image, strip

    >>> img = Image([1, 2, 3])
    >>> strip(img)
    array([1, 2, 3])

    >>> nested = [Image([1, 2]), Image([3, 4])]
    >>> strip(nested)
    [array([1, 2]), array([3, 4])]

    >>> mixed = (Image([5]), 6, 'a')
    >>> strip(mixed)
    (array([5]), 6, 'a')

    """

    # Check if the input is an instance of the Image class.
    # If so, return its underlying `_value` attribute.
    if isinstance(element, Image):
        return element._value

    # If the input is a list or tuple, recursively process each element.
    # Use the same type as the input (list or tuple) to maintain the structure.
    if isinstance(element, (list, tuple)):
        return type(element)([strip(i) for i in element])

    # If the input is neither an Image, list, nor tuple, return it unchanged.
    return element


def coerce(
    images: list[Image | np.ndarray],
) -> list[Image]:
    """Coerce a list of images to a consistent type.

    This function ensures that all images in the input list are instances of
    the `Image` class. Additionally, if any image contains a CuPy array, all
    images are converted to CuPy arrays to ensure consistency.

    Parameters
    ----------
    images: list[Image | np.ndarray]
        A list of images to be coerced. Each image can be an `Image` instance 
        or a NumPy array.

    Returns
    -------
    list[Image]
        A list of `Image` instances where all elements are coerced to the same
        type (CuPy if CuPy arrays are present in any image).

    Examples
    --------
    >>> import numpy as np
    >>> from deeptrack.image import coerce, Image

    Create a list of images:
    
    >>> img1 = Image(np.array([1, 2, 3]))
    >>> img2 = np.array([4, 5, 6])

    Coerce the images to ensure consistency:

    >>> result = coerce([img1, img2])
    >>> print([type(img._value) for img in result])
    [<class 'numpy.ndarray'>, <class 'numpy.ndarray'>]

    If one image is a CuPy array, all are converted:
    
    >>> import cupy
    >>> img3 = Image(cupy.array([7, 8, 9]))
    >>> result = coerce([img1, img3])
    >>> print([type(img._value) for img in result])
    [<class cupy.ndarray>, <class cupy.ndarray>]

    """

    # Wrap all elements in the list as Image instances if not already.
    images = [Image(image, copy=False) for image in images]

    # Check if any image contains a CuPy array and, if so, coerce all to CuPy.
    if any(isinstance(i._value, cupy.ndarray) for i in images):
        return [i.to_cupy() for i in images]

    # Otherwise, return the list of Image instances.
    return images


# Generate a sorted list of "fastest" sizes for FFT computation.
# These sizes are optimized for FFT algorithms, typically being products of
# small primes (powers of 2 and 3).
_FASTEST_SIZES = [0]
for n in range(1, 10):
    _FASTEST_SIZES += [2 ** a * 3 ** (n - a - 1) for a in range(n)]
_FASTEST_SIZES = np.sort(_FASTEST_SIZES)


def pad_image_to_fft(
    image: Image | np.ndarray | np.ndarray,
    axes: Iterable[int] = (0, 1),
) -> Image | np.ndarray:
    """Pads an image to optimize Fast Fourier Transform (FFT) performance.

    This function pads an image by adding zeros to the end of specified axes 
    so that their lengths match the nearest larger size in `_FASTEST_SIZES`. 
    These sizes are selected to optimize FFT computations.

    Parameters
    ----------
    image: Image | np.ndarray
        The input image to pad. It should be an instance of the `Image` class 
        or any array-like structure compatible with FFT operations.
    axes: Iterable[int], optional
        The axes along which to apply padding. Defaults to `(0, 1)`.

    Returns
    -------
    Image | np.ndarray
        The padded image with dimensions optimized for FFT performance.

    Raises
    ------
    ValueError
        If no suitable size is found in `_FASTEST_SIZES` for any axis length.

    Examples
    --------
    >>> import numpy as np
    >>> from deeptrack.image import Image, pad_image_to_fft
    
    Pad an Image object:
    
    >>> img = Image(np.zeros((7, 13)))
    >>> padded_img = pad_image_to_fft(img)
    >>> print(padded_img.shape)
    (8, 16)

    Pad a NumPy array:

    >>> img = np.zeros((5, 11)))
    >>> padded_img = pad_image_to_fft(img)
    >>> print(padded_img.shape)
    (6, 12)

    """

    def _closest(
        dim: int,
    ) -> int:

        # Returns the smallest value frin _FASTEST_SIZES larger than dim.
        for size in _FASTEST_SIZES:
            if size >= dim:
                return size
        raise ValueError(
            f"No suitable size found in _FASTEST_SIZES={_FASTEST_SIZES} "
            f"for dimension {dim}."
        )

    # Compute new shape by finding the closest size for specified axes.
    new_shape = np.array(image.shape)
    for axis in axes:
        new_shape[axis] = _closest(new_shape[axis])

    # Calculate the padding for each axis.
    pad_width = [(0, increase) 
                 for increase 
                 in np.array(new_shape) - image.shape]

    # Pad the image using constant mode (add zeros).
    return np.pad(image, pad_width, mode="constant")


def maybe_cupy(
    array: np.ndarray | list | tuple,
) -> cupy.ndarray | np.ndarray:
    """Convert an array to a CuPy array if GPU is available and enabled.

    This function checks if GPU computation is enabled in the configuration. 
    If enabled, it converts the input array to a CuPy array for GPU-based 
    acceleration. Otherwise, it returns the input array unchanged.

    The function relies on the `gpu_enabled` flag in the `config` module to 
    determine whether GPU acceleration should be used.

    Parameters
    ----------
    array: np.ndarray | list | tuple
        The input array to be potentially converted to a CuPy array.

    Returns
    -------
    cupy.ndarray | np.ndarray
        A CuPy array if GPU is enabled, otherwise the original array.

    Raises
    ------
    ImportError
        If GPU is enabled but the `cupy` library is not installed.

    Examples
    --------
    >>> import numpy as np
    >>> from deeptrack.image import maybe_cupy

    If GPU is enabled:
    
    >>> array = np.array([1, 2, 3])
    >>> gpu_array = maybe_cupy(array)
    >>> type(gpu_array)
    <class cupy.ndarray>

    If GPU is not enabled:
    
    >>> array = np.array([1, 2, 3])
    >>> numpy_array = maybe_cupy(array)
    >>> type(numpy_array)
    <class 'numpy.ndarray'>

    """
    from deeptrack.backend import config
    if config.gpu_enabled:
        return cupy.array(array)

    return array