How WakeRoute works

1 What is a GPX file?

A GPX file is a standard format for GPS tracks. Most tracking apps and devices can export your activities as GPX:

• Sports watches / wearables (Garmin, Apple Watch via 3rd party apps, etc.).
• Fitness apps (Strava, Komoot, Runkeeper, many bike computers).
• Navigation tools (loggers on boats, car trackers, custom hardware, etc.).

GPX files typically contain a series of points with:

• Latitude / longitude.
• A timestamp for each point.
• Optionally, speed, elevation, and other data.

2 Upload page: creating a new animation

Fields on the upload form

• Track title (optional): A short name for your track, e.g. "Morning ride" or "Boat 3". If you leave it blank, WakeRoute uses the GPX's internal name or the filename.
• Page title (optional): A label for the whole run, e.g. "Saturday 10k with friends" or "Weekend road trip day 1".
• GPX file: The file exported from your app or device.

What happens when you click "Generate animation"

1. WakeRoute saves your GPX file and reads all the GPS points and timestamps.
2. It detects the local timezone from the coordinates.
3. It calculates:
   • Start and end times of the track.
   • Speed between each pair of points.
4. It checks whether this track overlaps in time with any existing tracks (more on that below).
5. It creates (or updates) a run: an HTML page with an interactive map and animation controls.

3 How overlapping tracks are grouped into a single run

WakeRoute is designed to handle situations where multiple people record overlapping activities at roughly the same time. For example:

• Two cyclists ride the same route together but upload their GPX files separately.
• A group drive with several cars, each with its own tracker.
• Multiple boats, skiers, or runners moving at the same time in the same area.

Overlap detection

For each upload, WakeRoute:

1. Computes the local start time and end time of the track.
2. Compares that time window with all existing tracks in its index.
3. If the new track's time range overlaps an existing track's time range (even partially), it considers them part of the same run.

Run IDs and shared links

Internally, each run has a run ID, e.g. abc123. All overlapping tracks share the same run ID, so they share the same URL:

Example:
1. You upload a walk at 9:00–9:30 and get /sail/run42 with just your track.
2. A friend uploads a bike ride from 9:10–9:45. WakeRoute detects overlap and connects that track to run42.
3. Now /sail/run42 shows both tracks animated together.

If someone else opens the original link after additional overlapping tracks are added, they'll see the updated, combined animation.

4 The animation view: controls & features

Timeline & play/pause

• A slider at the bottom represents time from the earliest track point to the latest.
• Moving the slider manually scrubs through time, updating all markers on the map.
• A play / pause button advances the slider automatically, replaying the run as an animation.
• A small time display shows the current time point in local time.

Colored tracks by speed

Each track is drawn on the map with segments colored by speed. For example:

• Slow segments appear in cooler colors.
• Fast segments appear in warmer colors.

A legend shows the speed scale in knots for sailing data, or km/h for other activities.

Markers for current position

Each track has a small marker (dot) that moves along as the animation progresses. Tooltips or labels on these markers can show:

• The track name (e.g. "Runner A", "Car 2").
• The current distance to the next reference point (if marks are configured).
• Other context like time and speed at that moment.

5 Optional: distance to "marks" or reference points

WakeRoute can optionally use a list of marks or reference points along your route. These are just named coordinates: they could be turns on a course, checkpoints, intersections, buoy locations, parking lots, etc.

For each track, WakeRoute can:

• Infer which marks were actually used (based on closest approach).
• Determine which mark a point is "heading to" next.
• Calculate the distance from the current position to that next mark.

During the animation, you can see:

• Each track's current distance to the next mark.
• The differences in distance between multiple tracks (e.g., who is 0.15 units ahead/behind relative to the leader).

If your deployment has a "marks & cities" configuration page, you can define different sets of marks per city and reuse them across runs.

6 Recent runs & sharing links

Recent runs page

The Recent runs page lists recently generated runs (based on their creation time and metadata). For each run you'll usually see:

• Run title (e.g. "Saturday Group Ride").
• Approximate date and time window.
• Number of tracks included in the run.

Clicking a run entry opens the animation view for that run.

Sharing

