Map widget for Dear PyGui
- Python >= 3.10
- Dear PyGui >= 1.3.1
You can install this package from pip, with
pip install dearpygui-map
Clone code repository from your local machine, install from there. Poetry is required.
git clone https://github.com/mkouhia/dearpygui-map.git
cd dearpygui-map
poetry build
# take note of the build step output, install package from the dist folder
pip install dist/PRODUCED_PACKAGE.whl
This basic example creates a map widget with defined size, initial center point (latitude, longitude) and initial zoom level. The zoom levels are same as on tiled maps, for example 12 could represent a town-sized view. Larger is more zoomed in.
import dearpygui.dearpygui as dpg
import dearpygui_map as dpg_map
dpg.create_context()
with dpg.window(label="Map demo"):
dpg_map.add_map_widget(
width=700,
height=500,
center=(60.1641, 24.9402),
zoom_level=12)
dpg.create_viewport(title="Dear PyGui map widget demo", width=800, height=600)
dpg.setup_dearpygui()
dpg.show_viewport()
dpg.start_dearpygui()
dpg.destroy_context()
The function add_map_widget
places a Dear PyGui drawlist with map contents,
return value is the drawlist tag.
By default, OpenStreetMap is used as the map tile source. This can be configured with add_map_widget
argument tile_source
, with similar source definition:
OpenStreetMap = TileServer(
name="OpenStreetMap",
base_url="http://{subdomain}.tile.openstreetmap.org/{z}/{x}/{y}.png",
subdomains=["a", "b", "c"],
max_zoom_level=19,
license_text="© OpenStreetMap contributors",
thread_limit=2,
)
Tiles are downloaded from the supplier on a background thread. Whenever map is zoomed or moved, more tiles are downloaded. The tiles are cached to local storage path in user cache directory - for different platforms, cache directories are:
Windows: C:\Users\<username>\AppData\Local\dearpygui_map\Cache
Mac OS X: ~/Library/Caches/dearpygui_map
Other: ~/.cache/dearpygui_map
As for now, dearpygui-map is in its early design phase and contains some items that may not be acceptable in production environments. These issues will be addressed later
- Tile download threads are created every time
TileManager.draw_layer
is called. - Non-visible tiles are not removed from dearpygui
- Zooming and panning leads to wait times before tiles are ready to be shown.
Poetry is required for development (see installation instructions)
- Create development environment with
poetry install
- Enter environment with
poetry shell
All code is to be formatted with black
:
black dearpygui_map
and code quality checked with pylint
:
pylint dearpygui_map
Tests should be written in pytest
, targeting maximum practical code coverage. Tests are run with:
pytest
and test coverage checked with
pytest --cov
Optionally, html test coverage reports can be produced with
pytest --cov dearpygui_map --cov-report html
Contributions are welcome. Please also see GitHub issues and milestones.