OBC OpenBikeComputer / docs

Packer and routing

obc-pack converts OpenStreetMap PBF extracts to the OBCM map format. It also builds POIs, opening-hours data, contours, and a navigation graph. The device uses this graph for route planning.

The GPX converter creates OBCR route files. The route matcher maps live positions to an active route.

Packing a map

From OpenStreetMap to a device map .pbf(s) + config 1 Ingest ways · relations merge · crop 2 BBox truncate µdeg 3 Land clip to bbox 4 Contours trace · clamp 15 m 5 Per-LOD simplify → quadtree 6 Serialize stream out .obcm
The packer ingests OSM data, adds generated features, builds each LOD, and writes one OBCM map.

The pipeline performs these operations:

  1. Ingest and optionally crop or merge PBF sources.
  2. Calculate the content bounding box.
  3. Add land, sea, and optional contours.
  4. Build POIs and the navigation graph.
  5. Build each level of detail (LOD).
  6. Write the map and release the completed LOD.

The packer keeps approximately one LOD quadtree in memory at a time. It removes a partial output file after an error or cancellation.

Styling: first match wins

The features object in config.json is ordered. The packer checks tag keys in document order. The first matching key and value supplies the style. An exact value has priority over the "*" catch-all. The packer drops a way when no style matches.

Style IDs start at 1 and follow document order. A style contains color, paint order, width, priority, minimum LOD, and line properties. The style table can contain at most 254 entries.

First matching rule, in document order a way's tags highway = primary building = yes config.json · in order highway → { primary ★ … } railway → { … } natural → { water, land … } building → { yes … } admin_level → { 2 … } first key the way carries wins — building is never reached style #5 color (RGB565) z_index · weight priority 1–4 min_lod line_style · color2
A way uses the first matching tag key. An exact value has priority over the catch-all value.

Ingest: two passes, then assemble

The ingester normally reads each PBF twice. Pass 1 stores node coordinates and collects renderable area relations. Pass 2 resolves ways and captures relation-member geometry. The ingester then uses GEOS to assemble polygons and holes.

A closed way becomes a polygon only when its tags identify an area. A closed road loop remains a line.

Two passes over the .pbf, then relation assembly .pbf Pass 1 node store · id → coord + collect area relations Pass 2 ways → lines · polygons coastlines (always) capture member geometry build_area lake + island = 1 hole closed way? area tag → polygon else → line never both — a closed road loop is a line only
The ingester reads nodes and relations first. It then resolves ways and assembles area relations.

Cropping to a box

Use --bbox W,S,E,N to select data during ingest. This option adds an ID-selection pass before the two normal passes.

The selection keeps each selected way complete. It also keeps all required nodes and renderable area-relation members. Thus, roads do not stop at artificial box edges. Area relations do not lose required geometry.

Complete objects can extend outside the requested box. Therefore, the map header bounding box can be larger than the requested box. Do not use the output bounding box as the next crop request.

Merging several regions

The ingester can read multiple PBF files in the same passes. It does not create an intermediate merged file. For a duplicate object type and ID, the first listed file wins. The ingester emits surviving objects in ascending ID order for each type. These rules make the result deterministic.

Land and sea

OpenStreetMap supplies coastlines, but not a complete land fill. The packer downloads and caches a global land-polygon dataset. It clips this dataset to the content bounding box. When land is the backdrop, the packer stores only the sea complement. Use --no-land to skip this stage.

Sea is the clipped complement; land is the backdrop global land polygons bbox bbox − land land backdrop sea complement, on top land = the lowest-z style; the screen is cleared to it, then sea + roads paint over it.
The packer clips the land dataset to the map. It stores the sea complement when land is the backdrop.

Contours, traced from the terrain

The packer can trace contours from OBCT terrain. Set contours.enabled and supply --terrain. The packer uses marching squares on the terrain lattice. It skips a lattice square if one corner has no height.

The packer creates contour.major and contour.index line features. The defaults are a 100 m interval and an index at every fifth contour. The default pre-LOD simplify tolerance is 15 m. The configuration can change these values.

A contour class needs a matching style rule. Contours then use the normal LOD and quadtree pipeline. The terrain-layer flag lets the renderer hide their ink. It does not remove their bytes from the map.

Extracting POIs

The packer uses a fixed table of 18 OSM tag mappings. The table covers water, campsites, accommodation, resupply, pharmacies, and bicycle shops. The first matching table row supplies the subtype.

POI subtype IDs, categories, and fallback labels are normative. The packer stores names as at most 24 printable ASCII bytes. It transliterates supported Latin characters. An unnamed POI uses its subtype fallback label.

The packer deduplicates nearby candidates within each category. It gives node POIs priority over area centroids. It then builds one spatial index for each category.

