mirror of
https://github.com/mauriceboe/TREK.git
synced 2026-10-18 21:16:47 +00:00
Maurice
9ce6eed9ad
* feat(places): hand a trip back as GPX TREK reads GPX but never wrote it, so a planned trip could not reach the offline map or the handheld it was planned for. The importer already fixes the mapping: a wpt is a place, a rte or trk is a place with route_geometry, so writing is that reversed. Days have no import counterpart and become routes of their stops in order, which is the part that puts a plan on a device. XMLBuilder comes from the same fast-xml-parser the importer parses with, so nothing new is pulled in. * feat(dayplan): a GPX button beside PDF and ICS Scopes are worded by what someone wants on their device rather than by the GPX element: the whole trip, just the places for an offline map, just the days to follow a plan. An empty trip says so instead of reporting a failed download. * feat(mobile): GPX in the export sheet, which is no longer calendar-only The sheet held the PDF export next to the calendar entries and was still called Export Calendar; with GPX beside them the name was simply wrong. * i18n(dayplan): translate the GPX export into all locales * docs(map): document the GPX export * fix(dayplan): drop the GPX tooltip and centre both export menus The tooltip sat under the cursor exactly where the menu opens, so hovering the button produced both at once. The label lives on as an aria-label. Both menus now open centred under their button instead of hanging off its right edge.
105 lines
8.1 KiB
Markdown
105 lines
8.1 KiB
Markdown
# Map Features
|
|
|
|
The trip planner map shows your places, route lines, transport overlays, and your current location in real time.
|
|
|
|
|
|
|
|
## Map renderer
|
|
|
|
TREK uses **Leaflet** by default. If you configure a Mapbox access token in Settings → Map, the map upgrades to **Mapbox GL** with higher-quality tiles, 3D buildings, and terrain. If Mapbox GL is selected but no access token is present, TREK falls back to Leaflet automatically so the map is never blank.
|
|
|
|
The scopes required for Mapbox GL are:
|
|
- STYLES:TILES
|
|
- STYLES:READ
|
|
- FONTS:READ
|
|
- DATASETS:WRITE
|
|
- VISION:CREATE
|
|
|
|
## Place markers
|
|
|
|
Each place is shown as a circular marker:
|
|
|
|
- **Photo marker** — if the place has a photo (proxied from Google or another provider), that image appears in the circle.
|
|
- **Icon marker** — if no photo is available, a category-colored icon is shown instead.
|
|
- **Selected place** — the active place has a larger marker.
|
|
- **Order badge** — a small badge at the bottom-right of each marker shows the order number(s) of that place within the day's itinerary. If the place appears on multiple days, all order positions are shown separated by `·`.
|
|
|
|
When zoomed out, nearby markers are grouped into clusters. Clicking a cluster zooms the map to fit its members; at maximum zoom the cluster spiderfies to show individual markers.
|
|
|
|
## Route lines
|
|
|
|
When you have a day selected, a dark dashed line connects consecutive places in that day's order.
|
|
|
|
## GPX tracks
|
|
|
|
Tracks and routes imported from a `.gpx`, `.kml`, or `.kmz` file are drawn as lines on the map. Each track imported into a trip is given its own colour automatically, so several walks in the same area stay distinguishable without any setup.
|
|
|
|
To change a track's colour, open the place and use the **Track color** row: pick one of the presets, choose your own with the colour picker, or hit the dashed cell to go back to the automatic colour — the category colour if the place has one, otherwise the default blue.
|
|
|
|
Any track that carries a colour — assigned at import or picked by you — is drawn with a thin white casing so it stays readable on satellite imagery and dark basemaps. Tracks imported before this version keep their previous look until you give them a colour.
|
|
|
|
Clicking a line on the map selects that track and opens its details — useful when the start markers are still clustered together. In the places list, each track shows a short stroke in the colour it is drawn in, which is how you tell which line belongs to which entry.
|
|
|
|
### Exporting a trip as GPX
|
|
|
|
The **GPX** button in the day sidebar's toolbar, next to PDF and ICS, hands the trip back as a `.gpx` file for offline maps such as Organic Maps, for a handheld GPS, or for any other tool that reads the format. On a phone the same download sits in the trip's **Export** sheet, under "More".
|
|
|
|
Three scopes:
|
|
|
|
- **Whole trip** — every place as a waypoint, every imported track as a track, and every planned day as a route.
|
|
- **Places only** — the same without the day routes, for when you just want the pins on an offline map.
|
|
- **Days as routes** — only the planned days, each one a route through its stops in the order you arranged them. This is the one that puts a day's plan on a device you can follow.
|
|
|
|
Places carry their description and address, and their category travels along as the GPX symbol, so devices that support it can show a different icon per kind of stop. Elevation is written back for tracks that were imported with it. Exporting is a read, so every trip member can do it, not only those who may edit.
|
|
|
|
## Route time pills
|
|
|
|
At zoom level 12 or higher, small pill-shaped labels appear between consecutive places and show the estimated **walking time** and **driving time** for each segment. Below zoom 12 they are hidden to keep the map clean.
|
|
|
|
## Reservation and transport overlay
|
|
|
|
Flights, trains, cars, and cruises can be drawn as overlays between their endpoint places. Overlays are **off by default** — activate each reservation individually by clicking the small **Route** icon next to the booking row in the day sidebar, or use one of the bulk options below. The selection is remembered per trip in your browser. Click the icon again to hide it.
|
|
|
|
- **Flights and cruises** — geodesic great-circle arcs
|
|
- **Cars, buses, taxis and bicycles** — real routed lines that follow actual roads, fetched on demand from a public OSRM router (driving for car/bus/taxi, cycling for bicycle). A straight line is shown while the route loads and kept if routing fails or the trip is very long (~2000 km+)
|
|
- **Trains** — a straight line between the endpoints; a multi-leg train draws its whole station chain (from → stop → to)
|
|
- **Antimeridian crossings** — routes that cross the date line now draw as one continuous arc instead of splitting into disconnected segments at the map edges
|
|
- **Endpoint markers** — pill-shaped labels with the transport icon and the endpoint code (e.g. IATA airport code) or location name
|
|
- **Flight stats** — a floating label on the arc shows departure code → arrival code and, when times are available, the duration and great-circle distance. Stats labels are only rendered for flights.
|
|
- **Confirmed reservations** — solid line; **Pending** — dashed line
|
|
|
|
**Bulk options**, alongside the per-booking toggle:
|
|
|
|
- **Show all / hide all** — a route icon button in the day-plan toolbar (next to Undo/Reorder) flips every routable booking on the trip on or off at once, without affecting bookings you've toggled individually.
|
|
- **Always show booking routes** (Settings → General → Travel & map) — an account-wide default that shows every booking's route automatically on any trip you haven't touched before. It sets the *default* only — a trip where you've already used the per-booking toggle or the bulk button keeps its own choice even if you change this setting afterwards.
|
|
|
|
> **Admin:** Whether endpoint text labels appear on the endpoint markers is controlled by the **Booking route labels** setting in Settings → General (`map_booking_labels`).
|
|
|
|
## Plugin map markers
|
|
|
|
Installed plugins can add their own markers to the trip map — for example to show bookings on the map (#587). A plugin implements the `mapMarkerProvider` hook and returns marker specs (`id`, `lat`, `lng`, and optional `label`, `popupText`, `url`, `icon`, `tone`); TREK range-checks the coordinates, length-caps the text, allows only http/https/mailto links, and draws them itself. Markers are additive and fail-safe: a plugin never runs code on the map canvas, and one that errors or is slow simply contributes nothing.
|
|
|
|
Plugins can also draw bounded vector overlays — a computed route, a reachable-range corridor, a zone — via the `mapLayerProvider` hook (polylines, polygons and metric circles, styled with the same tone palette). TREK clamps every styling value, enforces per-plugin vertex budgets, and always draws its own day route on top. Both hooks work on the Leaflet and the Mapbox/MapLibre GL renderer, on desktop and mobile.
|
|
|
|
> **Plugins:** requires the `hook:map-marker-provider` permission (markers) or `hook:map-layer-provider` (overlays). See [Plugin-Development](Plugin-Development) for the hook contracts.
|
|
|
|
## Location button
|
|
|
|
The location button sits in the bottom-right corner of the map on mobile devices and cycles through three states:
|
|
|
|
| State | Icon | Behavior |
|
|
|---|---|---|
|
|
| Off | Outline locate | Location not tracked |
|
|
| Show | Solid blue locate | Your position is shown as a dot |
|
|
| Follow | Solid blue arrow | Map re-centers as you move |
|
|
|
|
If geolocation is denied or unavailable, the button turns red.
|
|
|
|
## Right-click / middle-click to create a place
|
|
|
|
Right-click anywhere on the **Leaflet** map to open the Place form with the clicked coordinates and a reverse-geocoded address already filled in.
|
|
|
|
On the **Mapbox GL** map, right-click is reserved for the built-in rotate/pitch gesture, so use **middle-click** instead to trigger the same Place form.
|
|
|
|
**See also:** [Places-and-Search](Places-and-Search) · [Day-Plans-and-Notes](Day-Plans-and-Notes) · [Route-Optimization](Route-Optimization) · [Map-Settings](Map-Settings) · [Reservations-and-Bookings](Reservations-and-Bookings)
|