Qt Location Mapbox GL Plugin

Overview

This geo services plugin allows applications to access Mapbox mapping services using the Qt Location API. The use of these services is governed by the Mapbox terms of service.

This plugin differs from the Mapbox plugin because it uses the Mapbox GL map engine for rendering both raster tiles and vector tiles in real-time. The benefits are: text staying upright, font antialiasing, labels flowing between zoom levels, smooth pan, tilt, rotation and continuous zoom.

The appearance and behavior of vector maps can be customized by creating custom map styles. This can be done with tools like Mapbox Studio.

The Mapbox GL geo services plugin can be loaded by using the plugin key "mapboxgl".

Both Mapbox geo services plugins require an access token to access map styles and tiles hosted by Mapbox. To create a Mapbox account visit https://www.mapbox.com/pricing.

Note: the API for this plugin is introduced in Qt 5.9 as technology preview.

Platform Support

Qt Location Mapbox GL Plugin has the following support for platforms:

Microsoft Windows (win32) - Supported, requires MinGW 5.0+
Linux X11 - Supported, requires GCC 4.9+
macOS - Supported
Android - Supported
Embedded Linux - Supported, requires GCC 4.9+
iOS - Supported
WinRT - Not supported

Parameters

Optional plugin parameters

The following table lists optional parameters that can be passed to the Mapbox plugin.

Parameter	Description
mapboxgl.access_token	Access token provided by Mapbox. The token can also be specified using the environment variable `MAPBOX_ACCESS_TOKEN`, but if also set using a plugin parameter, then this last one will have the precedence over the environment variable. When not set, a development token will be used by default. The development token is subject to the Mapbox Terms of Services and must not be used in production. This property has no effect on styles hosted outside the Mapbox servers.
mapboxgl.api_base_url	Set a custom API base URL. When not set, the URL defaults to https://api.mapbox.com. This parameter is ignored if the the mapboxgl.china property is set.
mapboxgl.china	Use Mapbox China API base URLs and styles. Please notice that Mapbox China requires a specific access token. Contact Mapbox sales for more information.
mapboxgl.mapping.additional_style_urls	Additional, comma separated, Mapbox style URLs to be added to the available style URLs. Additional styles will be prepended to the supportedMapTypes property of the Map item.
mapboxgl.mapping.cache.directory	Absolute path to map tile cache directory used as network disk cache. The default place for the cache is the `QtLocation/mapboxgl` subdirectory in the location returned by QStandardPaths::writableLocation(), called with QStandardPaths::GenericCacheLocation as a parameter. On systems that have no concept of a shared cache, the application-specific QStandardPaths::CacheLocation is used instead. This is an ambient cache, meaning it will get populated on the fly until it reaches the size limit, and when that happens, it will evict the least used tiles. This cache can also be used for storing offline tiles, but the offline database must be populated using the offline tool. The offline database will work alongside with the ambient cache in the same file. Make sure to comply with Mapbox Terms of Service before creating an offline database. Note: The map tile cache file name must be "mapboxgl.db". When using the offline tool, the default output is "offline.db". For using the generated output from the offline tool, you must move that to the proper directory, and rename it as "mapboxgl.db". The offline tool also provides the "--output" parameter for specifying the name of the generated output.
mapboxgl.mapping.cache.memory	Whether or not the cache should be in-memory only. Valid values are true and false. The default value is false. When set to true, the disk cache is never created. The ambient cache will work in-memory, but the offline database cannot be used with this option enabled.
mapboxgl.mapping.cache.size	Cache size for map resources in bytes. The default size of this cache is 50 MiB. Make sure to comply with Mapbox Terms of Service before increasing this value.
mapboxgl.mapping.use_fbo	Sets whether to use a framebuffer object to render Mapbox GL Native. Valid values are true and false. The default value is true. When set to false, the map is rendered issuing OpenGL commands directly, through a QSGRenderNode, to improve the rendering performance. This mode is experimental, and it does not support QQuickItem transformations nor stencil clipping. It might be also produce rendering artifacts e.g. when adding it inside a Flipable item.
mapboxgl.mapping.items.insert_before	Some map items such as MapPolyline, MapPolygon and MapRectangle will be rendered after the topmost layer of the style. With this parameter set, the map items will be rendered before the layer ID specified, unless the layer is not present on the current style, which will fallback to the default behavior. This parameter can be used to display route lines under labels.