Nodes + way-centroids → classify → fold names → dedup a tagged node amenity=drinking_water a closed way tourism=camp_site → ring centroid fixed table · first match amenity=drinking_water → Water natural=spring      → Water tourism=camp_site   → Campsite … 18 subtypes, 6 categories fold name → ASCII, ≤ 24 B "Bäckerei Müller" → "Baeckerei Mueller" dedup — same category within 50 m = one POI node centroid the node wins priority: node beats centroid, then named beats unnamed, then first-seen.
The packer classifies, normalizes, and deduplicates POIs before it builds the POI index.

Parsing opening hours

The packer parses a subset of the OSM opening_hours grammar. It stores a 29-byte weekly schedule in a shared pool. The device does not parse the source text.

The subset supports these forms:

  • Weekday ranges and lists.
  • Up to two intervals per day.
  • 24/7, off, and closed.
  • Time-only rules for all days.
  • Overnight intervals.
  • Representative seasonal weeks.

The parser rounds times to the nearest 15 minutes with half-to-even rounding. It flags a partial result when it drops an unsupported rule. A fully unsupported value produces no schedule.

opening_hours → normalize → flag → dedup pool raw OSM tag Mo-Fr 08:00-18:00; Sa 09-13 Apr-Oct: …; PH off parse (subset grammar) → 7 days × ≤2 intervals seasonal — Apr-Oct flattened to a representative in-season week truncated — PH / 3rd interval dropped dedup — a region's shops share hours identical schedules → one blob; POI stores its index a POI with no parseable hours stores 0xFFFF — only POIs that actually have hours cost a pool slot
The packer converts supported opening-hours rules to one fixed weekly schedule.

Building the navigation graph

The packer always builds the navigation graph. It keeps OSM node IDs for routable ways. Shared node IDs form junctions. The packer splits ways at junctions and removes duplicate edges. It removes small disconnected components with the configured threshold.

The legality filter rejects private access, motor roads, and bicycle prohibitions. It classifies each accepted edge by highway and surface. The packed way_kind byte contains both classes. See OBCM section 8 for the normative tables and layout.

The serializer writes tiled nodes, adjacency records, edge geometry, and snap anchors. It densifies and splits long geometry so each record fits its chunk.

Filter routable ways → find junctions → split + dedup into edges ① routable? highway + access residential · track · path · cycleway ✓ footway · steps · service ✓ (walk a bike) motorway ✗ · trunk ✗ unless bicycle=yes access=no|private · bicycle=no ✗ independent of render styling ② a shared node = a junction touched ≥2× → junction endpoints are always junctions; interior shape points never are ③ split into edges + dedup cut each way at every junction → edge interiors are junction-free dedup key: unordered (a,b) + geometry a way + its reverse = one edge cost = great-circle length, metres junction nodes (dense pack-run ids) joined by undirected edges → serialized as the map's §8 navigation graph
The packer converts routable OSM ways to a navigation graph. Shared OSM nodes form graph junctions.

Weighting the graph: bike profiles

Each map contains one to eight bike profiles. The defaults are Road, Gravel, MTB, and Touring. Each profile supplies highway, surface, and climb weights.

Highway and surface multipliers use 1/16 fixed-point values. A value of 16 means 1.0. Zero forbids the class. Every nonzero multiplier must be at least 1.0. This limit keeps the A* distance heuristic admissible.

The router starts weighted A* with epsilon 1.3. If the fixed search table fills, it retries with 2.0 and then 3.0. The successful epsilon bounds the returned profile-weighted cost.

Weighting the climb

Each adjacency stores ascent for its travel direction. The packer calculates ascent along the edge polyline. It samples terrain at intervals of at most 50 m. The shared integrator uses a 3 m dead band. A missing sample pauses the dead band without using zero elevation. Valid samples after the gap start a new ascent segment. The gap contributes no ascent. An edge with no valid sample has zero ascent.

edge_cost = weighted_distance + ascent_m × climb_weight

The climb weight is a profile value from 0 through 255. Zero disables climb cost. The defaults are Road 10, Gravel 8, MTB 6, and Touring 8. A descent never reduces edge cost.

the same two points, two climb weights — measured on grimsel crest 1 380 m start goal 1 066 m climb weight 0 — straight over the top 8 340 m · ▲ 1 008 m · high point 1 380 m climb weight 10 — round the valley 10 914 m · ▲ 784 m · never above the goal the answer switches between w = 8 and w = 10: +2.6 km of ground bought for −224 m of climb, and a crest 314 m lower the MTB profile at w = 6 declines the same detour and keeps its line — the product statement, not a bug
The packer samples terrain along each edge. It stores directional ascent in each adjacency.

Building the LOD pyramid

Each style defines the coarsest permitted LOD. Each LOD defines its simplify and size thresholds. The packer builds each LOD independently.

  • min_area_px removes small polygons and holes from coarse LODs.
  • merge_fills combines fills with the same render identity.
  • merge_lines joins connected lines with the same render identity.
  • min_line_km removes short joined lines.
  • Coverage simplification creates coarse semantic coverage.

min_line_km requires merge_lines. The finest LOD does not use min_area_px. The packer joins lines before it applies the line-length filter.

