Pure Maps

Matrix Discussions

Latest release SFOS Ubuntu Touch Flatpak

Packaging status

Pure Maps is an application for Sailfish OS and Linux to display vector and raster maps, places, routes, and provide navigation instructions with a flexible selection of data and service providers.

Pure Maps is free software released under the GNU General Public License (GPL), see the file COPYING for details. Pure Maps is a fork of WhoGo Maps that was made to continue its development.

There are three main communication channels with the users: GitHub discussions and issues, Matrix channel #pure-maps:matrix.org and a thread at TMO.

Please use Github issues to address specific problems and development requests. General discussion is expected either through corresponding topics in GitHub discussions, issues, Matrix channel, or TMO thread.

Currently, the homepage for Pure Maps is a placeholder. You are welcome to help by working on the corresponding issue.

Pure Maps supports positional argument (one) that could either specify geo:latitude,longitude URI or a search string that will be searched by geocoder.

If Pure Maps instance is running already, it will be contacted via DBus and the request will be forwarded.

DBus (service io.github.rinigus.PureMaps at session bus) can be used to

• search: method Search
• show poi: method ShowPoi
• get navigation status and control it.

There service is split as described below.

Path: /io/github/rinigus/PureMaps Interface: io.github.rinigus.PureMaps

Methods:

• Search(String search_string) - activates search action for given search_string

• ShowPoi(String title, Double latitude, Double longitude) - show POI on map with the given coordinates and title.

Path: /io/github/rinigus/PureMaps/navigator Interface: io.github.rinigus.PureMaps.navigator

Methods:

• Clear() - stops navigation and removes current route

• Start() -> Boolean - start navigation and returns true if successful. If already started or has no route defined, will return false to indicate failure.

• Stop() - stop navigation if running.

Properties and signals:

Each property has a corresponding ...Changed signal to indicate when the value of the property has changed.

• destDist, destEta, destTime - human readable strings with the remaining distance, time, and estimated time of arrival

• direction and directionValid - bearing of the current route segment and whether it is valid (current location is on route)

• hasRoute - whether route has been set in application

• icon - icon name for the next maneuver

• language - navigation instructions language

• manDist, manTime - remaining distance and time for the next maneuver in human readable form

• mode - mode of transportation

• narrative - longer next maneuver instruction, should be available for all maneuvers

• alongRoute - whether current location is on route and movement is along it.

• progress - current progress along the route in percentage (0-100)

• running - whether navigation in active

• street - short form of the narrative usually shown in Pure Maps next to the maneuver icon. Could be absent for some maneuvers

• totalDist, totalTime - total route distance and time in human readable form.

Note that you will need API keys if you wish to access the services that require them (such as Mapbox). For that, register as a developer and insert these keys in the preferences. Among services that don't require API keys are OSM Scout Server (for offline maps), HSL (raster tiles for Finland), Sputnik (raster tiles in Russian), Photon (search).

Pure Maps is packaged for different distributions. Included in the source tree: Sailfish OS version is packaged as RPM, Linux version is packaged using Flatpak or RPM, and Ubuntu Touch version as click. Several distributions provide packaging scripts in their source trees.

For packaging, please copy poor/apikeys.py to tools/apikeys.py and fill missing API keys for the services that you plan to use. Note that the format of tools/apikeys.py has changed with 2.9 release.

Flatpak specific instructions are available under packaging/flatpak.

Ubuntu Touch specific instructions are available in Ubuntu Touch README.

For development of Pure Maps and testing on desktop, you would have to choose platform for which you develop, install dependencies, and be able to run the application. In this case, Qt Creator or VSCode can be used.

Alternative is to use Dev Containers. Three containers are available:

• Qt5 Latest (Debian 12) provides the latest Qt 5 packages available in Debian 12, currently Qt 5.15.8.
• Qt6 Latest (Fedora 44) tracks the latest Qt 6 packages released by Fedora 44.

To use them, install a Dev Containers compatible editor extension, such as VSCode Dev Containers, and make sure either Docker or Podman is available. Open the Pure Maps source tree in the editor, run the "Dev Containers: Reopen in Container" command, and select one of the containers above. The container builds the development dependencies and mounts the source tree at /workspace. If you switch containers later, use the "Dev Containers: Rebuild and Reopen in Container" command so the selected image is rebuilt. See Dev Container README for details about containers.

There are three CMake presets available: debug-kirigami-qt5 for Qt 5, debug-qtcontrols6 for Qt 6, and debug-kirigami6 for Qt 6 with Kirigami. These presets use Ninja, write the build tree to build, set CMAKE_INSTALL_PREFIX to install under the source tree, enable RUN_FROM_SOURCE, and bundle the development copies of GPXPy and the Geoclue2 Qt plugin. Configure with cmake --preset <preset-name> and build with cmake --build build.

Do not run cmake --install for builds configured with these presets. They are made for running Pure Maps directly from the source folder, and CMake emits a warning for this configuration. For installation or packaging, use a separate build configured without RUN_FROM_SOURCE.

Another alternative, is to use Flatpak-based environment and develop using that. For this approach, see separate README.

Building and Debugging for Ubuntu Touch is described in README.

To support multiple platforms, QML code is split into platform-specific and platform-independent parts. Platform-independent part is in qml folder with the platform-dependent code under qml/<platform-id>. Correct platform is picked up in installation phase (make install) or is set by make for local builds.

Within platform-independent code, platform is included allowing to access platform-specific implementations of page stack, file dialog, and other specific aspects. For this approach to work, API in the platform specific implementation has to be the same for all platforms.

To add new platform, add new directory under qml, new Makefile target to set it, and implement all the required QML items. Take a look under other platforms for examples.

To build PureMaps from source, please refer to the Build.md file. It provides comprehensive instructions for compiling the application on systems such as Debian 12 and Ubuntu 24.04.

Throughout QML, Python, and C++ code, all the same type items (properties, signals, functions), are ordered alphabetically.

Its possible that some of the implemented code does not fully comply with the outlined order. Then it should be fixed eventually.

To simplify development, there are few simple rules regarding QML file organization. QML files are organized as follows (use the needed components):

import A
import B
import pm 1.0
import "js/util.js" as Util
Item {
 id: item
 // base class defined properties in alphabetic order
 prop_a: val_a
 prop_b: val_b
 // new properties in alphabetic order
 property var np_a: default_a
 default property bool np_b: default_b
 // readonly properties
 readonly property var images: QtObject {
 readonly property string pixel: "pure-image-pixel"
 readonly property string poi: "pure-image-poi"
 readonly property string poiBookmarked: "pure-image-poi-bookmarked"
 }
 // signals
 signal mySignal
 // local unexported properties
 property bool _locked: false
 // behavior
 Behavior on bearing {
 RotationAnimation {
 direction: RotationAnimation.Shortest
 duration: map.ready ? 500 : 0
 easing.type: Easing.Linear
 }
 }
 // new sub-items following the same principles
 Item {
 id: subitem
 }
 // connections
 Connections {
 }
 // signal handlers
 Component.onCompleted: init()
 onActivated: doSomething()
 // signal handlers as functions
 function handleActivated(activated_arg) {
 doSomethingWithArg(activated_arg)
 }
 // functions
 function a() {
 return 10;
 }
}

You can translate Pure Maps to a new language or improve an existing translation using Transifex.

If you don't have a Transifex account and want to fix a minor issue, you can create a pull request or open an issue.