dpg-map

dpg-map is a Dear PyGui widget for interactive XYZ raster maps, tile caching, and geographic overlays.

import dpg_map as dpgm

The widget is built for telemetry dashboards and internal tools that need maps inside normal Dear PyGui layouts. Runtime updates are thread-safe: marker, trajectory, view, provider, and cache calls update logical state or enqueue renderer work, while Dear PyGui draw calls stay on the GUI thread.

Install

For local development:

uv sync
uv run pytest

From another local project:

uv add --editable ../dpg-map
uv run python -c "import dpg_map as dpgm; print(dpgm.list_providers())"

Minimal Example

from typing import Any

import dearpygui.dearpygui as _dpg
import dpg_map as dpgm

dpg: Any = _dpg

dpgm.configure(user_agent="my-app/0.1 contact@example.com")

dpg.create_context()
dpg.create_viewport(title="Map", width=900, height=600)

with dpg.window(label="Map", width=-1, height=-1):
    with dpgm.map_widget(tag="map", center=(47.9029, 1.9093), zoom=15, width=-1, height=-1):
        dpgm.add_marker("vehicle", lat=47.9029, lon=1.9093, label="Vehicle")

dpg.setup_dearpygui()
dpg.show_viewport()
dpg.start_dearpygui()
dpg.destroy_context()

Run the bundled example:

uv run python examples/basic_map.py

Documentation

• Getting Started
• Examples
• API Reference

Internal rebuild notes, implementation plans, and agent logs live in codex/.

Highlights

• OpenStreetMap provider registered by default as osm
• Custom XYZ tile providers
• Pan and cursor-centered zoom
• Markers, polylines, and live trajectories
• Overlay layers with visibility and z-order controls
• Memory tile cache and provider-namespaced disk cache
• Multiple independent map widgets in one Dear PyGui app
• Background-thread runtime updates for telemetry workloads

Project Commands

uv run pytest
uv run ruff check .
uv run ruff format --check .
uv run pyright