Layer Styling with gq

Overview

rfp applies cartographic styles from the gq style registry to spatial data layers. When you open a styled GeoPackage in QGIS, layers automatically display with curated New Graph Environment cartography — no manual styling required.

The pipeline:

gq registry (JSON) → PyQGIS (Docker) → layer_styles table → QGIS auto-loads

Applying styles

After creating a project or downloading data with rfp_source():

library(rfp)

rfp_styles_apply("background_layers.gpkg")
#> ℹ Applying gq styles via Docker (qgis/qgis:latest)
#> Styling: whse_fish.pscis_assessment_svw (registry: crossings_pscis_assessment)
#> Styling: whse_basemapping.transport_line (registry: roads_dra)
#> ...
#> Done: 11 styled, 5 skipped
#> ✔ Styles applied

How matching works

The function automatically matches GPKG layer names to gq registry entries using a three-step lookup chain:

1. xref_layers — user-supplied overrides (checked first)
2. Exact name match — layer name matches a registry key directly
3. source_layer field — the gq registry entry’s source_layer matches the GPKG layer name (e.g., registry key roads_dra has source_layer: "whse_basemapping.transport_line")

Most layers match automatically via step 3 — the gq registry already maps registry keys to their BC Data Catalogue layer names.

Custom layer mapping

When a layer name doesn’t match any registry entry, use xref_layers:

rfp_styles_apply(
  "background_layers.gpkg",
  xref_layers = c(
    "my_custom_roads" = "roads_dra",
    "special_crossings" = "crossings_pscis_assessment"
  )
)

Names are layer names in your data; values are gq registry keys.

Format support

rfp_styles_apply() is format-agnostic:

Format	How styles are stored
GeoPackage (.gpkg)	layer_styles table inside the file
GeoJSON, Shapefile, KML	.qml sidecar file alongside the data
Directory of files	One .qml per file

QGIS auto-reads styles from both locations.

Rendering a preview

Verify styles without opening QGIS:

rfp_map_render("background_layers.gpkg", path_out = "preview.png")

This renders all styled layers to a PNG image via headless PyQGIS in Docker. Useful for vignettes, automated testing, and quick visual checks.

# Render specific layers at higher resolution
rfp_map_render(
  "background_layers.gpkg",
  path_out = "detail.png",
  layers = c("whse_fish.pscis_assessment_svw",
             "whse_basemapping.fwa_named_streams"),
  width = 2400,
  height = 1800
)

How it works under the hood

rfp_styles_apply() runs a PyQGIS script inside the official qgis/qgis Docker container:

1. Serialises the gq registry to a temp JSON file
2. Bind-mounts the data, registry, and script into the container
3. The Python script builds QgsSymbol objects from registry properties (fill color, stroke, marker shape, categorized classification)
4. QGIS serialises the symbols to QML via exportNamedStyle()
5. QML is written to the layer_styles table via Python’s sqlite3 module
6. The container exits; the GPKG on the host now contains styled layers

No native QGIS install required — Docker handles everything.

Supported style types

Type	Registry fields	Example
Simple fill (polygon)	fill.color, fill.opacity, stroke.*	Lakes, parks
Simple line	stroke.color, stroke.width, stroke.opacity	Roads, streams
Simple marker (point)	mark.color, mark.shape, mark.radius	Obstacles, stations
Categorized	classification.field, classification.classes	BEC zones, PSCIS barrier status

Labels and graduated renderers are planned for future releases.