RizwanMunawar/trajectory-forcast

Trajectory Forecast is a lightweight Python package for real-time object tracking and trajectory forecasting with Ultralytics YOLO. It tracks objects in video, keeps their motion history, and predicts where they are likely to move next. Use it for trajectory prediction 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.

Common use cases

• Vehicle trajectory prediction and traffic analysis
• Pedestrian movement forecasting
• Robotics and autonomous-system perception
• Video surveillance and motion analysis

CLI options

Option	Description
--model	Ultralytics YOLO model to use
--source	Input video, stream, or supported source
--output	Path for the processed output video
--config	Optional YAML configuration file
--show	Display the processed video
--save	Save the processed result
--imgsz	Override inference image size; smaller values may improve speed but reduce accuracy
--half	Request half-precision inference where supported
--device	Select inference device, e.g. cpu, 0, or mps; default is automatic

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

# Optional inference performance controls (defaults preserve Ultralytics behavior)
imgsz: 640                      # Inference image size; lower may be faster but less accurate
half: false                     # Enable half precision where supported
# device: "0"                   # Optional: "cpu", "0", or "mps"; omitted = auto

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

YOLO detection → Object tracking → Motion history → Kalman forecasting → Future trajectory

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. The inference loop also transfers the tracked box coordinates, IDs and classes to CPU in one batch per frame, avoiding multiple GPU synchronization points, and disables verbose per-frame Ultralytics output. Use --profile to report average per-frame time for video decoding, YOLO inference/tracking, forecasting and drawing, output writing, display, and total processing. Profiling is intended for measurement and adds a small amount of timing overhead.

For fair comparisons, use the same video, model, device, tracker, output options, and warm-up conditions. Compare multiple runs and report median FPS alongside detection/forecast quality. Lowering imgsz or enabling half may improve throughput on supported hardware but can change detection results. The package does not claim a fixed speedup because performance depends on hardware and workload.

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.