pyopenlayersqt

OpenLayers + Qt (QWebEngine) mapping widgets for Python desktop apps.

pyopenlayersqt embeds OpenLayers in a PySide6 QWebEngineView and wraps it with Python classes for desktop geospatial workflows: map layers, feature IDs, selection, styling, tables, filtering, editing, and application actions.

Use it when your Qt app needs more than static plots or a handful of markers: high-volume point rendering, uncertainty ellipses, editable vectors, lazy tables, linked parent/child selections, WMS/tile/raster overlays, time filtering, measurement tools, and a packaged CSV viewer that demonstrates the whole stack.

Contents

• Why pyopenlayersqt
• Install
• Quick Start
• Build a desktop map app
  • 1. Map widget
  • 2. Pick the right layer
  • 3. Add data and styles
  • 4. Selection
  • 5. Tables
  • 6. Filtering
• CSV viewer app
• Examples
• Public API reference
• Performance notes
• Contributing

Why pyopenlayersqt

Compared with a basic Qt graphics view or static plotting widget, pyopenlayersqt gives you web-map interaction, tiled basemaps, OpenLayers rendering primitives, and Python-side application state in one package. Compared with hand-rolling a web app inside QWebEngine, it gives you the bridge, layer wrappers, table widgets, filtering widgets, examples, and CSV integration patterns up front.

Common applications this is built for:

Install

pip install pyopenlayersqt

Requirements: Python 3.8+, PySide6 6.5+, NumPy, Pillow, and Matplotlib.

Quick Start

import sys
from PySide6 import QtWidgets
from PySide6.QtGui import QColor
from pyopenlayersqt import OLMapWidget, PointStyle

app = QtWidgets.QApplication(sys.argv)

map_widget = OLMapWidget(center=(37.0, -120.0), zoom=6)
layer = map_widget.add_vector_layer("cities", selectable=True)

layer.add_points(
    coords=[(37.7749, -122.4194), (34.0522, -118.2437)],
    ids=["sf", "la"],
    style=PointStyle(radius=8, fill_color=QColor("tomato")),
)

map_widget.fit_to_data()
map_widget.show()
sys.exit(app.exec())

Run a working version from the repository:

python examples/01_basic_map_with_markers.py

Build a desktop map app

1. Map widget

OLMapWidget is a QWebEngineView that owns the OpenLayers map, base layers, Python↔JavaScript bridge, selection state, and view controls.

from PySide6.QtGui import QColor
from pyopenlayersqt import OLMapWidget

map_widget = OLMapWidget(
    center=(40.0, -100.0),
    zoom=4,
    show_coordinates=True,
    show_osm_layer=True,
    show_country_boundaries=False,
)

map_widget.set_view(center=(39.7392, -104.9903), zoom=10)
map_widget.set_base_opacity(0.7)
map_widget.set_map_background_color(QColor("aliceblue"))

Map widget capability table:

2. Pick the right layer

All layers support set_opacity(opacity), set_visible(visible), and remove(). Raster layers also support named images with set_image(), remove_image(), set_image_opacity(), and clear().

Capability matrix:

3. Add data and styles

Use (latitude, longitude) coordinates everywhere. Use stable string IDs if features need selection, recoloring, deletion, table rows, or filtering.

Vector features

from pathlib import Path
from PySide6.QtGui import QColor
from pyopenlayersqt import PointStyle, PolygonStyle, CircleStyle, EllipseStyle, VectorVertexEditing

vector = map_widget.add_vector_layer(
    "editable",
    selectable=True,
    movable=True,
    vertex_editing=VectorVertexEditing.MOVE,
)

vector.add_points(
    [(37.77, -122.42), (34.05, -118.24)],
    ids=["sf", "la"],
    style=PointStyle(radius=6, fill_color=QColor("steelblue"), stroke_color=QColor("white")),
)

vector.add_icon_points(
    [(36.17, -115.14)],
    ids=["vegas"],
    icon=Path("examples/assets/orange_pin.svg"),
    selected_icon=Path("examples/assets/selected_pin.svg"),
    anchor=(0.5, 1.0),
)

