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
147 lines
3.5 KiB
Markdown
147 lines
3.5 KiB
Markdown
# Examples
|
|
|
|
The `examples/` directory contains runnable Dear PyGui programs:
|
|
|
|
```bash
|
|
uv run python examples/basic_map.py
|
|
uv run python examples/custom_provider.py
|
|
uv run python examples/cache_stress.py
|
|
uv run python examples/markers_live_thread.py
|
|
uv run python examples/trajectory_live_thread.py
|
|
uv run python examples/sizing_window.py
|
|
uv run python examples/sizing_child.py
|
|
uv run python examples/sizing_table.py
|
|
uv run python examples/hidden_tab.py
|
|
```
|
|
|
|
## Basic Map
|
|
|
|
Creates one map and one marker.
|
|
|
|
```python
|
|
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)
|
|
```
|
|
|
|
Run:
|
|
|
|
```bash
|
|
uv run python examples/basic_map.py
|
|
```
|
|
|
|
## Live Marker Updates
|
|
|
|
Use explicit `map_tag` from background threads or callbacks.
|
|
|
|
```python
|
|
dpgm.add_marker("vehicle", lat=47.9029, lon=1.9093, map_tag="map")
|
|
|
|
def update_from_telemetry(lat: float, lon: float) -> None:
|
|
dpgm.update_marker("vehicle", lat=lat, lon=lon, map_tag="map")
|
|
```
|
|
|
|
Run a threaded stress example:
|
|
|
|
```bash
|
|
uv run python examples/markers_live_thread.py
|
|
```
|
|
|
|
## Live Trajectory
|
|
|
|
Keep an application-owned point buffer and pass immutable snapshots to `update_trajectory(...)`.
|
|
|
|
```python
|
|
points: list[tuple[float, float]] = []
|
|
dpgm.add_trajectory("track", points=[], show_points=True, point_stride=12, map_tag="map")
|
|
|
|
def push_point(lat: float, lon: float) -> None:
|
|
points.append((lat, lon))
|
|
dpgm.update_trajectory("track", points=tuple(points), map_tag="map")
|
|
```
|
|
|
|
Run:
|
|
|
|
```bash
|
|
uv run python examples/trajectory_live_thread.py
|
|
```
|
|
|
|
## Multiple Maps
|
|
|
|
Each map is independent. Reusing overlay tags across different maps is valid, but runtime updates
|
|
should pass `map_tag` to avoid ambiguity.
|
|
|
|
```python
|
|
with dpgm.map_widget(tag="live-map", center=(47.9, 1.9), zoom=15, width=-1, height=300):
|
|
dpgm.add_marker("vehicle", lat=47.9, lon=1.9)
|
|
|
|
with dpgm.map_widget(tag="recap-map", center=(47.9, 1.9), zoom=13, width=-1, height=300):
|
|
dpgm.add_trajectory("vehicle", points=[])
|
|
|
|
dpgm.update_marker("vehicle", lat=47.901, lon=1.902, map_tag="live-map")
|
|
dpgm.update_trajectory("vehicle", points=lap_points, map_tag="recap-map")
|
|
```
|
|
|
|
## Custom Provider Switch
|
|
|
|
Register a provider, create the map with it, and switch at runtime.
|
|
|
|
```python
|
|
carto = dpgm.TileProvider(
|
|
name="carto-light",
|
|
url_template="https://{s}.basemaps.cartocdn.com/light_all/{z}/{x}/{y}{r}.png",
|
|
subdomains=("a", "b", "c", "d"),
|
|
attribution="(c) OpenStreetMap contributors (c) CARTO",
|
|
)
|
|
|
|
dpgm.register_provider(carto)
|
|
dpgm.set_provider("carto-light", map_tag="map")
|
|
dpgm.set_provider("osm", map_tag="map")
|
|
```
|
|
|
|
Run:
|
|
|
|
```bash
|
|
uv run python examples/custom_provider.py
|
|
```
|
|
|
|
## Cache Controls
|
|
|
|
Configure a local cache and expose buttons in your UI.
|
|
|
|
```python
|
|
dpgm.configure(cache_dir=".tile-cache", memory_cache_max_tiles=128)
|
|
|
|
def clear_memory() -> None:
|
|
dpgm.clear_memory_cache(map_tag="map")
|
|
|
|
def clear_disk() -> None:
|
|
dpgm.clear_disk_cache(map_tag="map")
|
|
|
|
def refresh_stats() -> str:
|
|
stats = dpgm.get_cache_stats(map_tag="map")
|
|
return f"{stats.memory_tiles} memory tiles, {stats.disk_bytes} disk bytes"
|
|
```
|
|
|
|
Run:
|
|
|
|
```bash
|
|
uv run python examples/cache_stress.py
|
|
```
|
|
|
|
## Layout And Sizing
|
|
|
|
The widget works inside windows, child windows, tables, and hidden tabs.
|
|
|
|
```python
|
|
with dpg.child_window(width=-1, height=420):
|
|
with dpgm.map_widget(tag="map-child", width=-1, height=-1):
|
|
dpgm.add_marker("inside-child", lat=47.0, lon=2.0)
|
|
```
|
|
|
|
Run:
|
|
|
|
```bash
|
|
uv run python examples/sizing_child.py
|
|
```
|