CD / docs /MAP_ORIENTATION.md
tkadkghdlf's picture
Sync DemoService 2b90f6cbf85d5888fb1af12e975040d9e35ba2ad
5c08c9a verified
|
Raw History Blame Contribute Delete
3.5 kB

Route display orientation

  • display_rotation_deg is clockwise screen rotation, in degrees, applied to the basemap and route together. It is NOT a GPS coordinate transform or a device/screen orientation setting. Never pass it to Android/Wear orientation.
  • Preserve a finite rotation supplied by a route producer. Do not read an unversioned parameters[3] without verifying its units and axes.
  • The main generator now recovers rotation using its existing selected GPX example (shape_example_index), or its canonical guided outline. The same complex correlation handles scale, start point and reversed traversal. Only similarity >= 0.75 gets a template-estimated orientation; this threshold is presentation-only, not a change to art readiness or recommendation scores.
  • display_rotation_source=template_match means estimated alignment to the available template, not proof that the original placement angle was retained. Symmetric shapes may have multiple equivalent orientations. Rotation cannot remove distortion, reflection or road detours.
  • Generated previews/details default to template orientation. Interactive maps offer a labelled button to switch back to north-up. Active running maps default to north-up, offer the same switch when metadata exists, and keep manual pan/ zoom state between live updates. Results use the same angle on both maps.
  • All 232 bundled samples now have a checked-in per-ID orientation catalogue (sampleRouteOrientations.json), attached on load in search, nearby sample maps and saved-course lists, and handed off to actual course detail/run views. It aligns to upright category outlines; it does not invent a historical placement angle that was never stored. The two running-dog variants were visually corrected and approved-road near-duplicates inherit source poses. tools/review_sample_orientations.py regenerates the catalogue and full before/after contact sheets without touching the public GPS route files. Alignment scores are diagnostic only, not route-quality acceptance scores.
  • Angle metadata survives generated detail, course preview, local bookmark and run checkpoint storage. Other legacy/shared routes without angle metadata remain north-up; they are not guessed from a heading or route start/end.
  • Rotation uses pinned leaflet-rotate@0.2.8 (GPL-3.0), extending Leaflet 1.9. Keep its upstream license and account for its license when redistributing the web bundle: https://github.com/Raruto/leaflet-rotate . It is loaded only in the client-only Leaflet component; controls and marker text stay upright.

Checks

python -m pytest api/ai-service/tests/test_gpx_shape_similarity.py api/ai-service/tests/test_route_display_orientation.py

cd main; npm run build

node tools/test-map-orientation.cjs against the local app. The browser test uses a local course fixture, not a real GPS run or quality acceptance test.

node tools/test-sample-map-orientation.cjs selects all 232 actual bundled samples through the saved-course UI, verifies each displayed angle, unchanged GPS polyline and fitted viewport, then checks four real route-search galleries and course-detail handoff. Only user/auth/location state is mocked. Bulk tile requests are stubbed to avoid downloading hundreds of maps; evidence captures clear the temporary browser cache and reload real OSM tiles. This is orientation verification, not a new field-safety or Strava Art quality acceptance decision.