Overview

Parameter	Default	Purpose	Effect of Increasing	Effect of Decreasing	Use Case Tip
`max_age`	`30`	Frames a track survives without detection.	Longer track persistence (handles occlusions better).	Tracks terminate faster (reduces stale tracks).	Increase for crowded/occluded scenes.
`n_init`	`3`	Detections needed to start a new track.	More reliable tracks (fewer false positives).	Faster track initiation (but more noise).	Decrease for rapid-moving objects.
`max_iou_distance`	`0.7`	IoU threshold for motion-based matching.	More tolerant to large movements/occlusions.	Stricter position matching (reduces mismatches).	Increase for erratic motion.
`max_cosine_distance`	`0.2`	Threshold for appearance-based Re-ID.	Looser Re-ID (more ID switches).	Stricter Re-ID (fewer switches but may drop tracks).	Decrease for distinct appearances.
`nn_budget`	`100`	Max stored appearance features per track.	Better Re-ID accuracy (higher memory).	Lower memory usage (may reduce accuracy).	Adjust based on GPU memory.
`nms_max_overlap`	`1.0`	Overlap threshold for Non-Max Suppression.	Allows more overlapping tracks.	Aggressive suppression (reduces duplicates).	Set to `1.0` for crowded scenes.
`gating_threshold`	`None`	Mahalanobis distance threshold for gating.	More permissive to motion uncertainty.	Stricter motion consistency checks.	Tune if Kalman filter is unstable.

More Clarification on Some Parameters

Definition: Threshold for appearance-based matching (range: 0 to 1).
Mechanics:
- Compares the cosine similarity between stored appearance features (Re-ID embeddings) of tracks and new detections.
- Lower values (e.g., 0.2) enforce stricter matching, reducing ID switches but increasing missed matches.
- Higher values (e.g., 0.4) tolerate more appearance variation but risk incorrect associations.
Impact: Directly controls the trade-off between track continuity and false positives.

Definition: Threshold for Non-Maximum Suppression (NMS) to filter overlapping detections (range: 0 to 1).
Mechanics:
- 1.0 disables NMS, allowing full overlap (useful for crowded scenes with occluded objects).
- Lower values (e.g., 0.5) suppress detections with high overlap, reducing duplicates but potentially splitting tracks.
Impact: Balances between track fragmentation (low values) and overcounting (high values).

Definition: Mahalanobis distance threshold to validate motion-based matches (Kalman filter predictions).
Mechanics:
- Filters implausible matches by comparing predicted vs. observed positions.
- Higher values allow more uncertainty in motion (useful for erratic movement).
- Lower values enforce strict motion consistency (reduces mismatches but may drop valid tracks).
Impact: Mitigates drift in Kalman filter predictions during occlusions or rapid motion.

Appearance Features:
- High-dimensional vectors (e.g., 128-D) extracted by a Re-ID model (e.g., CNN) encoding object appearance.
- Stored for each track to re-identify objects after occlusions.
Why GPU Memory?
- Computation: Re-ID models run on GPUs for parallel processing of deep learning operations (matrix multiplications).
- Storage: Features are cached in GPU memory during inference for real-time matching.
- nn_budget: Limits the number of features stored per track to prevent GPU memory exhaustion. Higher budgets improve Re-ID but demand more VRAM.