Create QGIS Mapbox GL Style plugin

Author: ebelo

.github/workflows/build.yml

@@ -22,9 +22,6 @@ jobs:
         with:
           python-version: '3.12'
 
-      - name: Install packaging dependencies
-        run: python -m pip install --upgrade pypdf
-
       - name: Build plugin ZIP
         id: package
         run: |
@@ -39,11 +36,11 @@ jobs:
           REF_NAME: ${{ github.ref_name }}
         run: |
           if [ "$EVENT_NAME" = "pull_request" ]; then
-            echo "name=qfit-plugin-pr-${PR_NUMBER}-${GITHUB_SHA::7}" >> "$GITHUB_OUTPUT"
+            echo "name=qgis-mapbox-gl-style-plugin-pr-${PR_NUMBER}-${GITHUB_SHA::7}" >> "$GITHUB_OUTPUT"
           elif [ "$REF_NAME" = "main" ]; then
-            echo "name=qfit-plugin-main-${GITHUB_SHA::7}" >> "$GITHUB_OUTPUT"
+            echo "name=qgis-mapbox-gl-style-plugin-main-${GITHUB_SHA::7}" >> "$GITHUB_OUTPUT"
           else
-            echo "name=qfit-plugin-${GITHUB_SHA::7}" >> "$GITHUB_OUTPUT"
+            echo "name=qgis-mapbox-gl-style-plugin-${GITHUB_SHA::7}" >> "$GITHUB_OUTPUT"
           fi
 
       - name: Upload plugin ZIP

.github/workflows/plugin-security-scan.yml

@@ -22,7 +22,7 @@ jobs:
           python-version: '3.12'
 
       - name: Install scan dependencies
-        run: python -m pip install --upgrade pypdf bandit detect-secrets flake8
+        run: python -m pip install --upgrade bandit detect-secrets flake8
 
       - name: Build packaged plugin and run local-style scans
         run: python scripts/run_plugin_security_scan.py --allow-findings

.github/workflows/tests.yml

@@ -22,7 +22,7 @@ jobs:
           python-version: '3.12'
 
       - name: Install test dependencies
-        run: python -m pip install --upgrade pyyaml pypdf
+        run: python -m pip install --upgrade pillow
 
       - name: Run unit tests
         run: python -m unittest discover -s tests -v

README.md

@@ -1,287 +1,100 @@
-# qfit
+# QGIS Mapbox GL Style
 
-Explore fitness activity data spatially in QGIS.
+QGIS plugin and validation harness for loading Mapbox vector tiles in QGIS and adapting Mapbox GL JS styles to the QGIS styling engine.
 
-qfit is a QGIS plugin that turns synced fitness activities into GeoPackage-backed layers, analysis views, and atlas-ready publish data for mapping and print workflows.
+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.
 
-![qfit screenshot in QGIS](docs/images/qfit-screenshot.png)
+## What It Does
 
-*qfit in QGIS, showing synced activity tracks and points with the plugin dock open.*
+- 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
 
-This README is split into two parts:
+No Mapbox token, tile payload, sprite payload, downloaded style JSON, or render output is committed.
 
-1. **Part 1, for human readers** using qfit in QGIS
-2. **Part 2, for contributors and AI coding agents** changing the codebase
+## QGIS Plugin Use
 
----
+Install or package the plugin as `qgis_mapbox_gl_style`.
 
-## Part 1, for human readers
+The plugin reads the Mapbox token from QGIS settings first, then from environment variables:
 
