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 coordinates.

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 spanned by the track (first→last detection)

• A list of point indices aligned with frames; missing detections are None

• A list of coordinates describing the particle’s positions

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

See also

playnano.analysis.modules.feature_detection

Mask based particle detection method.

playnano.analysis.modules.log_blob_detection

LoG-based particle detection method.

, Author, ------, Daniel, AI, --------------------, AI-based, and, refactoring, and, algorithms, and

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 feature detection module using nearest-neighbor coordinate matching across adjacent frames. A new track is created for each unmatched feature.

Version

0.2.0

Version 0.2.0 allows tracks to continue across missing detections and supports scaling the distance threshold with time since last detection.

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, max_missing: int = 0, distance_scale: str = 'constant', **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).

• max_missing (int, optional) – Maximum allowed consecutive missing detections before terminating a track. Default is 0 (no missing allowed).

• distance_scale (str, optional) – How to scale max_distance with time since last detection in frames: “constant” (default), “linear” (scale linearly with time), or “sqrt” (scale with square root of time).

Returns:

Dictionary with keys:

• trackslist of dict

  Per-track dictionaries containing:

  • id : int Track ID

  • frames : list[int] Frame indices spanned by track

  • point_indices : list[Optional[int]] Indices into features_per_frame

  • coords : list[Optional[tuple[float, float]]] Coordinates (coord0, coord1) aligned with frames; None indicates missing detection.

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

• n_tracks : int Total number of tracks

Return type:

dict

version = '0.2.0'