Configuration Guide

SwarmSort is highly configurable to adapt to different tracking scenarios. This guide covers all configuration options and their relationships.

Important

Understanding max_distance: The max_distance parameter is the foundation of SwarmSort’s configuration. It should be set higher than the maximum expected movement between frames because:

• The actual matching uses a combination of spatial distance, embedding similarity, and uncertainty

• With embeddings enabled, the effective matching distance is reduced by visual similarity

• Uncertainty penalties further modify the association costs

• A good starting point is 1.5-2x the expected maximum pixel movement between frames

Example: If objects move up to 100 pixels between frames, set max_distance=150 to account for matching uncertainties.

Configuration Overview Table

SwarmSort Configuration Parameters

Parameter	Default	Type	Description
Core Tracking
max_distance	80.0	float	Base distance for association (see note above)
detection_conf_threshold	0.0	float	Minimum confidence to process detections
max_track_age	30	int	Frames before track deletion (30 = 1s at 30fps)
deduplication_distance	10.0	float	Min distance between detections (NMS-style)
Motion Modeling
kalman_type	‘simple’	str	‘simple’ or ‘oc’ (OC-SORT style)
Uncertainty System
uncertainty_weight	0.33	float	Weight for uncertainty penalties (0=disabled)
local_density_radius	max_distance	float	Radius for density computation (defaults to max_distance)
Embeddings
do_embeddings	True	bool	Enable visual feature matching
embedding_weight	1.0	float	Weight of appearance vs motion
max_embeddings_per_track	15	int	Embedding history size per track
embedding_matching_method	‘weighted_average’	str	‘average’, ‘weighted_average’, ‘best_match’, or ‘median’
embedding_function	‘cupytexture’	str	Feature extractor: ‘cupytexture’, ‘cupytexture_color’, ‘cupytexture_mega’
embedding_threshold_adjustment	1.0	float	Gating threshold expansion factor
store_embedding_scores	False	bool	Store match scores in TrackedObject
embedding_score_history_length	5	int	Number of recent scores to keep per track
Embedding Scaling
embedding_scaling_method	‘min_robustmax’	str	Distance normalization method
embedding_scaling_update_rate	0.05	float	Learning rate for scaling statistics
embedding_scaling_min_samples	200	int	Samples before scaling activation
Collision Handling
collision_freeze_embeddings	True	bool	Freeze embeddings when tracks are close
embedding_freeze_density	1	int	Number of nearby tracks to trigger freeze
collision_safety_distance	30.0	float	Distance threshold for collision detection
Assignment Strategy
assignment_strategy	‘hybrid’	str	‘hungarian’, ‘greedy’, or ‘hybrid’
greedy_threshold	max_distance/5	float	Distance for greedy matching (default: 30.0 when max_distance=150)
hungarian_fallback_threshold	1.0	float	Multiplier of max_distance for Hungarian fallback
sparse_computation_threshold	300	int	Object count threshold for sparse mode
use_probabilistic_costs	False	bool	Use Mahalanobis distance for costs
greedy_confidence_boost	1.0	float	Confidence boost for greedy matches
Track Initialization
min_consecutive_detections	6	int	Detections needed to confirm track
max_detection_gap	2	int	Max frame gap during initialization
pending_detection_distance	80.0	float	Distance threshold for pending detections
init_conf_threshold	0.0	float	Min confidence to start tracking
Re-identification
reid_enabled	True	bool	Enable track re-identification
reid_max_distance	150.0	float	Maximum distance for ReID
reid_embedding_threshold	0.3	float	Embedding similarity for ReID
reid_min_frames_lost	2	int	Frames lost before ReID attempt
Probabilistic Mode
base_position_variance	15.0	float	Base uncertainty in pixels²
velocity_variance_scale	2.0	float	Velocity contribution to uncertainty
velocity_isotropic_threshold	0.1	float	Threshold for circular covariance
time_covariance_inflation	0.1	float	Uncertainty growth per missed frame
mahalanobis_normalization	5.0	float	Scale factor for Mahalanobis distance
probabilistic_gating_multiplier	1.5	float	Pre-filter threshold expansion
singular_covariance_threshold	1e-6	float	Fallback to Euclidean threshold
Debug Settings
debug_embeddings	False	bool	Print embedding debug info
plot_embeddings	False	bool	Generate embedding plots (requires matplotlib)
debug_timings	True	bool	Print per-frame timing info

