F1-Telemetry-Analysis A "Pit Wall" style F1 telemetry dashboard. A FastAPI backend pulls historical and live session data via FastF1 and serves it to a React frontend, which renders a dynamic track map, synchronized telemetry traces, and sector/lap analysis.

Features

• Dynamic track map — 2D circuit layout with corner labels, generated per-session from real telemetry and cached to disk so it's only computed once per circuit.
• Live driver positioning — driver X/Y coordinates plotted on the track map, synced to a shared session clock.
• Telemetry traces — Speed, RPM, Gear, Throttle, Brake, and DRS, synchronized across drivers.
• Historical replay — load and step through any race, qualifying, or practice session FastF1 has data for.
• Driver comparison / time delta — overlay two drivers' fastest laps and see the time delta build up over distance.
• Qualifying traffic detection — flags moments where a driver on a flying lap gets caught behind a car running a prep/out lap, based on proximity and lap classification.
• Track status overlay — yellow flag, Safety Car, VSC, and red flag periods mapped onto the session timeline.
• Practice/qualifying stint breakdown — tyre compound, stint length, and lap classification (push/prep/in/out) per driver.

Comprehensive F1 telemetry dashboard and analysis tools. This repository contains:

• A FastAPI backend that uses fastf1, pandas, and numpy to fetch and serve telemetry, track and session data.
• A Next.js frontend (in the frontend/ folder) which renders the track map, timing tower and lap analysis UI.
• Utilities to pregenerate track layouts and run a live poller for ongoing sessions.

This README documents the tech stack, installation steps, and how to run the demo locally.

Tech Stack:

• Python 3.10+: backend and utilities
• fastf1: fetches F1 timing and telemetry data
• FastAPI: backend HTTP API
• uvicorn: ASGI server for FastAPI
• pandas / numpy: data manipulation
• Next.js (React): frontend UI (frontend/)

Files of interest:

• api.py: main backend API serving /api/schedule, /api/track, /api/session, /api/time-delta.
• live_race.py: alternative FastAPI service that polls live sessions and exposes live endpoints.
• pregenerate.py: utility to pregenerate and cache track layout CSVs into data/.
• frontend/: Next.js app. API base is frontend/src/lib/api.ts.

Prerequisites

• Python 3.10 or newer
• Node.js 18+ and npm/yarn/pnpm for the frontend

Install (Backend)

From repository root:

python -m venv .venv
# Windows (PowerShell)
.\.venv\Scripts\Activate.ps1
# macOS / Linux
# source .venv/bin/activate

pip install -r requirements.txt

Notes:

• The requirements.txt includes fastf1, fastapi, uvicorn[standard], pandas, numpy, requests, and websockets.
• The app writes cache to ./cache (generated by fastf1) and ./data for pregenerated CSVs.

Run the Backend (development)

Start the main API (used by the frontend):

uvicorn api:app --reload --port 8000

Start the live poller API (optional, runs its own FastAPI app and background poller):

uvicorn live_race:app --reload --port 8001

Pregenerate track data (optional but recommended for faster demo runs):

python pregenerate.py

Frontend (Next.js)

cd frontend
npm install
npm run dev

The frontend runs on http://localhost:3000 by default and the client is configured to talk to http://localhost:8000 (see frontend/src/lib/api.ts if you need to change the API base URL).

Demo flow (quick)

1. Ensure uvicorn api:app is running on port 8000.
2. (Optional) Run python pregenerate.py to create cached data/*_track_layout.csv and *_corners.csv files.
3. Run cd frontend && npm run dev and open http://localhost:3000.

Troubleshooting

• If the frontend cannot fetch schedule/track/session data, confirm the backend is reachable at http://localhost:8000 and that CORS allows http://localhost:3000 (configured in api.py).
• If fastf1 fails to fetch session data, check network access to the underlying timing endpoints and ensure fastf1 cache folders (./cache, ./cache_live) are writable.

Tests and utilities

• test_integration.py contains simple requests-based checks for the API.
• pregenerate.py prefetches tracks to data/ for offline/demo use.

---