Feature

class deeptrack.features.Feature(_input: Any = [], **kwargs: dict[str, Any])

Bases: DeepTrackNode

Base feature class.

Features define the image generation process. All features operate on lists of images. Most features, such as noise, apply some tranformation to all images in the list. This transformation can be additive, such as adding some Gaussian noise or a background illumination, or non-additive, such as introducing Poisson noise or performing a low-pass filter. This transformation is defined by the method get(image, **kwargs), which all implementations of the class Feature need to define.

Whenever a Feature is initiated, all keyword arguments passed to the constructor will be wrapped as a Property, and stored in the properties attribute as a PropertyDict. When a Feature is resolved, the current value of each property is sent as input to the get method.

Parameters

_input: np.ndarray or list of np.ndarray or Image or list of Image,

optional. A list of np.ndarray or DeepTrackNode objects or a single np.ndarray or an Image object representing the input data for the feature. This parameter specifies what the feature will process. If left empty, no initial input is set.

**kwargs: dict of str and Any

Keyword arguments to configure the feature. Each keyword argument is wrapped as a Property and added to the properties attribute, allowing dynamic sampling and parameterization during the feature’s execution.

Attributes

properties: PropertyDict

A dictionary containing all keyword arguments passed to the constructor, wrapped as instances of Property. The properties can dynamically sample values during pipeline execution. A sampled copy of this dictionary is passed to the get function and appended to the properties of the output image.

__list_merge_strategy__: int

Specifies how the output of .get(image, **kwargs) is merged with the input list. Options include: - MERGE_STRATEGY_OVERRIDE (0, default): The input list is replaced by the new list. - MERGE_STRATEGY_APPEND (1): The new list is appended to the end of the input list.

__distributed__: bool

Determines whether .get(image, **kwargs) is applied to each element of the input list independently (__distributed__ = True) or to the list as a whole (__distributed__ = False).

__property_memorability__: int

Specifies whether to store the feature’s properties in the output image. Properties with a memorability value of 1 or lower are stored by default.

__conversion_table__: ConversionTable

Defines the unit conversions used by the feature to convert its properties into the desired units.

__gpu_compatible__: bool

Indicates whether the feature can use GPU acceleration. When enabled, GPU execution is triggered based on input size or backend settings.

Methods

get(image: np.ndarray | list[np.ndarray] | Image | list[Image], **kwargs: Any) -> Image | list[Image]

Abstract method that defines how the feature transforms the input.

__call__(image_list: np.ndarray | list[np.ndarray] | Image | list[Image] | None = None, _ID: tuple[int, …] = (), **kwargs: Any) -> Any

Executes the feature or pipeline on the input and applies property overrides from kwargs.

store_properties(x: bool = True, recursive: bool = True) -> None

Controls whether the properties are stored in the output Image object.

torch(dtype: torch.dtype | None = None, device: torch.device | None = None, permute_mode: str = “never”) -> ‘Feature’

Converts the feature into a PyTorch-compatible feature.

batch(batch_size: int = 32) -> tuple | list[Image]

Batches the feature for repeated execution.

action(_ID: tuple[int, …] = ()) -> Image | list[Image]

Core logic to create or transform the image.

__use_gpu__(inp: np.ndarrary | Image, **_: Any) -> bool

Determines if the feature should use the GPU.

update(**global_arguments: Any) -> Feature

Refreshes the feature to create a new image.

add_feature(feature: Feature) -> Feature

Adds a feature to the dependency graph of this one.

seed(_ID: tuple[int, …] = ()) -> None

Sets the random seed for the feature, ensuring deterministic behavior.

bind_arguments(arguments: Feature) -> Feature

Binds another feature’s properties as arguments to this feature.

_normalize(**properties: dict[str, Any]) -> dict[str, Any]

Normalizes the properties of the feature.

plot(input_image: np.ndarray | list[np.ndarray] | Image | list[Image] | None = None, resolve_kwargs: dict | None = None, interval: float | None = None, **kwargs) -> Any

Visualizes the output of the feature.

_process_properties(propertydict: dict[str, Any]) -> dict[str, Any]

Preprocesses the input properties before calling the get method.

_activate_sources(x: Any) -> None

Activates sources in the input data.

__getattr__(key: str) -> Any

Custom attribute access for the Feature class.

__iter__() -> Iterable

Iterates over the feature.

__next__() -> Any

Returns the next element in the feature.

__rshift__(other: Any) -> Feature

Allows chaining of features.

__rrshift__(other: Any) -> Feature

Allows right chaining of features.

__add__(other: Any) -> Feature

Overrides add operator.

__radd__(other: Any) -> Feature

Overrides right add operator.

__sub__(other: Any) -> Feature

Overrides subtraction operator.

__rsub__(other: Any) -> Feature

Overrides right subtraction operator.

__mul__(other: Any) -> Feature

Overrides multiplication operator.

__rmul__(other: Any) -> Feature

Overrides right multiplication operator.

