Mapchete Process Configuration¶
A Mapchete process configuration (a Mapchete file) is a YAML File which requires a certain schema. Some parameters can be separately defined per zoom level if necessary.
# mandatory parameters
######################
# this is the location of user python code:
process: example_process.py
# alternatively, you can point to a python module:
# process: mapchete.processes.convert
# process pyramid definition
pyramid:
grid: geodetic
metatiling: 4 # can be 1, 2, 4, 8, 16 (default 1)
pixelbuffer: 10
# process input
input:
file1:
zoom>=10: testdata/dummy1.tif
file2: testdata/dummy2.tif
# process output
output:
path: testdata/tmp/example
format: GTiff
dtype: float32
bands: 1
metatiling: 1
# zoom level range:
zoom_levels:
min: 7
max: 11
# or define single zoom level
# zoom_levels: 5
# optional parameters
#####################
# geographical subset:
bounds: [1.0, 2.0, 3.0, 4.0]
# generate overview levels from baselevels
baselevels:
min: 11
max: 11
# free parameters
#################
some_integer_parameter: 12
some_float_parameter: 5.3
some_string_parameter:
zoom<=7: string1
zoom>7: string2
some_bool_parameter: true
Mandatory parameters¶
process¶
Path to python file, relative from the Mapchete file or module path from within python.
pyramid¶
Process pyramid and projection can be defined here. The two default pyramids available
are geodetic
and mercator
metatiling¶
Metatile size used by process. A metatiling setting of 2 combines 2x2 tiles into a bigger metatile. Metatile size can only be one of 1, 2, 4, 8, 16. For more details, go to Tiling and projections.
Example:
# process 8x8 tiles
metatiling: 8
pixelbuffer¶
Buffer around each process tile in pixels. This can prevent artefacts at tile boundaries and is sometimes required when using some algorithms or image filters (e.g. hillshade). Tile buffers of course overlap with their neighbors so it is recommended to keep the buffers as small as possible and the metatiles as large as possible to minimize redundant processed areas.
Example:
# this will result in a tile size of 276x276 px instead of 256x256
pixelbuffer: 10
input¶
see Input Formats
output¶
see Output Formats
zoom_levels¶
A process can also have one or more valid zoom levels. Outside of these zoom levels, it returns empty data.
Example:
# only zooms 0 to 8 are processed
zoom_levels:
min: 0
max: 8
# only zoom 10 to is processed
zoom_levels: 10
Optional parameters¶
bounds¶
Likewise, a process can also be limited to geographical bounds. The bouds are
to be given in the output pyramid CRS and in form of a list and in the form
[left, bottom, right, top]
.
Example:
# only the area between the South Pole and 60°S is processed
bounds: [-180, -90, 180, -60]
baselevels¶
baselevels
are zoom levels which are always freshly processed using the
original input data. Process zoom levels which are outside of the baselevels
range are interpolated from the next zoom level. This is useful when a process
can be run on one or just a few zoom levels and the rest can be interpolated.
The baselevels
setting requires four parameters: min
and max
describe the zoom level range. In lower
and higher
, the resampling
method used to interpolate must be defined.
Example:
# process zoom ranges from 0 to 14
process_minzoom: 0
process_maxzoom: 14
# levels 10, 11 and 12 are processed
# level 9 is interpolated from 10, level 8 from level 9 and so on
# likewise, level 13 is extrapolated from 12 and level 14 from 13
baselevels:
min: 10
max: 12
# for levels 0 to 9 use cubic resampling
lower: cubic
# for levels 13 and 14 use bilinear resampling
higher: bilinear
User defined parameters¶
All other entries used in the Mapchete file are considered user specific and can
be accessed using mp.params
from within the Process class. mp.params
is a dictionary which contains all parameters.
Example:
Mapchete file:
scaling: 2.0
Process file:
def execute(mp):
scaling = mp.params["scaling"] # scaling now has the value 2.0
Zoom level dependent parameters¶
User defined parameters can be adapted for zoom levels. This is usefull if a
process needs different input parameters for different scales (i.e. zoom
levels). mp.params
will always provide a configuration snapshot for the
zoom level of the current tile.
This can be triggered by adding another level to the YAML file using one of the following prefixes:
zoom=
zoom_levelzoom<=
zoom_levelzoom<
zoom_levelzoom>=
zoom_levelzoom>
zoom_level
Example:
Mapchete file:
scaling:
zoom<=8: 2.0
zoom>8: 1.5
Process file:
def execute(mp):
scaling = mp.params["scaling"]
# scaling has the value 2.0 if the current tile is from zoom 8 or
# lower and 1.5 from zoom 9 or higher
This works likewise for input data:
input:
land_polygons:
zoom<=10: land_polygons_simplified.shp
zoom>10: land_polygons.shp
def execute(mp):
with mp.open("land_polygons") as polygons:
p = polygons.read()
# if the current tile zoom is 10 or lower, features from
# land_polygons_simplified.shp are returned, if the tile zoom
# is 11 or higher, features from land_polygons.shp are returned