Wrapper

class deeptrack.wrappers.Wrapper(array: ~numpy.ndarray | ~torch.Tensor, properties: dict[str, ~typing.Any] = <factory>)

Bases: object

Base class for any structure needing properties.

A Wrapper stores an array together with a dictionary of properties. The wrapper behaves similarly to the underlying array for arithmetic and logical operations while preserving the associated metadata.

When operations are applied to wrappers, a new wrapper is returned where the array contains the result of the operation and the properties are copied from the left-hand operand.

Parameters

array: np.ndarray | torch.Tensor

The array wrapped by this object.

properties: dict[str, Any], optional

Dictionary of metadata associated with the array.

Attributes

array: np.ndarray | torch.Tensor

The wrapped array.

properties: dict[str, Any]

Metadata associated with the array.

Methods

copy(*, array, properties) -> Wrapper

Return a shallow copy of the wrapper.

as_array() -> np.ndarray | torch.Tensor

Return the wrapped array.

get_property(key, default) -> Any

Retrieve a value, checking wrapper attributes before properties.

Examples

Wrappers can be used with both NumPy and PyTorch backends through the DeepTrack backend configuration.

>>> import deeptrack as dt
>>> from deeptrack import xp

Use the NumPy backend:

>>> dt.config.set_backend("numpy")
>>> a = xp.arange(9, dtype=xp.float32).reshape(3, 3)
>>> w = dt.Wrapper(a, properties={"position": (1, 2)})
>>> w
Wrapper(array=array([[0., 1., 2.],
       [3., 4., 5.],
       [6., 7., 8.]], dtype=float32), properties={'position': (1, 2)})

Array attributes are accessible:

>>> w.shape
(3, 3)

>>> w.ndim
2

Properties are also accessible:

>>> w.properties
{'position': (1, 2)}

Arithmetic operations return new wrappers and preserve properties:

>>> w2 = w + 2
>>> w2
Wrapper(array=array([[ 2.,  3.,  4.],
       [ 5.,  6.,  7.],
       [ 8.,  9., 10.]], dtype=float32), properties={'position': (1, 2)})

Wrappers can also be combined:

>>> b = xp.ones((3, 3), dtype=xp.float32)
>>> w3 = w + dt.Wrapper(b)
>>> w3
Wrapper(array=array([[1., 2., 3.],
       [4., 5., 6.],
       [7., 8., 9.]], dtype=float32), properties={'position': (1, 2)})

Logical operations return wrappers as well:

>>> mask = w > 5
>>> mask
Wrapper(array=array([[False, False, False],
       [False, False, False],
       [ True,  True,  True]]), properties={'position': (1, 2)})

Switch to the PyTorch backend:

>>> dt.config.set_backend("torch")
>>> a = xp.arange(9, dtype=xp.float32).reshape(3, 3)
>>> w = dt.Wrapper(a, properties={"position": (1, 2)})
>>> w
Wrapper(array=tensor([[0., 1., 2.],
       [3., 4., 5.],
       [6., 7., 8.]]), properties={'position': (1, 2)})

Operations behave the same way:

>>> w2 = 2 + w
>>> w2
Wrapper(array=tensor([[ 2.,  3.,  4.],
       [ 5.,  6.,  7.],
       [ 8.,  9., 10.]]), properties={'position': (1, 2)})

Attributes Summary

array
ndim	Number of dimensions of the wrapped array.
properties
shape	Shape of the wrapped array.

Methods Summary

as_array()	Return the underlying array.
copy(*[, array, properties])	Return a shallow copy of the Wrapper.
get_property(key[, default])	Return a property value with attribute fallback.

Attributes Documentation

array: ndarray | Tensor = <dataclasses._MISSING_TYPE object>

ndim

Number of dimensions of the wrapped array.

properties: dict[str, Any] = <dataclasses._MISSING_TYPE object>

shape

Shape of the wrapped array.

Methods Documentation

as_array() → ndarray | Tensor

Return the underlying array.

Notes

The raw array is also directly available as self.array. This method exists mainly for API compatibility and clarity.

Returns

np.ndarray | torch.Tensor

The wrapped array.

copy(*, array: ndarray | Tensor | None = None, properties: dict[str, Any] | None = None) → Wrapper

Return a shallow copy of the Wrapper.

Parameters

array: np.ndarray | torch.Tensor | None, optional

Replacement for the wrapped array. If None, the existing array is reused.

properties: dict[str, Any] | None, optional

Replacement for the properties dictionary. If None, a shallow copy of the current properties is used.

Returns

Wrapper

A new Wrapper instance.

get_property(key: str, default: Any | None = None) → Any

Return a property value with attribute fallback.

This method first attempts to retrieve key as an attribute of the wrapper. If the attribute does not exist, the method looks for key in the wrapper’s properties dictionary.

Parameters

key: str

Name of the property to retrieve.

default: Any, optional

Value returned if the property is not found.

Returns

Any

The resolved property value.

Examples

>>> import deeptrack as dt

>>> import numpy as np
>>>
>>> w = dt.Wrapper(np.zeros((2, 2)), properties={"id": 1})
>>> w.get_property("id")
1

Attributes take precedence over dictionary properties:

>>> w.get_property("shape")
(2, 2)