f1-race-replay README

The project's README from github.com/IAmTomShaw/f1-race-replay. As one markdown file: README.md.

F1 Race Replay 🏎️ 🏁

A Python application for visualizing Formula 1 race telemetry and replaying race events with interactive controls and a graphical interface.

Race Replay Preview

HUGE NEWS: The telemetry stream feature is now in a usable state. See the telemetry demo documentation for access instructions, data format details, and usage ideas.

Features

Controls

Safety Car

The replay includes a simulated Safety Car that appears on track whenever the F1 data indicates a Safety Car deployment (track status code 4). Since the F1 API does not provide GPS telemetry for the actual Safety Car, its position is simulated based on the race leader's position.

How it works

Technical details

The SC position computation happens in _compute_safety_car_positions() in src/f1_data.py. Each frame gets a safety_car field:

{
  "safety_car": {
    "x": 1234.56,
    "y": 7890.12,
    "phase": "on_track",
    "alpha": 1.0
  }
}
Field Description
x, y World coordinates of the SC
phase "deploying", "on_track", or "returning"
alpha Opacity value from 0.0 (invisible) to 1.0 (fully visible), used for fade in/out animation

Note: If you have existing cached .pkl files from previous runs, you must re-run with --refresh-data to generate SC position data. Older cached files will simply show no Safety Car.

Qualifying Session Support (in development)

Recently added support for Qualifying session replays with telemetry visualization including speed, gear, throttle, and brake over the lap distance. This feature is still being refined.

Requirements

Install dependencies:

pip install -r requirements.txt

FastF1 cache folder will be created automatically on first run. If it is not created, you can manually create a folder named .fastf1-cache in the project root

First Run Notice: Loading a session for the first time may take noticeably longer because telemetry data must be downloaded, processed, and cached locally. Subsequent launches of the same session are significantly faster..

Environment Setup

To get started with this project locally, you can follow these steps:

  1. Clone the Repository:

    git clone https://github.com/IAmTomShaw/f1-race-replay
 cd f1-race-replay

  2. Create a Virtual Environment: This process differs based on your operating system.

    • On macOS/Linux:
      python3 -m venv venv
source venv/bin/activate
    • On Windows:
      python -m venv venv
.\venv\Scripts\activate

  3. Install Dependencies:

    pip install -r requirements.txt

  4. Run the Application: You can now run the application using the instructions in the Usage section below.

Troubleshooting

If the pull data proccess fails, run:

pip install --upgrade fastf1

Usage

DEFAULT GUI MENU: To use the new GUI menu system, you can simply run:

python main.py

GUI Menu Preview

This will open a graphical interface where you can select the year and round of the race weekend you want to replay. This is still a new feature, so please report any issues you encounter.

OPTIONAL CLI MENU: To use the CLI menu system, you can simply run:

python main.py --cli

CLI Menu Preview

This will prompt you with series of questions and a list of options to make your choice from using the arrow keys and enter key.

If you would already know the year and round number of the session you would like to watch, you run the commands directly as follows:

Run the main script and specify the year and round:

python main.py --viewer --year 2025 --round 12

To run without HUD:

python main.py --viewer --year 2025 --round 12 --no-hud

To run a Sprint session (if the event has one), add --sprint:

python main.py --viewer --year 2025 --round 12 --sprint

The application will load a pre-computed telemetry dataset if you have run it before for the same event. To force re-computation of telemetry data, use the --refresh-data flag:

python main.py --viewer --year 2025 --round 12 --refresh-data

Qualifying Session Replay

To run a Qualifying session replay, use the --qualifying flag:

python main.py --viewer --year 2025 --round 12 --qualifying

To run a Sprint Qualifying session (if the event has one), add --sprint:

python main.py --viewer --year 2025 --round 12 --qualifying --sprint

File Structure

f1-race-replay/
├── main.py                    # Entry point, handles session loading and starts the replay
├── requirements.txt           # Python dependencies
├── README.md                  # Project documentation
├── roadmap.md                 # Planned features and project vision
├── resources/
│   └── preview.png           # Race replay preview image
├── src/
│   ├── f1_data.py            # Telemetry loading, processing, frame generation & SC position simulation
│   ├── arcade_replay.py      # Visualization and UI logic
│   └── ui_components.py      # UI components like buttons and leaderboard
│   ├── interfaces/
│   │   └── qualifying.py     # Qualifying session interface and telemetry visualization
│   │   └── race_replay.py    # Race replay interface, SC rendering & telemetry visualization
│   └── lib/
│       └── tyres.py          # Type definitions for telemetry data structures
│       └── time.py           # Time formatting utilities
└── .fastf1-cache/            # FastF1 cache folder (created automatically upon first run)
└── computed_data/            # Computed telemetry data (created automatically upon first run)

