dpg-map/docs/API_REFERENCE.md

API Reference

Public imports are available from:

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.

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.

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.

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.

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.

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.