vector.add_line(
    [(37.77, -122.42), (36.17, -115.14), (34.05, -118.24)],
    feature_id="route",
    style=PolygonStyle(stroke_color=QColor("dodgerblue"), stroke_width=3),
)

vector.add_polygon(
    [(37.8, -122.5), (37.8, -122.3), (37.6, -122.3), (37.6, -122.5)],
    feature_id="area",
    style=PolygonStyle(fill_color=QColor("dodgerblue"), fill_opacity=0.15, stroke_color=QColor("dodgerblue")),
)

vector.add_circle((37.77, -122.42), radius_m=2_000, feature_id="buffer", style=CircleStyle(fill_opacity=0.12))
vector.add_ellipse((37.77, -122.42), sma_m=3_000, smi_m=1_000, tilt_deg=35, feature_id="uncertainty", style=EllipseStyle(stroke_color=QColor("gold")))

Custom icon sources may be local paths, Path objects, bytes-like image data, QByteArray, http(s) URLs, data: URIs, file: URIs, or qrc: URIs. Local files and bytes are served through the widget's embedded HTTP cache.

Fast points

from PySide6.QtGui import QColor
from pyopenlayersqt import FastPointsStyle

fast = map_widget.add_fast_points_layer(
    "measurements",
    selectable=True,
    style=FastPointsStyle(radius=2.5, default_color=QColor("seagreen"), selected_radius=6, selected_color=QColor("yellow")),
    cell_size_m=750,
)

fast.add_points(coords, ids=ids, colors_rgba=optional_colors)
fast.set_colors(["pt-1", "pt-2"], [QColor("red"), QColor("orange")])
fast.hide_features(["pt-3"])
fast.show_all_features()

Fast geo-points with uncertainty

from PySide6.QtGui import QColor
from pyopenlayersqt import FastGeoPointsStyle

geo = map_widget.add_fast_geopoints_layer(
    "geo",
    selectable=True,
    style=FastGeoPointsStyle(
        point_radius=3,
        default_color=QColor("steelblue"),
        selected_color=QColor("white"),
        ellipse_stroke_color=QColor("steelblue"),
        fill_ellipses=False,
        ellipses_visible=True,
    ),
    cell_size_m=750,
)

geo.add_points_with_ellipses(
    coords=coords,
    sma_m=semi_major_m,
    smi_m=semi_minor_m,
    tilt_deg=tilt_degrees,
    ids=ids,
)
geo.set_selected_ellipses_visible(False)

WMS and raster overlays

from pyopenlayersqt import WMSOptions

wms = map_widget.add_wms(
    WMSOptions(
        url="https://ahocevar.com/geoserver/wms",
        params={"LAYERS": "topp:states", "TILED": True, "FORMAT": "image/png", "TRANSPARENT": True},
        opacity=0.85,
    ),
    name="states",
)

raster = map_widget.add_raster_layer(name="heatmap", opacity=0.6)
raster.set_image(
    png_bytes_or_path_or_url,
    bounds=[(lat_min, lon_min), (lat_max, lon_max)],
    name="temperature",
    opacity=0.8,
)
raster.set_image_opacity("temperature", 0.5)

4. Selection

Selection is ID-based and synchronized between OpenLayers and Python. The key contract is: use the same feature ID in the layer, table key, filter model, and application state.

from PySide6.QtGui import QColor
from pyopenlayersqt import PointStyle

current_selection = {}  # layer_id -> list[str]

def on_selection_changed(selection):
    if selection.feature_ids:
        current_selection[selection.layer_id] = list(selection.feature_ids)
    else:
        current_selection.pop(selection.layer_id, None)

map_widget.selectionChanged.connect(on_selection_changed)

# Programmatic selection by layer kind
map_widget.set_vector_selection(vector.id, ["sf"])
map_widget.set_fast_points_selection(fast.id, ["pt-1", "pt-2"])
map_widget.set_fast_geopoints_selection(geo.id, ["geo-1"])

Common selected-feature operations:

vector.update_feature_styles(["sf"], [PointStyle(radius=10, fill_color=QColor("red"))])
fast.set_colors(["pt-1"], [QColor("red")])
geo.set_colors(["geo-1"], [QColor("red")])

