[PR #285] feat: add Lap Time Evolution chart with full race strategy analysis #273

New issue

Open

opened 2026-05-07 00:19:30 +02:00 by BreizhHardware · 0 comments

BreizhHardware commented

2026-05-07 00:19:30 +02:00

Owner

📋 Pull Request Information

Original PR: https://github.com/IAmTomShaw/f1-race-replay/pull/285
Author: @4f4d
Created: 4/28/2026
Status: 🔄 Open

Base: main ← Head: feat/lap-time-evolution-chart

📝 Commits (4)

3dbec95 feat: add Lap Time Evolution chart with tyre stint analysis, delta mode, and SC/VSC overlays
cb6c4b7 Polish lap time and gap chart UX
8919ec6 Improve chart interaction responsiveness
f201cae Tighten chart hover and branch audit fixes

📊 Changes

3 files changed (+3016 additions, -3 deletions)

View changed files

📝 src/gui/insights_menu.py (+16 -2)
➕ src/insights/lap_time_chart_window.py (+2385 -0)
📝 src/interfaces/race_replay.py (+615 -1)

📄 Description

Closes #284

Summary

Introduces a new Lap Time Evolution insight window under Race Analysis. The feature is designed for race-pace analysis rather than raw telemetry inspection, combining lap times, tyre context, pit-stop events, neutralization overlays, and race-gap context in a single interactive chart.

This PR also includes follow-up fixes made after the initial branch push so that the chart semantics, controls, and default views are accurate and usable in real race sessions.

Features

Core Visualisation

Per-driver lap-time traces using the existing driver colour palette
Tyre compound markers per lap:
- Soft ●
- Medium ■
- Hard ▲
- Intermediate ◆
- Wet ★
Stint-average dashed lines and faint tyre-coloured stint bands for focused drivers
Pit-stop markers for focused drivers

Race Context Overlays

Safety Car, Virtual Safety Car, and Red Flag spans rendered as shaded labelled zones
Correct SC/VSC/RED colour handling when multiple status periods occur in the same session
Pure Pace mode to hide SC/VSC and pit-distorted laps

View Modes

Mode	Meaning	Use Case
Lap Time	Driver lap time for each completed lap	Pace comparison, tyre degradation, stint quality
Gap to Leader	Timing-line gap to the race leader after each completed lap	Race-gap trend, convergence/divergence, stop-loss context

Interactive Controls

Control	Action
Scroll / Pinch	Zoom
Click & Drag	Pan
Double-click	Reset view to mode home view
Axis Limits	Enter exact X/Y ranges
Undo / Redo buttons	Navigate chart-view history
Driver Dropdown	Show all drivers or isolate one driver
Click Legend	Toggle driver focus / multi-select
Hover	Show lap, tyre, tyre age, gap/lap-time context
`?` Button	Open feature/help overlay

Best-Lap Indicators

Session Best Lap Time marker
Personal Best Lap Time marker per driver
In Lap Time mode, personal-best tooltips also show Gap to SB

Important Follow-up Fixes Included

These changes are part of the branch state that should be reviewed, even though they were made after the original commit was first pushed:

Gap mode semantics fixed
- The original implementation used a lap-time delta proxy.
- The chart now uses lap completion timestamps so Gap to Leader reflects the race-timing concept users expect.
SC/VSC/RED overlay colouring fixed
- Status-zone colour rebinding now works correctly across consecutive mixed status periods.
Mode-switch blank-chart issue fixed
- Switching between Lap Time and Gap to Leader no longer leaves stale y-limits that can hide the plot.
Gap-mode scaling improved
- Long pit/garage-stop outliers no longer flatten the default competitive field view.
- Focusing a driver in Gap to Leader now isolates the trace without re-scaling the chart around extreme outliers.
Tooltip clarity improved
- Gap to Leader tooltips now use race-gap wording instead of ambiguous lap-time wording.
- Lap Time personal-best tooltips now show Gap to SB.
View controls improved
- Added Axis Limits
- Added Undo / Redo buttons for chart-view navigation
- Removed unstable shortcut-only dependence
- Suppressed hover tooltips while the cursor is over the legend so legend interaction is cleaner

Files

New Files

File	Description
`src/insights/lap_time_chart_window.py`	Main chart window, rendering, interaction, overlays, HUD, tooltips, zoom/pan controls

Modified Files

File	Description
`src/gui/insights_menu.py`	Adds the Lap Time Evolution entry under Race Analysis
`src/interfaces/race_replay.py`	Precomputes lap-time payload and status-lap data; now includes lap completion timestamps for accurate gap mode

Visual Demo

https://github.com/user-attachments/assets/8de1e619-9034-46cf-ac85-f5022a1a4e9d

Key Design Decisions

Offline computation
- Lap times and status periods are precomputed once rather than derived during live rendering.
- This keeps the UI responsive during replay.
Gap mode uses timing-line completion data
- Gap to Leader is based on race timing context, not “fastest visible lap” heuristics.
Focused-driver gap view keeps stable default scaling
- Selecting a driver should improve readability, not distort it around large outliers.
Interactive state is part of the UX
- The chart preserves mode-specific view state and supports explicit axis control for closer inspection.

Known Limitations / Future Work

The chart uses matplotlib + QtAgg, which is adequate here but not ideal for very high-frequency interactive workloads or when higher FPS is needed.
If future work adds heavier real-time interaction or cross-session comparison, a faster charting backend may be worth evaluating.

Tests performed

Tested and validated across different seasons and different seasons.
Everything works as mentioned with various edge cases handled as mentioned.

Update

Since the initial push, this PR has been amended to address several correctness and UX issues in the Lap Time Evolution window:

corrected Gap to Leader semantics to use lap-completion timing at the line
fixed SC/VSC/Red Flag zone colouring during redraw
fixed mode-switch blank-chart / y-axis state issues
improved gap-mode scaling so focused-driver views do not get squashed by extreme outlier gaps
refined tooltip content and best-lap labeling
added axis-limits controls and button-based view history navigation
stabilized the top-right live lap/time readout and added help/legend shortcuts (H, I)
improved legend hover handling and other interaction polish

Note: changes/fixes have been force pushed into a single commit to mitigate from the ongoing incorrect squash merge issue of GitHub.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/IAmTomShaw/f1-race-replay/pull/285 **Author:** [@4f4d](https://github.com/4f4d) **Created:** 4/28/2026 **Status:** 🔄 Open **Base:** `main` ← **Head:** `feat/lap-time-evolution-chart` --- ### 📝 Commits (4) - [`3dbec95`](https://github.com/IAmTomShaw/f1-race-replay/commit/3dbec95ab2a044c0f8e6d24e52ffda5ce9ab1410) feat: add Lap Time Evolution chart with tyre stint analysis, delta mode, and SC/VSC overlays - [`cb6c4b7`](https://github.com/IAmTomShaw/f1-race-replay/commit/cb6c4b7e858f731b437f52a827f037da226ab961) Polish lap time and gap chart UX - [`8919ec6`](https://github.com/IAmTomShaw/f1-race-replay/commit/8919ec6d12440caee41b12f894f4767fae27b04b) Improve chart interaction responsiveness - [`f201cae`](https://github.com/IAmTomShaw/f1-race-replay/commit/f201cae84a7766e6bb92cfa164ded0c9d560f446) Tighten chart hover and branch audit fixes ### 📊 Changes **3 files changed** (+3016 additions, -3 deletions) <details> <summary>View changed files</summary> 📝 `src/gui/insights_menu.py` (+16 -2) ➕ `src/insights/lap_time_chart_window.py` (+2385 -0) 📝 `src/interfaces/race_replay.py` (+615 -1) </details> ### 📄 Description Closes #284 ## Summary Introduces a new **Lap Time Evolution** insight window under **Race Analysis**. The feature is designed for race-pace analysis rather than raw telemetry inspection, combining lap times, tyre context, pit-stop events, neutralization overlays, and race-gap context in a single interactive chart. This PR also includes follow-up fixes made after the initial branch push so that the chart semantics, controls, and default views are accurate and usable in real race sessions. ## Features ### Core Visualisation - **Per-driver lap-time traces** using the existing driver colour palette - **Tyre compound markers** per lap: - Soft `●` - Medium `■` - Hard `▲` - Intermediate `◆` - Wet `★` - **Stint-average dashed lines** and faint tyre-coloured stint bands for focused drivers - **Pit-stop markers** for focused drivers ### Race Context Overlays - **Safety Car**, **Virtual Safety Car**, and **Red Flag** spans rendered as shaded labelled zones - Correct SC/VSC/RED colour handling when multiple status periods occur in the same session - **Pure Pace** mode to hide SC/VSC and pit-distorted laps ### View Modes | Mode | Meaning | Use Case | |------|---------|----------| | **Lap Time** | Driver lap time for each completed lap | Pace comparison, tyre degradation, stint quality | | **Gap to Leader** | Timing-line gap to the race leader after each completed lap | Race-gap trend, convergence/divergence, stop-loss context | ### Interactive Controls | Control | Action | |---------|--------| | Scroll / Pinch | Zoom | | Click & Drag | Pan | | Double-click | Reset view to mode home view | | Axis Limits | Enter exact X/Y ranges | | Undo / Redo buttons | Navigate chart-view history | | Driver Dropdown | Show all drivers or isolate one driver | | Click Legend | Toggle driver focus / multi-select | | Hover | Show lap, tyre, tyre age, gap/lap-time context | | `?` Button | Open feature/help overlay | ### Best-Lap Indicators - **Session Best Lap Time** marker - **Personal Best Lap Time** marker per driver - In **Lap Time** mode, personal-best tooltips also show **Gap to SB** ## Important Follow-up Fixes Included These changes are part of the branch state that should be reviewed, even though they were made after the original commit was first pushed: 1. **Gap mode semantics fixed** - The original implementation used a lap-time delta proxy. - The chart now uses **lap completion timestamps** so `Gap to Leader` reflects the race-timing concept users expect. 2. **SC/VSC/RED overlay colouring fixed** - Status-zone colour rebinding now works correctly across consecutive mixed status periods. 3. **Mode-switch blank-chart issue fixed** - Switching between `Lap Time` and `Gap to Leader` no longer leaves stale y-limits that can hide the plot. 4. **Gap-mode scaling improved** - Long pit/garage-stop outliers no longer flatten the default competitive field view. - Focusing a driver in `Gap to Leader` now isolates the trace without re-scaling the chart around extreme outliers. 5. **Tooltip clarity improved** - `Gap to Leader` tooltips now use race-gap wording instead of ambiguous lap-time wording. - `Lap Time` personal-best tooltips now show `Gap to SB`. 6. **View controls improved** - Added **Axis Limits** - Added **Undo / Redo** buttons for chart-view navigation - Removed unstable shortcut-only dependence - Suppressed hover tooltips while the cursor is over the legend so legend interaction is cleaner ## Files ### New Files | File | Description | |------|-------------| | `src/insights/lap_time_chart_window.py` | Main chart window, rendering, interaction, overlays, HUD, tooltips, zoom/pan controls | ### Modified Files | File | Description | |------|-------------| | `src/gui/insights_menu.py` | Adds the Lap Time Evolution entry under Race Analysis | | `src/interfaces/race_replay.py` | Precomputes lap-time payload and status-lap data; now includes lap completion timestamps for accurate gap mode | ## Visual Demo https://github.com/user-attachments/assets/8de1e619-9034-46cf-ac85-f5022a1a4e9d ## Key Design Decisions 1. **Offline computation** - Lap times and status periods are precomputed once rather than derived during live rendering. - This keeps the UI responsive during replay. 2. **Gap mode uses timing-line completion data** - `Gap to Leader` is based on race timing context, not “fastest visible lap” heuristics. 3. **Focused-driver gap view keeps stable default scaling** - Selecting a driver should improve readability, not distort it around large outliers. 4. **Interactive state is part of the UX** - The chart preserves mode-specific view state and supports explicit axis control for closer inspection. ## Known Limitations / Future Work - The chart uses **matplotlib + QtAgg**, which is adequate here but not ideal for very high-frequency interactive workloads or when higher FPS is needed. - If future work adds heavier real-time interaction or cross-session comparison, a faster charting backend may be worth evaluating. ## Tests performed - Tested and validated across different seasons and different seasons. - Everything works as mentioned with various edge cases handled as mentioned. ## Update Since the initial push, this PR has been amended to address several correctness and UX issues in the Lap Time Evolution window: - corrected Gap to Leader semantics to use lap-completion timing at the line - fixed SC/VSC/Red Flag zone colouring during redraw - fixed mode-switch blank-chart / y-axis state issues - improved gap-mode scaling so focused-driver views do not get squashed by extreme outlier gaps - refined tooltip content and best-lap labeling - added axis-limits controls and button-based view history navigation - stabilized the top-right live lap/time readout and added help/legend shortcuts (`H`, `I`) - improved legend hover handling and other interaction polish Note: changes/fixes have been force pushed into a single commit to mitigate from the ongoing incorrect squash merge issue of GitHub. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>