PyQGIS Engineering & Automation

Custom Map Canvas Overlays and Rendering

Implementing Custom Map Canvas Overlays and Rendering is a foundational capability for building interactive, production-grade QGIS plugins. Unlike static…

Implementing Custom Map Canvas Overlays and Rendering is a foundational capability for building interactive, production-grade QGIS plugins. Unlike static vector or raster layers, canvas overlays render directly on the viewport, enabling real-time visual feedback, dynamic annotations, selection highlights, and tool-specific graphics without modifying the underlying geospatial data. For GIS developers and automation engineers, mastering this rendering pipeline is essential when building Plugin Development & UI Integration workflows that demand responsive, context-aware mapping interfaces. This guide provides a structured workflow, tested PyQGIS patterns, and diagnostic strategies for implementing high-performance canvas overlays in QGIS 3.x.

Prerequisites & Environment Setup

Before implementing custom overlays, ensure your development environment meets the following baseline requirements:

  • QGIS 3.28+ (LTR): The rendering architecture and QgsMapCanvasItem API are stable across modern LTR releases. Earlier versions exhibit inconsistent scene-graph invalidation behavior.
  • PyQGIS Environment: Python 3.9+ with access to qgis.core, qgis.gui, and qgis.PyQt modules. Verify your environment loads the correct SIP bindings for Qt5/Qt6 compatibility.
  • Qt Graphics View Fundamentals: Understanding of QGraphicsItem, QPainter, and coordinate transformation matrices. Refer to the official Qt Graphics View Framework documentation for foundational concepts on scene-graph rendering and viewport updates.
  • Spatial Reference Awareness: Familiarity with how QGIS handles on-the-fly CRS transformations and screen-to-map coordinate mapping.

Canvas overlays frequently pair with configuration interfaces. When building parameter-driven overlays, you will typically route user inputs through Designing Qt Dialogs and Form Widgets before applying them to the rendering pipeline. This architectural separation ensures that UI logic never interferes with the canvas refresh cycle, preserving frame-rate stability during user interaction.

Understanding the QGIS Rendering Pipeline

The QGIS map canvas operates on an extended version of Qt’s Graphics View Framework, augmented with geospatial coordinate handling, layer compositing, and anti-aliasing controls. The rendering pipeline follows a strict, deterministic sequence:

  1. Coordinate Transformation: Map coordinates (CRS) are converted to screen pixels via QgsMapToPixel.
  2. Item Registration: Custom items inheriting from QgsMapCanvasItem are attached to the canvas scene.
  3. Paint Dispatch: The canvas triggers paint() during viewport refresh cycles, passing a QPainter instance and a QgsRenderContext.
  4. Bounding Box Caching: boundingRect() defines the invalidation region. Accurate bounds prevent unnecessary redraws and clipping artifacts.
flowchart LR
    MAP["Map coords in CRS"] --> PX["toCanvasCoordinates()"]
    PX --> ITEM["QgsMapCanvasItem in scene"]
    ITEM --> PAINT["paint(QPainter)"]
    PAINT --> BR["boundingRect() defines redraw region"]

Heavy computational tasks should never block this pipeline. If your overlay depends on spatial analysis results, compute them asynchronously or pre-process them using Building Custom Processing Algorithms before feeding the output to the canvas renderer. Blocking the main thread during paint() will cause UI freezes, dropped frames, and degraded user experience.

Step-by-Step Implementation Workflow

Follow this sequence to build a reliable, maintainable overlay. Each step addresses a specific layer of the rendering contract.

1. Subclass QgsMapCanvasItem

Create a dedicated class that inherits from QgsMapCanvasItem. This base class handles canvas attachment, coordinate conversion, and scene integration. It automatically registers with the canvas viewport and inherits the correct parent-child hierarchy for event propagation.

python
from qgis.gui import QgsMapCanvasItem
from qgis.core import QgsPointXY
from PyQt5.QtCore import QRectF
from PyQt5.QtGui import QPainter, QColor, QPen, QPolygonF

class CustomOverlayItem(QgsMapCanvasItem):
    def __init__(self, canvas):
        super().__init__(canvas)
        self._points = []
        self._color = QColor(255, 0, 0, 128)

    def set_points(self, points: list[QgsPointXY]):
        self._points = points
        self.update()  # Triggers boundingBox() and paint() recalculation

2. Handle Coordinate Transformations & CRS Context

QgsMapCanvasItem provides toCanvasCoordinates(), which converts a map-space QgsPointXY into canvas (screen) coordinates. Store map coordinates internally and convert to screen pixels only when rendering. Always account for CRS mismatches by transforming geometries to the canvas CRS before storage.

python
def _screen_points(self):
    """Convert stored map points to canvas (screen) coordinates."""
    return [self.toCanvasCoordinates(pt) for pt in self._points]

3. Implement the paint() Method

QgsMapCanvasItem.paint() receives a QPainter (plus the standard QGraphicsItem option and widget arguments) — not a QgsRenderContext. Configure the painter, convert your stored map points to canvas coordinates, and draw the geometry. Always check for empty data to avoid rendering artifacts, and use painter.save()/painter.restore() to isolate state changes.

python
def paint(self, painter: QPainter, option=None, widget=None):
    if not self._points:
        return

    painter.save()
    painter.setRenderHint(QPainter.Antialiasing)
    painter.setPen(QPen(self._color, 2))
    painter.setBrush(self._color)

    # paint() only gets a QPainter; map the stored points to canvas coordinates
    screen_points = self._screen_points()

    # Draw geometry
    if len(screen_points) >= 3:
        painter.drawPolygon(QPolygonF(screen_points))
    elif len(screen_points) == 2:
        painter.drawLine(screen_points[0], screen_points[1])

    painter.restore()

