Angle

class deeptrack.elementwise.Angle(feature: Feature | None = None, **kwargs: Any)

Bases: ElementwiseFeature

Apply the angle (phase) function elementwise.

This feature applies an angle/phase operation to each element in a NumPy array or a PyTorch tensor. It supports both direct input and pipeline composition.

The angle function returns the phase angle (in radians) of a complex number. For real-valued inputs, it returns 0 for positive and π for negative values.

Note: This feature is implemented with a manual dispatch because xp.angle (from array-api-compat) may return a NumPy array even when given a PyTorch tensor. This class guarantees backend preservation.

Parameters

feature: Feature | None, optional

The input feature to which the angle function will be applied. If None, the function is applied directly to the input array or tensor.

Examples

>>> import deeptrack as dt
>>> from deeptrack.elementwise import Angle

Use with NumPy directly:

>>> import numpy as np
>>> result = Angle()(np.array([1+0j, 0+1j, -1+0j, 1+1j]))
>>> result
array([0.        , 1.57079633, 3.14159265, 0.78539816])

Use with PyTorch directly:

>>> import torch
>>> result = Angle()(torch.tensor([1+0j, 0+1j, -1+0j, 1+1j]))
>>> result
tensor([0.0000, 1.5708, 3.1416, 0.7854])

Use in a pipeline with a NumPy value:

>>> value = dt.Value(value=np.array([1+0j, 0+1j, -1+0j, 1+1j]))
>>> pipeline = value >> Angle()
>>> result = pipeline()
>>> result
array([0.        , 1.57079633, 3.14159265, 0.78539816])

Use in a pipeline with a PyTorch value:

>>> value = dt.Value(value=torch.tensor([1+0j, 0+1j, -1+0j, 1+1j]))
>>> pipeline = value >> Angle()
>>> result = pipeline()
>>> result
tensor([0.0000, 1.5708, 3.1416, 0.7854])

These are equivalent to:

>>> pipeline = Angle(value)