trajectory-forecast 26.0.1

Real-time multi-object tracking with lightweight trajectory forecasting, built on top of Ultralytics YOLO. Track objects in video, keep their motion history, and estimate where they are moving next. Trajectory Forecast can be used from the command line or directly from Python.

Installation

pip install trajectory-forecast

Quick start

Run tracking and trajectory forecasting on a video:

trajectory-forecast --model yolo26n.pt --source "https://tinyurl.com/2f3yrppv" --show

If you want to save the results

trajectory-forecast \
  --model yolo26n.pt \
  --source "https://tinyurl.com/2f3yrppv" \
  --output result.mp4 \
  --show \
  --save

https://github.com/user-attachments/assets/9a1267c2-4ba4-49f6-9802-e80fed5e682f

Any Ultralytics-supported detection model can be used.

Python

from tf import run_inference

run_inference(
    model_path="yolo26n.pt",
    source="video.mp4",
    output_path="result.mp4",
)

Configuration

The defaults work without a config file. To customize tracking or forecasting, create a YAML file:

conf: 0.5                      # Minimum detection confidence
tracker: "bytetrack.yaml"      # Tracker used to keep object IDs between frames
classes: [0, 2, 5, 6, 7]       # Object class IDs to detect and track

history: 30                    # Number of previous positions kept per object
min_points: 5                  # Positions required before forecasting starts
forecast_steps: 35             # Number of future frames to predict
min_speed: 1.0                 # Skip forecasting for nearly stationary objects
max_gap_frames: 5              # Keep motion state through short detection gaps

process_noise: 1.0             # Higher values adapt faster to motion changes
measurement_noise: 10.0        # Higher values smooth noisy detections more

forecast_color: [255, 0, 0]    # Forecast path color in BGR format

Then pass it to the CLI:

trajectory-forecast \
  --model yolo26n.pt \
  --source "video.mp4" \
  --config config.yaml

The most useful forecasting options are:

• forecast_steps: how many future frames to predict.
• min_points: tracking history required before forecasting starts.
• min_speed: skips forecasts for nearly stationary objects.
• max_gap_frames: keeps motion state through short detection gaps.
• process_noise: controls how quickly the motion estimate adapts.
• measurement_noise: controls how strongly detection noise is smoothed.

How forecasting works

Each tracked object has its own acceleration-aware Kalman motion state.

In every frame, the filter updates the object's position, velocity, and acceleration based on the latest tracked position. Future points are then generated from that filtered motion state. This helps the forecast respond to changes in speed rather than assuming that every object will continue at a fixed velocity.

Short detection gaps retain the motion state for up to max_gap_frames. If the tracker assigns a completely new ID, a new forecast state is created for that track.

The forecasting layer uses float32 state arrays and vectorized future-point generation to keep its per-frame overhead small. The terminal also reports trajectory forecasting time separately from the detector's inference timing.

Project structure

tf/
├── cli.py           # Command-line interface
├── config.py        # Configuration
├── drawing.py       # Visualization
├── forecasting.py   # Motion model and future prediction
├── inference.py     # Detection, tracking and forecasting pipeline
├── tracker.py       # Per-track state and history
└── utils.py         # Utilities

Contributing

Contributions and improvements are welcome. Open an issue or pull request if you find a bug or have an idea for improving tracking or forecasting.

For a practical walkthrough, see the trajectory forecasting guide.