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‘Image’ or List[‘Image’], optional

Defines a list of DeepTrackNode objects that calculate the input of the feature. In most cases, this can be left empty.

**kwargsDict[str, Any]

All Keyword arguments will be wrapped as instances of Property and included in the properties attribute.

Attributes

propertiesPropertyDict

A dict that contains all keyword arguments passed to the constructor wrapped as Distributions. A sampled copy of this dict is sent as input to the get function, and is appended to the properties field of the output image.

__list_merge_strategy__int

Controls how the output of .get(image, **kwargs) is merged with the input list. It can be MERGE_STRATEGY_OVERRIDE (0, default), where the input is replaced by the new list, or MERGE_STRATEGY_APPEND (1), where the new list is appended to the end of the input list.

__distributed__bool

Controls whether .get(image, **kwargs) is called on each element in the list separately (__distributed__ = True), or if it is called on the list as a whole (__distributed__ = False).

__property_memorability__int

Controls whether to store the features properties to the Image. Values 1 or lower will be included by default.

__conversion_table__ConversionTable

A ConversionTable that is used to convert properties of the feature to the desired units.

__gpu_compatible__bool

Controls whether to use GPU acceleration for the feature.

Methods

get(

image: Union[‘Image’, List[‘Image’]], **kwargs: Any

) -> Union[‘Image’, List[‘Image’]]

Abstract method that defines how the feature transforms the input.

__call__(image_list: Optional[Union[Image, List[Image]]] = 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: Optional[torch.dtype] = None, device: Optional[torch.device] = None,

permute_mode: str = “never”) -> ‘Feature’

Converts the feature into a PyTorch-compatible feature.

batch(batch_size: int = 32) -> Union[tuple, List[Image]]

Batches the feature for repeated execution.

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

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

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)	Bind 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)	Refresh the feature to create a new image.

Methods Documentation

__call__(image_list: Image | List[Image] | None = 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.

Arguments

image_list‘Image’ or List[‘Image’], optional

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

**kwargsDict[str, 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.

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

Parameters

_IDTuple[int, …]

The ID of the current execution.

Returns

Image or List[Image]

The resolved image or list of images.

add_feature(feature: Feature) → Feature

Adds a feature to the dependecy graph of this one.

Parameters

featureFeature

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.

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

Parameters

batch_sizeint

Number of times to sample or generate data.

Returns

tuple or List[‘Image’]

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

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

Often used internally by advanced features or pipelines.

See features.Arguments.

get(image: 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‘Image’ or List[‘Image’]

The Image or list of images to transform.

**kwargsDict[str, Any]

The current value of all properties in properties as well as any global arguments.

Returns

‘Image’ or List[‘Image’]

The transformed image or list of images.

Raises

NotImplementedError

Must be overridden by subclasses.

plot(input_image: Image | None = None, resolve_kwargs: dict | None = None, interval: float | None = None, **kwargs)

Visualizes the output of the feature.

Resolves the feature and visualizes the result. If the output is an Image, show it using pyplot.imshow. If the output is a list, create an Animation. For notebooks, the animation is played inline using to_jshtml(). For scripts, the animation is played using the matplotlib backend.

Any parameters in kwargs will be passed to pyplot.imshow.

Parameters

input_imageImage or List[Image], optional

Passed as argument to resolve call

resolve_kwargsdict, optional

Passed as kwarg arguments to resolve call

intervalfloat

The time between frames in animation in ms. Default 33.

kwargs

keyword arguments passed to the method pyplot.imshow()

resolve(image_list: Image | List[Image] | None = 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.

Arguments

image_list‘Image’ or List[‘Image’], optional

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

**kwargsDict[str, 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

_IDTuple[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

togglebool

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

recursivebool

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

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

Convert the feature to a PyTorch feature.

Parameters

dtypetorch.dtype, optional

The data type of the output.

devicetorch.device, optional

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

permute_modestr

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

Returns

Feature

The transformed, PyTorch-compatible feature.

update(**global_arguments) → Feature

Refresh the feature to create a new image.

Per default, when a feature is called multiple times, it will return the same value. To tell the feature to return a new value, first call update().

Returns

Feature

The updated feature.