Release v1.0.0
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
This commit is contained in:
411
docs/API_REFERENCE.md
Normal file
411
docs/API_REFERENCE.md
Normal file
@@ -0,0 +1,411 @@
|
||||
# API Reference
|
||||
|
||||
Public imports are available from:
|
||||
|
||||
```python
|
||||
import dpg_map as dpgm
|
||||
```
|
||||
|
||||
Unless stated otherwise, runtime public functions are safe to call from non-GUI threads. They
|
||||
update logical state and enqueue GUI-thread renderer work. `map_widget(...)` is the main exception:
|
||||
it creates Dear PyGui items and must run on the GUI thread.
|
||||
|
||||
## Common Types
|
||||
|
||||
- `Tag`: `str | int`
|
||||
- `LatLon`: `tuple[float, float]` as `(lat, lon)`
|
||||
- `Point`: `tuple[float, float]` as `(x, y)`
|
||||
- `Bounds`: `tuple[LatLon, LatLon]` as `((south, west), (north, east))`
|
||||
- `Color`: RGB or RGBA integer tuple, usually `(r, g, b, a)`
|
||||
|
||||
## Configuration
|
||||
|
||||
### `configure(...) -> None`
|
||||
|
||||
Configure package-wide defaults used by subsequently created maps.
|
||||
|
||||
```python
|
||||
dpgm.configure(
|
||||
user_agent=None,
|
||||
cache_dir=None,
|
||||
default_provider="osm",
|
||||
memory_cache_max_tiles=512,
|
||||
disk_cache_max_bytes=2_000_000_000,
|
||||
prefetch_margin_tiles=1,
|
||||
tile_worker_count=4,
|
||||
overlay_update_policy="coalesce",
|
||||
debug=False,
|
||||
)
|
||||
```
|
||||
|
||||
Parameters:
|
||||
|
||||
- `user_agent`: HTTP user agent for tile requests.
|
||||
- `cache_dir`: persistent tile cache root. Defaults to a platform user cache directory.
|
||||
- `default_provider`: provider name or `TileProvider` used by new maps.
|
||||
- `memory_cache_max_tiles`: maximum decoded runtime tile count per map.
|
||||
- `disk_cache_max_bytes`: maximum disk cache size. Use `None` for no size limit.
|
||||
- `prefetch_margin_tiles`: number of tiles to request around the visible viewport.
|
||||
- `tile_worker_count`: background worker count for disk/network/decode work.
|
||||
- `overlay_update_policy`: currently only `"coalesce"` is supported.
|
||||
- `debug`: store debug mode flag in global config.
|
||||
|
||||
Raises `ValueError` for invalid cache, worker, prefetch, or update-policy settings.
|
||||
|
||||
## Widget
|
||||
|
||||
### `map_widget(...) -> Iterator[Tag | None]`
|
||||
|
||||
Create a Dear PyGui child-window map shell and logical map context.
|
||||
|
||||
```python
|
||||
with dpgm.map_widget(
|
||||
tag="map",
|
||||
center=(47.9029, 1.9093),
|
||||
zoom=15,
|
||||
provider="osm",
|
||||
width=-1,
|
||||
height=-1,
|
||||
):
|
||||
dpgm.add_marker("vehicle", lat=47.9029, lon=1.9093)
|
||||
```
|
||||
|
||||
Parameters:
|
||||
|
||||
- `tag`: map tag. If omitted, a generated tag is used.
|
||||
- `center`: initial `(lat, lon)`.
|
||||
- `zoom`: initial zoom, clamped to provider range.
|
||||
- `provider`: provider name or `TileProvider`; defaults to configured default provider.
|
||||
- `width`, `height`: Dear PyGui child-window size arguments.
|
||||
- `autosize_x`, `autosize_y`: Dear PyGui child-window autosize flags.
|
||||
- `cache_dir`: optional per-map cache directory passed as keyword argument.
|
||||
- `user_agent`: optional per-map tile user agent passed as keyword argument.
|
||||
- Other keyword arguments are forwarded to `dpg.add_child_window(...)`.
|
||||
|
||||
GUI-thread only.
|
||||
|
||||
## View
|
||||
|
||||
### `set_center(lat, lon, *, map_tag=None) -> None`
|
||||
|
||||
Set the map center without changing zoom.
|
||||
|
||||
### `get_center(*, map_tag=None) -> LatLon`
|
||||
|
||||
Return the current logical map center.
|
||||
|
||||
### `set_zoom(zoom, *, map_tag=None) -> None`
|
||||
|
||||
Set the zoom, clamped to the current provider range.
|
||||
|
||||
### `get_zoom(*, map_tag=None) -> int`
|
||||
|
||||
Return the current logical zoom.
|
||||
|
||||
### `set_view(*, center=None, zoom=None, map_tag=None) -> None`
|
||||
|
||||
Set center and/or zoom as one logical view update.
|
||||
|
||||
```python
|
||||
dpgm.set_view(center=(47.9029, 1.9093), zoom=15, map_tag="map")
|
||||
```
|
||||
|
||||
### `fit_bounds(bounds, *, map_tag=None) -> None`
|
||||
|
||||
Set center and zoom so bounds fit the current draw area.
|
||||
|
||||
```python
|
||||
dpgm.fit_bounds(((47.89, 1.89), (47.92, 1.93)), map_tag="map")
|
||||
```
|
||||
|
||||
### `screen_to_latlon(x, y, *, map_tag=None) -> LatLon`
|
||||
|
||||
Convert map-local screen coordinates to latitude/longitude.
|
||||
|
||||
### `latlon_to_screen(lat, lon, *, map_tag=None) -> Point`
|
||||
|
||||
Convert latitude/longitude to map-local screen coordinates.
|
||||
|
||||
## Markers
|
||||
|
||||
### `add_marker(tag, *, lat, lon, label=None, layer="default", show=True, map_tag=None, **kwargs) -> Tag`
|
||||
|
||||
Add or replace a marker overlay.
|
||||
|
||||
Keyword options:
|
||||
|
||||
- `color`: marker fill color, default `(255, 80, 80, 255)`.
|
||||
- `radius`: marker radius in pixels, default `5.0`.
|
||||
- `show_label`: draw `label` next to the marker, default `False`.
|
||||
- `user_data`: stored with the overlay model.
|
||||
- `callback`: stored with the overlay model for application use.
|
||||
|
||||
### `update_marker(tag, *, lat=None, lon=None, label=None, map_tag=None, **kwargs) -> None`
|
||||
|
||||
Update marker properties without changing map view.
|
||||
|
||||
Supported keyword updates:
|
||||
|
||||
- `show`
|
||||
- `color`
|
||||
- `radius`
|
||||
|
||||
### `set_marker_position(tag, lat, lon, *, map_tag=None) -> None`
|
||||
|
||||
Shortcut for `update_marker(..., lat=lat, lon=lon)`.
|
||||
|
||||
### `set_marker_label(tag, label, *, map_tag=None) -> None`
|
||||
|
||||
Shortcut for `update_marker(..., label=label)`.
|
||||
|
||||
## Polylines
|
||||
|
||||
### `add_polyline(tag, *, points=None, lats=None, lons=None, layer="default", show=True, map_tag=None, **kwargs) -> Tag`
|
||||
|
||||
Add or replace a polyline overlay.
|
||||
|
||||
Provide either:
|
||||
|
||||
- `points=[(lat, lon), ...]`
|
||||
- or `lats=[...], lons=[...]`
|
||||
|
||||
Keyword options:
|
||||
|
||||
- `color`: line color, default `(80, 180, 255, 255)`.
|
||||
- `thickness`: line thickness, default `2.0`.
|
||||
- `closed`: close the polyline, default `False`.
|
||||
- `simplify`: stored with the overlay model, default `True`.
|
||||
- `user_data`: stored with the overlay model.
|
||||
|
||||
### `update_polyline(tag, *, points=None, lats=None, lons=None, map_tag=None, **kwargs) -> None`
|
||||
|
||||
Update polyline points or properties.
|
||||
|
||||
Supported keyword updates:
|
||||
|
||||
- `show`
|
||||
- `color`
|
||||
- `thickness`
|
||||
|
||||
### `set_polyline_points(tag, points, *, map_tag=None) -> None`
|
||||
|
||||
Shortcut for replacing a polyline point sequence.
|
||||
|
||||
## Trajectories
|
||||
|
||||
### `add_trajectory(tag, *, points=None, lats=None, lons=None, layer="default", show=True, map_tag=None, **kwargs) -> Tag`
|
||||
|
||||
Add or replace a trajectory overlay.
|
||||
|
||||
Provide either `points` or `lats`/`lons`. Empty trajectories are valid for live updates.
|
||||
|
||||
Keyword options:
|
||||
|
||||
- `timestamps`: optional sequence with the same length as points.
|
||||
- `color`: trajectory color, default `(255, 180, 60, 255)`.
|
||||
- `thickness`: line thickness, default `2.0`.
|
||||
- `show_points`: draw point markers along the trajectory, default `False`.
|
||||
- `point_stride`: draw every Nth point when `show_points=True`, default `1`.
|
||||
- `user_data`: stored with the overlay model.
|
||||
|
||||
### `update_trajectory(tag, *, points=None, lats=None, lons=None, map_tag=None, **kwargs) -> None`
|
||||
|
||||
Update trajectory points or properties.
|
||||
|
||||
Supported keyword updates:
|
||||
|
||||
- `timestamps`
|
||||
- `show`
|
||||
- `color`
|
||||
- `thickness`
|
||||
|
||||
## Generic Overlay Control
|
||||
|
||||
### `set_overlay_show(tag, show, *, map_tag=None) -> None`
|
||||
|
||||
Show or hide an overlay without deleting it.
|
||||
|
||||
### `delete_overlay(tag, *, map_tag=None) -> None`
|
||||
|
||||
Delete an overlay from its map and layer.
|
||||
|
||||
When `map_tag` is omitted, the API can resolve an overlay only if the tag is unambiguous across
|
||||
registered maps. In multi-map apps, pass `map_tag`.
|
||||
|
||||
## Layers
|
||||
|
||||
### `add_layer(name, *, z_index=None, show=True, map_tag=None) -> None`
|
||||
|
||||
Create or update a logical overlay layer.
|
||||
|
||||
### `show_layer(name, *, map_tag=None) -> None`
|
||||
|
||||
Show all overlays assigned to a layer.
|
||||
|
||||
### `hide_layer(name, *, map_tag=None) -> None`
|
||||
|
||||
Hide all overlays assigned to a layer.
|
||||
|
||||
### `clear_layer(name, *, map_tag=None) -> None`
|
||||
|
||||
Delete all overlays assigned to a layer.
|
||||
|
||||
### `clear_map(*, map_tag=None) -> None`
|
||||
|
||||
Delete all overlays and invalidate map tile resources.
|
||||
|
||||
## Tile Providers
|
||||
|
||||
### `TileProvider`
|
||||
|
||||
Immutable tile provider definition.
|
||||
|
||||
```python
|
||||
dpgm.TileProvider(
|
||||
name="custom",
|
||||
url_template="https://example.com/{z}/{x}/{y}.png",
|
||||
min_zoom=0,
|
||||
max_zoom=19,
|
||||
tile_size=256,
|
||||
attribution="Tiles (c) Example",
|
||||
headers={},
|
||||
subdomains=(),
|
||||
retina=False,
|
||||
file_extension=None,
|
||||
)
|
||||
```
|
||||
|
||||
Fields:
|
||||
|
||||
- `name`: provider registry name.
|
||||
- `url_template`: XYZ URL template with `{z}`, `{x}`, and `{y}`.
|
||||
- `min_zoom`, `max_zoom`: valid zoom range.
|
||||
- `tile_size`: tile size in pixels.
|
||||
- `attribution`: text drawn on the map.
|
||||
- `headers`: request headers.
|
||||
- `subdomains`: values for `{s}`.
|
||||
- `retina`: if true, `{r}` expands to `"@2x"`.
|
||||
- `file_extension`: value for `{ext}` and disk cache extension.
|
||||
|
||||
### `register_provider(provider, *, replace=False) -> None`
|
||||
|
||||
Register a provider by name.
|
||||
|
||||
### `unregister_provider(name) -> None`
|
||||
|
||||
Remove a registered provider.
|
||||
|
||||
### `get_provider(name) -> TileProvider`
|
||||
|
||||
Return a registered provider.
|
||||
|
||||
### `list_providers() -> list[str]`
|
||||
|
||||
Return registered provider names in sorted order.
|
||||
|
||||
### `set_provider(provider, *, map_tag=None) -> None`
|
||||
|
||||
Switch a map to another provider while preserving overlays and center.
|
||||
|
||||
`provider` may be a provider name or a `TileProvider`. Provider switching clamps zoom to the new
|
||||
provider range and invalidates stale tile loads.
|
||||
|
||||
## Cache
|
||||
|
||||
### `CacheStats`
|
||||
|
||||
Public cache statistics snapshot.
|
||||
|
||||
Fields:
|
||||
|
||||
- `memory_tiles`
|
||||
- `memory_max_tiles`
|
||||
- `memory_hits`
|
||||
- `memory_misses`
|
||||
- `disk_bytes`
|
||||
- `disk_max_bytes`
|
||||
- `disk_hits`
|
||||
- `disk_misses`
|
||||
- `disk_path`
|
||||
|
||||
### `get_cache_stats(*, map_tag=None) -> CacheStats`
|
||||
|
||||
Return memory and disk cache diagnostics. With `map_tag=None`, returns global disk-cache stats and
|
||||
configured memory limit.
|
||||
|
||||
### `clear_memory_cache(*, map_tag=None) -> None`
|
||||
|
||||
Clear decoded in-memory tile data. If `map_tag` is omitted outside a map context, all registered
|
||||
maps are targeted.
|
||||
|
||||
### `clear_disk_cache(provider=None, *, map_tag=None) -> None`
|
||||
|
||||
Clear persistent tile cache data.
|
||||
|
||||
- `provider=None`: clear all provider namespaces.
|
||||
- `provider="osm"`: clear only one provider namespace.
|
||||
- `map_tag="map"`: enqueue a map-scoped clear through the renderer.
|
||||
|
||||
## Diagnostics
|
||||
|
||||
### `get_map_debug_state(*, map_tag=None) -> dict[str, Any]`
|
||||
|
||||
Return a diagnostic snapshot for a map. Keys include:
|
||||
|
||||
- `tag`
|
||||
- `center`
|
||||
- `zoom`
|
||||
- `requested_size`
|
||||
- `measured_size`
|
||||
- `visible`
|
||||
- `provider`
|
||||
- `overlay_count`
|
||||
- `layers`
|
||||
- `dirty_flags`
|
||||
- `pending_command_count`
|
||||
- `generation`
|
||||
- `active_drag`
|
||||
- `last_mouse_position`
|
||||
- `tiles`
|
||||
|
||||
This output is for debugging and logging. It is not guaranteed to be a stable serialization
|
||||
format.
|
||||
|
||||
## Exceptions
|
||||
|
||||
Public exception classes are defined in `dpg_map.exceptions`:
|
||||
|
||||
- `DpgMapError`
|
||||
- `ProviderError`
|
||||
- `ProviderExistsError`
|
||||
- `ProviderNotFoundError`
|
||||
- `InvalidProviderError`
|
||||
- `ProjectionError`
|
||||
- `MapNotFoundError`
|
||||
- `OverlayNotFoundError`
|
||||
- `CoordinateError`
|
||||
- `ThreadingError`
|
||||
- `CacheError`
|
||||
|
||||
Common error cases:
|
||||
|
||||
- Invalid latitude/longitude raises `CoordinateError`.
|
||||
- Unknown map tags raise `MapNotFoundError`.
|
||||
- Unknown overlay tags raise `OverlayNotFoundError`.
|
||||
- Unknown or invalid providers raise provider-specific errors.
|
||||
|
||||
## Threading Contract
|
||||
|
||||
GUI-thread only:
|
||||
|
||||
- `map_widget(...)`
|
||||
- Dear PyGui setup and application code that creates widgets
|
||||
|
||||
Runtime-safe public areas:
|
||||
|
||||
- View updates: `set_center`, `set_zoom`, `set_view`, `fit_bounds`
|
||||
- Overlay updates: `add_marker`, `update_marker`, `update_trajectory`, `delete_overlay`
|
||||
- Layer updates: `add_layer`, `show_layer`, `hide_layer`, `clear_layer`
|
||||
- Provider and cache updates: `set_provider`, `clear_memory_cache`, `clear_disk_cache`
|
||||
|
||||
The renderer owns Dear PyGui draw commands, textures, input handlers, and frame callbacks.
|
||||
Reference in New Issue
Block a user