dpg-map/docs/API_REFERENCE.md

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