-### What qfit does today
-
-qfit currently supports:
-
-- connecting to Strava with `client_id`, `client_secret`, and `refresh_token`
-- opening the Strava authorize page from the plugin and exchanging an auth code for a refresh token
-- fetching activities from Strava in the background
-- previewing fetched activities in the dock before writing anything to disk
-- storing a canonical local GeoPackage sync store
-- loading QGIS layers for tracks, start points, and optional sampled stream points
-- filtering by activity type, text search, date range, distance, and detailed-stream availability
-- applying visualization presets, optional temporal wiring, and an optional Mapbox basemap
-- running analysis workflows such as frequent starting points and activity heatmaps
-- generating atlas-ready publish layers and exporting a PDF atlas from the dock
-
-### Main outputs
-
-qfit uses a GeoPackage as both local sync store and QGIS data source.
-
-**Internal tables**
-- `activity_registry`
-- `sync_state`
-
-**Visible layers**
-- `activity_tracks`
-- `activity_starts`
-- `activity_points` (optional, derived from detailed streams)
-- `activity_atlas_pages`
-
-**Atlas helper tables**
-- `atlas_document_summary`
-- `atlas_cover_highlights`
-- `atlas_page_detail_items`
-- `atlas_toc_entries`
-- `atlas_profile_samples`
-
-### Typical workflow
-
-1. Configure Strava credentials.
-2. Fetch activities and preview the result in the dock.
-3. Choose an output `.gpkg` and store the data.
-4. Load the qfit layers into QGIS.
-5. Apply visualization or analysis workflows.
-6. Optionally generate atlas-ready publish data and export a PDF atlas.
-
-### Strava credentials
-
-You need:
-
-- `client_id`
-- `client_secret`
-- `refresh_token`
-
-qfit includes a built-in OAuth helper in `qfit` → `Configuration` for the refresh-token step.
-
-See:
-- `docs/strava-setup.md`
-
-### Background maps and styling
-
-qfit can load an optional Mapbox basemap and keep it below the qfit layers in the QGIS layer tree.
-
-For Mapbox basemaps, raster mode is the recommended choice when you need the closest visual match to Mapbox's own rendering. Vector mode is rendered natively by QGIS and should be treated as a practical local approximation: it can be more interactive and inspectable inside QGIS, but fonts, labels, sprites, antialiasing, and zoom interpolation will not be pixel-identical to Mapbox GL JS.
-
-The current visualization flow supports:
-
-- semantic activity styling by activity type
-- simpler line-based presets
-- track points / start points / heatmap-oriented views
-- temporal timestamp wiring when timestamp fields are available
-
-See:
-- `docs/map-style-guide.md`
-- `docs/mapbox-outdoors-comparison-harness.md` for manual Mapbox Outdoors browser-vs-QGIS parity checks
-
-### Publish and atlas support
-
-qfit can generate atlas-ready layers and helper tables for print layouts, then export a PDF atlas from the plugin.
-
-The current publish flow supports:
-
-- atlas page extent planning
-- cover and summary helper tables
-- TOC-ready helper rows
-- route-profile sample tables for layout charts
-- programmatic PDF export through the atlas/export subsystem
-
-For validation notes and rendering-sensitive workflow details, see:
-- `docs/atlas-validation-harness.md`
-
-### More docs
-
-- `docs/strava-setup.md`
-- `docs/schema.md`
-- `docs/map-style-guide.md`
-- `docs/mapbox-outdoors-comparison-harness.md`
-- `docs/qgis-testing.md`
-
----
-
-## Part 2, for contributors and AI coding agents
-
-### Read these first
-
-If you are changing internals, start here:
-
-- `CONTRIBUTING.md`
-- `docs/architecture.md`
-- `docs/qgis-plugin-architecture-principles.md`
-- `docs/refactoring-roadmap.md`
-- `docs/qgis-testing.md`
-- `docs/atlas-validation-harness.md` for atlas rendering/export-sensitive work
-- `docs/mapbox-outdoors-comparison-harness.md` for manual Mapbox Outdoors browser-vs-QGIS visual comparison work
-
-### Current architecture snapshot
-
-qfit is being evolved as a **modular monolith** with pragmatic **ports-and-adapters** boundaries.
-
-Preferred dependency direction:
-
-```text
-UI -> application/workflow -> domain + ports -> infrastructure adapters
+```bash
+export QGIS_MAPBOX_GL_STYLE_MAPBOX_TOKEN="pk..."
 ```
 
-In practice, that means:
-
-- keep `qfit_dockwidget.py` focused on UI glue
-- move workflow orchestration into feature-owned application modules
-- keep provider-neutral logic easier to test than QGIS-heavy code
-- keep QGIS, Strava, GeoPackage, settings, and PDF assembly details in infrastructure/adapters when that improves clarity
-- add ports/gateways only when they earn their keep
-
-### Current repo shape
-
-**Plugin entrypoints and UI host**
-- `qfit_plugin.py`
-- `qfit_dockwidget.py`
-- `qfit_config_dialog.py`
-- `qfit_dockwidget_base.ui`
-
-**Feature-owned packages**
-- `activities/` for fetch/sync/load workflows and provider-neutral activity logic
-- `analysis/` for analysis workflows, request/result shaping, and QGIS-backed analysis adapters
-- `atlas/` for publish/export workflows, runtime preparation, and PDF assembly
-- `configuration/` for settings, connection status, and dock-settings binding helpers
-- `providers/` for provider contracts and Strava-backed adapters
-- `ui/` for dock-widget dependency assembly and UI-only coordination helpers
-- `visualization/` for render planning, basemap workflows, temporal wiring, and QGIS layer adapters
-
-**Root-level modules**
-
-The top-level Python module layer is now mostly limited to:
-
-- plugin/bootstrap entrypoints
-- a few small shared helpers such as `polyline_utils.py`, `time_utils.py`, `mapbox_config.py`, and `qfit_cache.py`
-- transitional compatibility shims such as `activity_query.py`, `activity_classification.py`, `models.py`, `activity_storage.py`, and `layer_manager.py` that still exist only to cushion package migration
-
-Rule of thumb:
+The generic `MAPBOX_ACCESS_TOKEN` variable is also supported. `QFIT_MAPBOX_ACCESS_TOKEN` remains supported only for old validation scripts and local migration continuity.
 
-> Do not add new feature-specific top-level modules.
+In QGIS:
 
-If new code belongs to one feature, it should usually live under that feature package.
+1. Enable the plugin.
+2. Open `QGIS Mapbox GL Style -> Settings`.
+3. Enter a Mapbox token, style owner, style id, and tile mode.
+4. Run `QGIS Mapbox GL Style -> Load Mapbox Outdoors`.
 
-### Current architectural priorities
+The default style is `mapbox/outdoors-v12` in vector mode.
 
-1. Keep thinning `QfitDockWidget`.
-2. Preserve strict feature ownership.
-3. Move policy into application/domain while leaving mechanics in adapters.
-4. Keep request/result seams explicit where they reduce UI or framework coupling.
-5. Delete compatibility shims once in-repo callers are migrated.
+## Iterations
 
-### Practical coding rules
+Iterations are stored in `iterations/index.json`. Each entry records:
 
-- Prefer small, reviewable PR-sized slices.
-- Every behavior change needs tests.
-- New workflow logic should not accumulate in `QfitDockWidget`.
-- Prefer feature-owned modules over generic root-level helpers.
-- Prefer explicit request/result dataclasses when they replace long parameter lists or messy widget-state handoff.
-- Keep provider-neutral logic free of PyQGIS when practical.
-- Rendering/export-sensitive changes need artifact proof, not only green CI.
+- 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
 
-### Working conventions by area
-
-**activities/**
-- `activities/domain/` holds provider-neutral activity logic.
-- `activities/application/` owns fetch/sync/load workflows, preview helpers, and task wrappers.
-- GeoPackage-backed activity persistence belongs under infrastructure-oriented paths.
-
-**analysis/**
-- dock-facing analysis entrypoints are intentionally being thinned behind workflow-oriented application seams
-- request building, dispatch, result shaping, and status policy belong in application modules, not in the dock
-- QGIS-backed layer creation stays in analysis infrastructure
-
-**visualization/**
-- render planning, temporal intent, and user-facing visualization policy belong in `visualization/application/`
-- layer mutation, renderer construction, basemap loading, and QGIS project wiring belong in `visualization/infrastructure/`
-
-**atlas/**
-- `atlas/` owns publish/export workflows
-- keep naming and ownership crisp across request building, runtime preparation, task execution, and PDF assembly
-- avoid adding abstraction layers that do not clarify responsibility
-
-**ui/**
-- `ui/` is for dock-widget support code, dependency assembly, UI-only coordination, and similar glue
-- UI modules should call workflows and render results, not absorb more business logic
-
-### Testing
-
-Run the main test suite with:
+List iterations:
 
 ```bash
