Feat/dynamic frame rate integration

[AlexBodner]

What does this PR do?

This PR introduces Dynamic frame rate feature, which is activated by passing a timestamp to the tracker update function.

It is implemented in the State Estimator layer via an interaction with the new class KalmanMotionModel which handles the logic of swapping the motion model and noise matrices for the used model. Then, this is dispatched until tracklet predict level.

When using dynamic frame rate, we still use the linear velocity model, but we scale it by the delta time. To do the analog for the covariance matrix, it is not enough to just scale it, but we use the Discrete White Noise Acceleration Process matrix, which is the proper adjustment. This logic is implement in the ScalableProcessNoise class in src/trackers/utils/motion_models.py.

How much does this improve?

To evaluate this we tried by dropping frames trying to model network failures.

• The most basic model is dropping frames based on independent bernoullis, so dropping a frame with probability p.
  Here we get:

Then, we can model burst loss by correlating the frame drops.

• S2 (Burst loss): Loss comes in clusters (good and bad periods), producing contiguous dropout bursts.

Here we get:

• S3 (Burst + throttle): Same bursty loss as S2 plus a sustained mid-sequence low-frame-rate window that simulates temporary bandwidth throttling.

And the mean per dataset is:

We are seeing delta HOTA between using the new feature and not using it in pp. So we expect to see all positive results, but in DanceTrack static is performing up to 2pp better. This can happen due to usage of parameters tuned for static usage. Though in soccernet and sportsmot improves usage up to 6pps!

Here we see HOTA, but this gives an improvement to IDF1 and MOTA as well. Here we have a plot with ALL the results. Full is without frame dropping, to see the ceiling, dynamic is using this PRs feature, and static is tracking naively.

Type of Change

• New feature (non-breaking change that adds functionality)
• Documentation update

Testing

• I have tested this change locally
• I have added/updated tests for this change

Checklist

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code where necessary, particularly in hard-to-understand areas
• My changes generate no new warnings or errors
• I have updated the documentation accordingly (if applicable)

Additional Context

[Copilot]

Pull request overview

This PR adds optional timestamp-driven “dynamic frame rate” support across the tracker stack (trackers → tracklets → state estimators → Kalman motion/noise), enabling variable time gaps between update() calls to scale Kalman prediction and to prune lost tracks using a seconds-based budget while preserving fixed-rate behavior when timestamp is omitted.

Changes:

• Adds timestamp: float | None = None plumbing to BaseTracker.update() and concrete trackers, plus a PredictTiming helper to convert elapsed seconds into Kalman “frame-step” units.
• Introduces a motion-model layer (KalmanMotionModel + ScalableProcessNoise) to build F(frame_step) and DWNA-scaled Q(frame_step) for gaps.
• Adds docs + extensive unit/integration tests for timing, pruning, and motion/noise scaling.

Reviewed changes

Copilot reviewed 25 out of 26 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
CHANGELOG.md	Documents the new optional timestamp= API and motion-model additions.
docs/learn/track.md	Adds user-facing documentation for variable frame rate behavior and per-call timestamp mode.
src/trackers/core/base.py	Centralizes timestamp bookkeeping (_predict_timing) and predict dispatch to tracklets.
src/trackers/core/sort/tracker.py	Threads timestamp through SORT update flow and time-based pruning budget.
src/trackers/core/bytetrack/tracker.py	Threads timestamp through ByteTrack update flow and time-based pruning budget.
src/trackers/core/ocsort/tracker.py	Threads timestamp through OC-SORT update flow and adds seconds-budget pruning path.
src/trackers/core/botsort/tracker.py	Threads timestamp through BoTSORT update flow and time-based pruning budget.
src/trackers/core/sort/tracklet.py	Uses PredictTiming to scale predict steps and advance seconds miss clock.
src/trackers/core/bytetrack/tracklet.py	Uses PredictTiming to scale predict steps and advance seconds miss clock.
src/trackers/core/ocsort/tracklet.py	Uses PredictTiming to scale predict steps and advance seconds miss clock (plus ORU behavior).
src/trackers/core/botsort/tracklet.py	Uses PredictTiming to scale predict steps and advance seconds miss clock.
src/trackers/utils/base_tracklet.py	Adds shared seconds-based miss clock + unified “within budget” helper.
src/trackers/utils/predict_timing.py	Introduces PredictTiming and FIXED_RATE_TIMING.
src/trackers/utils/motion_models.py	Adds KalmanMotionModel and ScalableProcessNoise for F/Q scaling.
src/trackers/utils/state_representations.py	Routes frame_step into motion application before kf.predict().
src/trackers/utils/kalman_filter.py	Ensures predict/update algebra supports “no observation” updates cleanly.
tests/core/test_timestamp_plumbing.py	Integration tests for timestamp timing conversion and time-based pruning behavior.
tests/core/test_tracklets.py	Validates OC-SORT ORU unfreeze behavior stays fixed-rate (unit-step predicts).
tests/core/test_registration.py	Updates/extends registration coverage for new API surface (diff truncated in prompt).
tests/utils/test_state_estimators.py	Smoke tests for estimator predict defaults and motion-cache reset.
tests/utils/test_motion_models.py	Unit tests for F scaling and DWNA Q polynomial scaling properties.
tests/utils/test_kalman_filter.py	Unit tests for predict using stored matrices and update(None) semantics.

[AlexBodner]

I think its better to assume monotonicity of inputs. Wdyt @Borda ?