SwarmSort Documentation

SwarmSort Demo

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=80.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.

How It Works

SwarmSort uses a position-centric additive cost model for detection-track association:

cost = position_distance + embedding_weight × embedding_distance × max_distance

Tracking Pipeline:

  1. Motion Prediction - Kalman filter predicts track positions

  2. Cost Computation - Calculate association costs (spatial + appearance)

  3. Assignment - Match detections to tracks (Hungarian/greedy/hybrid)

  4. Track Management - Confirm new tracks, delete lost tracks

  5. Re-identification - Recover lost tracks using visual features

Contents

Getting Started

Reference

Indices and Tables