README.md
1# QtPBFImagePlugin
2Qt image plugin for displaying Mapbox vector tiles
3
4## Description
5QtPBFImagePlugin is a Qt image plugin that enables applications capable of
6displaying raster MBTiles maps or raster XYZ online maps to also display
7PBF(MVT) vector tiles without (almost, see usage) any application modifications.
8
9Standard Mapbox GL Styles are used for styling the maps. Most relevant style
10features used by [Maputnik](http://editor.openmaptiles.org) are supported.
11The style is loaded from the
12[$AppDataLocation](http://doc.qt.io/qt-5/qstandardpaths.html)/style/style.json
13file on plugin load. If the style uses a sprite, the sprite JSON file must
14be named sprite.json and the sprite image sprite.png and both files must be
15placed in the same directory as the style itself. A default fallback style
16(OSM-Liberty) for OpenMapTiles is part of the plugin.
17
18"Plain" PBF files as well as gzip compressed files (as used in MBTiles) are
19supported by the plugin. The tile size is (since version 2.0 of the plugin) 512px
20to fit the styles and available data (OpenMapTiles, Mapbox tiles).
21
22## Usage
23Due to a major design flaw in the Mapbox vector tiles specification - the zoom
24is not part of the PBF data - the plugin can not be used "as is", but passing
25the zoom level is necessary. This is done by exploiting the optional *format*
26parameter of the QImage constructor or the QImage::fromData() or
27QPixmap::loadFromData() functions. The zoom number is passed as ASCII string
28to the functions:
29```cpp
30QPixmap pm;
31pm.loadFromData(tileData, QString::number(zoom).toLatin1());
32```
33The plugin supports vector scaling using QImageReader's setScaledSize() method,
34so when used like in the following example:
35```cpp
36QImageReader reader(file, QString::number(zoom).toLatin1());
37reader.setScaledSize(QSize(1024, 1024));
38reader.read(&image);
39```
40you will get 1024x1024px tiles with a pixel ratio of 2 (= HiDPI tiles).
41
42## Build
43### Requirements
44* Qt >= 5.4 (5.6 for HiDPI support)
45* Google Protocol Buffers (protobuf-lite)
46* Zlib
47
48### Build steps
49#### Linux
50```shell
51qmake pbfplugin.pro
52make
53```
54#### Windows
55```shell
56qmake PROTOBUF=path/to/protobuf ZLIB=path/to/zlib pbfplugin.pro
57nmake
58```
59#### OS X
60```shell
61qmake PROTOBUF=path/to/protobuf pbfplugin.pro
62make
63```
64
65## Install
66Copy the plugin to the system Qt image plugins path to make it work. You may
67also set the QT_PLUGIN_PATH system variable before starting the application. For
68Linux, there are RPM and DEB [packages](https://build.opensuse.org/project/show/home:tumic:QtPBFImagePlugin)
69for most common distros available on OBS.
70
71## Limitations
72* Only data that is part of the PBF file is displayed. External layers defined in the
73style are ignored.
74* Text PBF features must have a unique id (OpenMapTiles >= v3.7) for the text layout
75algorithm to work properly.
76* Expressions not supported in the styles, only property functions are implemented.
77
78## Changelog
79[Changelog](https://build.opensuse.org/package/view_file/home:tumic:QtPBFImagePlugin/QtPBFImagePlugin/libqt5-qtpbfimageformat.changes)
80
81## Status
82A picture is worth a thousand words. Data and styles from https://openmaptiles.org.
83#### OSM-liberty
84
85
86
87
88
89
90#### Klokantech-basic
91
92
93
94
95
96
97## Applications using QtPBFImagePlugin
98* [GPXSee](https://www.gpxsee.org)
99
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}