Release Wisp 2.6.5: 3D lap review and comparison

CHANGELOG.md

@@ -2,6 +2,13 @@
 
 Notable changes to Wisp are recorded here.
 
+## 2.6.5 - 2026-10-07
+
+- Add an optional 3D lap-review map with recorded elevation and mouse controls for rotation, pan and zoom. Keep the existing 2D view.
+- Add Shared space to compare two lap maps with the same color scale, focus either lap and move their cursors together or independently.
+- Add power and torque channels, a color legend, contact markers and PNG export. Distinguish recorded object contacts from estimated possible contacts.
+- Move lap-position controls above the map and add a resizable map area with a camera reset button.
+
 ## 2.6.4 - 2026-10-06
 
 - Improve HUD and Tune compatibility with Forza updates on Steam and Xbox PC.

LICENSES/library-sources-distribution.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
-  "version": "2.6.4",
+  "version": "2.6.5",
   "archive": {
-    "filename": "Wisp-2.6.4-library-sources.zip",
-    "url": "https://github.com/Views2k/Wisp/releases/download/library-sources-2.6.4/Wisp-2.6.4-library-sources.zip",
+    "filename": "Wisp-2.6.5-library-sources.zip",
+    "url": "https://github.com/Views2k/Wisp/releases/download/library-sources-2.6.5/Wisp-2.6.5-library-sources.zip",
     "bytes": 879043478,
     "sha256": "6ee69a19f4b28c198c79f5f48b11a639bd7d6372b36f333c3ee4873aaf6d5ccc"
   }

README.md

@@ -5,19 +5,19 @@
   Supports Steam and Xbox app / Microsoft Store editions on Windows PC.<br>
   <br><strong>Versions before 2.4 can show delayed or choppy tachometer motion on NVIDIA systems when G-SYNC/VRR is enabled. I recommend updating to the latest release.</strong>
 
-  <a href="https://github.com/Views2k/Wisp/releases/download/v2.6.4/Wisp-Setup-2.6.4.exe"><strong>Download Wisp 2.6.4</strong></a> ·
+  <a href="https://github.com/Views2k/Wisp/releases/download/v2.6.5/Wisp-Setup-2.6.5.exe"><strong>Download Wisp 2.6.5</strong></a> ·
   <a href="https://wispoverlay.com/">Website</a> ·
   <a href="CHANGELOG.md">Changelog</a> ·
   <a href="docs/HOW-WISP-WAS-BUILT.md">Architecture</a><br><br>
   Support Wisp: <a href="https://ko-fi.com/views2k">Ko-fi</a> ·
   <a href="https://buymeacoffee.com/Views2k">Buy Me a Coffee</a>
 </p>
 
-## Wisp 2.6.4
+## Wisp 2.6.5
 
-2.6.4 improves HUD and Tune compatibility with Forza updates on Steam and Xbox PC, restores Drift Zone angle-bonus guidance on the latest builds, and adds a dismissible note from Views.
+2.6.5 adds 3D lap review with recorded elevation, shared-space comparison, channel legends, contact markers and PNG export.
 
