Styling and Labeling

This page is generated from the repository on every merge to main; changes made here are overwritten.

apply_categorized_style

Apply categorized style renderer based on field values. Pass palette='humanitarian_cluster' to color categories that match a known IASC global cluster name (Health, WASH, Food Security, Protection, Emergency Shelter, Nutrition, Education, Logistics, CCCM, Early Recovery, Emergency Telecommunications, plus common aliases like 'FSL' or 'Shelter') using commonly recognized humanitarian cluster colors -- the map a field coordinator recognizes instantly instead of one they have to re-read the legend for. Categories that don't match a known cluster name keep the default qualitative color assignment.

Parameter	Type	Required	Description
layer_name	string	yes
field	string	yes
opacity	number	no	0-100. Defaults to 75 for polygon layers (so overlapping layers/basemap underneath stay visible) and 100 for points/lines.
palette	string	no	Optional. 'humanitarian_cluster' (or 'ocha') colors categories matching a known IASC cluster name/alias; unmatched categories keep the default palette.

apply_graduated_style

Apply smart graduated choropleth style analyzing field distribution for optimal breaks. Pass cluster (e.g. 'WASH', 'Health', 'Food Security') to tint the ramp toward that IASC cluster's commonly recognized color instead of the auto-selected Viridis/Cividis ramp -- e.g. a WASH coverage % choropleth rendered in WASH's color, for the map a field coordinator recognizes instantly. Unrecognized cluster names fall back to the default ramp. Pass explicit breaks (e.g. [10000, 25000, 50000, 100000]) for a fixed, mode-independent set of class boundaries -- for humanitarian decision maps, an operational threshold (e.g. response-capacity bands) often matters more than a statistically 'optimal' Jenks/quantile break, and breaks overrides mode entirely when given (point 13 of docs/QGIS_PRODUCTION_ARCHITECTURE_REVIEW_2026-09-04.md).