The URL of a run (something like /sail/<run_id>) is sharable with others. Anyone with the link can see the map and animation in their browser, without needing to re-upload GPX files.

7 For yacht clubs: recurring series with multiple fleets

WakeRoute is built for club racing: a recurring series where 3-5 fleets start a few minutes apart on the same course, and each fleet wants its own results. Many clubs call this a Wednesday night beer can race, but the same setup works for any recurring race night.

One event, many race nights

Create a single series event for the season. This event persists all season; you do not need a new website event for each week. Each race night creates one or more races inside the same season event as boats start recording and select the course in the WakeRoute app.

Set the venue center latitude/longitude and the event area radius carefully. Nearby discovery in the app uses that venue radius to decide whether a sailor sitting on a boat is close enough to see the event.

Define your fleets once

Add your fleet classes to the event — e.g. Cruising Spinnaker, J/105, PHRF Non-Spin, Jib & Main. These carry over from week to week. When sailors record with the WakeRoute app, they pick their fleet at the start of recording.

How a typical race night works

1. Before the season, the organizer creates the website event, links the club marks library, adds fleet classes, and creates preset course options.
2. On race night, a sailor onboard opens the WakeRoute app. The app uses the phone's location to find nearby planned events. The sailor chooses the season event, selects tonight's course, picks their fleet, and starts recording.
3. WakeRoute creates a live recording event and bridges it back to the exact long-lived website event. The selected start time is interpreted in the venue's local date, so an evening race is not accidentally keyed to the next UTC day.
4. Other sailors nearby join the same live event from their phones. They select their fleet and start recording.
5. After racing, tracks upload automatically. WakeRoute groups each fleet's tracks into separate results — Cruising Spinnaker boats are compared only against other Cruising Spinnaker boats, J/105s only against J/105s, and so on.

Per-fleet results

Each fleet gets its own results page with speed plots, tack analysis, and animated replay showing only the boats in that fleet. The race hub page shows all fleets at a glance, with links to each fleet's results.

See every fleet on one map

When an Event Mode race has multiple fleets with ready results, each fleet's results page shows an Include all fleets button in the hero band. Clicking it overlays every fleet's boats from every course that raced on the same day onto the same map and timeline, with a small chip next to each boat showing which fleet it belongs to. When boats raced on different courses, the leaderboard groups by Course → Fleet → Boat, with collapsible sections at each level. It's useful for watching how different starts played out — leaders of one fleet passing through a trailing fleet, or a preferred side of the course being dominant regardless of class. Click the button again (now labelled Show only this fleet) to return to the single-fleet view. Each fleet's results page remains the canonical ranking source — the combined view is display-only.

Fix a wrong fleet pick

If a sailor accidentally selects the wrong fleet on their device, the results page has a fix: click the Run settings gear button in the hero band. It opens a dialog showing every boat in the run with a Move to… dropdown listing the other fleets in the same race. Select the correct fleet and click Move. WakeRoute re-renders both the old fleet's results (minus the moved boat) and the new fleet's results (plus the moved boat) automatically, then redirects to the updated page. If the event has a passcode, the organizer's passcode is required.

Add a boat to an event after recording

If a boat records without joining an event (e.g. forgot to select it, or used an external GPS device), you can associate it after the fact. On the results page, click the Add to event button. A dialog shows nearby events — pick one, choose a fleet for each boat, and optionally select a specific course/race if the event has multiple. Click Associate and WakeRoute re-renders the boat into the event's results.

Split one recording that covers several races

If a boat kept a single recording running across several races (instead of stopping and restarting between them), open Race config → Split into races. Pick the event for the day and your boat's fleet: WakeRoute slices the recording at each race's start time and creates a separate result per race — and each race automatically shows the other boats already in that race. If there's no event, choose No event — split manually and add a split time between each race to produce separate result pages. The original combined recording is replaced by the per-race results.

Move a boat to a different course

When an event has multiple courses (races) and a boat ends up in the wrong one, open Run settings and use the Move to course… dropdown under each boat. Select the correct course and click Move. WakeRoute re-renders both the source and destination course results automatically. If the event has a passcode, the organizer's passcode is required.

