QGIS plugin and validation harness for loading Mapbox vector tiles in QGIS and adapting Mapbox GL JS styles to the QGIS styling engine.
The first target style is Mapbox Outdoors (mapbox/outdoors-v12). The project keeps the qfit history that built the current QGIS symbology, then continues that work in a smaller repository focused only on Mapbox vector tiles and QGIS style parity.
The Chamonix sequence below shows how the QGIS rendering of Mapbox Outdoors evolved from an early converter pass to a mature outdoor style with clearer terrain, hillshade relief, paths, landcover, labels, and contour balance. Each frame is a fresh QGIS render from a historical iteration of the style work.
| Early conversion | Style audit |
|---|---|
 |
 |
| Symbols and labels | Opacity simplification |
|---|---|
 |
 |
| Landcover separation | Hillshade relief |
|---|---|
 |
 |
| Trail legibility | Mature result |
|---|---|
 |
 |
- adds a QGIS action to load Mapbox Outdoors as a vector tile layer
- fetches the Mapbox style JSON and sprite sheet at runtime
- simplifies Mapbox GL expressions that QGIS cannot convert directly
- applies the converted renderer and labeling with QGIS'
QgsMapBoxGlStyleConverter - post-processes labels, line styles, terrain fills, road shields, contour labels, paths, and other Outdoors-specific details from the qfit work
- keeps an iteration manifest so historical and future style snapshots can be rendered and compared
No Mapbox token, tile payload, sprite payload, downloaded style JSON, or render output is committed.
Install or package the plugin as qgis_mapbox_gl_style.
The plugin reads the Mapbox token from QGIS settings first, then from environment variables:
export QGIS_MAPBOX_GL_STYLE_MAPBOX_TOKEN="pk..."The generic MAPBOX_ACCESS_TOKEN variable is also supported. QFIT_MAPBOX_ACCESS_TOKEN remains supported only for old validation scripts and local migration continuity.
In QGIS:
- Enable the plugin.
- Open
QGIS Mapbox GL Style -> Settings. - Enter a Mapbox token, style owner, style id, and tile mode.
- Run
QGIS Mapbox GL Style -> Load Mapbox Outdoors.
The default style is mapbox/outdoors-v12 in vector mode.
Iterations are stored in iterations/index.json. Each entry records:
- a stable iteration id
- the original qfit commit
- the rewritten commit in this repository
- source pull requests and issue references
- the style owner/id and camera set
- notes about the visual/style milestone
List iterations:
python -m qgis_mapbox_gl_style.iterations listRender one historical iteration:
python -m qgis_mapbox_gl_style.iterations render --iteration 006 --camera-set issue-949The render command creates a detached git worktree at the selected filtered commit and runs the retained comparison harness from that snapshot. Artifacts are written under debug/iterations/<iteration>/<timestamp>/, which is ignored by git.
Use --dry-run to inspect the exact worktree and render command without executing QGIS/browser rendering.
Accept a future agent run as the next iteration:
python -m qgis_mapbox_gl_style.iterations accept --from-run debug/iterations/012/20260620T120000Z --label "Improve contour label placement"That appends the next manifest entry against the current repository HEAD.
The retained validation scripts live under validation/ and are intentionally close to their qfit originals. Some report fields still say qfit_* or "qfit preprocessing" because those names are part of the historical audit output and tests.
The main visual comparison harness is:
python validation/mapbox_outdoors_comparison.py --all-cameras --output-root debug/mapbox-outdoors-comparisonSee docs/mapbox-outdoors-comparison-harness.md for the full harness workflow.
Build a QGIS install ZIP:
python scripts/package_plugin.pyThe package is written to dist/qgis_mapbox_gl_style-<version>.zip.
This repository was seeded from the Mapbox/QGIS parts of ebelo/qfit with git filter-repo, so the style work remains inspectable as real git history instead of a copied final snapshot.
More detail is in docs/provenance.md.