Vector and Geoprocessing

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

add_layer_from_path (two-phase)

Load vector or raster file from a local path or remote URL (e.g. a GeoJSON download link).

Parameter	Type	Required	Description
file_path	string	yes
layer_name	string	no
sublayer	string	no	name of ONE layer/table inside a multi-layer file (GeoPackage, FileGDB, KML, GPX, SpatiaLite); omit to open the first and be told what else the file holds

apply_labels

Apply text labels to a vector layer, either from a single field (target_field) or a QGIS expression combining multiple fields/literals (expression) -- e.g. a governorate name, P-code, and a count combined into one label like "Sa'dah [YE22 | 4 Orgs]" via "adm1_name || ' [' || adm1_pcode || ' | ' || org_count || ' Orgs]'" -- instead of hand-writing QgsPalLayerSettings code via execute_pyqgis_script for a combined label. Pass exactly one of target_field/expression. Applies a white text halo/buffer by default so labels stay legible over dense polygons or dark rasters, and -- for point layers -- an 8-position ordered placement with collision avoidance instead of an arbitrary single position.

Parameter	Type	Required	Description
layer_name	string	yes
target_field	string	no	A single field to label from. Omit if using expression instead.
expression	string	no	A QGIS expression combining multiple fields/literals into one label. Omit if using target_field instead.
font_size	number	no	Label text point size. Defaults to 10 -- pass a larger value for higher-hierarchy features (e.g. a capital vs. a village) and a smaller one for dense point layers.
priority	number	no	PAL anti-collision priority, 0 (lowest) to 10 (highest). Defaults to 5. Higher-priority labels win when two labels would otherwise overlap.

buffer_analysis

Create a buffer polygon layer around features. distance is interpreted in the layer's OWN CRS units, not automatically converted -- meters for a typical projected/UTM CRS, but DEGREES for a geographic CRS (e.g. EPSG:4326/WGS84). Buffering a WGS84 layer by 500 expecting 500 meters actually buffers by 500 degrees (most of the way around the globe), not a small error but a silently nonsensical result. If the target layer's CRS is geographic, reproject it to an appropriate projected/UTM CRS first (or check get_layers()'s crs field before calling this). To buffer only SPECIFIC features (e.g. 'buffer around alerts X and Y', not the whole layer), first select them -- select_by_attribute for one value, or highlight_features with an expression like "event_id IN ('X','Y')" for several -- then call this with only_selected=True. Without only_selected=True, this always buffers every feature in the layer, regardless of any current selection.

Parameter	Type	Required	Description
layer_name	string	yes
distance	number	yes	Buffer distance in the layer's own CRS units (meters for a projected CRS, degrees for a geographic one -- see this tool's own description).
only_selected	boolean	no	If true, buffer only the layer's currently-selected features instead of the whole layer. Errors if nothing is selected, rather than silently falling back to the full layer.
output_name	string	no	Name for the new buffer layer, used exactly as given when the user asked for a specific name. Omit to get 'buffer'.

calculate_area

Calculate polygon area in square meters and write it into a new 'area_sqm' field on the layer. Destructive action requiring UI confirmation -- same underlying operation as field_calculator (in-place attribute mutation on the live layer).

Parameter	Type	Required	Description
layer_name	string	yes

calculate_length

Calculate line length in meters and write it into a new 'length_m' field on the layer. Destructive action requiring UI confirmation -- same underlying operation as field_calculator (in-place attribute mutation on the live layer).

Parameter	Type	Required	Description
layer_name	string	yes

centroid

Generate centroid points for polygon layer.

Parameter	Type	Required	Description
layer_name	string	yes

clip_layer

Clip vector layer by mask layer.

Parameter	Type	Required	Description
input_layer	string	yes
mask_layer	string	yes

convert_to_singlepart

Split multipart geometries (e.g. a MultiPolygon feature representing several separate islands) into one single-part feature per part. Useful cleanup before per-feature analysis like calculate_area or centroid, which otherwise treat all parts as one feature.

Parameter	Type	Required	Description
layer_name	string	yes

convex_hull

Generate the convex hull polygon(s) enclosing a layer's features -- the smallest convex polygon containing all of them. Useful for catchment/coverage-area style analysis (e.g. the outer boundary of a set of service points).

