Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 5 additions & 2 deletions HANDOFF.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ It started on 2026-10-13 as "WinterMiles" (an icTrainer alternative for riding G

## 2. Where it stands (November 2026, v0.3.9)

**Solid and tested:** route building (GPX parsing, resampling, smoothing, climb detection), physics, ride recording and FIT export, workouts (.zwo/.erg/.mrc and built-ins), fitness maths, gamification, the 3D world (terrain with roads cut into hillsides, buildings, forests of six kinds of tree with sprites in the distance, field boundaries and hedge-banked lanes, water, the surrounding road network, bridges, tunnels, overpasses, road surface/width/markings, race barriers that lean with the road and netting round hairpins, landmarks, weather), the virtual-gear maths, diagnostics, the relay. 106 automated tests (plus two that need the network and are skipped by default), plus visual checks through the automated smoke harness (section 6).
**Solid and tested:** route building (GPX parsing, resampling, smoothing, climb detection), physics, ride recording and FIT export, workouts (.zwo/.erg/.mrc and built-ins), fitness maths, gamification, the 3D world (terrain with roads cut into hillsides, buildings, forests of six kinds of tree with sprites in the distance, field boundaries and hedge-banked lanes, water, the surrounding road network, bridges, tunnels, overpasses, road surface/width/markings, race barriers that lean with the road and netting round hairpins, landmarks, weather), the virtual-gear maths, diagnostics, the relay. 114 automated tests (plus two that need the network and are skipped by default), plus visual checks through the automated smoke harness (section 6).

**Built but not proven with real use:**

Expand All @@ -23,6 +23,7 @@ It started on 2026-10-13 as "WinterMiles" (an icTrainer alternative for riding G
| **Trainers and sensors** | Protocols unit-tested against the specs. The first real trainer — a **Tacx Vortex Smart (T2180) over Bluetooth** — connected but **kept dropping out and showed no power**. Not yet diagnosed: a diagnostics report from a ride is needed. This is the top priority. |
| **Virtual gears** | The maths is unit-tested and shifting was checked with the demo rider and the smoke harness (`VP_SMOKE_SHIFT`), but it has **never been felt on a real trainer**. |
| **OpenBikeControl controllers** | Button decoding and the choice of one action per press are unit-tested; never connected to a real controller. |
| **Laps on loop routes** | Lap engine, bests, segments and renderers unit-tested in `crates/core`; smoke-run across the line on Linux with three.js, not yet with the native renderer (macOS). Group standings don't show who is a lap up. |
| **Strava** (OAuth, upload, segments, activities as ghosts) | Never run against the live API. Users must create their own API key (open source can't ship a secret). Scope is `read,activity:read_all,activity:write`. |
| **Windows and Linux** | Built and packaged by CI on every push (and Arch's package is installed in a container and its libraries checked), but **never run by a person**. |
| **Native renderer** (macOS, opt-in) | wgpu/Metal in an NSView under a transparent webview. Matches three.js in screenshots; HUD-over-native never checked in a real window; no clean release-build performance comparison. |
Expand Down Expand Up @@ -107,7 +108,7 @@ The full process is in [CONTRIBUTING.md](CONTRIBUTING.md): issue first → branc

## 6. Testing

- `cargo test --workspace` — 106 tests: 99 core, 1 relay, 6 app (plus two app tests that need the network: `cargo test -p velopopuli -- --ignored`); `npx tsc --noEmit` for the page. CI runs all of them.
- `cargo test --workspace` — 114 tests: 107 core, 1 relay, 6 app (plus two app tests that need the network: `cargo test -p velopopuli -- --ignored`); `npx tsc --noEmit` for the page. CI runs all of them.
- **The smoke harness** is how most visual and end-to-end checking has been done: a debug build that rides (or opens a screen) by itself, saves pictures and the visible text, and quits. All the `VP_SMOKE_*` switches are documented in the wiki's [Building from source](https://github.com/pepperstm/velopopuli/wiki/Building-from-source). The most useful: `VP_SMOKE_AT` (start part-way), `VP_SMOKE_CAM=3` (overhead — good for junctions), `VP_SMOKE_WINDOW=1` (whole window with HUD), `VP_SMOKE_CLIP=6` (frames for a demo clip), `VP_SMOKE_SURFACE`, `VP_SKIP_OVERPASS`, `VP_SMOKE_REPORT`. With `"nativeRenderer": true` in the data folder's `settings.json`, the native renderer's own frame is saved too, as `<name>.native.png` — the only way to see it, since window snapshots capture just the web view.
- The ride-start diagnostics line `[ride] surfaces … trails … berms … fords … widths …` shows what the map matching decided; a smoke run also prints each berm and ford.
- Good test routes: Bourg d'Oisans → Alpe d'Huez (town, river, hairpins — route it with BRouter); the Trouée d'Arenberg (OSM track "Drève des Boules d'Hérin", `surface=sett`); Meylan near Grenoble (roundabouts); any city crossing (viaducts). For trails, around Finale Ligure: graded singletrack and switchbacks (berms), Ponte dell'Acqua (OSM way 143650465, a log bridge), Strada Valle del Bosco (way 113195224, a ford over the Rio dell'Ericeto); a hike near Chamonix (grades estimated from `sac_scale`); a field near Chartres (the off-map dirt track). A test route is two files in the data folder: `data/routes.json` and `data/route-<id>.json` (`{name, gpx}`).
Expand Down Expand Up @@ -149,6 +150,7 @@ CI also builds every push to `main`; installers can be downloaded from the run's
- **Diagnostics are always on** (raw sensor data optional) so a user can send a useful report after the fact; reports strip names, tokens and locations.
- **GitHub reporting opens a pre-filled issue in the browser** rather than signing in from the app: a device-flow sign-in was started and dropped in favour of the simpler approach.
- **Apple Health removed** for now (no desktop HealthKit; export import was clunky).
- **Laps are `distance` on the loop plus `ridden` for totals.** `RideEngine` keeps `distance` as the position on the loop, in `[0, route.total]`, and adds `lap` (from 1) and `ridden` (metres across all laps). Everything meaning "where on the road" uses `distance`; everything meaning "how far ridden" (FIT, summary, progress, goal) uses `ridden`. Without laps `ridden == distance`, so ordinary rides are unchanged by construction. The choice is only accepted when the route is a loop (`Route.closed`, offered to the page by `route_is_loop`) and is kept on the ride as `laps`. Agreed with the maintainer (#67): ghosts off on lap rides, climbs and segments timed on each lap and kept fastest, and a lap ride never sets the route's best time.
- **Commits are under the maintainer's name only.**

## 10. Known traps
Expand All @@ -165,4 +167,5 @@ CI also builds every push to `main`; installers can be downloaded from the run's
- **Trees are 3D near the camera and sprites beyond about 200 m:** a chunk's trees are `[x, y, z, yaw, width, height, kind, shade]`, grouped by kind; each kind is one set of instances drawn twice, as its 3D model (`tree_model`) and as a camera-facing quad (`sprite_frame`) textured from an atlas that the page renders from the models at ride start (`trees.ts`) and hands to the native renderer as the `trees` texture. The vertex shaders split the trees one by one at each tree's own distance (`SPRITES_FROM` ± `SPRITE_SPREAD`/2, from a hash of its position), so the two copies of the rule — `spriteFrom` in `trees.ts` and `sprite_from` in `shader.wgsl` — must stay identical, or trees vanish or double at the switch. Atlas cells are cleared one at a time (`target.scissorTest`): three.js clears the whole target on every render otherwise.
- **Barrier sections lean with the road:** each is placed by `[x, y, z, yaw, distance, look, pitch]`, tipped about its own x axis first and then turned (`'YXZ'` in three.js, `vs_barrier` in the native shader), so both ends stand on the road and neighbours meet. A new renderer of them must apply the pitch, and in that order. Round a bend tighter than 30 m radius there are no sections; instead fence panels (look `FENCE`, orange netting) are laid evenly along the outside edge, so they meet end to end (`tight_bends` and `bend_fence` in `barriers.rs`). They are just another look, so neither renderer knows about them.
- **Berms tilt the riding surface and fords lower it:** anything standing *on* the route's surface (riders) must add `World::bank_at` (Rust) or `bankAt()` (page) — the lift at its offset (negative in a ford), and the roll. The inside edge of a berm is at the centre-line height; the outside is raised. The route's own `ele` is never changed by either, so gradients and physics are unaffected.
- **Lap wrap-around:** on a lap ride `distance` jumps from `total` back to near 0 at the line, so anything comparing or extrapolating distances must use wrapped arithmetic. A climb or segment that ends exactly on the line must finish on the crossing tick, or it stays active after the wrap. A slower later lap must not overwrite a faster earlier lap in `new_segment_bests`. The chase camera, rivals just behind, the barriers and the profile behind the rider must come from the end of the loop, not clamp to 0. A remote rider sitting at exactly 0 or `total` must still be drawn on a lap ride.
- **Road looks are numbered across three places:** a new look needs its constant in `surface.rs`, its texture in `SURFACES` in `surfaces.ts` (same order), and its name in the native renderer's match in `native/mod.rs`. Today: 0–4 surfaces, 5 lane, 6 timber, 7 singletrack, 8 ford.
4 changes: 3 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ Free and open source ([GPLv3](LICENSE)) for **Windows, macOS and Linux**. Writte

- **GPX in, virtual ride out.** Import routes from Strava, Komoot, RideWithGPS or a bike computer. Routes with no elevation data (planner exports) get it filled in automatically.
- **A 3D version of the real place.** The road follows your GPX; the surrounding landscape is built from open elevation data, so the mountains on the horizon are the real ones. OpenStreetMap supplies the rest: the towns and villages you pass through, forests where the real forests are, lakes, rivers and streams, the side roads, lanes, footpaths and railways around you, and the bridges and tunnels of the real road — you ride over the river on a bridge deck, into the hillside through a lit tunnel, and under the motorway or railway that crosses overhead. A live OpenStreetMap minimap and a gradient-coloured elevation profile sit alongside. Works offline with generated hills.
- **Laps.** On a closed route, ride it once, for 2, 3, 5, 10 or 20 laps, or until you stop. The HUD counts the laps and the distance ridden, and the profile, landmarks and riders carry on across the line.
- **A closed road, race-day style.** The road you ride is set apart from the map's road network: steel crowd barriers line both sides (with banners on some, each section standing on its feet and leaning with the road on hills, and orange netting round the outside of tight hairpins instead), its surface is the real one — tarmac, concrete slabs, cobbles, gravel or dirt — and so is its width: a 7 m main road, a 5 m village street, a 3 m farm track. Both come from OpenStreetMap's tags for the roads along the route (`surface`, `width`, `lanes`, and the road class), or are guessed from the road class when those can't be fetched. Where the route leaves the mapped roads for 100 m or more — across a field, along an unmapped trail — it becomes a dirt track. Widths change gradually, and buildings, signs, other riders and the barriers all follow them. Ride the Arenberg trench on its setts and the Strade Bianche on white gravel — and feel them: rougher surfaces roll heavier, so you slow down on screen and the trainer gets harder.
- **Mountain-bike trails.** Where the route follows an unpaved path, a bridleway, a walking trail or a trail graded for mountain bikes (OpenStreetMap's `mtb:scale`, S0–S6, or estimated from the hiking grade), you ride a narrow earth singletrack with no barriers, the HUD shows the grade, and the harder the grade the heavier it rolls — on screen and on the trainer.
- **Find a route in the app.** Search for a place, click waypoints on the map and get a route along bike-friendly roads with real elevation (BRouter), or pick one of eight famous climbs (Alpe d'Huez, Mont Ventoux, Stelvio, Galibier, Tourmalet, Mortirolo, Zoncolan, Box Hill). Mountain bikers can plan along trails, or pick from the **waymarked MTB routes** mapped in the area on screen.
Expand Down Expand Up @@ -61,7 +62,8 @@ Be aware of what has and has not been proven:

| Area | Status |
| --- | --- |
| GPX parsing, route building, climb detection, physics, ride recording, gamification, terrain, building and scenery generation, workouts, fitness maths, segment and ghost matching, landmarks, photo selection | Unit-tested (`cargo test`, 99 core tests) |
| GPX parsing, route building, climb detection, physics, ride recording, gamification, terrain, building and scenery generation, workouts, fitness maths, segment and ghost matching, landmarks, photo selection | Unit-tested (`cargo test`, 107 core tests) |
| Laps on loop routes | Unit-tested in `crates/core`: lap counting, distance ridden, climbs and segments timed on every lap, bests kept from the fastest lap, ghosts off. Smoke-run on Linux with the three.js renderer: the lap HUD, and riders, road and barriers across the line. **Not yet** run with the native renderer (macOS). FIT lap messages and ending the ride on the workout are not done |
| Group-ride relay | Tested in-process (`cargo test -p velopopuli-relay`) and with two app instances riding together through a local relay |
| Fan and lights | Requests checked against a pretend device for Home Assistant, Shelly and a webhook; not tried with real plugs |
| Route finder, famous climbs | All eight climbs planned through the live BRouter service and checked against their known length and height gain |
Expand Down
Loading
Loading