QML PositionSource with map matching support
This is a QML type -
PositionSourceMapMatched - that is designed to
be an extended PositionSource. In addition to regular PositionSource
functionality, it allows to determine current street name, direction
of travel along the street, current speed limit. For that, it
communicates with local OSM Scout
Server and uses map
maptching functionality of
Communication between PositionSourceMapMatched and OSM Scout Server is implemented through DBus. Thus, to use this QML type, you would need
The maps required for map matching can be downloaded by OSM Scout Server (GUI recommended).
While, at present, the type exposes only street name, direction, and speed limit, it can be easily extended to provide other information supported by Valhalla's map matching functionality. Note that it is focused on just-in-time data, not longer stretches.
The code is contained in a single QML file. So, copy PositionSourceMapMatched.qml into your source tree and use it via local import. Since its licensed under MIT license, it should be compatible with the variuos open source and proprietary licenses.
When used in the program, if the map matching mode is enabled,
PositionSourceMapMatched will automatically request map matched
position and available data regarding it. If needed, it will try to
start OSM Scout Server through systemd socket activation and will
follow apperance / disappearance of the server on D-Bus. The
corresponding status is communicated via properties.
In addition to regular usage, there are facilities for the use of the type in testing environment (feeding coordinates from outside) and timing statistics.
See included example for usage of
showing available data.
The exported API follows QML PositionSource.
The main limitations, when compared to the PositionSource, are:
positionproperty is replaced by JS Object with the same properties as the original. Thus, there are no methods or signals associated with the changes with the properties of
position(for example, you cannot follow
position). However, changes in
positionproperty are signaled, as usual, via on
updateTimeout()is not propagated due to the absence of this signal in Sailfish QtPositioning module. Feel free to uncomment the corresponding code in master and gps sections of the code.
The public API is extending PositionSource via additional properties. Below, the properties are described by their use: production, testing, and timining.
directionDirection of travel along the matched street or path. Given in degrees from true north.
directioncontains valid data
mapMatchingAvailableTrue if OSM Scout Server is running and exposing map matching via D-Bus
mapMatchingModeRequested map matching mode. This follows
enum Modevalues in valhallamapmatcher.h of OSM Scout Server code. At present, the following modes are available (value and its meaning listed below):
- 0 no map matching
- 1 car, "auto" in Valhalla API
- 2 car along shorter distance, "auto_shorter" in Valhalla API
- 3 bicycle
- 4 bus
- 5 pedestrian
Care will be taken to keep map matching modes backwards compatible and only extension of the values is planned, if needed.
streetNameStreet name of the matched Valhalla's edge. Can be empty due to the failed map matching or in the absence of the street name in OSM data.
streetSpeedAssumedSpeed assumed for traveling along the matched Valhalla's edge. Speed is given in meters/second, negative in the absence of data.
streetSpeedLimitSpeed limit for traveling along the matched Valhalla's edge. Speed is given in meters/second, negative in the absence of data.
Timing statistics properties
Timing statistics allows to determine performance of map matching. Statistics is given by average, minimum and maximum call times. Call time is defined as a time elapsed from obtaining GPS position change till receiving and processing the response of map matching algorithm.
trueto enable timing statistics. Statistics will be collected from the moment this property is set to
timingOverallAvrAverage call time for map matching in seconds.
timingOverallMaxMaximal call time for map matching in seconds.
timingOverallMinMinimal call time for map matching in seconds.
To simplify debugging in the absence of GPS signal, one can provide
coordinates by using
testingCoordinate property. For example, as
has been done earlier for Poor Maps by @otsaloma, one can hook changes
in map center QML item to this property. As soon as
testingCoordinate is set, a timer will be started that will update
internal PositionSourceMapMatched with the same period as requested by
updateInterval. To stop such testing, set
See included example for how to use this feature.