Parameter	Type	Required	Description
layer_name	string	yes

delaunay_triangulation

Generate a Delaunay triangulation from a point layer -- a mesh of non-overlapping triangles connecting the points, useful as a basis for terrain interpolation or network-like proximity analysis.

Parameter	Type	Required	Description
layer_name	string	yes

diagnose_topology

Diagnose self-intersections, slivers, exact-duplicate geometries, and (for polygon layers) overlapping features in a vector layer. Pass min_area to also flag polygons smaller than a given threshold (in the layer's CRS units squared) as small_polygons, distinct from exact zero-area slivers. Does NOT check for gaps between polygons meant to tile an area (e.g. missing coverage inside an admin boundary) -- that needs a reference boundary to diff against that this tool has no way to infer, and a heuristic based on dissolving the layer and looking for interior holes would misfire as a false gap on almost any real humanitarian admin-boundary layer (a coastline, an unmapped buffer zone, a deliberately excluded area are all real holes, not QA failures) -- that remains open, see point 4 of docs/QGIS_PRODUCTION_ARCHITECTURE_REVIEW_2026-09-04.md.

Parameter	Type	Required	Description
layer_name	string	yes
min_area	number	no	Optional. Flags polygons with 0 < area < min_area (in the layer's CRS units squared) as small_polygons, separate from exact zero-area slivers.

difference_layers

Subtract one vector layer from another (A minus B) -- e.g. 'everything outside the flood zone'. Set symmetric=true for a symmetric difference (everything in A or B but not in both) instead.

Parameter	Type	Required	Description
input_layer	string	yes	Layer to subtract from (A).
overlay_layer	string	yes	Layer to subtract (B).
symmetric	boolean	no	True for symmetric difference. Defaults to false.

dissolve_layer

Dissolve vector features optionally grouped by field.

Parameter	Type	Required	Description
layer_name	string	yes
field	string	no

field_calculator

Calculate or add field using QGIS expression. Destructive action requiring UI confirmation.

Parameter	Type	Required	Description
layer_name	string	yes
new_field	string	yes
expression	string	yes

field_statistics

Compute summary statistics (count, sum, mean, median, min, max, stdev, range) for a numeric field across every feature in a layer -- a flat project-wide summary, not per-zone (use zonal_statistics for that).

Parameter	Type	Required	Description
layer_name	string	yes
field	string	yes

find_nearest_features

For each feature in input_layer, find the nearest feature(s) in near_layer and join it (plus the nearest feature's attributes) -- e.g. 'nearest hospital to each village'. The 'distance' field is in the layer's own CRS units; distance_m is added in real metres (ellipsoidal) whenever those units are not metres, so use distance_m when the layers are in latitude/longitude. Creates a new layer; input_layer and near_layer are unchanged.

Parameter	Type	Required	Description
input_layer	string	yes	Layer whose features get a nearest-match added, e.g. villages.
near_layer	string	yes	Layer to search for the nearest feature in, e.g. hospitals.
neighbors	integer	no	How many nearest matches per feature. Defaults to 1.

fix_geometries

Fix invalid geometries in vector layer.

Parameter	Type	Required	Description
layer_name	string	yes

get_attributes

Get list of field/attribute names for a layer.

Parameter	Type	Required	Description
layer_name	string	yes

get_crs

Get CRS authid, description, and units for layer.

Parameter	Type	Required	Description
layer_name	string	yes

get_feature_count

Get total feature count in a layer.

Parameter	Type	Required	Description
layer_name	string	yes

get_layer_extent

Get a layer's extent, in its own CRS and transformed to WGS84 degrees. Use this -- never a remembered or estimated bounding box -- whenever a tool needs a bbox in degrees (fetch_osm_features, fetch_building_footprints, search_stac_satellite_imagery, fetch_worldpop_population). The result gives the box in BOTH orders, named: bbox_south_west_north_east for the OSM and building-footprint tools, bbox_west_south_east_north for the STAC search. Pass layer_name='canvas' for the current map view.

Parameter	Type	Required	Description
layer_name	string	yes	A layer name, or 'canvas' for the current map view.

get_layers

Get all layers in current QGIS project with name, type, ID, CRS, feature count, and field names in one call -- covers most basic inspection needs (a vector layer's field names, a rough size check via feature_count) without a separate get_attributes round trip per layer. Point 21 of docs/QGIS_PRODUCTION_ARCHITECTURE_REVIEW_2026-09-04.md. feature_count/fields are omitted for layers that don't have them (e.g. a raster has no attribute table).

No parameters.

highlight_features

Select features in a layer matching expression.

Parameter	Type	Required	Description
layer_name	string	yes
expression	string	yes

intersect_layers

Intersection of two vector layers.

Parameter	Type	Required	Description
layer1	string	yes
layer2	string	yes

invert_selection

Invert the current feature selection on a layer -- previously unselected features become selected and vice versa.

Parameter	Type	Required	Description
layer_name	string	yes

join_by_attribute

Join attributes from one layer to another by a shared field value (not location -- use spatial_join for that). If target_field/join_field are omitted, suggests fuzzy-matched candidate field pairs instead of running the join -- call again with the fields once you've picked one. Warns if the join field isn't unique on the join layer, since that duplicates features on the target side (1-to-many) rather than a clean 1-to-1 join.

Parameter	Type	Required	Description
target_layer	string	yes
join_layer	string	yes
target_field	string	no	Field on target_layer to join on. Omit to get fuzzy-matched suggestions.
join_field	string	no	Field on join_layer to join on. Omit to get fuzzy-matched suggestions.

load_tabular_data_as_layer

Load the FULL contents of a CSV or Excel (.xlsx/.xls) file as a real QGIS layer -- not a preview or a summary. Use this whenever the user has attached, downloaded, or referenced a spreadsheet/CSV file and wants the actual data in the project, not just a description of it. If the file has coordinate columns (e.g. latitude/longitude) or a WKT geometry column, pass x_field/y_field or wkt_field to create a real point/geometry layer; if omitted, this tool tries to auto-detect common column names on its own (for both CSV and Excel) and reports what it used -- if it can't confidently guess, it returns FIELD_SUGGESTION with the real column names instead of guessing wrong. A file with no coordinate columns (a forecast, survey or 3W table) is loaded as a plain non-spatial attribute table by passing as_table=true; omitting the coordinate arguments alone just returns the suggestion again.

Parameter	Type	Required	Description
file_path	string	yes	Absolute path to the .csv/.xlsx/.xls file.
layer_name	string	no
x_field	string	no	Longitude/X column name.
y_field	string	no	Latitude/Y column name.
wkt_field	string	no	Column containing WKT geometry strings.
sheet_name	string	no	Sheet name for Excel files with multiple sheets. Defaults to the first sheet.
crs	string	no	CRS of x_field/y_field coordinates. Defaults to EPSG:4326.
delimiter	string	no	CSV field delimiter. Defaults to ','.
as_table	boolean	no	true: load as a plain attribute table with no geometry (a forecast, survey or 3W file). Skips coordinate detection.

merge_layers

Merge multiple vector layers into one.

Parameter	Type	Required	Description
layer_names_list	array[string]	yes

obfuscate_sensitive_points

Displace or aggregate sensitive point locations (e.g. GBV survivors, individual IDP households, protection incidents) before they're mapped, exported, or included in any report -- a Do No Harm safeguard, and increasingly an explicit donor/ECHO compliance requirement. Recommend this as a step before add_incident_point/add_point_layer output or export_layer involving protection-flagged data goes anywhere -- never apply it silently or automatically without the user choosing to. Three methods: 'jitter' (random displacement within radius; radius is in the LAYER'S OWN CRS UNITS, not meters -- for a geographic CRS like EPSG:4326 a radius intended as '500 meters' would actually mean 500 DEGREES and scatter points across the globe, so reproject to a projected CRS first if a specific real-world distance matters), 'grid_snap' (collapses every point sharing a grid cell to that cell's centroid -- the strongest protection of the three, since it destroys individual-point identity rather than just displacing it; cell_size is also in the layer's own CRS units), or 'admin_unit_snap' (moves each point to the centroid of the admin-boundary polygon it falls within, from a separate polygon layer). The method and its parameter are always included in the output so they're disclosable in any report alongside the map. A MultiPoint feature is obfuscated part by part and written as one output point per part, with the same attributes.

Parameter	Type	Required	Description
layer_name	string	yes	Point layer with sensitive locations.
method	string	yes	One of: 'jitter', 'grid_snap', 'admin_unit_snap'.
radius	number	no	Required for 'jitter': max displacement, in the layer's own CRS units.
cell_size	number	no	Required for 'grid_snap': grid cell size, in the layer's own CRS units.
admin_layer_name	string	no	Required for 'admin_unit_snap': polygon layer of admin units to snap to.
output_layer_name	string	no	Optional name for the new layer; defaults to '{layer_name}_obfuscated'.
seed	integer	no	Optional random seed for 'jitter', for reproducible output.

open_attribute_table

Open attribute table GUI for layer.

Parameter	Type	Required	Description
layer_name	string	yes

remove_layer

Remove layer from QGIS project. Destructive action requiring UI confirmation.

Parameter	Type	Required	Description
layer_name	string	yes

rename_layer

Rename layer in QGIS project.

Parameter	Type	Required	Description
old_name	string	yes
new_name	string	yes

reproject_layer

Reproject layer to target CRS code (e.g. 'EPSG:4326').

Parameter	Type	Required	Description
layer_name	string	yes
crs_code	string	yes

run_query

Filter layer features using a QGIS expression.

Parameter	Type	Required	Description
layer_name	string	yes
expression	string	yes

select_by_attribute

Select features matching specific field value.

Parameter	Type	Required	Description
layer_name	string	yes
field	string	yes
value	string	yes

select_by_location

Select features in target_layer based on their spatial relationship to reference_layer (e.g. select all points within a polygon boundary). Use method to combine with an existing selection instead of replacing it (e.g. 'add' after a select_by_attribute call to build up a combined selection, or 'intersect' to narrow one down).

Parameter	Type	Required	Description
target_layer	string	yes	Layer whose features get selected.
reference_layer	string	yes	Layer to test spatial relationship against.
predicate	string	no	Spatial relationship: 'intersects' (default), 'contains', 'within', 'touches', 'overlaps', 'crosses', 'equals'.
method	string	no	'new' (default, replaces current selection), 'add', 'remove', or 'intersect' with the current selection.

simplify_geometry

Simplify (generalize) a layer's geometries by removing vertices within tolerance of a straight line -- reduces file size/complexity for display at smaller scales or for web export. Larger tolerance means more simplification.

Parameter	Type	Required	Description
layer_name	string	yes
tolerance	number	yes	Simplification tolerance in the layer's map units.

spatial_join

Join attributes from one layer to another by spatial location.

Parameter	Type	Required	Description
target_layer	string	yes
join_layer	string	yes

toggle_visibility

Show or hide a layer in layer tree.

Parameter	Type	Required	Description
layer_name	string	yes
visible	boolean	no

union_layers

Geometric union of two vector layers.

Parameter	Type	Required	Description
layer1	string	yes
layer2	string	yes

verify_crs_compatibility

Check if two layers share compatible Coordinate Reference Systems.

Parameter	Type	Required	Description
layer1	string	yes
layer2	string	yes

voronoi_polygons

Generate Voronoi polygons (Thiessen polygons) from a point layer -- each polygon covers the area closest to its point. Common for coverage/catchment analysis (e.g. 'which points are closest to each facility').

Parameter	Type	Required	Description
layer_name	string	yes
buffer_percent	number	no	Extends the diagram past the point extent by this percentage, to avoid clipped edge polygons. Defaults to 0.

zoom_to_feature

Zoom map canvas to a single feature, identified either by feature_id or by an attribute expression (e.g. "governorate_name = 'Ma'rib'"). Use expression when the feature_id isn't already known -- this looks it up and zooms in one call, instead of hand-writing PyQGIS to query for it first.

Parameter	Type	Required	Description
layer_name	string	yes
feature_id	integer	no	Feature ID to zoom to. Provide this or expression, not both.
expression	string	no	QGIS expression selecting exactly one feature by attribute, e.g. "name = 'Ma'rib'". Provide this or feature_id, not both.

zoom_to_layer

Zoom canvas to extent of layer.

Parameter	Type	Required	Description
layer_name	string	yes