🗺️ PySide6-OsmAnd-SDK

Bring OsmAnd's native offline map stack into modern Qt6 and PySide6 apps — with native widgets, .obf rendering, and cross-platform build tooling.

---

☕ Support

---

Demo Video

output.mp4

---

🚀 Quick Start

1. Clone and prepare Git LFS data

git lfs install
git lfs pull

The bundled World_basemap_2.obf demo map is stored through Git LFS. If the file is only about 100 bytes and starts with version https://git-lfs.github.com/spec/v1, it is still a pointer file and must be pulled with Git LFS before the preview can render real map data.

2. Install Python dependencies

python -m pip install -e .

3. Build the native runtime

Windows

powershell -ExecutionPolicy Bypass -File tools\osmand_render_helper_native\build_helper.ps1

or build the native widget with MSVC:

powershell -ExecutionPolicy Bypass -File tools\osmand_render_helper_native\build_native_widget_msvc.ps1

Linux

bash tools/osmand_render_helper_native/build_linux.sh

macOS

QT_ROOT=/opt/homebrew/opt/qt JOBS=4 bash tools/osmand_render_helper_native/build_macos.sh

4. Launch the preview

osmand-preview --backend auto

You can also run the entry point directly:

python -m maps.main --backend auto

---

🌟 Overview

PySide6-OsmAnd-SDK is an independent GitHub project for embedding OsmAnd's native map stack into modern Qt6 and PySide6 workflows.

It combines vendored OsmAnd core sources, native build tooling, Python integration, a Qt widget bridge, and a runnable preview application in one repository. The goal is to make offline map rendering easier to build, test, and embed from a single codebase.

Key highlights:

• 🧭 Ports the OsmAnd Qt5-era native map stack to Qt6.
• 🧩 Exposes a native C++ map widget for PySide6 applications.
• 🗺️ Supports offline rendering from OsmAnd .obf map data.
• ⚡ Provides both native OpenGL preview and Python-driven raster preview paths.
• 🛠 Ships build scripts for Windows, Linux, and macOS toolchains.
• 📦 Bundles demo map data and OsmAnd resources for local testing.

---

🧭 Why This Project Matters

This SDK is designed for developers who want OsmAnd's offline map engine while building with current-generation Qt and Python tooling. It reduces the friction of combining native C++ rendering with a PySide6 user interface, making it a practical foundation for desktop map viewers, GIS tools, travel applications, embedded map previews, and other offline-first location products.

By moving the native stack forward to Qt6 and validating PySide6 compatibility, the project helps OsmAnd-based development stay usable outside older Qt5-only integration paths.

---

✨ Key Capabilities

Capability	Description
Native widget hosting	Embed the OsmAnd native widget through PySide6 using .dll, .so, or .dylib runtimes.
Offline .obf rendering	Render OsmAnd binary map packages locally without depending on online map tiles.
Python raster path	Use helper-backed Python rendering for preview and integration workflows.
OpenGL preview	Test native OpenGL rendering paths through the included preview application.
Cross-platform builds	Build helper and widget outputs on Windows, Linux, and macOS.
Demo data included	Use the bundled World_basemap_2.obf and OsmAnd resources for local validation.

---

🧱 Repository Layout

Path	Purpose
vendor/osmand/build	Build tree and supporting files used by the Windows-oriented OsmAnd build flow.
vendor/osmand/core	Vendored OsmAnd core sources.
vendor/osmand/core-legacy	Vendored legacy core sources still required by the native build.
vendor/osmand/resources	OsmAnd rendering resources, styles, and data files.
tools/osmand_render_helper_native	Native helper and widget sources plus Windows, Linux, and macOS build scripts.
src/maps	PySide6 preview application and Python integration layer.
src/maps/main.py	Preview entry point.

---

🗺 Map Data and Styles

.obf files

OsmAnd .obf files are offline binary map packages. They store the geographic content consumed by the native engine, including roads, boundaries, land use, water, place labels, routing-related data, and points of interest.

This repository's preview defaults to:

src/maps/tiles/World_basemap_2.obf

The bundled .obf is only a default demo dataset. You can replace it with another OsmAnd .obf file, select a different file from the preview window, or point the runtime to a custom path through the documented environment variables.

