# 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
```