Building Custom Telemetry Windows

When you start a race replay, an Insights Menu automatically appears, providing quick access to various telemetry analysis tools. You can easily create custom insight windows that receive live telemetry data using the PitWallWindow base class:

from src.gui.pit_wall_window import PitWallWindow

class MyInsightWindow(PitWallWindow):
    def setup_ui(self):
        # Create your custom UI
        pass
    
    def on_telemetry_data(self, data):
        # Process telemetry data
        pass

The PitWallWindow base class handles all telemetry stream connection logic automatically, allowing you to focus solely on your window's functionality.

Key Features:

Documentation & Examples:

Customization

Contributing

There have been several contributions from the community that have helped enhance this project. I have added a contributors.md file to acknowledge those who have contributed features and improvements.

If you would like to contribute, feel free to:

Please see roadmap.md for planned features and project vision.

Known Issues

arcade.application.NoOpenGLException: Unable to create an OpenGL 3.3+ context. Check to make sure your system supports OpenGL 3.3 or higher

You can easily fix this by running this command:

$ conda install -c conda-forge libstdcxx-ng

Thanks to @el-mandaloriano for showing how to resolve this issue: #12

📝 License

This project is licensed under the MIT License.

⚠️ Disclaimer

No copyright infringement intended. Formula 1 and related trademarks are the property of their respective owners. All data used is sourced from publicly available APIs and is used for educational and non-commercial purposes only.

Built with ❤️ by Tom Shaw

f1-race-replay (IAmTomShaw/f1-race-replay)

Searching Database…

6.8K ·GitHub
F1-race-replay
Что это такое?F1 Race Replay — это настольное приложение на Python, которое визуализирует реальную телеметрию гонок Формулы 1 и позволяет воспроизводить события гонки на интерактивной анимированной карте трассы.
Это приложение с графическим интерфейсом или просто CLI-скрипт?Это настольное приложение с графическим интерфейсом, созданное на основе игровой библиотеки Arcade, though также предлагает необязательное текстовое меню CLI для выбора сессии для воспроизведения.
Как его запустить?Клонируйте репозиторий, создайте виртуальное окружение (шаги немного отличаются для macOS/Linux и Windows), установите зависимости, затем запустите меню GUI или передайте --year и --round напрямую основному скрипту.
Что нужно установить в первую очередь?Нужен Python 3.11+ и библиотеки FastF1, Arcade и numpy; FastF1 также создаёт локальную папку кэша при первом запуске для хранения загруженной телеметрии.
Таблица лидеров всегда точная?Нет — таблица лидеров может ошибаться на первых поворотах, во время пит-стопов и на финише из-за неточностей в расчёте позиций пилотов по телеметрии; команда всё ещё работает над исправлением этого.
Нужен ли Apple Silicon или что-то особенное?Нет, приложение работает на macOS, Linux и Windows; единственный шаг, зависящий от оборудования, — первый запуск любой гонки, который медленнее, потому что телеметрию нужно загрузить и закэшировать.
Как Safety Car отображается в повторах, если F1 не передаёт его GPS-данные?Его положение симулируется примерно в 500 метрах впереди лидера гонки по ломаной трассы, с анимированными фазами выезда, движения по трассе и возврата, а также пульсирующим оранжевым свечением; данные основаны на реальных таймингах Safety Car из данных статуса трассы FastF1.
Можно ли смотреть и квалификации, а не только гонки?Да, есть поддержка повторов квалификации (и спринт-квалификации) в разработке: скорость, передача, газ и тормоз по дистанции круга; включается флагом --qualifying.
Можно ли создать собственные виджеты телеметрии?Да, можно наследоваться от базового класса PitWallWindow, который автоматически управляет подключением к телеметрии в реальном времени и очисткой ресурсов, так что нужно реализовать только setupui() и ontelemetrydata().
Какие клавиши управляют воспроизведением?ПРОБЕЛ — пауза/продолжение, стрелки перематывают назад/вперёд и меняют скорость, клавиши 1–4 переключают на заранее заданные скорости, R — перезапуск, а D/B/L включают и выключают зону DRS, полосу прогресса и имена пилотов.
What are similar projects?live-panel-skill, Gource, hypoarena, word_cloud, ninjatracing, vistep, duckdb, miller
Which topics is it in?simulation, analytics, visualization, data-visualization, data-science, animation, gui, education, desktop-app, terminal, tool, cli
Creator
IAmTomShaw
Size
14 MB
Stars
6.8K
Updated
CommitOct 09
Age
10mo
Commits · 90 Days