Hector van der Aa
6990d011ff
This is the first releas of dpg-map, an AI coded dearpygui map widget built due to a lack of time to build it myself. It features multi-widget abilities, with layers, overlays etc
89 lines
2.0 KiB
Markdown
89 lines
2.0 KiB
Markdown
# dpg-map
|
|
|
|
`dpg-map` is a Dear PyGui widget for interactive XYZ raster maps, tile caching, and
|
|
geographic overlays.
|
|
|
|
```python
|
|
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:
|
|
|
|
```bash
|
|
uv sync
|
|
uv run pytest
|
|
```
|
|
|
|
From another local project:
|
|
|
|
```bash
|
|
uv add --editable ../dpg-map
|
|
uv run python -c "import dpg_map as dpgm; print(dpgm.list_providers())"
|
|
```
|
|
|
|
## Minimal Example
|
|
|
|
```python
|
|
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:
|
|
|
|
```bash
|
|
uv run python examples/basic_map.py
|
|
```
|
|
|
|
## Documentation
|
|
|
|
- [Getting Started](docs/GETTING_STARTED.md)
|
|
- [Examples](docs/EXAMPLES.md)
|
|
- [API Reference](docs/API_REFERENCE.md)
|
|
|
|
Internal rebuild notes, implementation plans, and agent logs live in [codex/](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
|
|
|
|
```bash
|
|
uv run pytest
|
|
uv run ruff check .
|
|
uv run ruff format --check .
|
|
uv run pyright
|
|
```
|