Maps & Tiles

Offline map display with multiple styles, tile management, and terrain support.

6 min read

Map Rendering

GroundWave uses MapLibre GL JS to render vector tiles served by the TileServer GL container running alongside the application. MapLibre is a fully open-source fork of Mapbox GL JS and provides GPU-accelerated rendering capable of smooth 60 fps performance on mobile devices and low-power single-board computers.

The tile server reads pre-downloaded .pmtiles or .mbtiles archives from a persistent Docker volume. All tile data is served entirely from local storage — no external tile CDN is contacted during map rendering.

The map viewport includes the following built-in controls:

Pan and zoom — drag to pan, scroll or pinch to zoom
Compass — tap to reset bearing to north
Geolocate — center the map on the device's reported position
Fullscreen — expand the map to fill the entire browser window
Scale bar — displays the current ground resolution in metric units

MapLibre renders entirely on the GPU via WebGL. Rendering performance is largely independent of tile count and scales well across zoom levels without additional server load.

Map Styles

GroundWave ships with a redesigned thumbnail-grid style picker UI that lets users switch between online and offline map styles instantly. Styles are grouped into two categories depending on connectivity requirements.

Online Styles

When internet access is available, four online map styles are accessible. These fetch tiles directly from third-party CDNs and are not available offline.

Style Name	Tile Source	Best For
Street	OpenStreetMap / default raster	General navigation, urban areas
Satellite	ESRI World Imagery	Terrain recognition, rural and wilderness
Topo	OpenTopoMap	Elevation, contour lines, hiking routes
Dark	CartoDB Dark Matter	Low-light conditions, reduced eye strain

Offline Styles (Protomaps)

Five style variants are available for offline vector tiles served from locally stored Protomaps archives. All variants use the same tile geometry; only the rendering style differs.

Variant	Description
Dark	Dark background with muted colors — default for field use
Light	Light background suitable for printing or high-ambient-light conditions
Grayscale	Neutral grayscale rendering for overlay-heavy workflows
White	Minimal white base, maximum contrast for overlays
Black	High-contrast black base for night operations

The dark offline variant is recommended for most field deployments. It reduces screen brightness, preserves night vision, and provides strong contrast for position markers and markers drawn on top.

Tile Management

GroundWave supports multiple tilesets installed side by side on the server. Admins manage tilesets through the admin dashboard Tiles tab, which exposes all server-side tile operations without requiring SSH or command-line access.

Available admin operations:

List tilesets — view all installed tilesets with name, format, size, and zoom range
Download — fetch a new tileset by specifying a location or bounding box; size is estimated before download begins
Import — upload a locally prepared .mbtiles or .pmtiles file directly to the server
Delete — remove a tileset to reclaim storage space
Set active — designate which tileset is used for offline rendering; the selection persists across server restarts

When the active tileset changes, all connected clients receive a real-time notification and the map automatically flies to the coverage area of the new tileset so the operator immediately sees the available map extent.

Tile archives can be several gigabytes. Ensure the Docker volume hosting tile data has sufficient disk space before beginning a download. Use the size estimation step to verify before committing to a large download.

Offline Raster / Satellite Tiles

In addition to vector tilesets, GroundWave supports downloading raster tile archives for offline satellite or aerial imagery. The download workflow mirrors vector tiles:

In the admin Tiles tab, select "Download Raster / Satellite".
Define the coverage area using a bounding box or place name.
Select the zoom range (higher zoom levels increase file size significantly).
Review the estimated size, then confirm the download.
A progress bar tracks the fetch. The tileset becomes available immediately on completion.

Once downloaded, offline satellite tiles are available without any internet connection and can be selected from the style picker in the same way as vector styles.

Terrain & Hillshade

GroundWave supports 3D terrain exaggeration and hillshade rendering using a Digital Elevation Model (DEM) tile source. When enabled, the map renders elevation as a three-dimensional surface with shaded relief that communicates slope, ridge lines, and valley positions at a glance.

DEM data can be pre-downloaded for offline use through the same tile management workflow used for vector and raster tilesets. The terrain layer is applied on top of whichever base style is currently active.

Terrain rendering is automatically disabled when georeferenced image overlays are active. MapLibre GL JS does not support image sources on a 3D terrain mesh. The terrain toggle re-enables automatically when all image overlays are hidden.

Tile Source Indicator

A persistent indicator in the map UI shows whether tile data is being served from the local TileServer GL container or fetched from an online CDN. The indicator displays one of two states:

Offline — tiles are loading from the locally installed tileset; no network dependency
Online — tiles are fetching from an external provider; internet access is required

This indicator is particularly useful during first-run and setup to confirm that offline tile data has loaded correctly, and in the field to detect unexpected fallback to online sources when connectivity is unreliable.