__truediv__(other: Any) -> Feature

Overrides division operator.

__rtruediv__(other: Any) -> Feature

Overrides right division operator.

__floordiv__(other: Any) -> Feature

Overrides floor division operator.

__rfloordiv__(other: Any) -> Feature

Overrides right floor division operator.

__pow__(other: Any) -> Feature

Overrides power operator.

__rpow__(other: Any) -> Feature

Overrides right power operator.

__gt__(other: Any) -> Feature

Overrides greater than operator.

__rgt__(other: Any) -> Feature

Overrides right greater than operator.

__lt__(other: Any) -> Feature

Overrides less than operator.

__rlt__(other: Any) -> Feature

Overrides right less than operator.

__le__(other: Any) -> Feature

Overrides less than or equal to operator.

__rle__(other: Any) -> Feature

Overrides right less than or equal to operator.

__ge__(other: Any) -> Feature

Overrides greater than or equal to operator.

__rge__(other: Any) -> Feature

Overrides right greater than or equal to operator.

__xor__(other: Any) -> Feature

Overrides XOR operator.

__and__(other: Feature) -> Feature

Overrides AND operator.

__rand__(other: Feature) -> Feature

Overrides right AND operator.

__getitem__(key: Any) -> Feature

Allows direct slicing of the data.

_format_input(image_list: np.ndarray | list[np.ndarray] | Image | list[Image], **kwargs: Any) -> list[Image]

Formats the input data for the feature.

_process_and_get(image_list: np.ndarray | list[np.ndarray] | Image | list[Image], **kwargs: Any) -> list[Image]

Calls the get method according to the __distributed__ attribute.

_process_output(image_list: np.ndarray | list[np.ndarray] | Image | list[Image], **kwargs: Any) -> None

Processes the output of the feature.

_image_wrapped_format_input(image_list: np.ndarray | list[np.ndarray] | Image | list[Image], **kwargs: Any) -> list[Image]

Ensures the input is a list of Image.

_no_wrap_format_input(image_list: np.ndarray | list[np.ndarray] | Image | list[Image], **kwargs: Any) -> list[Image]

Ensures the input is a list of Image.

_no_wrap_process_and_get(image_list: np.ndarray | list[np.ndarray] | Image | list[Image], **kwargs: Any) -> list[Image]

Calls the get method according to the __distributed__ attribute.

_image_wrapped_process_and_get(image_list: np.ndarray | list[np.ndarray] | Image | list[Image], **kwargs: Any) -> list[Image]

Calls the get method according to the __distributed__ attribute.

_image_wrapped_process_output(image_list: np.ndarray | list[np.ndarray] | Image | list[Image], **kwargs: Any) -> None

Processes the output of the feature.

_no_wrap_process_output(image_list: np.ndarray | list[np.ndarray] | Image | list[Image], **kwargs: Any) -> None

Processes the output of the feature.

_coerce_inputs(image_list: np.ndarray | list[np.ndarray] | Image | list[Image], **kwargs: Any) -> list[Image]

Coerces the input to a list of Image.

Methods Summary

__call__([image_list, _ID])	Execute the feature or pipeline.
action([_ID])	Core logic to create or transform the image.
add_feature(feature)	Adds a feature to the dependecy graph of this one.
batch([batch_size])	Batch the feature.
bind_arguments(arguments)	Binds another feature’s properties as arguments to this feature.
get(image, **kwargs)	Transform an image [abstract method].
plot([input_image, resolve_kwargs, interval])	Visualizes the output of the feature.
resolve([image_list, _ID])	Execute the feature or pipeline.
seed([_ID])	Seed the random number generator.
store_properties([toggle, recursive])	Control whether to return an Image object.
torch([dtype, device, permute_mode])	Convert the feature to a PyTorch feature.
update(**global_arguments)	Refreshes the feature to generate a new output.

Methods Documentation

__call__(image_list: np.ndarray | list[np.ndarray] | Image | list[Image] = None, _ID: tuple[int, ...] = (), **kwargs: dict[str, Any]) → Any

Execute the feature or pipeline.

This method executes the feature or pipeline on the provided input and updates the computation graph if necessary. It handles overriding properties using additional keyword arguments.

The actual computation is performed by calling the parent __call__ method in the DeepTrackNode class, which manages lazy evaluation and caching.

Parameters

image_list: np.ndarrray or list[np.ndarrray] or Image or list of Images, optional

The input to the feature or pipeline. If None, the feature uses previously set input values or propagates properties.

**kwargs: dict of str to Any

Additional parameters passed to the pipeline. These override properties with matching names. For example, calling feature(x, value=4) executes feature on the input x while setting the property value to 4. All features in a pipeline are affected by these overrides.

Returns

Any

The output of the feature or pipeline after execution.

action(_ID: tuple[int, ...] = ()) → Image | list[Image]

Core logic to create or transform the image.

This method creates or transforms the input image by calling the get() method with the correct inputs.

Parameters

_ID: tuple of int

The unique identifier for the current execution.