Parameter Relationships

Several parameters are dynamically linked to max_distance by default:

# Default relationships when not explicitly set:
local_density_radius = max_distance          # Same as max_distance
greedy_threshold = max_distance / 5          # 20% of max_distance
hungarian_fallback_threshold = 1.0           # 1x max_distance
reid_max_distance = max_distance            # Same as max_distance

This means changing max_distance automatically scales related parameters:

# Example: Adjusting for faster movement
config = SwarmSortConfig(max_distance=200)
# Automatically sets:
# - local_density_radius = 200
# - greedy_threshold = 40
# - reid_max_distance = 200

Core Parameters Detailed

Motion Modeling

kalman_type{‘simple’, ‘oc’}, default=’simple’

Type of Kalman filter for motion prediction.

• ‘simple’: Constant velocity model (faster)

• ‘oc’: OC-SORT style with acceleration (better for erratic motion)

Uncertainty System

uncertainty_weightfloat, default=0.33

Weight for uncertainty penalties in cost computation.

• 0.0: Disable uncertainty system (aggressive matching)

• 0.5: Balanced approach

• 1.0: Very conservative matching

local_density_radiusfloat, default=max_distance

Radius for computing local track density.

Embedding Features

do_embeddingsbool, default=True

Whether to use visual embeddings for matching.

embedding_weightfloat, default=1.0

Weight of embedding similarity in the cost function.

• 0: Only use motion

• 1: Equal weight to motion and appearance

• >1: Trust appearance more than motion

max_embeddings_per_trackint, default=15

Maximum number of embeddings stored per track.

embedding_matching_method{‘average’, ‘weighted_average’, ‘best_match’, ‘median’}, default=’weighted_average’

Method for matching multiple embeddings.

• ‘average’: Mean distance to all stored embeddings

• ‘weighted_average’: Recent embeddings weighted more (recommended)

• ‘best_match’: Minimum distance (most similar embedding wins)

• ‘median’: Median distance (robust to outliers)

embedding_functionstr, default=’cupytexture’

Feature extractor algorithm for visual embeddings.

• ‘cupytexture’: Fast texture-based features (GPU-accelerated)

• ‘cupytexture_color’: Includes color information

• ‘cupytexture_mega’: Most detailed features (slower)

embedding_threshold_adjustmentfloat, default=1.0

Expands the gating threshold for embedding-based matching. Effective max distance = max_distance × (1 + embedding_weight × embedding_threshold_adjustment).

store_embedding_scoresbool, default=False

When True, stores embedding match scores in TrackedObject for visualization/debugging.

Embedding Scaling

embedding_scaling_methodstr, default=’min_robustmax’

Method for normalizing embedding distances to [0,1] range.

embedding_scaling_update_ratefloat, default=0.05

Learning rate for updating scaling statistics (0.0 to 1.0).

embedding_scaling_min_samplesint, default=200

Minimum samples before embedding scaling is activated.

Collision Handling

collision_freeze_embeddingsbool, default=True

Freeze embedding updates when tracks are close together.

embedding_freeze_densityint, default=1

Number of nearby tracks to trigger embedding freeze.

collision_safety_distancefloat, default=30.0

Distance threshold below which objects are considered in collision.

Assignment Strategy

assignment_strategy{‘hungarian’, ‘greedy’, ‘hybrid’}, default=’hybrid’