-python3 -m pytest tests/ -x -q --tb=short
+python -m qgis_mapbox_gl_style.iterations list
 ```
 
-Run unittest discovery with:
+Render one historical iteration:
 
 ```bash
-python3 -m unittest discover -s tests -v
+python -m qgis_mapbox_gl_style.iterations render --iteration 006 --camera-set issue-949
 ```
 
-Run the PyQGIS smoke test with:
+The 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:
 
 ```bash
-python3 -m unittest tests.test_qgis_smoke -v
+python -m qgis_mapbox_gl_style.iterations accept --from-run debug/iterations/012/20260620T120000Z --label "Improve contour label placement"
 ```
 
-On machines without PyQGIS installed, the smoke test skips automatically.
-
-### Local install and packaging
+That appends the next manifest entry against the current repository `HEAD`.
 
-Install qfit into a local QGIS profile for testing with:
+## Validation Harness
 
-```bash
-python3 scripts/install_plugin.py --plugins-dir <QGIS plugins dir> --mode copy
-```
+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.
 
-Build a release-style plugin archive with:
+The main visual comparison harness is:
 
 ```bash
-python -m pip install pypdf
-python3 scripts/package_plugin.py
+python validation/mapbox_outdoors_comparison.py --all-cameras --output-root debug/mapbox-outdoors-comparison
 ```
 
-The release ZIP is written to `dist/`.
+See [docs/mapbox-outdoors-comparison-harness.md](docs/mapbox-outdoors-comparison-harness.md) for the full harness workflow.
 
-### CI and review expectations
+## Packaging
 
-Before treating a change as done:
+Build a QGIS install ZIP:
 
-- run the relevant tests
-- keep SonarCloud green
-- keep CodeQL/CI green
-- address meaningful review feedback
-- for export/rendering work, verify the final artifact, not just object construction
-
-### Short version for agents
+```bash
+python scripts/package_plugin.py
+```
 
-If you only remember a few rules, remember these:
+The package is written to `dist/qgis_mapbox_gl_style-<version>.zip`.
 
-- make `QfitDockWidget` thinner, not heavier
-- keep real feature logic inside feature-owned packages
-- keep QGIS-heavy mechanics out of provider-neutral workflow code
-- prefer small, behavior-preserving slices
-- delete migration shims once callers are gone
+## Provenance
 
-## License
+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.
 
-GPL-2.0-or-later. See [LICENSE](LICENSE).
+More detail is in [docs/provenance.md](docs/provenance.md).

__init__.py

@@ -1,4 +1,5 @@
 def classFactory(iface):
-    """Load qfit plugin class."""
-    from .qfit_plugin import QfitPlugin
-    return QfitPlugin(iface)
+    """Load the QGIS Mapbox GL Style plugin class."""
+    from .plugin import QgisMapboxGlStylePlugin
+
+    return QgisMapboxGlStylePlugin(iface)