qgis-knowledge-patch

# QGIS Knowledge Patch Use this skill when implementing, reviewing, migrating, or troubleshooting QGIS desktop, Server, Processing, provider, or PyQGIS work where recent behavior can change the answer. ## How to use this patch 1. Identify the QGIS version and, for provider-backed features, the packaged GDAL, PDAL, wrench, GEOS, or SFCGAL versions. 2. Read only the topic references needed for the task. 3. Apply guidance introduced no later than the project's QGIS version. 4. Prefer the installed build's capabilities, project files, and runtime behavior when they differ from this guidance. 5. Treat UI defaults separately from API availability and provider-library prerequisites. ## Reference index | Reference | Use for | | --- | --- | | [3D, mesh, and point clouds](references/3d-mesh-and-point-clouds.md) | 3D scenes, mesh editing, VPC/COPC, point-cloud rendering, editing, and analysis | | [Data sources and databases](references/data-sources-and-databases.md) | STAC, PostgreSQL, SQL Server, imports, Browser administration, OAPIF clients, and SensorThings | | [Expressions and APIs](references/expressions-and-apis.md) | Expressions, PyQGIS geometry, GPS, SFCGAL, GeoPandas, and 3D extension APIs | | [Layouts, editing, and profiles](references/layouts-editing-and-profiles.md) | Layouts, legends, charts, digitizing, forms, attributes, and elevation profiles | | [Plugins, projects, and migration](references/plugins-projects-and-migration.md) | QGIS 4 plugin metadata, Qt 6 migration, themes, project trust, profiles, and custom UI | | [Processing and analysis](references/processing-and-analysis.md) | Native, raster, vector, terrain, network, geometry, and metadata algorithms | | [Rendering and labeling](references/rendering-and-labeling.md) | Labels, symbols, masks, temporal rasters, annotations, and style transfer | | [Server and web services](references/server-and-web-services.md) | QGIS Server, WMS/WFS/OAPIF, OAuth2, caching, GetFeatureInfo, and remote raster behavior | ## Breaking changes and migration ### Advertise QGIS 4 compatibility with version bounds For plugin repositories, use `qgisMinimumVersion` and optional `qgisMaximumVersion`. With no maximum, compatibility is assumed only through the end of the minimum version's major line. A plugin retaining QGIS 3.22 support while advertising QGIS 4 support can use: ```ini [general] qgisMinimumVersion=3.22 qgisMaximumVersion=4.99 ``` The QGIS 4 Ready list accepts a plugin when either bound is at least 4.0. Remove `supportsQt6=True`; it is no longer recognized. Before widening the range, replace Qt 5-only APIs and direct `PyQt5` imports, preferably using `qgis.PyQt`, test on QGIS 4, and use the repository's `pyqgis4-checker` report. See [Plugins, projects, and migration](references/plugins-projects-and-migration.md). ### Redirect settings and deployment automation QGIS 4.2 uses settings separate from QGIS 3. Its first startup makes a one-time, lossless copy of the loaded QGIS 3 profile, but later edits do not synchronize. Installation, profile, backup, and enterprise deployment scripts must target the QGIS 4 location. ### Update the QGIS Server OAPIF route Since 4.0, the default OAPIF root is `/ogcapi`, replacing `/wfs3`. Set `QGIS_SERVER_API_WFS3_ROOT_PATH` when a deployment needs another path, and update reverse-proxy routes, clients, and tests together. ### Replace deprecated hub-distance algorithms Since 4.0, the C++ Hub Distance algorithm replaces Distance to Nearest Hub (Points) and Distance to Nearest Hub (Line to Hub). It provides both optional outputs; migrate models and automation away from the two deprecated IDs. ### Account for changed legend defaults Since 4.0, layout legends use All Project Layers, Visible Layers, or Manual Layer Selection instead of the former Auto update checkbox. New legends default to Visible Layers. This follows layer-tree visibility and changes but does not filter by map extent; a global layout option restores the old default. ## Capability gates Check runtime library versions before exposing these operations: - COG export controls and GDAL Data Identification require GDAL 3.13 or later (4.0). - GeoPackage field-domain updates and deletion require GDAL 3.12 or later (4.0). - M3C2 point-cloud comparison requires a build with PDAL later than 2.10 (4.0). - Export to Raster (TIN) maximum-edge filtering requires PDAL 2.6+ and wrench 1.2.2+ (4.0). - Approximate Medial Axis `extendToEdges` requires SFCGAL 2.3 (4.2). - Some raster, point-cloud, 3D Tiles, I3S, and provider features remain conditional on the providers compiled into the installed QGIS build. ## High-value desktop behavior ### Choose the right layout-legend mode - All Project Layers tracks the whole project. - Visible Layers tracks visibility, order, and layer-tree changes. - Manual Layer Selection keeps an explicit list. - Per-layer automatic legend inclusion is enabled by default for vector, raster, mesh, and point-cloud layers (4.0). ### Keep temporary outputs named Processing outputs can remain temporary while using a user-selected layer name (4.0). The memory-chip icon still identifies them as temporary; naming a result does not persist it. ### Preserve raw provider values when copying Attribute tables and Identify Results can copy literal provider values rather than represented values affected by locale formatting, expressions, or display relations (4.0). Choose the raw action for round-tripping or exact comparisons. ### Use cumulative temporal raster rendering Raster layers in represent-temporal-values mode can accumulate pixels over time (4.0), matching cumulative vector animation behavior. Enable it when raster and vector frames must remain temporally aligned. ### Use isolated label-collision controls - Cross-layer margins reserve space around a label (3.44). - Duplicate prevention suppresses case-sensitive matching text within a minimum distance across all layers (3.44). - Curved labels can ignore spaces and tabs during collision tests; this is off by default and applies only to curved placement (4.0). ## High-value Processing behavior ### Distinguish COG from ordinary GeoTIFF When creating Cloud Optimized GeoTIFF output, pass `-of COG` explicitly (4.0). The `.tif` or `.tiff` extension cannot distinguish the COG and GTiff drivers. With GDAL 3.13+, export dialogs can also request optimization and pyramids. ### Preserve provenance when merging vectors Merge Vector Layers can add source `layer` and `path` attributes (3.42). The option is enabled by default for backward compatibility; disable it only when the output schema must exclude provenance. ### Understand raster-rank NoData behavior Raster rank uses positive ranks from the low end and negative ranks from the high end: for `[10, 20, 30, 40]`, `2` gives `20` and `-2` gives `30` (3.44). The default ignores NoData unless the requested rank is unavailable; the alternate mode propagates NoData when any input cell is NoData. ### Keep WMS extraction scale-aware Clip Raster by Extent and Clip Raster by Mask Layer can request WMS input at a reference scale and service resolution (4.0). The default service resolution is 96 DPI. Use this when scale-dependent remote rendering must survive a clip. ## High-value APIs ### Geometry and dataframe conversion - `QgsGeometry.as_numpy()` preserves Z and M dimensionality as XYZ, XYM, or XYZM arrays (3.42). - `QgsGeos` is directly available to PyQGIS for GEOS-specific operations not exposed by `QgsGeometryEngine` (3.42). - `QgsGeometry.area3D()` computes polygonal surface area and returns zero for points and lines (4.0). - `QgsVectorLayer.as_geopandas()` creates a GeoPandas dataframe when GeoPandas is installed (4.0). ### Time-zone semantics `convert_timezone` preserves the instant and changes its local representation; `set_timezone` replaces the zone without changing the date or time components (4.0). Use `timezone_from_id`, `timezone_id`, and `get_timezone` for IANA-zone creation and inspection. ### Point-cloud color expressions Point-cloud renderers can modify `@point_color` with point attributes (4.2). Arithmetic is channel-by-channel RGBA. Multiplication permits the color on either side, while other operators require it on the left, for example: ```qgis @point_color * (@intensity / 65535) ``` ## Server operational checks - `QGIS_SERVER_PROJECT_CACHE_SIZE` controls server project-cache QCache cost (3.44). - `QGIS_SERVER_RETRY_BAD_LAYERS=true` retests previously bad layers on every request and restores them after dependencies recover (4.0). - HTML GetFeatureInfo can use only the layer maptip via the project setting corresponding to `WITH_MAPTIP=HTML_FI_ONLY_MAPTIP` (4.0). - WMS highlight-label frames accept background, outline color, outline width, and size vendor parameters, optionally scoped per map (4.2). - QGIS Server can answer mesh GetFeatureInfo (4.0) and export FlatGeobuf from OGC API Features (4.2). ## Verification checklist - Confirm the installed QGIS and provider-library versions. - Check defaults separately for newly created and existing projects. - For plugin migration, test imports, metadata bounds, UI behavior, and package validation on QGIS 4. - For Server changes, test direct requests and proxy-routed public URLs. - For Processing, inspect output schema, NoData handling, CRS, temporary versus persisted status, and conditional outputs. - For 3D or point clouds, verify both renderer support and data locality before enabling editing.