Tonight's course (and mid-evening swaps)

Most clubs have a fixed set of buoys (say ~9 permanent marks) and the race committee picks an ordered subset each race night — for example Start → M3 → M1 → M5 → Finish. WakeRoute lets the organizer pre-configure these as named preset courses, then any boat picks which one is in play from the WakeRoute app a few minutes before the first start.

1. Organizer (once per season, in the web editor): on the event's edit page, scroll to Preset Courses for Tonight. Click New preset course, name it (e.g. "North Loop"), check the club marks you want, reorder them with Up/Down, and save. Repeat for each course variant (e.g. "South Triangle", "Windward-Leeward Short"). Start-line ends can be pinged from the app at race time or corrected later from the results page.
2. Any sailor (race evening, in the WakeRoute app): when starting or joining the recording, the wizard shows the list of preset courses with the mark sequence for each. Tap the one the race committee just announced and continue.
3. Mid-evening swap: if the wind shifts and the RC changes the course between races, any boat can open the HUD menu, tap Change course, and pick the new one. Tracks uploaded after the swap are routed to a new race bound to the new course. Previous races keep their original course intact — no retroactive rewrites.

Setting the start line: RC End & Pin End pings

The preset course defines the marks but intentionally leaves the start line empty — the RC boat and pin move every race night. To record the actual line in play, one boat pings the two ends from the WakeRoute app right as the RC sets the line:

1. Open the recording HUD. The first page is the race start timer. Near the RC boat, tap Ping RC End. Near the pin, tap Ping Pin End. Each button captures your current GPS position and posts it to the live event.
2. The pings propagate to every boat in the event — they do not need to ping again. The timer page also shows your current perpendicular distance to the start line once both ends are pinged.
3. After the race, the ping coordinates are drawn as a dashed start line on every fleet's results page automatically.

Fixing a race after the fact

If the start line was never pinged (or the wrong mark was in play, or a shifted course wasn't captured live), the organizer can still correct the race from the web. Each fleet's results page has a Fix course marks button in the hero band that opens an inline mark editor directly on the results map. Click the map to add marks, drag them to reposition, and click a mark name to rename or delete it. You can also choose from preset courses configured for the event. Changes are auto-saved and only affect that specific race result — other races are not touched. New marks are automatically added to the event's mark library for future use.

Every fleet's results page also has a Set start line control for dropping fresh RC End and Pin End coordinates on just that race (useful when the same named course is reused every Wednesday but the line moves each night). Clicking the button turns the race map into a two-click picker — tap the RC boat location, then the pin location, then Confirm. The dashed start line appears immediately and the playback timeline snaps to the race start time so you can hit Play and watch the race unfold from the gun.

Uploading via the web (without the WakeRoute app)

Sailors who record GPX tracks with other apps or devices can upload them on the web. On the upload form, select the event from the "Attach upload to existing event" dropdown, then choose the correct fleet class. WakeRoute will auto-match the track to the right week's race based on the track's timestamps and location.

Optional: passcode protection

A passcode protects the website edit page only. It is for organizers who should manage marks, preset courses, fleets, and later course corrections. Recording, joining, and uploading from the app are not passcode-gated.

8 Tips, examples, and troubleshooting

Good use cases

• Running / walking: Compare pace and route choices on repeated runs.
• Cycling: Overlay multiple riders' data from the same group ride.
• Driving: Visualize a road trip day, compare different cars or routes.
• Boating or water sports: Replay tacks, turns, or races across multiple boats.
• Hiking / skiing: Understand how groups spread out over time on the mountain.

When tracks don't combine as expected

• Make sure the activities actually overlap in time. If one track ends hours before another begins, they will be separate runs.
• Check device time settings. If one device's clock is off by many hours, the time windows might not overlap correctly.
• If you see multiple entries in the Recent page for what should be one run, it may be from older runs created before combination logic or cleanup were applied. New uploads should follow the consistent "shared run ID" behavior.

GPX export tips

• Prefer exports that include timestamps and full GPS detail. If you see options like "route only" vs "full activity", pick the full one.
• If the track looks very coarse (few points) the animation will still work, but speed and distance estimates may be less smooth.