vector.remove_features(["sf"])
fast.remove_points(["pt-1"])
geo.remove_ids(["geo-1"])

For right-click app actions, listen to map_widget.jsEvent for "contextmenu"; payloads include map coordinates and the clicked feature/layer when available.

For regular clicks, use mapClicked or on_map_click() instead of injecting JavaScript. The callback can require standard modifiers and arbitrary held keys:

from pyopenlayersqt import MapClickEvent

def add_target(event: MapClickEvent) -> None:
    print(event.lat, event.lon)

# Invoke only while the map has focus and T is held during the click.
map_widget.on_map_click(add_target, keys="t")
# Standard modifiers can be combined with ordinary keys.
map_widget.on_map_click(add_target, modifiers=("ctrl", "shift"), keys="t")

5. Tables

FeatureTableWidget is designed to mirror feature rows and keep table selection in sync with map selection.

from pyopenlayersqt import ColumnSpec, FeatureTableWidget

columns = [
    ColumnSpec("ID", lambda r: r["feature_id"]),
    ColumnSpec("Name", lambda r: r.get("name", "")),
    ColumnSpec("Latitude", lambda r: r.get("lat", ""), fmt=lambda v: f"{float(v):.5f}" if v != "" else ""),
]

table = FeatureTableWidget(
    columns=columns,
    key_fn=lambda r: (r["layer_id"], r["feature_id"]),
    debounce_ms=90,
)

table.append_rows([
    {"layer_id": vector.id, "feature_id": "sf", "name": "San Francisco", "lat": 37.7749},
])

# table -> map
def on_table_selection(keys):
    selected_for_vector = [fid for layer_id, fid in keys if layer_id == vector.id]
    map_widget.set_vector_selection(vector.id, selected_for_vector)

table.selectionKeysChanged.connect(on_table_selection)

# map -> table
def on_map_selection(selection):
    table.select_keys([(selection.layer_id, fid) for fid in selection.feature_ids], clear_first=True)

map_widget.selectionChanged.connect(on_map_selection)

For huge tables, set a TableRowProvider instead of appending row dictionaries. The provider lazily implements row_count(), data(...), key(source_row), row_for_key(key), and row_data(source_row).

For parent/child workflows, use TableLink with MultiSelectLink: one parent table/layer fans out to one or more child tables/layers using dictionaries of child_feature_id -> parent_feature_id. Metadata-only child tables are supported with key_layer_id.

Table/application capability table:

6. Filtering

Filtering is usually a combination of map hide/show and table visible-row updates.

from pyopenlayersqt import RangeSliderWidget

slider = RangeSliderWidget(min_val=0.0, max_val=100.0, step=1.0, label="Value")

def apply_filter(min_val, max_val):
    visible = [row["feature_id"] for row in rows if min_val <= row["value"] <= max_val]
    hidden = [row["feature_id"] for row in rows if not (min_val <= row["value"] <= max_val)]

    fast.hide_features(hidden)
    fast.show_features(visible)
    table.hide_rows_by_keys([(fast.id, fid) for fid in hidden])
    table.show_rows_by_keys([(fast.id, fid) for fid in visible])

slider.rangeChanged.connect(apply_filter)

Use RangeSliderWidget(is_iso8601=True) for timestamp ranges and TimeHistogramSliderWidget when a histogram overview helps users understand dense time data.

CSV viewer app

The package includes a runnable CSV map viewer app through the csv_plotter console script:

csv_plotter --csv path/to/data.csv

The app is useful for exploring large latitude/longitude CSV files without writing code. It uses OLMapWidget, fast point/geo-point layers, FeatureTableWidget, and TimeHistogramSliderWidget to provide:

• manual column selection for latitude, longitude, optional time, and optional uncertainty fields;
• streaming-oriented loading for large CSV files;
• selectable map points synchronized with a lazy table;
• color-by-column workflows for categorical and numeric data;
• text/wildcard filtering and time filtering;
• optional WMS/base-layer controls;
• performance log lines when PYOPENLAYERSQT_PERF=1 is set.

If you are building your own CSV-style desktop viewer, treat the app as an integration reference for large data loading, compact indexes, map/table selection, and filter-driven hide/show behavior.