Each tier: filter by min_lod, dissolve fills + stitch lines, cull short lines, simplify, cull tiny areas, then quadtree features coast · sea min 0 motorway min 0 forest min 1 footway min 2 building min 2 LOD 0 · country min_lod ≤ 0 · simplify 120 m LOD 1 · region + min_lod ≤ 1 · simplify 18 m LOD 2 · street + everything · full detail quadtree quadtree quadtree → the LOD pyramid in the .obcm
Each LOD applies its configured filters. The packer then builds and writes its quadtree.

The quadtree: packing geometry into chunks

Each LOD uses a quadtree over the global bounding box. A node becomes a leaf when both conditions are true:

  • Its estimated feature bytes fit the configured chunk size.
  • Each feature has at most 32 rings.

Otherwise, the node splits into four children. The packer clips features to each child box. A feature that crosses a boundary can occur in multiple children. The renderer walks the same flat quadtree to select visible chunks.

A leaf splits when its chunk fills; straddlers are clipped dense → deeper clipped at the boundary → leaf fills: size += 12 + pts·4 > chunk_size → split 4 a straddling feature is clipped to each child's box, so every leaf's geometry is self-contained — which is what lets the device decode one chunk without touching its neighbours. this is the same tree the device walks to cull
A quadtree node becomes a leaf when its features fit the chunk and ring limits.

The builder

The product builder assembles published cells. It does not run the packer. A selection can contain named regions, boxes, lassos, and GPX corridors. The builder unions all parts before it prices or downloads cells. Thus, overlapping parts do not duplicate cells.

The builder verifies each object length and SHA-256 digest. The assembler verifies the completed map before it exposes the output. If the catalog supplies terrain, the builder downloads the required terrain cells. The assembler puts them in the final map terrain region. The builder does not provide a terrain switch.

Editing a skin

The product skin editor changes presentation fields only. It does not change feature types, style IDs, LODs, or routing profiles. The editor uses the production reader and renderer for its preview. The builder rejects a saved skin that does not match the current schema.

One source, three hosts

One Svelte application supplies the website, desktop app, and maintainer server. Host modules supply transport and storage capabilities. They do not supply separate selection or assembly algorithms.

CapabilityWebsiteDesktopMaintainer server
Coverage selectionYesYesYes
WebAssembly assemblyYesYesYes
Product skin editorYesYesYes
Managed ride libraryNoYesNo
Advanced schema editorNoNoYes
Product PBF buildNoNoNo

The maintainer server can pack a fixed reference crop for schema previews. This preview is not a product build path. Published cells still require an explicit maintainer bake.

Device and ride surfaces

The builder outputs one .obcm file. A device transfer commits the complete map or no map. The device verifies a whole-object CRC-32 before it commits the map. The desktop app also manages routes and recorded rides. It acknowledges an imported ride only after durable storage.

Where the hosted tier lives

The website is a static application. The catalog and cells use separate object storage. A catalog update does not require a website deployment. The publisher uploads content before it publishes the new catalog root.

Following a route

The GPX converter creates an OBCR route. It keeps exact source statistics before it reduces display geometry. It chunks the route and shares the seam point between adjacent chunks. The same no_std converter runs on the device, simulator, and web host.

GPX → OBCR · one streaming pass decimate the geometry, but measure distance + climb from every raw point ① the shape — decimate, keep the corners dropped — within 1 m of the line kept — a corner + force-keep every ~1.2 km distance & climb are summed over EVERY raw point — exact, though the stored line is decimated ② the climb — a ±3 m dead-band ±3 m along the route → elev wiggle < 3 m → ignored past ±3 m → book + re-anchor one dead-band, shared: converter · profile · live baro climb
The GPX converter keeps exact ride statistics and reduces only the displayed geometry.

Map-matching: a forward-biased cursor

The matcher keeps a cursor on the active route. For each position fix, it searches a bounded segment window around that cursor. The window has more forward range than backward range. This bias prevents a loop from matching an earlier pass.

Snap each fix to the nearest segment in a forward window forward window cursor fix cross-track dist ← progress along the route far fix off-route → freeze off-route hysteresis > 25 m → off-route < 15 m → back on the gap is the dead-band that keeps the flag from flapping on GPS jitter at the edge
The matcher searches forward from its route cursor. It freezes progress when the rider is off-route.

The first fix searches the complete route. Normal tracking searches 3 segments backward and 64 segments forward. Off-route tracking searches 3 segments backward and 320 segments forward. A caller can request the wide window after an unmatched interval.

The matcher marks the rider off-route at 25 m or more. It clears this state below 15 m. This hysteresis prevents state changes from GPS noise. While off-route, cross-track distance stays live and route progress stays fixed.

Attribution and share-alike

OpenStreetMap data uses the Open Database License 1.0. A rendered map is a Produced Work. The device provides the required attribution on its About page.

A published .obcm map is a Derivative Database. The catalog declares ODbL-1.0 and publishes the license text. A distributor of this map data must follow the same license terms. Maps with terrain-derived contours also require the Copernicus attribution.

Implementation