PeakNavApp

PeakNav is an app to view world mountains in 3D.

Explore the mountains, see paths and ways projected onto their 3D shapes, as well as the names of the nearby peaks!

Available for Android, Windows, macOS and Linux.

Download

Android — Google Play

Desktop — the latest release:

Platform	File
Windows 10/11 (64-bit)	peaknav-<version>-windows-x64-setup.exe
macOS, Apple silicon	peaknav-<version>-macos-aarch64.dmg
macOS, Intel	peaknav-<version>-macos-x86_64.dmg
Debian / Ubuntu	peaknav_<version>_amd64.deb
Any other Linux	peaknav-<version>-x86_64.AppImage
Anything else, or you already have Java	peaknav-<version>.jar

Every desktop download bundles its own Java runtime, so no Java installation is required. The .jar is the exception — it needs Java 17 or later (java -jar peaknav-<version>.jar) — and it is also the only build that covers ARM and 32-bit machines, which have no installer of their own.

The desktop builds are not code-signed yet, so the first launch needs one extra step: on Windows, SmartScreen shows "Windows protected your PC" — click More info, then Run anyway; on macOS, right-click the app and choose Open rather than double-clicking. Downloaded maps and settings are kept outside the installation (%APPDATA%\PeakNav, ~/Library/Application Support/PeakNav, or ~/.peaknav), so upgrading or reinstalling never costs you your data.

Python package

PeakNav is also on PyPI, as peaknav:

pip install peaknav

Three modules, in increasing order of what they need from the machine:

• peaknav.terrain — the elevation of any coordinate on Earth, in pure Python (one dependency: Pillow). It reads the same compressed ASTER dataset the app renders — with summit heights corrected against surveyed values — downloading tiles per area and caching them locally.

  >>> from peaknav.terrain import elevation_at
  >>> elevation_at(45.9417, 7.7480)          # the Breithorn
  4160

• peaknav.headless — the real PeakNav renderer running off-screen, driven from Python: camera control, view options, rendered frames — for scripted snapshots, panoramas and videos. Needs Java 17+ and a display; the renderer jar (peaknav-headless-<version>.jar, attached to every GitHub release) is downloaded on first use, verified against a pinned digest, and cached — or point $PEAKNAV_HEADLESS_JAR at your own build. The renderer speaks plain HTTP (self-described at /openapi.json), so anything that can curl can drive it too.

  from peaknav.headless import PeakNavHeadless
  
  with PeakNavHeadless(45.9763, 7.6586) as nav:
      nav.look(bearing_deg=230, pitch_deg=-4)
      nav.set_altitude_asl(3200)
      nav.save_frame("matterhorn.png")

• peaknav.jupyter (experimental) — an interactive PeakNav view inside a Jupyter notebook, with pan/tilt controls, altitude, coordinates and display toggles (pip install "peaknav[jupyter]").

The package sources, example notebooks and developer documentation live in peaknav-python/.

Datasets

This app works with data of two datasets (currently hosted on HuggingFace repository):

• global-elevation-aster-slippy-tiles-tar-gz contains the ASTER elevation dataset with a clever compression algorithm, retiled according to the slippy tiles convention.
• global-openstreetmap-extraction-slippy-tiles-tar contains data extracted from OpenStreetMap, also retiled according to the slippy map convention.

Gallery

Build

To build the project, follow these steps:

• Download the Liberation Fonts .ttf files and extract them into the ./assets/liberation_fonts/ folder.

• Convert all .svg files located in ./assets_nonshared/icons/ to .png format, and place the resulting files in the ./assets/icons/ folder.

• Build the Apache Lucene search index for geographical names into ./assets/geonames_index.362/. Download cities500.txt and alternateNamesV2.txt from GeoNames, then:

  ./gradlew :core:buildGeonamesIndex \
      --args="cities500.txt alternateNamesV2.txt assets/geonames_index.362"

  • Lucene is pinned to 3.6.2, the last version compatible with Android — don't bump it.

  • The index carries the string fields name, asciiname, lat_store, lon_store and population_store. Each place is one document whose name field holds every name it can be searched by — the local form, a selection of translations, and accent-free spellings — so "Venezia" and "Venice" both find the same city and the stored data is paid for once.

  • The builder lives in its own source set, core/src/tools/java, so none of it ships in the app.

  • Mountain peaks can then be added from OpenStreetMap extracts (Geofabrik .osm.pbf files), without rebuilding from the GeoNames dumps:

    pip install osmium
    python3 tools/extract_osm_peaks.py peaks.tsv /path/to/pbf_dir
    ./gradlew :core:addPeaksToIndex --args="peaks.tsv assets/geonames_index.362"

    A third argument sets a minimum elevation; peaks with a Wikipedia article are kept regardless of it. Search results show peaks with their elevation — "Matterhorn (4478 m)" — and rank them below any city sharing their name.

• Build the project with Gradle — this process is straightforward when using Android Studio, and supports both Android and Desktop builds.

Headless renderer

The headless/ module builds the app as a library that draws off-screen, for producing views from code instead of from a person at a keyboard — screenshots, panoramas, videos, documentation images:

./gradlew :headless:renderJar    # standalone fat jar, no Gradle needed to run it
java -jar headless/build/libs/peaknav-headless-<version>.jar \
    --lat 46.0207 --lon 7.7491 --bearing 210 --out matterhorn.png

The same jar is attached to every GitHub release as peaknav-headless-<version>.jar, so rendering from a script does not require building the project. It still needs a display connection (the window is created hidden, but GL needs one), and --serve [port] starts a REST server describing itself at /openapi.json, so it can be driven from Python — or anything that speaks HTTP. The peaknav Python package, described in the Python package section above, is exactly such a client; see headless/README.md for the Java API and implementation notes.

Desktop installers

./gradlew :desktop:installers

Produces all of the downloads listed above into desktop/build/installers/: the Windows setup executable, both macOS disk images, the Debian package and the AppImage. They are built with construo (application image plus a bundled JRE 17) wrapped by NSIS, genisoimage, dpkg-deb and mksquashfs — all of which cross-compile, so every artefact can be produced from a single machine whichever OS it runs. Needs nsis, genisoimage and squashfs-tools installed; see desktop/packaging/README.md for details and the signing caveats.

License

The source code and assets are licensed under the GNU General Public License, version 3 — Copyright © Francesco Bonazzi. See LICENSE.

Three things are not covered by it: the name PeakNav, the PeakNav logo, and the application launcher icon — see TRADEMARK-AND-ASSETS.md. Everything else, the interface icons and the rendered images included, is under the GPL. You may fork and publish the code freely under your own name and launcher icon.

The map data, terrain, imagery and third-party libraries it builds on carry their own licenses and attribution requirements, listed in THIRD_PARTY_LICENSES.md and reproduced on the app's own License page.