User Manual & Troubleshooting

1. Overview

Bridleway Map shows your GPX ride history overlaid on council bridleway, byway, and BOAT data for 8 districts across the north of England. All path types — bridleways, BOATs, and byways — are shown for every district that has them. It calculates which paths you have ridden and tracks your progress toward completing them all.

It also tracks your progress on two structured cycling challenges: the Facey 50 (50 Kirklees road climbs) and the Calderdale 50 (50 Calderdale road climbs), automatically detecting which climbs you've completed from your GPX history.

2. Initial setup

1. 1

   Place your GPX files

   Export rides from Strava (Settings → Export Account Data) and copy the .gpx files into data/gpx/activities/.

2. 2

   Place bridleway data

   Copy council GeoJSON files into data/bridleways/ using the naming convention District-Type-JSON.json, e.g. Calderdale-Bridleways-JSON.json.

3. 3

   Run the pipeline

   In the project directory, run:

   npm run prepare-data

   This parses GPX files, merges and builds the bridleway map data, runs the geospatial analysis, and detects Facey 50 and Calderdale 50 completions (~2 minutes).

4. 4

   Start the app

   npm run dev

   Open http://localhost:4321 in your browser.

3. Using the map

Sidebar controls

Basemap layer toggle

Two buttons in the top-right corner of the map switch the basemap:

Colour coding

Clicking a path

Click any path to see a popup with its reference number, ridden status, and (for unridden paths) a Mark as Ridden button. Click a ride track to see its name and date.

4. Adding & viewing rides

Uploading a new GPX file

1. On the Map page, scroll to Add Ride at the bottom of the sidebar.
2. Drag a .gpx file onto the drop zone, or click it to browse.
3. Click Upload & re-parse rides. The file is saved and all rides are re-parsed (a few seconds).
4. Click Re-run analysis in the Progress section to update the ridden stats for the new ride.

Bulk import

Copy any number of .gpx files directly into data/gpx/activities/, then run npm run prepare-data from the terminal.

Rides table

The Rides page lists every parsed ride with date, distance, duration, and elevation gain, grouped by year. Click a row to see the ride's GPS track on a map.

5. Marking paths as ridden

The geospatial analysis automatically detects ridden paths using a 15 m GPS buffer, but sometimes GPS noise or a brief detour means a path you rode isn't detected. You can mark it manually.

How to mark a path

1. Load the relevant district on the map.
2. Click the unridden path (shown in blue).
3. In the popup, click ✓ Mark as Ridden.
4. The path turns orange immediately and is hidden when "Show unridden only" is active.

How to unmark a path

1. Click the orange (manually marked) path.
2. In the popup, click ✕ Unmark.

Updating the stats

Manual marks are saved instantly to data/manual-ridden.json and reflected in the map immediately. To update the district progress percentages, click Re-run analysis in the sidebar's Progress section.

6. Running the analysis

The analysis compares every GPS point in your ride tracks against every bridleway segment using a spatial grid index. A segment is marked ridden if any part of it falls within ~15 m of a GPS point.

Via the UI

Click Re-run analysis in the sidebar's Progress section. The button shows a running state while it works (~1–2 minutes) and reloads the page when done.

Via the terminal

npm run analyze

Then refresh the browser to see updated stats.

Updating climb completions

Facey 50 and Calderdale 50 completion data is updated separately. Run:

npm run analyze-climbs

Or include it in the full pipeline with npm run prepare-data.

When to re-run

• After uploading a new GPX ride
• After manually marking or unmarking paths
• After adding new bridleway GeoJSON files

7. Progress & statistics

The Progress page shows per-district stats: total miles of rights of way, miles ridden, and percentage complete. The sidebar on the Map page shows the same bars at a glance.

Both GPS-detected and manually marked rides contribute to the mileage totals after analysis is re-run.

8. Facey 50

The Facey 50 page tracks your progress on the 50 Kirklees road climbs defined by the Facey Fifty challenge. Completions are detected automatically from your GPX history.

How completion is detected

A climb is counted as completed if a ride track passes within 200 m of the climb start and within 300 m of the climb end. Only rides within the Kirklees area bounding box are checked.

Viewing a climb

Click any row in the table to open a detail panel showing:

• Distance, ascent, and average gradient
• A map of the climb route (orange line)
• Completion date(s) and number of attempts
• A link to the Strava segment

Updating completions

npm run analyze-climbs

Run this after uploading new GPX files to pick up any newly completed climbs.

9. Calderdale 50

The Calderdale 50 page tracks your progress on the 50 Calderdale road climbs from calderdale50.wordpress.com. It follows the same detection approach as the Facey 50.

Area filter

The 50 climbs are grouped into 13 areas (Cornholme, Greetland, Halifax, Hebden Bridge, and so on). Click an area pill at the top of the page to filter the table to that area only. Each pill shows a done / total count for that area. Click All to show everything.

Viewing a climb

Click any row to open a detail panel showing the climb map, stats, completion info, and a link to the plotaroute.com route definition.

Updating completions

npm run analyze-climbs

This updates both Facey 50 and Calderdale 50 completion data in one command.

10. Troubleshooting

11. Data & privacy

All ride and bridleway data stays on your machine. Nothing is sent to any external service.

Map tiles are fetched from external servers — only tile coordinates (not your location or ride data) are sent:

• OpenStreetMap tiles from openstreetmap.org
• OS 1:25k tiles via OS Data Hub (Ordnance Survey)