SwarmSort Documentation
High-performance multi-object tracking optimized for microscopy and scenarios with hundreds of objects
SwarmSort is a standalone Python library for real-time multi-object tracking (MOT) that maintains consistent object identities across video frames. It implements state-of-the-art algorithms including uncertainty-based cost systems, smart embedding freezing for collision scenarios, and hybrid assignment strategies to achieve robust tracking in challenging conditions.
Quick Start
from swarmsort import SwarmSortTracker, Detection, SwarmSortConfig
import numpy as np
# Configure tracker for your use case
config = SwarmSortConfig(
max_distance=150.0, # Maximum association distance
uncertainty_weight=0.33, # Enable uncertainty-aware tracking
assignment_strategy='hybrid', # Smart assignment strategy
do_embeddings=True # Use visual features
)
tracker = SwarmSortTracker(config)
# Process detections from your detector
detections = [
Detection(position=np.array([100, 200]), confidence=0.9),
Detection(position=np.array([300, 400]), confidence=0.85)
]
# Get tracked objects with persistent IDs
tracked_objects = tracker.update(detections)
for obj in tracked_objects:
print(f"Track {obj.id}: position {obj.position}")
Key Features
- Robust Identity Management
Maintains consistent IDs through occlusions, crossings, and disappearances using motion prediction and visual re-identification.
- Uncertainty-Aware Association
Adaptive cost computation based on track age, local density, and detection reliability for robust tracking.
- Smart Collision Handling
Prevents ID switches in dense scenarios through intelligent embedding freezing and density-based adaptation.
- Real-Time Performance
30-120 FPS through Numba JIT compilation, vectorized operations, and optional GPU acceleration.
- Production Ready
200+ unit tests, cross-platform support, and comprehensive error handling.
Contents
Getting Started