Returns

Image or list of Images

The resolved image or list of resolved images.

add_feature(feature: Feature) → Feature

Adds a feature to the dependecy graph of this one.

Parameters

feature: Feature

The feature to add as a dependency.

Returns

Feature

The newly added feature (for chaining).

batch(batch_size: int = 32) → tuple | list[Image]

Batch the feature.

This method produces a batch of outputs by repeatedly calling update() and __call__().

Parameters

batch_size: int

The number of times to sample or generate data.

Returns

tuple or list of Images

A tuple of stacked arrays (if the outputs are NumPy arrays or torch tensors) or a list of images if the outputs are not stackable.

bind_arguments(arguments: Feature) → Feature

Binds another feature’s properties as arguments to this feature.

This method allows properties of arguments to be dynamically linked to this feature, enabling shared configurations across multiple features. It is commonly used in advanced feature pipelines.

See Also

features.Arguments

A utility that helps manage and propagate feature arguments efficiently.

Parameters

arguments: Feature

The feature whose properties will be bound as arguments to this feature.

Returns

Feature

The current feature instance with bound arguments.

get(image: np.ndarray | list[np.ndarray] | Image | list[Image], **kwargs: dict[str, Any]) → Image | list[Image]

Transform an image [abstract method].

Abstract method that defines how the feature transforms the input. The current value of all properties will be passed as keyword arguments.

Parameters

image: np.ndarray or list of np.ndarray or Image or list of Images

The image or list of images to transform.

**kwargs: dict of str to Any

The current value of all properties in properties, as well as any global arguments passed to the feature.

Returns

Image or list of Images

The transformed image or list of images.

Raises

NotImplementedError

Raised if this method is not overridden by subclasses.

plot(input_image: np.ndarray | list[np.ndarray] | Image | list[Image] = None, resolve_kwargs: dict = None, interval: float = None, **kwargs) → Any

Visualizes the output of the feature.

This method resolves the feature and visualizes the result. If the output is an Image, it displays it using pyplot.imshow. If the output is a list, it creates an animation. In Jupyter notebooks, the animation is played inline using to_jshtml(). In scripts, the animation is displayed using the matplotlib backend.

Any parameters in kwargs are passed to pyplot.imshow.

Parameters

input_image: np.ndarray or list np.ndarray or Image or list of Image, optional

The input image or list of images passed as an argument to the resolve call. If None, uses previously set input values or propagates properties.

resolve_kwargs: dict, optional

Additional keyword arguments passed to the resolve call.

interval: float, optional

The time between frames in the animation, in milliseconds. The default value is 33 ms.

**kwargs: dict, optional

Additional keyword arguments passed to pyplot.imshow.

Returns

Any

The output of the feature or pipeline after execution.

resolve(image_list: np.ndarray | list[np.ndarray] | Image | list[Image] = None, _ID: tuple[int, ...] = (), **kwargs: dict[str, Any]) → Any

Execute the feature or pipeline.

This method executes the feature or pipeline on the provided input and updates the computation graph if necessary. It handles overriding properties using additional keyword arguments.

The actual computation is performed by calling the parent __call__ method in the DeepTrackNode class, which manages lazy evaluation and caching.

Parameters

image_list: np.ndarrray or list[np.ndarrray] or Image or list of Images, optional

The input to the feature or pipeline. If None, the feature uses previously set input values or propagates properties.

**kwargs: dict of str to Any

Additional parameters passed to the pipeline. These override properties with matching names. For example, calling feature(x, value=4) executes feature on the input x while setting the property value to 4. All features in a pipeline are affected by these overrides.

Returns

Any

The output of the feature or pipeline after execution.

seed(_ID: tuple[int, ...] = ()) → None

Seed the random number generator.

Parameters

_ID: tuple[int, …], optional

Unique identifier for parallel evaluations.

store_properties(toggle: bool = True, recursive: bool = True) → None

Control whether to return an Image object.

If selected True, the output of the evaluation of the feature is an Image object that also contains the properties.

Parameters

toggle: bool

If True, store properties. If False, do not store.

recursive: bool

If True, also set the same behavior for all dependent features.

torch(dtype: torch.dtype = None, device: torch.device = None, permute_mode: str = 'never') → Feature

Convert the feature to a PyTorch feature.

Parameters

dtype: torch.dtype, optional

The data type of the output.

device: torch.device, optional

The target device of the output (e.g., CPU or GPU).

permute_mode: str

Controls whether to permute image axes for PyTorch. Defaults to “never”.

Returns

Feature

The transformed, PyTorch-compatible feature.

update(**global_arguments: Any) → Feature

Refreshes the feature to generate a new output.

By default, when a feature is called multiple times, it returns the same value. Calling update() forces the feature to recompute and return a new value the next time it is evaluated.

Parameters

**global_arguments: Any

Optional global arguments that can be passed to modify the feature update behavior.

Returns

Feature

The updated feature instance, ensuring the next evaluation produces a fresh result.