Algorithm for detection-track assignment.

• ‘hungarian’: Optimal but slower

• ‘greedy’: Fast but suboptimal

• ‘hybrid’: Best of both worlds

greedy_thresholdfloat, default=30.0

Distance threshold for greedy assignment in hybrid mode.

sparse_computation_thresholdint, default=300

Object count threshold for switching to sparse computation mode.

use_probabilistic_costsbool, default=False

When True, use Mahalanobis distance instead of Euclidean for cost computation.

greedy_confidence_boostfloat, default=1.0

Confidence multiplier for greedy matches in hybrid mode.

Track Initialization

min_consecutive_detectionsint, default=6

Minimum detections required to confirm a track.

• Lower: Faster response, more false positives

• Higher: Slower response, fewer false positives

max_detection_gapint, default=2

Maximum frame gap allowed during track initialization.

pending_detection_distancefloat, default=80.0

Distance threshold for matching pending detections.

init_conf_thresholdfloat, default=0.0

Minimum confidence score to start tracking an object (0.0 to 1.0).

Re-identification

reid_enabledbool, default=True

Enable re-identification of lost tracks.

reid_max_distancefloat, default=150.0

Maximum distance for re-identification.

reid_embedding_thresholdfloat, default=0.3

Embedding similarity threshold for re-identification.

reid_min_frames_lostint, default=2

Minimum frames a track must be lost before attempting ReID.

Probabilistic Mode

Enable probabilistic mode with use_probabilistic_costs=True for Mahalanobis distance-based matching.

base_position_variancefloat, default=15.0

Base uncertainty in position (pixels²).

velocity_variance_scalefloat, default=2.0

Velocity contribution to uncertainty computation.

velocity_isotropic_thresholdfloat, default=0.1

Speed threshold below which covariance becomes circular (isotropic).

time_covariance_inflationfloat, default=0.1

Uncertainty growth rate per missed frame.

mahalanobis_normalizationfloat, default=5.0

Scale factor for Mahalanobis distance normalization.

probabilistic_gating_multiplierfloat, default=1.5

Pre-filter threshold expansion for probabilistic mode.

singular_covariance_thresholdfloat, default=1e-6

Threshold for detecting singular covariance matrices; falls back to Euclidean.

Debug Settings

debug_embeddingsbool, default=False

Print detailed embedding information for debugging.

plot_embeddingsbool, default=False

Generate embedding visualization plots (requires matplotlib).

debug_timingsbool, default=True

Print per-frame timing information for performance analysis.

Configuration Examples

Microscopy Tracking

config = SwarmSortConfig(
    max_distance=50.0,                  # Small movements
    kalman_type='simple',               # Predictable motion
    min_consecutive_detections=3,       # Quick initialization
    assignment_strategy='hybrid',       # Handle many objects
    uncertainty_weight=0.2              # Low uncertainty
)

Surveillance Camera

config = SwarmSortConfig(
    do_embeddings=True,
    embedding_weight=1.5,               # Appearance important
    reid_enabled=True,                  # Re-identify people
    reid_max_distance=200.0,
    max_track_age=60                    # Keep tracks longer
)

Sports Analytics

config = SwarmSortConfig(
    max_distance=150.0,
    kalman_type='oc',                   # Handle acceleration
    detection_conf_threshold=0.5,       # Only clear detections
    assignment_strategy='hungarian',    # Accurate assignment
    min_consecutive_detections=2        # Fast player detection
)

Loading from YAML

You can also load configuration from a YAML file:

# swarmsort_config.yaml
max_distance: 150.0
detection_conf_threshold: 0.3
do_embeddings: true
embedding_weight: 1.0
assignment_strategy: hybrid
min_consecutive_detections: 4

from swarmsort import SwarmSortConfig, SwarmSortTracker

config = SwarmSortConfig.from_yaml('swarmsort_config.yaml')
tracker = SwarmSortTracker(config)