-[Clips](#clips) · [Tune](#tune) · [Lap review](#lap-review) · [Live map and lap delta](#live-map-and-lap-delta) · [Install](#install) · [2.6.4 release notes](docs/releases/Wisp-2.6.4-release-notes.md)
+[Clips](#clips) · [Tune](#tune) · [Lap review](#lap-review) · [Live map and lap delta](#live-map-and-lap-delta) · [Install](#install) · [2.6.5 release notes](docs/releases/Wisp-2.6.5-release-notes.md)
 
 ### Clips
 
@@ -59,7 +59,9 @@ Current-car reading supports **Steam and Xbox app / Microsoft Store FH6 with imp
 
 ### Lap review
 
-Open a saved run in **Runs → Lap review** to inspect the line you drove. Move one cursor across the map and graphs to review speed, inputs, G-force, RPM, gear and wheel readings. Choose a section and compare its time, distance and inputs with another lap or a pinned benchmark. Events mark braking, throttle pickup and shifts.
+Open a saved run in **Runs → Lap review** to inspect the line you drove in **2D or 3D**. The 3D view preserves recorded elevation at the same scale as horizontal distance. Rotate, pan and zoom the map, color it by speed, inputs, G-force, RPM, gear, wheel readings, horsepower, torque or elevation, and follow the selected point in the graph. Choose a section and compare its time, distance and inputs with another lap or a pinned benchmark. Events mark braking, throttle pickup and shifts.
+
+Optional **Shared space** places two laps beside each other with one camera and color scale. Focus either track, move both cursors together or inspect A and B independently, then return to the overview. Resize the map and use **Save PNG** to share the current view and legend. Contact markers distinguish recorded object evidence and saved annotations from possible-contact estimates; they do not identify every collision. [Read the lap-review guide](docs/LAP-REVIEW.md).
 
 Turn on **Save completed laps automatically** to keep laps for later review, grouped by day and car. It uses the timing mode selected in HUD settings while Wisp is running. Choosing Run B takes priority over a compatible pinned benchmark.
 
@@ -244,8 +246,8 @@ An optional quick tour introduces Clips, Tune, live map, lap delta and lap
 review. Start from the welcome banner or choose **Replay the quick tour**
 in Release Notes.
 
-[Download Wisp 2.6.4](https://github.com/Views2k/Wisp/releases/download/v2.6.4/Wisp-Setup-2.6.4.exe) ·
-[2.6.4 release notes](docs/releases/Wisp-2.6.4-release-notes.md) ·
+[Download Wisp 2.6.5](https://github.com/Views2k/Wisp/releases/download/v2.6.5/Wisp-Setup-2.6.5.exe) ·
+[2.6.5 release notes](docs/releases/Wisp-2.6.5-release-notes.md) ·
 [Changelog](CHANGELOG.md)
 
 Older interface screenshots retain their original version labels. The gameplay
@@ -372,11 +374,11 @@ require administrator access or a separate .NET runtime.
 
 ## Install
 
-1. Download [Wisp-Setup-2.6.4.exe](https://github.com/Views2k/Wisp/releases/download/v2.6.4/Wisp-Setup-2.6.4.exe).
+1. Download [Wisp-Setup-2.6.5.exe](https://github.com/Views2k/Wisp/releases/download/v2.6.5/Wisp-Setup-2.6.5.exe).
 2. Run the installer.
 3. Complete the required setup wizard on first launch.
 
-The [release page](https://github.com/Views2k/Wisp/releases/tag/v2.6.4) also provides the installer checksum and a ZIP containing the same installer. To verify the download, compare its SHA-256 with the `.sha256` file:
+The [release page](https://github.com/Views2k/Wisp/releases/tag/v2.6.5) also provides the installer checksum and a ZIP containing the same installer. To verify the download, compare its SHA-256 with the `.sha256` file:
 
 **[WINDOWS POWERSHELL]**
 
@@ -496,6 +498,7 @@ To build the self-contained installer:
 
 ## Documentation
 
+- [Wisp 2.6.5 release notes](docs/releases/Wisp-2.6.5-release-notes.md)
 - [Wisp 2.6.4 release notes](docs/releases/Wisp-2.6.4-release-notes.md)
 - [Wisp 2.6.3 release notes](docs/releases/Wisp-2.6.3-release-notes.md)
 - [Wisp 2.6.2 release notes](docs/releases/Wisp-2.6.2-release-notes.md)

docs/LAP-REVIEW-3D-PRIVATE.md

@@ -0,0 +1,88 @@
+# Lap review 3D private test
+
+Historical engineering notes for the private test builds that became Wisp 2.6.5.
+For current controls and usage, see the [lap-review guide](LAP-REVIEW.md).
+
+The 2D review stays the default. 3D uses saved XYZ positions with the same scale
+on every axis; the ground projection is a depth cue, not a terrain reconstruction.
+Camera and cursor changes reuse frozen geometry. Scene preparation is cancellable
+and runs off the UI thread. Dense display paths retain height and selected-channel
+extrema, while cursor and analysis retain the original full-resolution samples.
+
+All fourteen existing channels, wheel selection, Run B / benchmark comparison,
+shared cursor, selected sections, readouts and graph handoff are retained.
+Horsepower, torque and elevation are additional channels. PNG export includes
+the current camera, channel legend and selected-point value, uses a bounded image,
+and saves atomically without overwriting existing files.
+
+## Private 07 audit fixes
+
+Verified defects and fixes from the private 06 audit and follow-up checks:
+
+- Unmatched Both mode updated B only through the slider. All A selection paths
+  now update paired progress; selecting B works symmetrically. Independent A/B
+  keeps the other cursor fixed. Relative progress does not enable timing matches.
+- Matched B keyboard steps could map back to the same A sample. Directional
+  navigation now advances through valid matches and preserves missing-match gaps.
+- Default tooltips used a light system background with Wisp's light text. Tooltips
+  now use themed colors, wrapping and bounded width; the full-map tooltip is removed.
+- Shared-space geometry could be reused after switching to a single track.
+  Preparation now includes layout mode in its identity before reusing a scene.
+- Track picking ignored depth. Segment picking prefers the visible overpass;
+  foreground annotations retain hit priority. Empty space focuses without selection.
+- Distant world positions distorted shared-space scale. Each lap is horizontally
+  centered with one physical scale and unchanged recorded elevation.
+- Map height was lost on reopen; it is now bounded and saved when resizing ends.
+  Compact upward resizing no longer jumps to a larger minimum. Home restores auto size.
+- Elevation values and legends use feet with mph, meters otherwise. Geometry keeps
+  equal physical scale on all axes.
+- Filled and hollow contact stars distinguish reported/saved evidence from estimates.
+  Unused manual-editor commands, storage method and advice have been removed.
+
+Wheel zoom still requires map focus so page scrolling works naturally. Right-click
+or click empty map space to focus without changing the lap point; this is explained
+beside the controls. Contact-format corrections and evidence limits are below.
+
+## Contact evidence
+
+The official FH6 Data Out layout documents SmashableVelDiff and SmashableMass:
+https://support.forza.net/hc/en-us/articles/51744149102611-Forza-Horizon-6-Data-Out-Documentation
+
+These fields report breakable-object velocity loss and mass, not a general
+wall/car collision flag. Object contact requires a continuous observed
+zero-to-positive impulse. A repeated game tick is accepted only with unchanged
+sample time, identity and position (within 1 cm), without a gap or clock rewind;
+repeated lap-clock values do not discard an otherwise continuous object impulse.
+Possible contact is a conservative movement estimate. Existing Contact annotations
+in saved or imported runs remain visible; the manual contact editor has been removed.
+No universal collision accuracy is claimed.
+Historical runs discarded these fields and cannot retrospectively recover them.
+
+New journals declare run schema 3 before recording samples, preventing older
+readers from recovering a partial prefix and discarding newer contact data.
+Finalized recordings and recovered journals with no positive object field omit
+the optional fields and use schema 1 or 2, preserving Wisp 2.6.4 readability.
+If either field is positive, schema 3 retains every object sample, including zero
+baselines, and requires this private build or newer. Existing finalized files and
+imports retain their format and data during metadata edits; no migration is performed.
+
+## Platform assessment
+
+Steam: saved-run visualization uses no game memory or executable-specific data.
+Object telemetry uses FH6's documented 324-byte Data Out packet contract.
+Xbox app / Microsoft Store: the same visualization and packet contract applies;
+no platform-specific native reader was changed. No new live-game collision capture
+was performed on either edition. Packet fixtures establish parsing, not real-world
+coverage of walls, other cars, repeated impacts or dropped packets.
+
+## Verification boundary
+
+Focused checks cover existing channels and interactions, 3D projection/elevation,
+color pixels, stale asynchronous scene protection, retained contact annotations,
+repeated-clock object impulses, schema recovery/import/export and PNG output. The private
+installer retains the standard full packaging gates. Detailed results and source
+revision are retained with the delivered installer.
+
+The stored-lap performance check uses one existing run read-only and a synthetic
+180,000-point size-limit case. CPU preparation and software-render timing do not
+establish gameplay FPS or guarantee every machine's interaction performance.

docs/LAP-REVIEW.md

@@ -1,19 +1,62 @@
 # Lap review
 
-This describes the unreleased lap-review candidate. The public 2.5.2 installer does not include it.
+Review the line you drove, inspect its telemetry and compare selected sections with another lap. The map uses saved positions from your recording.
+
+## Record and open laps
 
 Open **Runs → Lap review**. Enable **Save completed laps automatically** to retain detailed laps while Wisp is running. Capture uses the timing mode in the HUD's lap settings: Race / Rivals laps or Time Attack. It works with the lap overlays disabled. Manual run recording remains available; older recordings need position and lap telemetry to show a driven map.
 
 Automatic capture uses the existing lap tracker's accepted completion boundary. Joining halfway through a lap, missing telemetry, rewinding, changing car or exceeding the recording limit prevents that interrupted lap from being saved as a complete capture. Completed saves are written to the existing local run library, with its storage limits and export/removal tools. Turn the option off to stop future captures. Pending completed saves finish when Wisp closes.
 
-Choose a saved run and a lap. The map is the car's recorded path, not a supplied circuit outline or a claim about track limits. The start ring and shared cursor identify locations. Click the map or graph, use arrow keys, or move the sample slider. Choose speed, time delta, throttle, brake, steering input, G-force, RPM or gear as the channel. Tire temperature, slip ratio, raw slip angle and normalized suspension travel also have a wheel selector for the map and graph. The sample readout shows these values for all four wheels together.
+## Map, channels and cursor
+
+Choose a saved run and a lap. The map is the car's recorded path, not a supplied circuit outline or a claim about track limits. The start ring and shared cursor identify locations. Click the map or graph, use arrow keys, or move the **Lap position** slider above the map.
+
+**2D** is the default. Switch to **3D** to view the saved XYZ positions with the same physical scale on every axis, preserving the recorded elevation changes. The ground projection helps show depth; it does not reconstruct terrain or track boundaries. Elevation values use feet when speed is set to mph and meters otherwise.
+
+Use **Color** to choose speed, time delta, throttle, brake, steering input, lateral/longitudinal/combined G-force, RPM, gear, horsepower, torque or elevation. Tire temperature, slip ratio, raw slip angle and normalized suspension travel also have a wheel selector for the map and graph. The legend shows the channel, units and numeric range; the sample readout shows wheel values for all four wheels together. Unavailable data stays unavailable.
+
+### 3D controls
+
+| Input | Action |
+| --- | --- |
+| Click a track point | Select that location; in Shared space, move closer to that lap |
+| Left-drag | Rotate |
+| Shift-drag, right-drag or middle-drag | Pan |
+| Ctrl-drag | Roll |
+| Mouse wheel while the map has focus | Zoom |
+| Arrow keys while the map has focus | Step through recorded points |
+| Home / End while the map has focus | Select the first / last point |
+| Double-click, R, or **Reset camera** | Reset the camera |
+
+Right-click or click empty map space to focus it without changing the selected point. Before the map has focus, the wheel scrolls the page. **Zoom in** and **Zoom out** are also available as buttons. Picking another point on an already focused lap keeps your adjusted camera view.
+
+Drag **Resize map** to change the map height; Wisp remembers the height when resizing ends. With the resize handle focused, Up/Down adjusts the height and Home restores automatic sizing.
+
+**Save PNG** saves the current 2D or 3D map with its channel legend and selected-point values. It includes the current camera and Shared space view when enabled. Resize and frame the map before saving, and choose an unused filename to keep existing images.
+
+## Sections and reference laps
 
 Use **Start section here** and **End section here** around a corner or straight. Compare entry, minimum and exit speed, time, distance, throttle/brake/coasting fractions, G-force, RPM, gear changes and tire values. **Open section in graphs** connects the same interval to the existing Runs graph workspace. Whole-lap timing uses the recorded timing boundary; section statistics describe the actual recorded samples and their coverage.
 
-Select Run B using the existing comparison controls, then choose its reference lap. Without Run B, the reference picker uses laps from the current run. **Pin this lap as benchmark** keeps a selected run/lap reference between Wisp sessions; rename the run and add its tune label in the normal run details. Pinning does not copy the recording, prevent its removal, or change the live HUD's session-best/previous-lap reference. If the pinned run is unavailable, choose another or unpin it.
+Select Run B using the existing comparison controls, then choose its reference lap. Run B takes priority over a compatible pinned benchmark. Without Run B or a compatible pinned benchmark, the reference picker uses laps from the current run. **Pin this lap as benchmark** keeps a selected run/lap reference between Wisp sessions; rename the run and add its tune label in the normal run details. Pinning does not copy the recording, prevent its removal, or change the live HUD's session-best/previous-lap reference. If the pinned run is unavailable, choose another or unpin it.
 
 Time delta is this lap's time minus the reference's time at matching world positions. A negative value is ahead. Route direction, continuity, start location, car and timing mode must agree, and most of both routes must match. Ambiguous or missing positions get no delta. Comparison does not establish identical tune, conditions or an officially clean lap. Existing telemetry does not provide a reliable official lap-validity flag or full track boundary.
 
+### Shared space and independent cursors
+
+In 3D, enable **Shared space** when two distinct laps with recorded positions are selected. It is optional and starts off. The laps are arranged beside each other in one scene, using a common physical scale and channel color range while retaining their recorded elevation. Click either track to focus it. Zoom out, choose **Show both laps**, or press Escape while the map has focus to return to the overview.
+
+Choose **Both** to move the cursors together. Compatible comparisons follow matching track positions. When the laps cannot be matched, Both follows relative progress by recorded distance; this does not enable time delta or matched section statistics. **A** and **B** let you inspect the laps independently while keeping the other cursor fixed. Moving B independently leaves A and its graph at their selected point.
+
+Shared space can display different cars or routes when both laps have usable positions. That visual comparison does not relax the timing and benchmark requirements above.
+
+## Contact markers
+
+**Show contacts** displays filled stars for recorded breakable-object evidence or existing saved Contact annotations, and hollow stars for **Possible contact (estimate)**. Object evidence comes from the game's reported breakable-object velocity loss and mass. Possible contacts are inferred from movement; they can be wrong. These markers do not establish every wall/car collision, an officially clean lap, or the absence of contact when no marker appears.
+
+Saved or imported Contact annotations remain visible. There is no manual contact editor. Older recordings that did not retain object telemetry cannot recover that evidence retrospectively. See the [run-file format guide](run-library-format.md) for sharing and older-version compatibility.
+
 ## Why these measurements
 
 RACELOGIC recommends locating time losses in the delta trace, then examining braking location, apex speed and the line through corner entry and exit. Wisp uses the corresponding telemetry and selected sections; it does not infer where a real apex or legal kerb lies from a bare path. [Circuit Tools guidance](https://en.racelogic.support/motorsport/discontinued-legacy/software/circuit-tools-2/kb/how-to-use-circuit-tools-to-become-faster/).