Optional map parameters

The Map item using this plugin, can also be customized using MapParameters, allowing runtime changes to the map style and data.

Examples of what can be currently controlled using MapParameter are:

Hide and show parts of the map, like roads and buildings.
Change paint properties like color and opacity of various parts of the map.
Change layout properties like thickness and line joints.
Add data to the map.
Add sprites to the map.

With the exception of extrusion and data driven style properties, every property described at the Mapbox Style Specification can be changed at runtime.

The MapParameters, used to control the style of the map at runtime, always have a type property, followed by user defined properties that try to match the Mapbox Style Specification naming as much as possible, replacing the dash with camel case for technical reasons (i.e. line-cap will be translated to lineCap).

Parameter type	Description
source	A style data source. When using a source of sourceType geojson, the data property can be both inlined or sourced from qrc. Supported source types are: vector, raster, raster-dem, image and geojson. 'geojson'.
layer	Adds a new style layer to the map. On a Mapbox GL map, layers are used in styles for adding styling rules to specific subsets of data. A layer will contain a reference to the data for which they are defining a style. Use the before attribute to insert a layer before an existing layer.
paint	Defines how a layer will be painted. Paint properties can be used for changing the color and opacity of roads in the map or the land color, among other things.
layout	Defines how a layer will be layouted. Layout properties can be used for setting a layer's visibility, and for defining the spacing between dashes in a dashed line, among other things.
image	Adds a sprite to the map to be used by a style layer. This property is required if any style layer uses the properties such as backgroundPattern, fillPattern, linePattern, or iconImage.
filter	A filter selects specific features from a layer. This can be used for adding a layer from a GeoJSON source based on specific parts of the data source, like by using only the points in the GeoJSON.

Example usage

This example adds inline GeoJSON data to the map. Simply adding a source is not enough to get the data visible. It is also necessary to create a layer based on this source. After the layer is added, we also need to style its paint and layout properties. In this case we are changing the line color to blue, and the line width to 8 pixels, as well as also setting round line joints and caps.

 Map {
     plugin: Plugin { name: "mapboxgl" }

     center: QtPositioning.coordinate(60.170448, 24.942046) // Helsinki
     zoomLevel: 12

     MapParameter {
         type: "source"

         property var name: "routeSource"
         property var sourceType: "geojson"
         property var data: '{ "type": "FeatureCollection", "features": \
             [{ "type": "Feature", "properties": {}, "geometry": { \
             "type": "LineString", "coordinates": [[ 24.934938848018646, \
             60.16830257086771 ], [ 24.943315386772156, 60.16227776476442 ]]}}]}'
     }

     MapParameter {
         type: "layer"

         property var name: "route"
         property var layerType: "line"
         property var source: "routeSource"

         // Draw under the first road label layer
         // of the mapbox-streets style.
         property var before: "road-label-small"
     }

     MapParameter {
         type: "paint"

         property var layer: "route"
         property var lineColor: "blue"
         property var lineWidth: 8.0
     }

     MapParameter {
         type: "layout"

         property var layer: "route"
         property var lineJoin: "round"
         property var lineCap: "round"
     }
 }

Note that the order we add the parameters is important, because there is dependency between the parameters. Adding a layer before adding a source will create an invalid layer, same goes for adding a paint property for a layer that doesn't exist.

Paint and layout properties can also be used for styling existing layers of the current style, and not only layers created at runtime. Mapbox Studio can be used for inspecting layers of a given style.

Contents