Available output options

The default behaviour of MapTiler Engine is to write tiles each into its own file, under the directory structure:

output_directory/z/x/y.ext

Where z is the zoom level, and x and y tile coordinates on relevant zoom level in the tiling profile.

The produced directory structure contains also a simple HTML viewer and description of the dataset in metadata.json, compatible with mb-util and MapTiler Server project.

MapTiler Engine supports direct output of the rendered map tiles into an SQLite database (MBTiles or GeoPackage format). This simplifies transfer and management of the tilesets and is practical for mobile applications.


Tiling profile / Tile Matrix Set

A global option defining the output system of tiles - the target coordinate system, tile pixel size, etc. MapTiler Engine comes with these predefined most popular systems and possibility to specify a custom profile.

-mercator

DEFAULT. The spherical Mercator tile profile compatible with Google, Bing, Yahoo Maps, MapQuest, OpenStreetMap, and mobile maps on iOS and Android. This is the most commonly used profile. It uses coordinate system defined as EPSG:3857 or EPSG:900913. Details available here.

In case you wish to use different tiling system, you must specify it as the first command on the command line. These are the alternatives:

-gearth

Tile profile specific for Google Earth according to the KML SuperOverlay definition.

-raster

Rendering raster files without a need of georeferencing is also possible.

-garmin

To produce the format for Garmin GPS devices, with a size 1024x1024 pixels and output to .kml file. Afterwards, pack the tiles and the .kml tiles into a .zip archive, change its extension to .kmz and save it into the device.

-custom

You can specify your own tiling system. See the appropriate section under the Advanced options chapter for more information.

Example: command for producing tiles for use with Google Earth:

  maptiler-engine -gearth -o tiles map.tif

Example: command for producing tiles for use with Geodetic WGS84 Plate Caree:

  maptiler-engine -raster -o raster-tiles map.tif

Custom tiling presets

MapTiler Engine offers predefined custom tiling presets (custom tile grids) for Advanced customers. Each custom tiling preset has its own area coverage, some are for World, other covers only specifical States or group of States.

-preset geodetic

WGS84 Plate Caree / Unprojected. Compatible with most existing WMS servers, OpenLayers base map.

Example:

  maptiler-engine -preset geodetic -o wgs84-tiles map.tif
-preset standard_grid

Standard global tilegrid with a selected Coordinate system. This tiling preset keeps the original coordinate system (SRS), and cuts the input map into tiles according to the spherical mercator tile profile. Note this is not compatible with Google Mercator profile mercator!

Example:

  maptiler-engine -preset standard_grid -o st-grid-tiles map.tif
-preset baidu

Tilegrid defined for China customers. This preset cover only China region and is compatible with Baidu Maps service.

Example:

  maptiler-engine -preset baidu -o tiles map-china.tif
-preset yandex

Custom tiling preset used in Russian web mapping service, compatible with Yandex.Maps. Coverage is limitted to Russia and Ukraine.

Example:

  maptiler-engine -preset yandex -o tiles map-russia.tif
-preset cz_jtsk

National tiling grid for Czechia and Slovakia with a precision up to 1 meter per pixel.

Example:

  maptiler-engine -preset cz_jtsk -o cz-tiles map-czechia.tif
-preset fr_rgf93

Tilegrid defined for precise overlay of maps in France, using Lambert 93 conic projection.

Example:

  maptiler-engine -preset fr_rgf93 -o fr-tiles map-france.tif
-preset nl_rdnew

National tiling grid for Netherlands - Rijksdriehoekstelsel New / Amersfoort.

Example:

  maptiler-engine -preset nl_rdnew -o netherlands-map map-amsterdam.tif
-preset uk_osgb [zoom_group]

National tiling grid for the United Kingdom using Ordnance Survey projection. This custom preset requires a specific zoom_group, which limits output zoom levels of this grid. Supported values with zoom levels in the bracket are: 0 (z0), 1 (z1 - z2), 2 (z3 - z6), 3 (z7 - z8), 4 (z9 - z10).

Example:

  maptiler-engine -preset uk_osgb 1 -o gb-z1 map-london.tif -zoom 1 2
  maptiler-engine -preset uk_osgb 2 -o gb-z3 map-london.tif -zoom 3 6
-preset ch_lv03 [zoom_group]

Swiss national tiling grid used in Switzerland and Liechtenstein with high precision. This custom preset requires a specific zoom group, with values from 0 to 21. These values are mostly represented for the specific zoom level. Output tiles could be combined and are compatible with SwissTopo maps.

Example:

  maptiler-engine -preset ch_lv03 3 -o ch-z3 map-zurich.tif -zoom 3 3
  maptiler-engine -preset ch_lv03 4 -o ch-z4 map-zurich.tif -zoom 4 4

Note that, -zoom 3 3 is not required and it is automatically limited as defined for this zoom group.

-preset nz_nztm [zoom_group]

New Zealand Geodetic Datum (NZGD2000), official geodetic datum for New Zealand and its offshore islands. This custom preset requires a specific zoom group, which limits output zoom levels of this grid. Supported values with zoom levels in the bracket are: 0 (z0-z7), 1 (z8-z10), 2 (z11-z13), 3 (z14-z16).

Example:

  maptiler-engine -preset nz_nztm 1 -o nz-z8 map-new-zealand.tif

Retina / HiDPI tiles

-scale [value]

To create high-resolution Retina / HiDPI tiles with variable floating scale. Retina tiles are available for each profile and custom tiling presets listed above. Important note, the scale value cannot exceeded max allowed tile size in pixels: 4096 x 4096. It means, max available value for -scale is 16.0.

Example: the command for producing standard Retina tiles in Mercator profile

  maptiler-engine -mercator -scale 2.0 -o tiles@2x map.tif

Example: the command for producing Retina tiles at 1.5 scale in raster profile

  maptiler-engine -raster -scale 1.5 -o tiles-retina map.tif

Zoom levels

-zoom [min] [max]

This option determines which layers of the tile pyramid will be generated. The default is the “native” level calculated from image resolution. In case you need to add additional zoom levels, you can either define them as absolute numeric values or as relative numbers to the “native” levels with prefix + and -. Each input file can have its own explicit option for zoom levels.

Example: zoom levels are automatically calculated as eg. 1 - 5

  maptiler-engine -o tiles map.tif

Example: zoom levels are explicitly set to be 3 - 5

  maptiler-engine -o tiles map.tif -zoom 3 5

Example: zoom levels are set to be 1 - 6 with relative value to native zoom levels

  maptiler-engine -o tiles map.tif -zoom +0 +1

Example: zoom levels are set to be 2 - 4 with relative value to native zoom levels

  maptiler-engine -o tiles map.tif -zoom +1 -1

Example: zoom levels are set to 0 - 4, as explicit minimum, relative maximum to native zoom level

  maptiler-engine -o tiles map.tif -zoom 0 -1

Tile formats

The produced tiles can be saved in one of several image format. MapTiler Engine includes optimization of the final filesize and used a number of colors (quantization), to minimize the disk size occupied by the rendered maps as well as the time necessary to transfer the maps to clients once the tiles are online.

Formats with support for transparency

-f png8a

DEFAULT. Paletted RGBA PNG image optimized for rendering speed and output size

-f png8qa

Paletted RGBA PNG image

-f png or -f png32

RGBA PNG image

-f webp or -f webp32

RGBA WebP image

Non-transparent formats

-f jpg or -f jpeg

Progressive JPEG image in the YCbCr color space

-f png8

Paletted RGB PNG image optimized for rendering speed and output size

-f png8q

Paletted RGB PNG image

-f png24

RGB PNG image

-f webp24

RGB WebP image


Tile transparency or a background color

No matter what input datasets you specify, after transforming them into the tiling profile projection, MapTiler Engine will handle them as RGBA images. The transparency can come from the image itself as an alpha channel (with support for partly transparent areas), it can be derived from a selected color (so-called NODATA color), or can be just a result of the transformation with the GDAL warping algorithm - for areas without available input data.

If the tile is completely transparent it is never saved to the disk to save the storage space.

If all of the pixels are fully visible (eg. opaque, maximum alpha is 255), the alpha channel is discarded and the tile is marked as non-transparent / opaque. Otherwise, the tile is marked as partly transparent with alpha.

If partly transparent tiles are saved in a tile format without support for transparency (such as JPEG specified with -f jpg option) then the background color is applied. Default background color is white (255,255,255), but you can specify your own with the option:

-bg [r] [g] [b]

The color of the background replacing transparency in the non-transparent tile formats.

For example:

  maptiler-engine -f png8 -bg 0 128 0 ...
-ignore_alpha

If your dataset contains four channels, but the fourth channel is not alpha channel, you can use this option to ignore this channel.

For example:

  maptiler-engine -f png32 -ignore_alpha input_4bands.tif ...

Tile store format

-store dir|mbtiles|geopackage

This option enforces the form of storage which is used for saving the rendered tiles. Possible options are the directory (dir), the MBTiles (mbtiles) and the GeoPackage (geopackage). The default is the directory, but in case the -o parameter ends with .mbtiles or .gpkg then rendering into MBTiles or GeoPackage is selected, respectively. This option specifies the store form explicitly. Note: for more details on this subject read the section Output in the chapter Usage above.

-sparse

Skip the empty space between separate maps and don’t create empty tiles. This option can improve the speed of rendering if there are huge areas between maps. This is the default option for -store dir.

-no_sparse

Fills the empty space between separate maps (if there is some) with empty tiles in the background colour. This option can take longer to render and take more disk space, if there are huge areas between maps, as these have to be created. This is a default option for -store mbtiles and -store geopackage.

Setting the sparse option in GUI is in Advanced options dialog.


MBTiles compatibility for GeoPackage

MapTiler Engine provides a toggle to make the generated GeoPackage conform to the MBTiles specification. The options to control it are:

-mbtiles_compatible

DEFAULT. The generated GeoPackage will be MBTiles-compatible. >= 11.2

-no_mbtiles_compatible

MBTiles compatibility turned off. >= 11.2

As providing compliance with the MBTiles specification requires creating additional structures in the output GeoPackage file, its size will be slightly larger than that of the one generated without MBTiles compatibility.


Hybrid tile format

MapTiler Engine allows rendering into a hybrid tile format which allows transparent tiles using transparent format (such as PNG) and tiles without any transparency at all are saved in a different format (such as JPEG). For aerial photos overlays or other datasets, this can mean a significant saving of the storage. Generated files are without extensions. This is done to simplify the generated OpenLayers viewer.

Example of usage:

  maptiler-engine -f hybrid <opaque> <transparent> ...
  maptiler-engine -f hybrid jpg png8a ...

Tile quality

There are some options to specify parameters of the conversion into image formats, which can significantly reduce the size of produced tiles by degrading the output.

-jpg_quality [value]

The quality of JPEG compression. A number between 10 and 95. The default is 85.

-quant_quality [value]

The quality of quantization. A number between 1 and 100. The default is 100.

-quant_speed [value]

Higher speed levels disable expensive algorithms and reduce quantization precision. Speed 1 gives marginally better quality at significant CPU cost. Speed 10 has usually 5% lower quality but is 8 times faster than speed 8. The default is 10. If you experience issues with the visual quality of generated tiles with quantization involved try to set -quant_speed to lower values.

-webp_quality [value]

The quality of WebP compression. A number between 1 and 100. Level 100 means lossless compression. The default is 75.

-webp_alpha_quality [value]

The quality of WebP alpha channel compression. A number between 1 and 100. Level 100 means lossless compression. The default is 100.

-webp_lossless

Lossless WebP compression switch. >= 11.1

-webp_lossy

Lossy WebP compression switch. >= 11.1

-webp_preset [default|picture|photo|drawing|icon|text]

WebP compression presets that use optimal algorithm parameters for a given data type. >= 11.1

Example of the rendering of a seamless map out of file map1.tif and map2.tif into tiles with an internal palette with optimal colors with higher visual:

  maptiler-engine -o tiles -f png8a -quant_quality 90 -quant_speed 4 map1.tif map2.tif

Watermark

-watermark [image_file.png]

It is possible to place your own watermark over rendered tiles to protect the online maps. The file should be smaller than a size of tiles. It is placed in a random position and burned into tiles.

A nice watermark file can be easily generated online by calling the Google Chart API: http://chart.apis.google.com/chart?chst=d_text_outline&chld=FFFFFF|11|h|000000|b|%C2%A9%20ABC

By replacing ABC at the end of this URL a custom text phrase can be specified. We recommend setting the transparency of such watermark file by using a Photoshop or similar tool before applying it with MapTiler Engine.

-watermark_opacity [value]

Set the opacity percentage that will be applied to the watermark image. Use the integer number in range from 1 (almost transparent) to 100 (fully visible). When applying the opacity to the image that is already opaque, these opacities will be combined. The default value is 100. >= 12.1

Example of applying the watermark image with 70% opacity:

  maptiler-engine -o tiles -watermark watermark_image.png -watermark_opacity 70 map.tif