QtPBFImagePlugin/README.md

128 lines
5.3 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.
2020-04-09 22:47:21 +02:00
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
2019-10-05 18:47:39 +02:00
supported by the plugin. The tile size is (since version 2.0 of the plugin) 512px
to fit the styles and available data (OpenMapTiles, Mapbox tiles).
2018-11-28 23:56:07 +01:00
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());
2019-10-05 18:49:34 +02:00
reader.setScaledSize(QSize(1024, 1024));
2018-11-17 22:09:32 +01:00
reader.read(&image);
```
2019-10-05 18:49:34 +02:00
you will get 1024x1024px tiles with a pixel ratio of 2 (= HiDPI tiles).
2018-10-29 01:04:26 +01:00
2020-07-03 01:23:40 +02:00
For a sample code see the [pbf2png](https://github.com/tumic0/pbf2png)
conversion utility.
2020-04-09 22:47:21 +02:00
## Styles
The map style is loaded from the
[$AppDataLocation](http://doc.qt.io/qt-5/qstandardpaths.html)/style/style.json
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
2020-04-10 13:13:20 +02:00
placed in the same directory as the style itself. *A style compatible with the
tiles data schema (Mapbox, OpenMapTiles, Tilezen) must be used.*
2020-04-09 22:47:21 +02:00
For a list of "ready to use" styles see the
[QtPBFImagePlugin-styles](https://github.com/tumic0/QtPBFImagePlugin-styles)
repository.
2018-10-29 01:04:26 +01:00
## Build
2018-11-04 09:13:36 +01:00
### Requirements
* Qt5 >= 5.11 or Qt6
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.
2020-04-09 22:47:21 +02:00
* Expressions are not supported in the styles, only property functions are implemented.
2018-10-29 22:15:57 +01:00
2019-10-05 22:06:37 +02:00
## Changelog
[Changelog](https://build.opensuse.org/package/view_file/home:tumic:QtPBFImagePlugin/QtPBFImagePlugin/libqt5-qtpbfimageformat.changes)
2018-10-29 22:15:57 +01:00
## Status
2020-04-09 23:42:02 +02:00
A picture is worth a thousand words.
2020-04-11 11:27:17 +02:00
#### OpenMapTiles
* Data: [MapTiler](https://github.com/tumic0/GPXSee-maps/blob/master/World/MapTiler.tpl)
* Style: [OSM-liberty](https://github.com/tumic0/QtPBFImagePlugin-styles/blob/master/OpenMapTiles/osm-liberty/style.json)
2018-10-29 22:15:57 +01:00
![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)
2020-04-09 23:42:02 +02:00
![osm-liberty 12](https://tumic0.github.io/QtPBFImagePlugin/images/osm-liberty-12.png)
2018-10-29 22:15:57 +01:00
![osm-liberty 14](https://tumic0.github.io/QtPBFImagePlugin/images/osm-liberty-14.png)
2020-04-09 23:42:02 +02:00
![osm-liberty 15](https://tumic0.github.io/QtPBFImagePlugin/images/osm-liberty-15.png)
2018-10-29 22:15:57 +01:00
2020-04-11 11:27:17 +02:00
#### Mapbox
* Data: [Mapbox](https://github.com/tumic0/GPXSee-maps/blob/master/World/Mapbox.tpl)
* Style: [Bright](https://github.com/tumic0/QtPBFImagePlugin-styles/blob/master/Mapbox/bright/style.json)
2020-04-09 23:42:02 +02:00
![bright 4](https://tumic0.github.io/QtPBFImagePlugin/images/bright-4.png)
![bright 6](https://tumic0.github.io/QtPBFImagePlugin/images/bright-6.png)
2020-04-11 11:49:37 +02:00
![bright 13](https://tumic0.github.io/QtPBFImagePlugin/images/bright-13.png)
![bright 15](https://tumic0.github.io/QtPBFImagePlugin/images/bright-15.png)
![bright 17](https://tumic0.github.io/QtPBFImagePlugin/images/bright-17.png)
#### Tilezen
* Data: [HERE](https://github.com/tumic0/GPXSee-maps/blob/master/World/here-vector.tpl)
* Style: [Apollo-Bright](https://github.com/tumic0/QtPBFImagePlugin-styles/blob/master/Tilezen/apollo-bright/style.json)
![apollo-bright 4](https://tumic0.github.io/QtPBFImagePlugin/images/apollo-bright-4.png)
![apollo-bright 6](https://tumic0.github.io/QtPBFImagePlugin/images/apollo-bright-6.png)
![apollo-bright 12](https://tumic0.github.io/QtPBFImagePlugin/images/apollo-bright-12.png)
![apollo-bright 15](https://tumic0.github.io/QtPBFImagePlugin/images/apollo-bright-15.png)
![apollo-bright 16](https://tumic0.github.io/QtPBFImagePlugin/images/apollo-bright-16.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)