Overview & Design Philosophy
PlanX CartoLab is a thematic mapping and print-layout studio for QGIS. It bridges the gap between analytical GIS outputs and publication-ready cartography — every tool produces styled, legend-ready vector layers or directly modifies the QGIS rendering engine. The plugin is built on a single conviction: a map that is hard to read is a map that will not be read. CartoLab encodes cartographic best practices (perceptual scaling, colour-blind-safe palettes, adaptive classification) as Processing algorithms that produce reproducible, defensible map designs.
Every algorithm operates inside the QGIS Processing framework — all maps are deterministic, repeatable, and batch-scriptable. CartoLab applies renderers and symbology directly to layers via QGIS's rendering API; there are no temporary image exports or raster intermediaries unless the algorithm intrinsically produces raster output. The plugin ships with the complete ColorBrewer 2.0 palette collection and the perceptually-uniform viridis family, both accessible from any styling tool.
Design principle. CartoLab follows a prepare → classify → style → layout pipeline. Normalize raw counts into map-ready rates. Classify with an algorithm appropriate to the data distribution. Apply a perceptually-tested colour palette. Assemble the result into a print layout with legend, scale bar, north arrow, and grid — all in one click with Auto Map Sheet.
Quick Start
New user path. (1) On first launch, CartoLab offers to build a sample map — accept to see the full pipeline in action. (2) Select any polygon layer, run Quick Style with a numeric field and the Viridis palette — you have a choropleth in one step. (3) For publication: run Auto Map Sheet to assemble the current map view into a print layout with legend, scale bar, north arrow, grid, and credits. (4) Explore the Colour Palette Library in the dashboard to find palettes filtered by colour-blind safety.
Colour Palette Library
CartoLab ships 25+ palettes organized by data type, with a colour-blind-safe flag on each. All palettes are sampled to an arbitrary class count via linear interpolation (sequential/diverging) or ordered cycling (qualitative).
Scientific Perceptually-Uniform
Viridis, Magma, Plasma, Inferno, Cividis — all colour-blind-safe. Designed for continuous data where perceptual linearity matters (readers should see equal steps as equal differences).
ColorBrewer Sequential
Blues, Greens, Oranges, Reds, Purples, Greys — all colour-blind-safe. Single-hue progressions for ordered data (low→high).
ColorBrewer Diverging
RdBu, PuOr, BrBG, PRGn, RdYlBu, RdYlGn, Spectral — most colour-blind-safe. Two-hue ramps for data with a meaningful midpoint (e.g., change from baseline).
ColorBrewer Qualitative
Set1, Set2, Set3, Pastel1, Dark2, Paired, Accent. Discrete hues for categorical data — no implied ordering. Not all are colour-blind-safe; the dashboard filter identifies which are.
Dashboard & Layout Tools
Beyond the Processing Toolbox algorithms, CartoLab provides a dockable dashboard and layout automation tools accessible from the plugin toolbar.
Auto Map Sheet
One-click print layout from the current map canvas view. Assembles map frame, legend (auto-detected from active layer's renderer), scale bar, north arrow, coordinate grid, and credits footer. Configurable DPI (96–600), export formats (PNG, PDF, SVG).
Layout Manager
Open, duplicate, rename, delete, and batch-export print layouts. Each layout preset carries its own DPI and format configuration. PNG/PDF/SVG export at 96–600 dpi.
Colour Palette Browser
Live preview of any palette on the current map. Filter by colour-blind-safe status. Shows the palette kind (sequential/diverging/qualitative) and sample count.
Floating Annotation
Place styled HTML annotation boxes on the map canvas. Useful for inset explanations, data source credits, or analytical notes that travel with the map view.
Onboarding
First-run welcome dialog that builds a sample map in seconds, demonstrating the full CartoLab pipeline — from normalization through classification to styled output — on bundled sample data.
Transforms raw count fields into map-ready values. The single most important preprocessing step in choropleth mapping: mapping a raw count as colour simply redraws the population distribution. Normalization removes the size effect so the map shows rates, densities, or relative intensities — the quantities that actually vary independently of enumeration unit size.
Parameters
| Parameter | Type | Default | Description |
|---|
| INPUT | Vector Layer | — | Input layer |
| FIELD | Numeric Field | — | Numerator value field |
| METHOD | Enum | Rate | Rate / Z-score / Robust z (MAD) / Min-max / Percentile rank / Log₁₀ |
| DENOMINATOR | Numeric Field (opt) | — | Denominator (Rate method only) |
| SCALE | Double | 1.0 | Rate multiplier (e.g. 100,000 for per-100k) |
| OUTPUT | Vector Layer | — | Output with norm_value field |
rate = (numerator / denominator) × scale z = (x − μ) / σ robust_z = (x − median) / MAD
Cartographic rule. Never map a raw count. Always normalize by area (density), population (per-capita rate), or another defensible denominator. The choice of denominator is a cartographic argument, not a technical convenience — it encodes what the map claims to show. A map of "crime per square kilometre" and a map of "crime per 1,000 residents" can look entirely different from the same raw count data.
Classifies a numeric field using one of three advanced algorithms, each optimized for a different distribution shape. The choice of classifier is the second-most consequential cartographic decision after normalization — it determines which patterns the map reveals and which it obscures.
Parameters
| Parameter | Type | Default | Description |
|---|
| INPUT | Vector Layer | — | Input layer |
| FIELD | Numeric Field | — | Field to classify |
| CLASSES | Integer | 5 | Number of classes (2–20) |
| METHOD | Enum | GIC | Adaptive GIC / Head-Tail Breaks / Fisher-Jenks |
| OUTPUT | Vector Layer | — | Output with gic_class field + graduated renderer |
When to use which.
Adaptive GIC: Best general-purpose classifier. Handles skewed continuous data by computing class breaks that follow a geometric progression — narrower bins in the dense part of the distribution, wider bins in the sparse tail. Produces legible maps for the skewed distributions that dominate planning data.
Head/Tail Breaks: For heavy-tailed / power-law distributions (city sizes, traffic volumes, wealth). Recursively splits data at the arithmetic mean, identifying a hierarchy of "head" (above-mean) and "tail" (below-mean) clusters. Reveals the nested structure that conventional classifiers collapse.
Fisher-Jenks: Minimizes within-class variance — the statistically optimal classifier for a given class count. Computationally intensive (dynamic programming); best when statistical fidelity is the primary concern and class count is small (≤7).
Jenks, G.F. (1967). "The Data Model Concept in Statistical Mapping." International Yearbook of Cartography 7: 186–190. · Jiang, B. (2013). "Head/Tail Breaks: A New Classification Scheme for Data with a Heavy-Tailed Distribution." The Professional Geographer 65(3): 482–494.
The core cartographic algorithms. Each produces a distinct visual encoding of spatial data — colour matrices, opacity channels, dot textures, sized symbols, and waveform profiles.
Creates an N×N bivariate choropleth by classifying two numeric fields and assigning each polygon a cell in a 2D colour matrix. The four corner colours (Low-Low, Low-High, High-Low, High-High) define the colour space; intermediate cells are interpolated. Automatically applies a categorized renderer with the full bivariate legend. Output fields: bivar_x_class, bivar_y_class, bivar_class (e.g., "(1,2)").
Parameters
| Parameter | Type | Default | Description |
|---|
| INPUT | Vector Layer | — | Input polygon layer |
| FIELD_X | Numeric Field | — | X-axis variable |
| FIELD_Y | Numeric Field | — | Y-axis variable |
| CLASSES | Integer | 3 | Grid size (2–5; 3×3 = 9 colours) |
| METHOD | Enum | Geometric | Geometric Interval / Fisher-Jenks |
| COLOR_LL/HL/LH/HH | Color | corners | Four corner colours of the bivariate matrix |
| OUTPUT | Vector Layer | — | Auto-styled bivariate choropleth |
Cartographic design. Bivariate maps encode two variables simultaneously — but readers can only interpret ~3–5 distinguishable classes per axis. Beyond 4×4 (16 colours), the matrix becomes illegible. The four corners should follow a tested scheme: typically LL=pale neutral, LH=blue, HL=red/pink, HH=brown/purple, following Brewer's diagnostic colour scheme recommendations. The automatic post-processor applies semi-transparent white polygon outlines (alpha=140) for clean separation without the "jigsaw puzzle" effect of heavy black borders.
Brewer, C.A. (1994). "Color Use Guidelines for Mapping and Visualization." In Visualization in Modern Cartography, Elsevier, 123–147. · Brewer, C.A. & Pickle, L. (2002). "Evaluation of Methods for Classifying Epidemiological Data." Annals of the AAG 92(4): 662–681.
Encodes a secondary reliability/uncertainty variable as opacity (alpha channel). The primary variable drives colour intensity; the secondary variable controls transparency — highly reliable areas are opaque and visually dominant; uncertain areas fade into the background. Adds vba_alpha (0–255) and vba_alpha_pct (0–100) fields. Configure min/max opacity (default 25–255) to control the visual weight of uncertain data.
Parameters
| Parameter | Type | Default | Description |
|---|
| INPUT | Vector Layer | — | Input layer |
| FIELD_COLOUR | Numeric Field | — | Primary variable (colour) |
| FIELD_ALPHA | Numeric Field | — | Reliability variable (opacity) |
| ALPHA_MIN | Integer | 25 | Minimum opacity (0–255) |
| ALPHA_MAX | Integer | 255 | Maximum opacity (0–255) |
| OUTPUT | Vector Layer | — | VbA output with alpha fields |
Use case. VbA is the standard method for visually communicating confidence alongside estimate. Map census income (colour) with sampling error margin (alpha) → affluent areas with large error bars appear washed out, correctly signalling that the colour is less trustworthy there. Map model predictions with cross-validation R² as the alpha variable → well-predicted areas pop, poorly-predicted areas recede.
Roth, R.E., Woodruff, A.W. & Johnson, Z.F. (2010). "Value-by-Alpha Maps: An Alternative Technique to the Cartogram." The Cartographic Journal 47(2): 130–140.
Scatters dots inside polygons — one dot per N units of a count field — so data density reads as visual texture rather than colour. Seeded placement (deterministic, reproducible) with hole-awareness (dots avoid interior holes). Each dot inherits its source polygon's attributes, enabling multi-group dot maps by colouring dots categorically.
Parameters
| Parameter | Type | Default | Description |
|---|
| INPUT | Polygon Layer | — | Input polygon layer |
| FIELD | Numeric Field | — | Count field |
| VALUE_PER_DOT | Double | 100.0 | Population value each dot represents |
| SEED | Integer | 42 | Deterministic seed for reproducible placement |
| OUTPUT | Point Layer | — | Dot points with source attributes |
Dot value selection. Choose VALUE_PER_DOT so the densest polygon produces at most a few hundred dots — too many dots merge into a solid fill; too few lose the texture effect. Good rule of thumb: max dots per polygon ≈ 300. For a polygon with 30,000 population, set VALUE_PER_DOT = 100. The pure-Python generator (no random module, deterministic from seed) ensures identical output on every run.
Places a point at each feature centroid with symbol size proportional to a numeric field. Flannery perceptual compensation (size = value0.5716) corrects for the well-documented tendency of map readers to underestimate circle areas — without it, large values appear too small relative to their true magnitude. Adds a psym_size field (mm) for data-defined marker size, plus suggested nested legend values.
Parameters
| Parameter | Type | Default | Description |
|---|
| INPUT | Vector Layer | — | Input layer |
| FIELD | Numeric Field | — | Magnitude field |
| MAX_SIZE | Double | 12.0 | Max symbol diameter (mm) |
| MIN_SIZE | Double | 1.0 | Min symbol diameter (mm) |
| FLANNERY | Boolean | true | Apply Flannery perceptual compensation |
| OUTPUT | Point Layer | — | Output with psym_size field |
size = min + (max − min) · (valuek − min_valk) / (max_valk − min_valk) k=0.5716 (Flannery) or 0.5 (true area)
Flannery, J.J. (1971). "The Relative Effectiveness of Some Common Graduated Point Symbols in the Presentation of Quantitative Data." The Canadian Cartographer 8(2): 96–109.
Generates overlapping waveform profiles from a single-band raster by deforming horizontal scanlines vertically according to raster values. Produces a vector line layer suitable for dark-background styling with transparency — the iconic "joyplot" aesthetic. Best raster inputs: DEM, density surfaces, LST, impervious surface ratio. Control vertical exaggeration, line spacing, smoothing passes, and clip extent.
Parameters
| Parameter | Type | Default | Description |
|---|
| RASTER | Raster | — | Single-band input raster |
| N_LINES | Integer | 60 | Scanline count (5–500) |
| VERTICAL_SCALE | Double | 1.0 | Vertical exaggeration (0.01–100) |
| LINE_SPACING | Double | 1.0 | Baseline spacing in map units |
| SMOOTH | Integer | 2 | Smoothing passes (0=raw, 20=max) |
| EXTENT | Extent (opt) | — | Clip extent |
| OUTPUT | Line Layer | — | Ridge line vectors |
Styling tip. Use a dark canvas background (#1a1a2e or similar), apply a light-coloured stroke (white or pale cyan) with 20–40% opacity, and set line width to 0.3–0.5 mm. The overlapping transparent lines create the characteristic "glow" where ridges intersect. For elevation data, a single-hue gradient (dark blue for low valleys → bright white for high peaks) works well.
Distorts polygon areas to be proportional to a numeric field using the diffusion method of Gastner & Newman (2004). The algorithm iteratively displaces polygon boundaries — treating area as a density that diffuses from high-density to low-density regions — until each polygon's area represents its field value. A zero-width buffer fixes topology issues on exit. Outputs the final iteration count and residual average error (%) as processing outputs.
Parameters
| Parameter | Type | Default | Description |
|---|
| INPUT | Polygon Layer | — | Input polygon layer (≥2 features) |
| FIELD | Numeric Field | — | Area-representation field |
| MAX_ITERATIONS | Integer | 30 | Max iterations (1–200) |
| MAX_ERROR | Double | 5.0 | Max average error % (0.1–100) |
| OUTPUT | Polygon Layer | — | Cartogram output |
Density ρi = valuei / areai → Diffusion flux ∝ ∇ρ → Boundary displacement until ρ uniform
Algorithm. The Gastner-Newman diffusion method is the gold standard for continuous-area cartograms. Unlike rubber-sheet algorithms that can produce self-intersecting geometries, the diffusion approach preserves topology and produces smooth, recognizable shapes even at high distortion levels. The Gaussian-weighted diffusion kernel with adaptive damping (implemented in CartoLab's CartogramEngine) improves convergence on irregular polygon tessellations.
Gastner, M.T. & Newman, M.E.J. (2004). "Diffusion-based method for producing density-equalizing maps." PNAS 101(20): 7499–7504.
Aggregates a point layer into a pointy-top hexagonal grid. Only hexagons that contain points are emitted — dense scatterplots become clean, overplot-free density surfaces. Supports count, sum, and mean statistics on an optional weight field. Output carries hex_count, hex_sum, and hex_mean fields and is auto-graduated on the chosen statistic. Cell size is the hexagon radius in map units.
Parameters
| Parameter | Type | Default | Description |
|---|
| INPUT | Point Layer | — | Input point layer |
| CELL_SIZE | Double | 1000.0 | Hexagon radius (map units) |
| WEIGHT | Numeric Field (opt) | — | Weight field for sum/mean |
| STAT | Enum | Count | Count / Sum / Mean |
| OUTPUT | Polygon Layer | — | Hexbin grid with stats |
Why hexagons? Hexagonal binning is superior to square grids for visual analysis: hexagons have a lower perimeter-to-area ratio (less visual clutter from grid lines), each cell has 6 equidistant neighbours (square grids have 4 edge + 4 corner neighbours at different distances), and the hexagonal lattice avoids the vertical/horizontal streaking artifacts that square grids can create. CartoLab uses pointy-top hexagons (flat sides are vertical).
Carr, D.B., Littlefield, R.J., Nicholson, W.L. & Littlefield, J.S. (1987). "Scatterplot Matrix Techniques for Large N." Journal of the American Statistical Association 82(398): 424–436.
Generates a line layer of meridians and parallels across a user-specified extent on "nice" round coordinate intervals. Each line carries its orientation (vertical/horizontal), constant coordinate value, and a formatted label string — label the output with the label field for automatic coordinate annotation. Leave an interval at 0 to auto-pick a round step that produces ~8 lines across the extent.
Parameters
| Parameter | Type | Default | Description |
|---|
| EXTENT | Extent | — | Grid extent (in target CRS) |
| X_INTERVAL | Double | 0.0 | Meridian spacing (0=auto) |
| Y_INTERVAL | Double | 0.0 | Parallel spacing (0=auto) |
| OUTPUT | Line Layer | — | Graticule line vectors |
Computes the visual center of each polygon — the interior point farthest from any polygon edge — using the polylabel algorithm (Mapbox). Unlike centroids (which can fall outside concave polygons or in narrow inlets), the visual center is guaranteed to be inside the polygon and in the position that maximizes label legibility. Configurable precision (default 1.0 map units). Output is a point layer with dist_to_edge field.
Parameters
| Parameter | Type | Default | Description |
|---|
| INPUT | Polygon Layer | — | Input polygon layer |
| PRECISION | Double | 1.0 | Search precision (map units) |
| OUTPUT | Point Layer | — | Visual-center points |
polylabel: quad-tree search for the point maximizing distance to the polygon boundary, with precision ε
Algorithm. The polylabel algorithm recursively subdivides the polygon's bounding box using a quad-tree, computing the signed distance to the polygon boundary at each cell center. Cells that cannot contain a better point (because their radius + best distance so far < distance to boundary at cell center) are pruned. This is O(n log n) in practice and produces points perceptually centered in the polygon's "widest" region — ideal for label placement.
Applies a polished native QGIS 2.5D renderer to a loaded polygon layer — no plugin renderer, no WebGL, pure QGIS engine. Supports two height modes (real height in metres, or floor count × floor height), two render modes (native 2.5D material with configurable roof/wall/shadow, or per-floor colour bands with selectable palettes), stepped extrusion for architectural detail, soft shadows, and QML export. Configurable viewing angle, height scale, and max height clamp.
Parameters
| Parameter | Type | Default | Description |
|---|
| INPUT | Polygon Layer | — | Building footprint layer |
| HEIGHT_FIELD | Numeric Field | — | Height or floor-count field |
| HEIGHT_MODE | Enum | Metres | Metres / Floor count × floor height |
| RENDER_MODE | Enum | Native | Native 2.5D material / Per-floor colour bands |
| PRESET | Enum | — | Material preset (White Modern, Sandstone, Dark Slate, Terracotta, Glass Blue, Concrete) |
| ANGLE | Double | 70° | Viewing angle (0–180) |
| SHADOW_ENABLED | Boolean | true | Enable soft shadows |
| STEPPED | Boolean | false | Stepped extrusion for roof detail |
Floor bands mode. When render mode is set to per-floor colour bands, CartoLab creates one QGIS renderer rule per floor band with graduated colours — the ground floor is the darkest shade, the top floor the lightest (or reverse, depending on palette). This produces a Lego-style stacked effect that makes floor-count data legible at a glance. Selectable palettes include Viridis, Magma, Blues, Greens, and warm/cool gradients. Auto-detected max floors from the data.
Style any vector layer in one step. Pick a field and a colour palette (ColorBrewer or the colour-blind-safe viridis family). CartoLab auto-detects field type: numeric fields → graduated renderer with configurable class count and method (Quantile, Equal Interval, Geometric Interval); text fields → categorized renderer with unique-value colours. The renderer is applied to the selected layer in place — no intermediate output layer, no duplication. Reversible with QGIS's rendering history.
Parameters
| Parameter | Type | Default | Description |
|---|
| INPUT | Vector Layer | — | Layer to style (modified in place) |
| FIELD | Field | — | Field to base styling on |
| MODE | Enum | Auto | Auto / Graduated / Categorized |
| CLASSES | Integer | 5 | Number of classes (graduated, 2–12) |
| METHOD | Enum | Quantile | Quantile / Equal Interval / Geometric Interval |
| PALETTE | Enum | Viridis | Palette name from the 25+ palette library |
| REVERSE | Boolean | false | Reverse palette order |
When to use each method. Quantile (equal count) ensures every class has roughly the same number of features — good for highlighting relative rank, bad when outliers should stand alone. Equal interval is simple and interpretable — good when data are uniformly distributed, bad for skewed data (most features fall in 1–2 classes). Geometric interval adapts to skew — best general-purpose choice for the heavy-tailed distributions common in planning data.
Cartographic Design Notes
The Normalize-First Rule
Every choropleth map should display a rate, density, or proportion, never a raw count. A map of "total population by district" is a map of district size — large districts will always appear dominant regardless of their actual population density. Normalize by area (population/km²), by population (cases per 100,000 residents), or by another meaningful denominator before applying any colour ramp. CartoLab's Normalize Field tool enforces this rule with six normalization methods.
Colour-Blind-Safe Design
Approximately 8% of men and 0.5% of women have some form of colour vision deficiency (CVD). CartoLab's palette library flags each palette with a cb_safe boolean. All five scientific palettes (Viridis, Magma, Plasma, Inferno, Cividis) and most ColorBrewer sequential/diverging palettes are CVD-safe. The dashboard filter toggles to show only CVD-safe palettes. When publishing maps for general audiences, always verify your palette choice against a CVD simulation.
Perceptual Scaling
Map readers systematically underestimate the area of circles — a circle representing value 100 looks only about 70% as large as it should relative to a circle representing value 50. Flannery (1971) quantified this as a power-law exponent of ~0.87 (readers perceive area ∝ radius1.74 rather than radius²). The Flannery compensation exponent (0.5716) corrects for this by sizing symbols so their perceived area is proportional to the data value. CartoLab's Proportional Symbols tool applies this by default; disable it only for true mathematical area-proportional symbols when exact geometric scaling is required.
Classification and the Modifiable Areal Unit Problem (MAUP)
Changing the number of classes changes the map — sometimes dramatically. Five classes may show a clear regional pattern that seven classes fragment into noise. There is no "correct" class count; the choice should be defended in relation to the map's purpose. For exploratory analysis, use 5–7 classes with Geometric Interval (robust to skew). For publication, test 3–5 class counts and choose the one that tells the clearest story without oversimplifying. CartoLab's Advanced Classification tool makes this testing fast — re-run with different class counts and compare.
Print Layout Resolution
CartoLab's Layout Manager exports at configurable DPI (96–600). For screen viewing, 96–150 DPI is sufficient. For print, 300 DPI is the standard for most publications; 600 DPI for maps with fine linework or small text. PDF is the recommended vector format — it preserves text editability and scales to any resolution. PNG at 300 DPI produces a raster suitable for Word/PowerPoint documents. SVG preserves full editability in vector graphics software.
Academic References
Brewer, C.A. (1994). "Color Use Guidelines for Mapping and Visualization." In Visualization in Modern Cartography, Elsevier, 123–147.
Brewer, C.A. (2003). "A Transition in Improving Maps: The ColorBrewer Example." Cartography and Geographic Information Science 30(2): 159–162.
Brewer, C.A. & Pickle, L. (2002). "Evaluation of Methods for Classifying Epidemiological Data on Choropleth Maps in Series." Annals of the AAG 92(4): 662–681.
Carr, D.B., Littlefield, R.J., Nicholson, W.L. & Littlefield, J.S. (1987). "Scatterplot Matrix Techniques for Large N." JASA 82(398): 424–436.
Dent, B.D., Torguson, J.S. & Hodler, T.W. (2009). Cartography: Thematic Map Design (6th ed.). McGraw-Hill.
Flannery, J.J. (1971). "The Relative Effectiveness of Some Common Graduated Point Symbols." The Canadian Cartographer 8(2): 96–109.
Gastner, M.T. & Newman, M.E.J. (2004). "Diffusion-based method for producing density-equalizing maps." PNAS 101(20): 7499–7504.
Jenks, G.F. (1967). "The Data Model Concept in Statistical Mapping." International Yearbook of Cartography 7: 186–190.
Jiang, B. (2013). "Head/Tail Breaks: A New Classification Scheme for Data with a Heavy-Tailed Distribution." The Professional Geographer 65(3): 482–494.
Roth, R.E., Woodruff, A.W. & Johnson, Z.F. (2010). "Value-by-Alpha Maps: An Alternative Technique to the Cartogram." The Cartographic Journal 47(2): 130–140.
Slocum, T.A., McMaster, R.B., Kessler, F.C. & Howard, H.H. (2009). Thematic Cartography and Geovisualization (3rd ed.). Pearson.