cli: add hyperparameter tuning for trackers

[SkalskiP]

Description

Add a trackers tune CLI subcommand that runs hyperparameter optimization for any registered tracker. The tuner takes pre-computed detections (MOT format) and ground-truth annotations, repeatedly instantiates the tracker with different parameter configurations proposed by Optuna, evaluates each configuration using the existing evaluate_mot_sequences engine, and reports the best-found parameters.

# Basic usage — tune ByteTrack on MOT17 with 100 trials
trackers tune \
  --tracker bytetrack \
  --gt-dir path/to/gt/ \
  --detections-dir path/to/detections/ \
  --n-trials 100

# Pick objective metric and metric families to compute
trackers tune \
  --tracker sort \
  --gt-dir path/to/gt/ \
  --detections-dir path/to/detections/ \
  --metrics HOTA MOTA IDF1 \
  --objective HOTA \
  --n-trials 200

Search space definition

Each tracker declares a search_space class variable alongside its __init__ parameters.

class ByteTrackTracker(BaseTracker):
    search_space: ClassVar[dict[str, dict]] = {
        "lost_track_buffer": {"type": "randint", "range": [10, 61]},
        "track_activation_threshold": {"type": "uniform", "range": [0.5, 0.9]},
        "minimum_iou_threshold": {"type": "uniform", "range": [0.05, 0.5]},
        "high_conf_det_threshold": {"type": "uniform", "range": [0.3, 0.8]},
    }

Tasks

• Define search_space: ClassVar[dict[str, dict]] on SORTTracker and ByteTrackTracker with sensible ranges for each tunable parameter. Validate that every key in search_space matches a parameter name in __init__.
• Implement a Tuner class that wraps an Optuna study: converts search_space to Optuna distributions, runs trials calling the objective function.
• Register the tune subcommand in trackers/scripts/__main__.py with arguments: --tracker, --gt-dir, --detections-dir, --metrics, --objective, --n-trials, --output, --resume.
• Add optuna as an optional dependency under trackers[tune] in pyproject.toml.
• Document usage: expected input format for detections-dir and gt-dir, how to generate detections with trackers track, example commands, and the meaning of output files.

[omkar-334]

hey @SkalskiP i'm working on this

[SkalskiP]

Hi @omkar-334, I assigned you to this task. It is quite complex. I would like us to break it down into 3 smaller PRs.

1. Search space definitions

• Add search_space ClassVar to SORTTracker and ByteTrackTracker and validate it in BaseTracker.__init_subclass__.
• Add validation in __init_subclass__ that every key in search_space exists in the __init__ signature.
• search_space is optional (trackers without it still work).
• If present, every key must match a param name in __init__; mismatch raises ValueError.

2. Tuner class + objective function

• Tuner class that wraps Optuna and an internal objective function.
• Update pyproject.toml with new optional dependency.
• Run evaluation with evaluate_mot_sequences from trackers/eval/evaluate.py.
• Each trial must call tracker reset() method.
• Tuner.run() creates an Optuna study, runs trials, returns best params dict

3. CLI subcommand

• Wire the Tuner into a trackers tune subcommand following the exact pattern of trackers eval.
• CLI arguments:
  • --tracker (required, choices from BaseTracker._registered_trackers())
  • --gt-dir (required, Path)
  • --detections-dir (required, Path)
  • --objective (optional, default "HOTA")
  • --n-trials (optional, int, default 100)
  • --output (optional, Path for results JSON)

[SkalskiP]

This #291 is a draft PR that will hold the code for this task until all stages are ready to be merged.

[SkalskiP]

Hi @omkar-334 will you be working on part 2?

[omkar-334]

yes @SkalskiP im working on it. will make a PR very soon

[SkalskiP]

Hi @omkar-334 I'm so happy to hear that. 🔥