Cloud API Server API Style Engine

Advanced options

Options in the optfile

In case you have a large number of arguments to pass to MapTiler Engine, such as many input files (total amount is unlimited for MapTiler Engine or MapTiler Engine Pro), you can prepare a text file with all the arguments and call it with -optfile myarguments.mtp. List of files can be easily created with ls or dir commands.

-optfile [myarguments.mtp]

Any arguments normally passed on the command line could be part of the -optfile text file. MapTiler Engine can combine arguments on the command line with arguments in the text file, such as:

  maptiler-engine -o output_directory --optfile myarguments.mtp

The .mtp extension is acronym for MapTiler Project, which can be used in MapTiler Engine Pro GUI, see our tutorial page.

Temporary directory location

During rendering, MapTiler Engine also writes a substantial amount of data to a temporary directory. Not as much as will be in the output directory, but still. Please make sure there is enough space in the filesystem for it.

By default, the temporary directory will be created in the system default temporary location (/tmp/ on Unix-like systems, or path from the environment variable%TEMP% on Windows-like systems). You can override this with the option:

-work_dir [directory]

The location where to store temporary data during rendering. By default the system temporary directory.

Example:

  maptiler-engine -work_dir /tmp -o /mnt/data/tiles /mnt/maps/*.tif

Setting metadata for the output

It is possible to set certain metadata of the output generated with MapTiler Engine. The option is supported for all available output formats.

-name [string]

Name of the generated map. >= 11.1

-description [string]

Description of the generated map. >= 11.1

-legend [string]

Legend of the generated map. >= 11.1

-attribution [string]

Attribution of the generated map, contains author or data sources. >= 11.1

Resampling methods

The visual quality of the output tiles is also defined by the resampling method. Selected method is used for interpolation of the values of individual pixels and it affects the sharpness vs smoothness of the produced maps.

-resampling near

Nearest neighbor resampling. Rarely makes sense for production data. Can be used for quick testing, since it is much faster than the others.

-resampling bilinear

DEFAULT. Bilinear resampling (2x2 pixel kernel).

-resampling cubic

Cubic convolution approximation (4x4 pixel kernel).

-resampling cubic_spline

Cubic B-Spline Approximation (4x4 pixel kernel).

-resampling average

Average resampling, computes the average of all non-NODATA contributing pixels. (GDAL >= 1.10.0)

-resampling mode

Mode resampling, selects the value which appears most often of all the sampled points. (GDAL >= 1.10.0)

Resampling overviews produced by MapTiler Engine are using the average method, by default. Another possible method is Nearest neighbor.

-overviews_resampling near

Nearest neighbor overviews resampling. Mostly used for elevation maps or similar.

-overviews_resampling average

Average overviews resampling, computes the averate of all non-NODATA contributing pixels.

Defining a custom tiling profile for a specified coordinate system

MapTiler Engine allows defining a custom system of tiles which should be rendered. Such tiling scheme, or in the terminology of OGC WMTS service the TileMatrixSet is for the MapTiler Engine defined with parameters which must follow the tile profile option: -custom. This is global option, need to be specified BEFORE the input filenames

-tiling_srs [definition]

The spatial reference system, e.g. the coordinate system in which the tiles are created. Follows the definitions known from -srs.

-tiling_bbox [minx] [miny] [maxx] [maxy]

The area which should be split into tiles defined in the tiling_srs coordinates.

-tiling_resolution [zoomlevel] [resolution]

Resolution in units of the tiling spatial reference system per pixel on the given zoom level. MapTiler Engine will automatically compute values for all other zoom levels, each having half the resolution of the previous one.

-tiling_resolution from_output

Resolution is calculated so as to fit whole input mapset into one tile on zoom level 0 with respect to bbox, srs, and tile size.

-tiling_resolution from_input

The default behavior if the resolution is not specified. Resolution is calculated so as to not supersample the largest input map with respect to bbox, srs and tile size.

-tile_size [width] [height]

The pixel dimensions of one tile.

-tiling_centered

Tile (0, 0) is in the center of the world.

Tiling scheme - naming of tiles

MapTiler Engine uses Google XYZ naming of tiles, by default. It supports also the OSGEO TMS naming (with flipped Y axis), QuadKey naming (known by Microsoft Bing Maps), and ZYX naming (known by Microsoft Bing Maps). These tiling schemes are supported only for tile store in the directory (-store dir). This is global option, need to be specified BEFORE the input filenames.

-xyz or -zxy

Google XYZ (top-left origin) naming of tiles. Folder path as output_directory/{z}/{x}/{y}.{ext}.

-tms

OSGEO TMS (bottom-left origin), flipped Y axis as oppose to Google XYZ. This tiling scheme is defined as a standard for MBTiles.

-quadkey

Microsoft Bing QuadKey (top-left origin). MapTiler Engine generates files named as quadkey separated into directories named as zoom level (output_directory/{z}/{quadkey}.{ext}). Details at this microsoft website.

-zyx

Microsoft Bing ZYX (top-left origin) naming of tiles. Folder path as output_directory/{z}/{y}/{x}.{ext}.

Choose bands from multiple channels for RGBA color model

MapTiler Engine allows to choose bands for RGB(A) color model from multiple map channels. The example is aerial images such as Sentinel 2 sources, which contains multiple spectral bands (channels) with different bandwidth, like Near Infra-Red, vegetation, cloud detection, etc. Only three classical bands are used for rendering via MapTiler Engine - RGB, Red Green and Blue bands, to construct True Color Images. This is file options, need to be specified AFTER the name of the input file.

-b [red] -b [green] -b [blue] -b [alpha]

Select an input band for the processing color model RGBA. The last part -b [alpha] is optional to select Alpha channel. Bands are numbered from 1. This allows to reorder source bands. >= 11.1

Example for Sentinel 2 image, where RGB bands are 4th, 3rd and 2nd, respectively for Red Green Blue colors:

  maptiler-engine -o tiles sentinel2-image.multiband.tif -b 4 -b 3 -b 2

Example for generating red-only (1st band) image with alpha channel (4th band):

  maptiler-engine -o red-tiles image.tif -b 1 -b 1 -b 1 -b 4
-band_desc [string]

Select an input band for the processing color model RGBA by the band description. The [string] parameter can be a substring of the full band description string. Usage is the same as for the -b command. >= 11.1

Define band data scale

It is possible to set the data scale for each of the color bands in the output generated with MapTiler Engine.

-data_scale [min] [max]

Set data scale range for a band. The min parameter is optional. If omitted, the value will be set to 0. If the command is given only once, the same values will be set for all bands. To set different values for separate bands, the command has to be given 3 times (4 in case the alpha channel is used). >= 11.1

Example for setting all bands to range 0 - 400:

  maptiler-engine -o scaled-bands image.tif -data_scale 400

Example for setting different values for RGBA bands:

  maptiler-engine -o scaled-bands image.tif -data_scale 100 -data_scale 200 -data_scale 300 -data_scale 400

Interrupt and resume long-time rendering

The long-time rendering job can be interrupted by the end-user or a system failure (power-failure, no free space on the disk). MapTiler Engine supports only simple resume mode - render process can be continued on the same computer with the same options.

-keep_unfinished

To prevent deleting the existing output tiles and temporary files created by the application.

-resume

To continue in the unfinished or interrupted rendering process. Requires the same arguments on the same computer. It skips encoding of the existing tiles. This option can be used also for the startup of the rendering process, it will automatically keep unfinished tiles.

Advanced warping arguments

The advanced warping algorithms parameters can be specified with the option:

-wo “NAME=VALUE”

The warp options. See the papszWarpOptions field at GDAL.

Example:

  maptiler-engine -o tiles -wo "SAMPLE_GRID=YES" t.tif -wo "SOURCE_EXTRA=16"

Watch progress in a frontend

MapTiler Engine can produce progress easily parsed in a frontend application. Simply use the first argument -progress and application output the progress on the standard output in the TSV (tabulator separated values) format: Stage TAB Percentage TAB Iteration TAB Total

Example:

  maptiler-engine -progress -o tiles map1.tif map2.tif map3.tif

  Opening    16 %    1    6
  Opening    33 %    2    6
  Opening    50 %    3    6
  Opening    66 %    4    6
  Opening    83 %    5    6
  Opening   100 %    6    6
  Warping     0 %    0    4
  Warping    25 %    1    4
  Warping    50 %    2    4
  Warping    75 %    3    4
  Warping   100 %    4    4
  Rendering   0 %    0    512
  ...
  Rendering   100 %    512    512

Usage on a computer cluster

MapTiler Engine can run on an MPI cluster if a cluster-specific binary has been requested. If you have the MPI version, a shell wrapper to run it on a cluster is delivered as well.

A version of MapTiler Engine utilizing Map Reduce approach and Hadoop is under development, this will replace the older MPI.

More details are available on MapTiler Cluster page.

Toptile options for cluster processing

With MapTiler Engine it is possible to limit tiles generation to a specified tile subpyramid, what can dramatically reduce the rendering time in case only a part of the input is needed to be rendered. The coordinates of the required toptile need to be passed in z/x/y format to the following command. It is also possible (but not required for the subpyramid to generate) to specify a custom location in format of path/to/file.tif, where the toptile file will be saved as a watermark-free image. >= 12.1

Example

maptiler-engine -o tiles -cluster_job 12/770/1607 -cluster_toptile toptile/toptile_image.tif ~/home/maps/high-res-map.tif

Vector inputs

MapTiler Engine v10.0 and higher version supports rendering of Vector inputs into MVT (Vector tile) format. Vector rendering support requires an underlying GDAL library version 2.3.0 or higher, which is limited on the native Linux distribution. Using a docker image with MapTiler Engine is recommended way for vector rendering on Linux OS. MapTiler Engine offers GUI for Vector layers with a practical sample how-to article.

Vector input consist of one or more layers, which are rendered into the specific target layer in MVT format. Each feature of the source layer contains key=value attributes, that could be processed or renamed into the final attributes of the target layer. The following arguments are supported for the Vector input: -srs, -zoom, and -bbox, as they are described above. Other arguments are not respected for Vector rendering yet.

-layer [src_name]

Select the source layer for the further processing of the vector input by the name. This argument is required for the arguments below.

-target [name]

Select (or create a new) target layer in the final tiles of MVT format. This is the name of the layer, which could be styled. This argument may be repeated more times to process features into a separate target layer with a different list of fields.

-field [output_name] [src_name]

Set the attribute field with the name src_name from the source_layer to be presented in the final target layer as a attribute key output_name. The attribute value for each features from source layer is copied. This argument may be repeated more times to copy more attributes.

-vector_tile_size [size]

Set the output vector tile size in pixels. >= 11.1

-vector_compress

Use compression of the output vector tiles. >= 11.1

-vector_no_compress

Do not use compression of the output vector tiles. >= 11.1

Let assume, we have one Vector input with two source layers: lines and polygons. The source layer lines consists of the streets with these attributes keys Name, Identifier and Main. The source layer polygons contains geometry of some buildings with attributes keys Ident, Num and Name. We do want to create two target layers with renamed attributes.

Example

  maptiler-engine -o mymap.mbtiles \
  input.shp \
  -layer lines \
    -target streets \
    -field id Identifier \
    -field name Name \
    -field is_main Main \
  -layer polygons \
    -target buildings \
    -field id Ident \
    -field name Name \
    -field number Num

The example above creates two new output layers: streets with attributes keys id, name, and is_main; and buildings layer with attributes keys id, name, and number.