playnano.analysis.modules.particle_tracking module

Module for linking particle features across frames to build trajectories.

This module defines the ParticleTrackingModule, which links features detected in sequential frames of an AFM image stack using nearest-neighbor matching based on feature centroids.

Features are matched across frames if they lie within a specified maximum distance. Tracks are formed by chaining these matches over time.

Each resulting track includes:

• A unique track ID

• A list of frames where the particle appears

• A list of point indices referencing the original features

• A list of centroids describing the particle’s positions

Optionally, per-track masks are extracted from the labeled feature masks.

class playnano.analysis.modules.particle_tracking.ParticleTrackingModule

Bases: AnalysisModule

Link detected features frame-to-frame to produce particle trajectories.

This module links features detected by a prior featuredetection module using nearest-neighbor centroid matching across adjacent frames. A new track is created for each unmatched feature.

Version

0.1.0

property name: str

Name of the analysis module.

Returns:

Unique identifier: “particle_tracking”.

Return type:

str

requires = ['feature_detection', 'log_blob_detection']

run(stack: AFMImageStack, previous_results: dict[str, Any] | None = None, detection_module: str = 'feature_detection', coord_key: str = 'features_per_frame', coord_columns: Sequence[str] = ('centroid_x', 'centroid_y'), max_distance: float = 5.0, **params) → dict[str, Any]

Track particles across frames using nearest-neighbor association.

Parameters:

• stack (AFMImageStack) – The input AFM image stack.

• previous_results (dict[str, Any], optional) –

  Must contain results from a detection module, including:

  • coord_key (e.g., “features_per_frame”): list of dicts with per-frame features

  • ”labeled_masks”: per-frame mask of label regions

• detection_module (str, optional) – Which module to read features from (default: “feature_detection”).

• coord_key (str, optional) – Key in previous_results[detection_module] containing per-frame feature dicts (default: “features_per_frame”).

• coord_columns (Sequence[str], optional) – Keys to extract coordinates from each feature; falls back to “centroid” if needed. Default is (“centroid_x”, “centroid_y”)).

• max_distance (float, optional) – Maximum allowed movement per frame in coordinate units (default: 5.0).

Returns:

Dictionary with keys:

• trackslist of dict

  Per-track dictionaries containing:

  • id : int Track ID

  • frames : list of int Frame indices

  • point_indices : list of int Indices into features_per_frame

  • centroids : list of tuple[float, float] (x, y) positions of the tracked points

• track_masks : dict[int, np.ndarray] Last mask per track

• n_tracks : int Total number of tracks

Return type:

dict

version = '0.1.0'