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 givensearch_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 returnstrueif succesful. If already started or has no route defined, will returnfalseto 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 -
directionanddirectionValid- 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.
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 can be used. See details below.
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.
In addition to common dependencies for QML applications, the following are needed:
- PyOtherSide https://github.com/thp/pyotherside
- PyXDG https://www.freedesktop.org/wiki/Software/pyxdg/
- Mapbox GL Native, Qt version, use the packaged version at https://github.com/rinigus/pkg-mapbox-gl-native
- Mapbox GL QML, unofficial QML bindings, https://github.com/rinigus/mapbox-gl-qml
- GPXPy, https://github.com/tkrajina/gpxpy
- S2 Geometry Library, https://github.com/google/s2geometry
- For Kirigami platform: Nemo DBus https://github.com/sailfishos/nemo-qml-plugin-dbus
When developing with Kirigami using flatpak builder, dependencies will be pulled and installed in flatpak. See instructions regarding Kirigami below.
GPXPy is also provided as a thirdparty submodule and can be installed
together with Pure Maps by setting corresponding option during cmake
configuration phase.
Starting from Pure Maps version 2.0, the application has to be compiled. You could either
- compile/install/run
- compile/run from source tree
In the both cases, you would have to specify platform via -DFLAVOR
to cmake. Supported platforms:
- Kirigami:
FLAVOR=kirigami - QtControls:
FLAVOR=qtcontrols - Sailfish:
FLAVOR=silica - Ubuntu Touch:
FLAVOR=uuitk
It is recommended to build the sources in a separate folder, as in
mkdir build
cd build
cmake -DFLAVOR=kirigami ..
make && make install
For compile/install/run, use regular make and make install before
running application.
To run from the source tree, add -DRUN_FROM_SOURCE=ON option when
running cmake. Please note that, when running from source tree, do
not run make install in the build folder. Otherwise it can overwrite
your source files. In this case, make and running compiled
executable directly would allow you to run application without
installation. For example, from Qt Creator directly.
The build options can be specified in Qt Creator under "Build settings" of the project. Just add them to the additional arguments of cmake.
Mainly targeting packagers, it is possible to specify default
providers using cmake project options. Notice the difference in
supplied values for basemap and other options:
DEFAULT_PROFILE=profilewhere profile is either online or offlineDEFAULT_BASEMAP=providerMapprovideris either specified in basemap JSON as "provider" or, if absent, as "name"DEFAULT_GEOCODER=providerDEFAULT_GUIDE=providerDEFAULT_ROUTER=provider
In the last three options, provider corresponds to the basename of
JSON/Python file describing the provider. Example: "photon".
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.
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 "."
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()
// functions
function a() {
return 10;
}
}
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent