QtPBFImagePlugin/README.md

144 lines
5.8 KiB
Markdown
Raw Permalink 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
2021-07-16 22:23:58 +02:00
features used by [Maputnik](https://maputnik.github.io/editor) 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*
2023-12-11 11:40:18 +01:00
parameter of the QImage constructor or the *QImage::loadFromData()* or
*QPixmap::loadFromData()* functions. The zoom number is passed as ASCII string
2018-10-29 01:04:26 +01:00
to the functions:
```cpp
2023-12-11 11:40:18 +01:00
QImage img;
img.loadFromData(data, QByteArray::number(zoom));
2018-10-29 01:04:26 +01:00
```
2023-12-10 15:53:19 +01:00
For a complete code sample see the [pbf2png](https://github.com/tumic0/pbf2png)
conversion utility.
### HiDPI
2023-12-11 11:40:18 +01:00
The plugin supports vector scaling using QImageReader's *setScaledSize()* method,
2018-11-17 22:09:32 +01:00
so when used like in the following example:
```cpp
2023-12-10 17:46:39 +01:00
QImage img;
2023-12-10 08:18:16 +01:00
QImageReader reader(file, QByteArray::number(zoom));
2019-10-05 18:49:34 +02:00
reader.setScaledSize(QSize(1024, 1024));
2023-12-10 17:46:39 +01:00
reader.read(&img);
2018-11-17 22:09:32 +01:00
```
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
2023-12-10 15:53:19 +01:00
### Overzoom
Since version 3 of the plugin tile overzoom is supported. If you set *format*
to `$zoom;$overzoom`:
2023-12-10 15:16:23 +01:00
```cpp
2023-12-11 11:40:18 +01:00
QImage img;
2023-12-10 17:46:39 +01:00
QByteArray fmt(QByteArray::number(zoom) + ';' + QByteArray::number(overzoom));
2023-12-11 11:40:18 +01:00
img.loadFromData(data, fmt);
2023-12-10 15:16:23 +01:00
```
you will get (512<<overzoom)x(512<<overzoom)px tiles with a pixel ratio of 1.
When overzoom is combined with setScaledSize(), the base size is the overzoomed
tile size.
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, Ordnance Survey, Esri, ...)
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
2024-02-04 19:11:06 +01:00
* Data: [MapTiler](https://github.com/tumic0/GPXSee-maps/blob/master/World/MapTiler-OpenMapTiles.tpl)
2020-04-11 11:27:17 +02:00
* 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)