Examples

Start with the examples that match the application you are building. The examples are intentionally workflow-oriented rather than toy-only snippets.

Public API reference

Top-level imports

from pyopenlayersqt import (
    OLMapWidget,
    # styles/options/models
    PointStyle, IconStyle, PolygonStyle, CircleStyle, EllipseStyle,
    FastPointsStyle, FastGeoPointsStyle, WMSOptions, TileLayerOptions,
    FeatureSelection, MeasurementUpdate, VectorVertexEditing, LatLon,
    # layers
    FastPointsLayer, FastGeoPointsLayer,
    # reusable widgets and linking helpers
    ColumnSpec, ContextMenuActionSpec, FeatureTableWidget, TableContextMenuEvent,
    TableRowProvider, RangeSliderWidget, TimeHistogramSliderWidget,
    TableLink, DualSelectLink, MultiSelectLink,
)

OLMapWidget

Constructor highlights: center=(lat, lon), zoom=2, show_coordinates=True, show_country_boundaries=False, country_boundaries_stroke_color=None, show_osm_layer=True, osm_url=None, and map_background_color (defaults to white).

Layer factory methods:

Fast layers default to selectable=False; pass selectable=True when map clicks or map/table selection sync should include those layers.

• add_vector_layer(name, selectable=True, movable=False, vertex_editing=VectorVertexEditing.MOVE)
• add_fast_points_layer(name, selectable=False, style=None, cell_size_m=1000.0)
• add_fast_geopoints_layer(name, selectable=False, style=None, cell_size_m=1000.0, show_ellipses=True)
• add_wms(options, name="wms")
• add_tile_layer(options, name="tile")
• add_raster_layer(name="raster", opacity=0.6) (then set_image(image, bounds, name="image"))

Important methods: set_base_opacity, set_base_visible, set_map_background_color, set_country_boundaries_visible, set_view, set_center, set_zoom, fit_bounds, auto_zoom_to_points, fit_to_data, zoom_resolution_m_per_px, get_view_extent, watch_view_extent, set_measure_mode, on_measurement_updated, on_map_click, clear_measurements, send.

Signals: ready, selectionChanged, mapClicked, viewExtentChanged, measurementUpdated, vectorFeatureChanged, jsEvent.

Layer APIs

Style primitives

Color fields accept QColor and CSS color names. Hex strings, CSS color strings, and legacy RGBA tuples remain supported for compatibility, but QColor is preferred in examples and application code.

Table, linking, and filter widgets

• FeatureTableWidget(columns, key_fn=None, debounce_ms=...): append/remove/select rows by stable keys.
• ColumnSpec(name, getter, fmt=None): declares display columns.
• ContextMenuActionSpec(label, callback): adds table context-menu actions.
• TableRowProvider: lazy/virtual table protocol for very large data.
• TableLink, DualSelectLink, MultiSelectLink: map/table selection linking helpers.
• RangeSliderWidget: dual-handle numeric or ISO8601 range filtering.
• TimeHistogramSliderWidget: time filtering with histogram context.

Performance notes

• Use FastPointsLayer or FastGeoPointsLayer for large point datasets.
• Tune cell_size_m to match density: larger cells are faster, smaller cells select more precisely.
• Prefer stable compact IDs; reuse them across map, table, and filters.
• Use virtual table providers for large datasets instead of materializing every row as a dictionary.
• Use hide_features()/show_features() for interactive filtering instead of removing and re-adding data.
• Debounce extent-driven loading with watch_view_extent(..., debounce_ms=...).
• For uncertainty ellipses, use min_ellipse_px and max_ellipses_per_path to avoid drawing invisible or overly fragmented geometry.

Architecture

• Python sends commands to JavaScript through the widget bridge.
• JavaScript sends events back through Qt Web Channel.
• Static OpenLayers assets are packaged with the wheel.
• Local icons and raster overlays are served from embedded/cache-backed HTTP endpoints so they work inside QWebEngine.

License

MIT License

Contributing

Contributions are welcome. For release and publishing notes, see CONTRIBUTING.md.

Credits

Built with OpenLayers, PySide6, NumPy, Pillow, and Matplotlib.