swarmsort.kalman_filters module

SwarmSort Kalman Filtering Module

This module provides Kalman filtering implementations for object tracking, including both simple and OC-SORT style filters for motion prediction and state estimation.

Functions:

simple_kalman_update: Simple Kalman filter update step simple_kalman_predict: Simple Kalman filter prediction step simple_kalman_predict_with_damping: Predict with configurable damping oc_sort_predict: OC-SORT style prediction using observation history oc_sort_update: OC-SORT style update for observation history compute_oc_sort_cost_matrix: OC-SORT style cost matrix computation

Constants:

DEFAULT_VELOCITY_DAMPING: Default velocity damping factor (0.95) DEFAULT_UPDATE_ALPHA: Default measurement weight in update (0.7) DEFAULT_VELOCITY_WEIGHT: Default velocity consistency weight (0.2)

swarmsort.kalman_filters.DEFAULT_UPDATE_ALPHA: float = 0.7

Default measurement weight in Kalman update (alpha blend factor).

swarmsort.kalman_filters.DEFAULT_VELOCITY_BETA: float = 0.3

Default velocity correction gain in alpha-beta filter. Lower values = smoother velocity, higher = more responsive.

swarmsort.kalman_filters.DEFAULT_VELOCITY_DAMPING: float = 0.95

Default velocity damping factor applied during prediction.

swarmsort.kalman_filters.DEFAULT_VELOCITY_WEIGHT: float = 0.2

Default weight for velocity consistency in OC-SORT cost computation.

swarmsort.kalman_filters.compute_oc_sort_cost_matrix(det_positions, track_last_observed_positions, track_velocities, track_misses, max_distance, velocity_weight=0.2)[source]

OC-SORT style cost computation with adaptive thresholds.

Parameters:

  • det_positions (ndarray) – Detection positions [N_det, 2]

  • track_last_observed_positions (ndarray) – Last observed track positions [N_track, 2]

  • track_velocities (ndarray) – Track velocities [N_track, 2]

  • track_misses (ndarray) – Number of misses for each track [N_track]

  • max_distance (float) – Maximum allowed distance for matching

  • velocity_weight (float) – Weight for velocity consistency term

Return type:

ndarray

Returns:

Cost matrix [N_det, N_track]

swarmsort.kalman_filters.oc_sort_predict(observation_history, observation_frames, current_frame)[source]

OC-SORT style prediction using observation history.

Parameters:

  • observation_history (ndarray) – Array of past observations [N, 2]

  • observation_frames (ndarray) – Array of frame numbers for observations [N]

  • current_frame (int) – Current frame number

Return type:

ndarray

Returns:

Predicted state [x, y, vx, vy]

swarmsort.kalman_filters.oc_sort_update(observation_history, observation_frames, new_observation, current_frame, max_history=30)[source]

OC-SORT style update - stores observations without filtering.

Parameters:

  • observation_history (ndarray) – Current observation history [N, 2]

  • observation_frames (ndarray) – Current frame history [N]

  • new_observation (ndarray) – New observation [2]

  • current_frame (int) – Current frame number

  • max_history (int) – Maximum history size

Return type:

Tuple[ndarray, ndarray]

Returns:

Tuple of (updated_history, updated_frames)

swarmsort.kalman_filters.simple_kalman_predict(x)[source]

Simplified Kalman prediction with default damping.

DEPRECATED: This function uses hardcoded DEFAULT_VELOCITY_DAMPING (0.95). Use simple_kalman_predict_with_damping() with config.kalman_velocity_damping instead. Kept for backward compatibility only.

Parameters:

x (ndarray) – Current state [x, y, vx, vy]

Return type:

ndarray

Returns:

Predicted state vector

swarmsort.kalman_filters.simple_kalman_predict_with_damping(x, damping)[source]

Simplified Kalman prediction with configurable damping.

Parameters:

  • x (ndarray) – Current state [x, y, vx, vy]

  • damping (float) – Velocity damping factor (0-1). Use config.kalman_velocity_damping.

Return type:

ndarray

Returns:

Predicted state vector

swarmsort.kalman_filters.simple_kalman_update(x_pred, z, is_reid=False, alpha=0.7, beta=0.3)[source]

Alpha-beta filter update with velocity correction.

This implements a proper alpha-beta filter where: - Alpha controls position smoothing (higher = trust measurement more) - Beta controls velocity correction from innovation (higher = more responsive)

Parameters:

  • x_pred (ndarray) – Predicted state [x, y, vx, vy]

  • z (ndarray) – Measurement [x, y]

  • is_reid (bool) – Whether this update is for re-identification (resets velocity)

  • alpha (float) – Position measurement weight (0-1). Default: 0.7

  • beta (float) – Velocity correction gain (0-1). Default: 0.3

Return type:

ndarray

Returns:

Updated state vector [x, y, vx, vy]