4. Define Accurate Bounding Boxes

The boundingRect() method (the QGraphicsItem override QGIS calls) is critical for canvas invalidation. Return a QRectF in canvas coordinates that fully encompasses your geometry. Underestimating bounds causes clipping; overestimating causes performance degradation due to excessive redraw regions. Add a small padding buffer (e.g., 2–4 pixels) to account for stroke width and anti-aliasing bleed.

python
def boundingRect(self) -> QRectF:
    if not self._points:
        return QRectF()

    # Compute the bounds directly in canvas (screen) coordinates
    screen_points = self._screen_points()
    xs = [p.x() for p in screen_points]
    ys = [p.y() for p in screen_points]
    rect = QRectF(min(xs), min(ys), max(xs) - min(xs), max(ys) - min(ys))

    # Add stroke padding to avoid clipping anti-aliased edges
    return rect.adjusted(-4, -4, 4, 4)

5. Register, Manage, and Clean Up Canvas State

Attach your item to the canvas and manage its lifecycle. QGIS does not automatically garbage-collect canvas items, so explicit cleanup is mandatory to prevent memory leaks and orphaned graphics.

python
# In your plugin/tool initialization:
canvas = iface.mapCanvas()
overlay = CustomOverlayItem(canvas)
canvas.scene().addItem(overlay)

# Cleanup on plugin unload:
def cleanup_overlay():
    canvas.scene().removeItem(overlay)
    overlay.deleteLater()

For detailed API signatures and lifecycle hooks, consult the official PyQGIS API Reference for QgsMapCanvasItem.

Event Handling & Interactive Overlays

Canvas items can intercept mouse and keyboard events by overriding mousePressEvent(), mouseMoveEvent(), and keyPressEvent(). This enables interactive drawing tools, snap-to-vertex behavior, and context-sensitive tooltips. Always call super() to preserve default canvas navigation (pan/zoom) unless you explicitly consume the event.

python
def mousePressEvent(self, event):
    if event.button() == Qt.LeftButton:
        # Capture click in map coordinates
        map_pt = self.toMapCoordinates(event.pos())
        self._points.append(map_pt)
        self.update()
        event.accept()  # Prevents event from propagating to canvas pan/zoom
    else:
        super().mousePressEvent(event)

When implementing interactive overlays, decouple event capture from rendering. Store raw inputs, validate them against snapping tolerances, and trigger a single update() call. This prevents redundant scene invalidations during rapid mouse movements.

Performance Optimization & Asynchronous Updates

Canvas rendering occurs on the main UI thread. Any delay in paint() directly impacts pan/zoom responsiveness. Follow these optimization rules:

  • Cache Screen Coordinates: Transform points once per zoom/pan event, not per frame. Use canvas.extentsChanged.connect() to invalidate caches only when necessary.
  • Limit Redraw Regions: Always return precise boundingBox() values. QGIS uses this to compute the minimal dirty rectangle.
  • Batch Updates: Call update() once after modifying multiple properties. Avoid calling it inside tight loops.
  • Offload Heavy Work: Use QgsTask for spatial queries, raster sampling, or network requests. Push results to the overlay via signals/slots to trigger a single update().

When overlays depend on complex spatial operations, decouple computation from rendering. Pre-process geometries or fetch attributes asynchronously, then inject the results into the overlay class. This pattern aligns with modern asynchronous execution best practices, ensuring the UI remains fluid during intensive operations.

Common Pitfalls & Diagnostic Strategies

Even experienced developers encounter rendering quirks. Here’s how to diagnose and resolve them:

Symptom Likely Cause Resolution
Overlay disappears on zoom Incorrect boundingRect() or missing update() call Verify screen-space bounds and ensure update() fires after data changes
Coordinates drift during pan Using cached screen coordinates without invalidation Recalculate on canvas.extentsChanged or use mapToPixel in paint()
UI freezes during render Heavy computation inside paint() Move logic to background thread; keep paint() strictly graphical
Memory leak on plugin unload Canvas item not removed from scene Call scene().removeItem() and deleteLater() in plugin unload()
Blurry lines on high-DPI Missing anti-aliasing or incorrect pen width Enable QPainter.Antialiasing and scale pen width by painter.devicePixelRatio()

Use QGIS’s built-in developer tools to profile rendering. Enable iface.mapCanvas().setRenderFlag(True) to force redraws, and monitor QgsRenderContext flags for performance bottlenecks. For advanced debugging, Qt’s QGraphicsView viewport updates can be traced using environment variables like QT_DEBUG_PLUGINS=1 or by temporarily overriding boundingRect() to visualize invalidation zones with a debug color.

Next Steps & Integration Patterns

Once your overlay renders reliably, integrate it into broader plugin workflows. Overlays are rarely standalone; they typically interact with toolbars, selection states, and attribute forms. Consider these integration patterns:

  • Tool-Specific Graphics: Bind overlay visibility to tool activation states. Clear or hide the overlay when switching tools to prevent visual clutter.
  • Selection Highlighting: Sync overlay geometry with QgsMapCanvas.selectionChanged() to provide custom highlight styles beyond QGIS defaults.
  • Dynamic Annotations: Use QgsMapCanvasItem subclasses for measurement lines, buffer previews, or routing paths. Update them reactively as users interact with the map.

Mastering Custom Map Canvas Overlays and Rendering unlocks highly responsive, professional-grade mapping interfaces. By adhering to strict coordinate management, precise bounding boxes, and asynchronous data pipelines, your plugins will scale gracefully across diverse datasets and hardware configurations. Continue exploring advanced UI patterns and cross-version compatibility strategies to future-proof your QGIS development stack.