Additional .obf map downloads are available from the official OsmAnd download list:

https://download.osmand.net/list.php

When a local plugin/data/geonames.sqlite3 GeoNames index is present, the preview search demo prefers it for place-name lookup and uses the active .obf search path as a fallback. The optimized database is compatible with the GeoNames-search project output, uses the compact cities500-based schema, and keeps global place-name queries such as 北京 / Beijing responsive without scanning the full database in Python.

Rendering styles

Rendering styles are XML-based rule files under:

vendor/osmand/resources/rendering_styles

Common examples include:

• default.render.xml
• mapnik.render.xml
• snowmobile.render.xml

These files control how the same .obf data appears on screen: colors, line rules, polygon fills, icons, labels, and theme-specific display logic. The Python integration layer passes both the selected .obf data source and active style file into the OsmAnd rendering backend, allowing the map presentation to change without changing the underlying geographic data.

---

🧰 Platform Setup

Windows

python -m pip install -e .
powershell -ExecutionPolicy Bypass -File tools\osmand_render_helper_native\build_helper.ps1
osmand-preview --backend auto

Alternative native widget build:

powershell -ExecutionPolicy Bypass -File tools\osmand_render_helper_native\build_native_widget_msvc.ps1

Direct entry point:

python src\maps\main.py --backend auto

Linux

Install system dependencies first:

# Ubuntu/Debian
sudo apt-get install build-essential cmake git qt6-base-dev libqt6opengl6-dev

# Fedora/RHEL
sudo dnf install gcc g++ cmake git qt6-qtbase-devel qt6-qtbase-gui qt6-qtdeclarative-devel

# Arch
sudo pacman -S base-devel cmake git qt6-base

Then build and run:

python -m pip install -e .
bash tools/osmand_render_helper_native/build_linux.sh
osmand-preview --backend auto

Direct entry point:

python src/maps/main.py --backend auto

macOS

brew install cmake qt git-lfs
git lfs install
git lfs pull
python -m pip install -e .
QT_ROOT=/opt/homebrew/opt/qt JOBS=4 bash tools/osmand_render_helper_native/build_macos.sh
osmand-preview --backend auto

Run either backend explicitly:

python -m maps.main --backend python
python -m maps.main --backend native

---

📚 Documentation

Document	Description
Python SDK Guide	Python integration, runtime selection, preview usage, and embedding notes.
Python SDK Guide 中文	中文版 Python SDK 使用指南。
Build Guide	Native helper/widget build process, platform toolchains, and runtime troubleshooting.
NOTICE	Licensing and third-party attribution context for vendored OsmAnd components.

---

📝 Runtime Notes

• The preview defaults to src/maps/tiles/World_basemap_2.obf and the vendored resources under vendor/osmand/resources.
• The bundled .obf is a Git LFS file; run git lfs pull after cloning before expecting visible map content.
• The bundled .obf is replaceable, so you can test other OsmAnd map extracts.
• Windows: helper outputs in tools/osmand_render_helper_native/dist and tools/osmand_render_helper_native/dist-msvc are generated and ignored by Git.
• Linux: helper outputs in tools/osmand_render_helper_native/dist-linux are generated and ignored by Git.
• macOS: helper outputs in tools/osmand_render_helper_native/dist-macosx are generated and ignored by Git.
• When the native widget runtime is available, the preview can use the embedded OsmAnd widget; otherwise the Python rendering path remains available.
• On Linux, the native widget library is built as a .so file; on macOS it is built as osmand_native_widget.dylib.
• If you embed the native widget on Linux and hit XCB/GLX issues, see BUILD.md and the Python SDK Guide for Qt runtime flags that must be applied before QApplication starts.

---

📄 License

Because this repository redistributes vendored OsmAnd source trees, the top-level project is documented as GPL-3.0-or-later.

Top-level license files:

• LICENSE: project-level license summary for PySide6-OsmAnd-SDK
• COPYING: verbatim GNU GPL v3 text

Vendored upstream trees keep their own original license files:

• vendor/osmand/core/LICENSE
• vendor/osmand/core-legacy/LICENSE
• vendor/osmand/resources/LICENSE

Additional context is summarized in NOTICE.md.

---

Created by OliverZhaohaibin.