Parameter	Type	Required	Description
layer_name	string	yes
field	string	yes
mode	string	no	'auto' (default), 'equal', 'quantile', 'stddev' (classes centered on the mean +/- N standard deviations), 'pretty' (rounded, human-friendly breaks for a public-facing map), or 'logarithmic' (log-spaced classes for heavily right-skewed data spanning orders of magnitude, e.g. population or income -- needs all-positive, non-identical values). Ignored if breaks is given.
num_classes	integer	no	Number of classes to split the data into. Defaults to 5. Ignored if breaks is given.
opacity	number	no	0-100. Defaults to 75 for polygon layers (so overlapping layers/basemap underneath stay visible) and 100 for points/lines.
cluster	string	no	Optional IASC cluster name/alias (e.g. 'WASH', 'Health') to tint the ramp toward that cluster's color instead of the auto-selected one.
color_from	string	no	Optional start colour of an explicit ramp, as plain words ('pale yellow') or #rrggbb. Use with color_to when the user names the colours.
color_to	string	no	Optional end colour of an explicit ramp ('dark red' or #rrggbb). Overrides the automatic ramp and cluster tint.
breaks	array[number]	no	Optional explicit class-boundary values (e.g. operational response thresholds), sorted ascending -- when given, these define the classes directly instead of an auto-selected classification method, overriding 'mode'. Data's actual min/max become the outer class bounds.

apply_graduated_symbol_style

Apply a graduated (proportional) SYMBOL SIZE style to a point layer -- circles scaled from a minimum to a maximum size based on a numeric field, analyzing the field's distribution for optimal class breaks the same way apply_graduated_style does for choropleth fill color. Use this for point data (e.g. 'graduated symbol map', 'proportional circles') instead of hand-writing QgsGraduatedSymbolRenderer/QgsRendererRange code via execute_pyqgis_script.

Parameter	Type	Required	Description
layer_name	string	yes
field	string	yes
min_size	number	no	Smallest symbol size in mm. Defaults to 4.
max_size	number	no	Largest symbol size in mm. Defaults to 24.
mode	string	no	'auto' (default), 'equal', 'quantile', 'stddev', or 'pretty'.
num_classes	integer	no	Target number of size classes. Defaults to 5, capped down to the field's actual number of distinct values if fewer.
color	string	no	Hex color (e.g. '#3182bd') for every symbol -- size carries the meaning here, not color. Defaults to a semi-transparent blue.

apply_heatmap_style

Apply heatmap renderer to point layer with transparent zero-density baseline so basemaps remain visible.

Parameter	Type	Required	Description
layer_name	string	yes
field	string	no

apply_point_cluster_style

Applies a point cluster or point displacement renderer to a point layer so overlapping or densely clustered points are cleanly grouped on the map rather than drawing on top of each other. Mode 'cluster' (default) aggregates nearby points within a distance threshold into numeric cluster badges; mode 'displacement' displays co-located or overlapping points arranged in a clean ring/spiral circle around the central coordinate.

Parameter	Type	Required	Description
layer_name	string	yes	Point layer to apply clustering/displacement to.
mode	string	no	'cluster' (default) for aggregate numeric count badges, 'displacement' for circle/ring offset around overlaps.
tolerance	number	no	Cluster distance tolerance in millimeters (default 15.0 mm).

apply_rule_based_style

Apply a rule-based renderer keyed to a controlled vocabulary of field values -- e.g. route/facility status (open/constrained/closed) -- with a FIXED color per value, rather than an auto-assigned qualitative palette (apply_categorized_style) or an auto-classified continuous gradient (apply_graduated_style). Use this when the categories carry a specific operational meaning that needs a caller-chosen color per value, not an auto-picked one. Any field value not matching one of the given rules automatically renders in a neutral gray 'Unknown / No data' class -- do not add your own catch-all rule, and never let an unassessed/missing status look the same as a real class.

Parameter	Type	Required	Description
layer_name	string	yes
field	string	yes
rules	array[object]	yes	One entry per controlled-vocabulary value, e.g. [{"value": "open", "label": "Open", "color_hex": "#2E7D32"}, {"value": "closed", "label": "Closed", "color_hex": "#B3261E"}].

auto_arrange_layer_order

Reorders every top-level layer in the project by geometry type so small features stay visible: points on top, then lines, then polygons, then rasters at the bottom. Call this after adding or styling multiple overlapping layers -- e.g. point markers plus an area/boundary polygon -- so the polygon's fill doesn't bury the points underneath it. This is the usual fix when a map with several layers looks 'messy' or a small icon layer has disappeared under a larger area layer.

No parameters.

change_layer_color

Change layer symbol fill/line color. Pass the colour the user said ("dark red", "pale yellow", "light blue") or a hex code.

Parameter	Type	Required	Description
layer_name	string	yes
color_hex	string	yes
opacity	number	no	Optional, 0-100. Leaves current opacity unchanged if omitted.

export_layer_sld

Exports a vector layer's symbology to an OGC SLD (Styled Layer Descriptor 1.1.0/1.0.0) file on disk. Use this when publishing styles to GeoServer/MapServer or sharing interoperable OGC styling with external GIS portals. Without output_path, saves beside the source file as '.sld' (or to Desktop for scratch/memory layers).

Parameter	Type	Required	Description
layer_name	string	yes	Vector layer to export styling from.
output_path	string	no	Optional explicit .sld file path. Defaults to beside the layer's source file.

hotspot_analysis

Compute a kernel density estimation surface from a point layer -- a real statistical density raster (higher values = more points/higher intensity nearby), not just a visual-only renderer. apply_heatmap_style changes how a layer LOOKS on screen but produces no reusable data; this tool produces an actual raster you can run zonal_statistics against (e.g. rank districts by incident density) or feed into weighted_overlay_analysis for risk-surface analysis. Use this for real hotspot/risk-concentration analysis, apply_heatmap_style for a quick visual only.

Parameter	Type	Required	Description
point_layer	string	yes
radius	number	yes	Kernel search radius in the layer's map units. Larger = smoother, less localized.
pixel_size	number	no	Output raster cell size in map units. Defaults to radius/10.
weight_field	string	no	Optional numeric field to weight points by (e.g. severity) instead of treating every point equally.

load_layer_style

Loads a previously saved .qml style file (from save_layer_style, or exported manually via QGIS's own Layer Properties -> Symbology -> Style -> Save Style) onto a layer, replacing its current symbology -- for reusing a standard humanitarian color scheme/classification across layers or maps instead of rebuilding it from scratch each time.

Parameter	Type	Required	Description
layer_name	string	yes
style_path	string	yes	Path to the .qml style file to load.

save_layer_style

Saves a layer's current symbology (renderer, colors, classification, labeling) to a real .qml style file on disk, so it can be reapplied later to this or another layer with load_layer_style -- for reusing a standard color scheme/classification across multiple layers or maps instead of rebuilding it with apply_categorized_style/apply_graduated_style every time. Without output_path, the file is saved beside the layer's own on-disk source (as '.qml'); for a scratch/memory layer with no real source, it falls back to Desktop instead. For a GeoPackage-backed layer, the style is ALSO written into the GeoPackage's own layer_styles table (OGC 12-128r17) so it travels with the .gpkg file itself -- e.g. opening it in another QGIS install or a different GIS package that reads that table -- not just as an external sidecar that can be misplaced or left behind.

Parameter	Type	Required	Description
layer_name	string	yes
output_path	string	no	Optional explicit .qml file path. Defaults to beside the layer's own source file.

set_layer_order

Explicitly sets the draw order of the given layers, top to bottom (the first name in the list renders on top of the rest, on top of everything else in the project). Use this when auto_arrange_layer_order's point > line > polygon > raster default isn't what's needed -- e.g. two polygon layers that need a specific stacking order relative to each other.

Parameter	Type	Required	Description
layer_names	array[string]	yes	Layer names in the desired draw order, first = topmost.

set_layer_transparency

Set a layer's overall opacity (0-100). Use this to make an area/polygon layer semi-transparent so layers or features underneath it (e.g. point markers) stay visible instead of being fully covered by a solid fill.

Parameter	Type	Required	Description
layer_name	string	yes
opacity_percent	number	yes	0 (fully transparent) to 100 (fully opaque).