QtPBFImagePlugin/README.md

94 lines
3.7 KiB
Markdown
Raw Normal View History

2018-10-29 00:07:56 +01:00
# QtPBFImagePlugin
2018-10-29 01:04:26 +01:00
Qt image plugin for displaying Mapbox vector tiles
## Description
QtPBFImagePlugin is a Qt image plugin that enables applications capable of
2019-01-03 01:44:57 +01:00
displaying raster MBTiles maps or raster XYZ online maps to also display
PBF(MVT) vector tiles without (almost, see usage) any application modifications.
2018-10-29 01:04:26 +01:00
2018-11-17 22:09:32 +01:00
Standard Mapbox GL Styles are used for styling the maps. Most relevant style
features used by [Maputnik](http://editor.openmaptiles.org) are supported.
The style is loaded from the
2018-11-01 18:25:45 +01:00
[$AppDataLocation](http://doc.qt.io/qt-5/qstandardpaths.html)/style/style.json
2018-11-22 22:04:07 +01:00
file on plugin load. If the style uses a sprite, the sprite JSON file must
be named sprite.json and the sprite image sprite.png and both files must be
placed in the same directory as the style itself. A default fallback style
(OSM-Liberty) for OpenMapTiles is part of the plugin.
2018-10-29 01:04:26 +01:00
2018-11-28 23:56:07 +01:00
"Plain" PBF files as well as gzip compressed files (as used in MBTiles) are
supported by the plugin.
2018-10-29 01:04:26 +01:00
## Usage
2018-10-29 22:23:41 +01:00
Due to a major design flaw in the Mapbox vector tiles specification - the zoom
is not part of the PBF data - the plugin can not be used "as is", but passing
2018-11-01 23:29:53 +01:00
the zoom level is necessary. This is done by exploiting the optional *format*
2018-10-29 01:04:26 +01:00
parameter of the QImage constructor or the QImage::fromData() or
QPixmap::loadFromData() functions. The zoom number is passed as ASCII string
to the functions:
```cpp
QPixmap pm;
2018-10-29 20:48:46 +01:00
pm.loadFromData(tileData, QString::number(zoom).toLatin1());
2018-10-29 01:04:26 +01:00
```
2018-11-17 22:09:32 +01:00
The plugin supports vector scaling using QImageReader's setScaledSize() method,
so when used like in the following example:
```cpp
QImageReader reader(file, QString::number(zoom).toLatin1());
reader.setScaledSize(QSize(512, 512));
reader.read(&image);
```
you will get 512x512px tiles with a pixel ratio of 2 (= HiDPI tiles).
2018-10-29 01:04:26 +01:00
## Build
2018-11-04 09:13:36 +01:00
### Requirements
2018-12-17 18:36:45 +01:00
* Qt >= 5.4 (5.6 for HiDPI support)
2018-10-29 01:04:26 +01:00
* Google Protocol Buffers (protobuf-lite)
2018-11-01 23:29:53 +01:00
* Zlib
2018-10-29 01:04:26 +01:00
2018-11-04 09:13:36 +01:00
### Build steps
2018-11-04 09:12:36 +01:00
#### Linux
2018-10-29 01:04:26 +01:00
```shell
2018-10-29 01:13:03 +01:00
qmake pbfplugin.pro
2018-10-29 01:04:26 +01:00
make
```
2018-11-04 09:12:36 +01:00
#### Windows
```shell
qmake PROTOBUF=path/to/protobuf ZLIB=path/to/zlib pbfplugin.pro
2018-11-06 01:45:26 +01:00
nmake
2018-11-04 09:12:36 +01:00
```
2018-11-17 22:09:32 +01:00
#### OS X
```shell
qmake PROTOBUF=path/to/protobuf pbfplugin.pro
make
```
2018-10-29 01:04:26 +01:00
## Install
Copy the plugin to the system Qt image plugins path to make it work. You may
2018-12-08 18:44:37 +01:00
also set the QT_PLUGIN_PATH system variable before starting the application. For
Linux, there are RPM and DEB [packages](https://build.opensuse.org/project/show/home:tumic:QtPBFImagePlugin)
for most common distros available on OBS.
2018-10-29 01:04:26 +01:00
## Limitations
2018-12-17 21:59:06 +01:00
* Only data that is part of the PBF file is displayed. External layers defined in the
2018-12-16 17:54:56 +01:00
style are ignored.
* Text PBF features must have a unique id (OpenMapTiles >= v3.7) for the text layout
2018-11-10 14:28:57 +01:00
algorithm to work properly.
2018-10-29 22:15:57 +01:00
## Status
2018-10-29 22:20:31 +01:00
A picture is worth a thousand words. Data and styles from https://openmaptiles.org.
2018-10-29 22:15:57 +01:00
#### OSM-liberty
![osm-liberty 2](https://tumic0.github.io/QtPBFImagePlugin/images/osm-liberty-2.png)
![osm-liberty 5](https://tumic0.github.io/QtPBFImagePlugin/images/osm-liberty-5.png)
2018-11-10 14:28:57 +01:00
![osm-liberty 8](https://tumic0.github.io/QtPBFImagePlugin/images/osm-liberty-8.png)
2018-10-29 22:15:57 +01:00
![osm-liberty 11](https://tumic0.github.io/QtPBFImagePlugin/images/osm-liberty-11.png)
![osm-liberty 14](https://tumic0.github.io/QtPBFImagePlugin/images/osm-liberty-14.png)
#### Klokantech-basic
![klokantech-basic 2](https://tumic0.github.io/QtPBFImagePlugin/images/klokantech-basic-2.png)
![klokantech-basic 4](https://tumic0.github.io/QtPBFImagePlugin/images/klokantech-basic-4.png)
2018-11-10 14:28:57 +01:00
![klokantech-basic 8](https://tumic0.github.io/QtPBFImagePlugin/images/klokantech-basic-8.png)
2018-10-29 22:15:57 +01:00
![klokantech-basic 13](https://tumic0.github.io/QtPBFImagePlugin/images/klokantech-basic-13.png)
![klokantech-basic 14](https://tumic0.github.io/QtPBFImagePlugin/images/klokantech-basic-14.png)
2018-10-29 22:20:31 +01:00
2018-12-09 11:25:27 +01:00
## Applications using QtPBFImagePlugin
2018-12-09 11:22:33 +01:00
* [GPXSee](https://www.gpxsee.org)