Awesome Open Source
Awesome Open Source

======== Mapchete

Tile-based geodata processing.

.. image:: :target:

.. image:: :target:

.. image:: :target:

.. image:: :target: :alt: Documentation Status

.. image:: :target:

Mapchete processes raster and vector geodata in digestable chunks.

Processing larger amounts of data requires chunking the input data into smaller tiles and process them one by one. Python provides a lot of useful packages to process geodata like shapely_ or numpy_. From within your process code you will have access to the geodata in the form of NumPy arrays for raster data or GeoJSON-like feature dictionaries for vector data.

With the help of fiona_ and rasterio_ Mapchete takes care about resampling and reprojecting geodata, applying your Python code to the tiles and writing the output either into a single file or into a directory of files organized in a WMTS_-like tile pyramid. Details on tiling scheme and available map projections are outlined in the tiling documentation_.

.. _shapely: .. _numpy: .. _fiona: .. _rasterio: .. _WMTS: .. _tiling documentation:

.. figure:: :align: center :target:

(standard Web Mercator pyramid used in the web)


You need a .mapchete file for the process configuration. The configuration is based on the YAML syntax.

.. code-block:: yaml

process:  # or a Python module path: mypythonpackage.myprocess
    min: 0
    max: 12
    dem: /path/to/dem.tif
    land_polygons: /path/to/polygon/file.geojson
    format: PNG_hillshade
    path: /output/path
    grid: mercator

# process specific parameters
resampling: cubic_spline

You also need either a .py file or a Python module path where you specify the process itself.

.. code-block:: python

def execute(mp, resampling="nearest"):

    # Open elevation model.
    with"dem") as src:
        # Skip tile if there is no data available or read data into a NumPy array.
        if src.is_empty(1):
            return "empty"
            dem =, resampling=resampling)

    # Create hillshade using a built-in hillshade function.
    hillshade = mp.hillshade(dem)

    # Clip with polygons from vector file and return result.
    with"land_polygons") as land_file:
        return mp.clip(hillshade,

You can then interactively inspect the process output directly on a map in a browser (first, install dependencies by pip install mapchete[serve] go to localhost:5000):

.. code-block:: shell

$ mapchete serve hillshade.mapchete --memory

The serve tool recognizes changes in your process configuration or in the process file. If you edit one of these, just refresh the browser and inspect the changes (note: use the --memory flag to make sure to reprocess each tile and turn off browser caching).

Once you are done with editing, batch process everything using the execute tool.

.. code-block:: shell

$ mapchete execute hillshade.mapchete


There are many more options such as zoom-dependent process parameters, metatiling, tile buffers or interpolating from an existing output of a higher zoom level. For deeper insights, please go to the documentation_.

.. _documentation:

Mapchete is used in many preprocessing steps for the EOX Maps_ layers:

  • Merge multiple DEMs into one global DEM.
  • Create a customized relief shade for the Terrain Layer.
  • Generalize landmasks & coastline from OSM for multiple zoom levels.
  • Extract cloudless pixel for Sentinel-2 cloudless_.

.. _cloudless: .. _EOX Maps:


via PyPi:

.. code-block:: shell

$ pip install mapchete

from source:

.. code-block:: shell

$ git clone [email protected]:ungarj/mapchete.git && cd mapchete
$ pip install .

To make sure Rasterio, Fiona and Shapely are properly built against your local GDAL and GEOS installations, don't install the binaries but build them on your system:

.. code-block:: shell

$ pip install --upgrade rasterio fiona shapely --no-binary :all:

To keep the core dependencies minimal if you install mapchete using pip, some features are only available if you manually install additional dependencies:

.. code-block:: shell

# for contour extraction:
$ pip install mapchete[contours]

# for S3 bucket reading and writing:
$ pip install mapchete[s3]

# for mapchete serve:
$ pip install mapchete[serve]

# for VRT generation:
$ pip install mapchete[vrt]


MIT License

Copyright (c) 2015 - 2020 EOX IT Services_

.. _EOX IT Services:

Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
python (50,901
gis (155
vector (110
raster (31
tile (29
pyramid (24
earth-observation (16

Find Open Source By Browsing 7,000 Topics Across 59 Categories