added reference to RTD & documentation on tiling schemes

README.rst

@@ -4,37 +4,25 @@ Mapchete
 
 Mapchete processes raster and vector geodata.
 
-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_.
+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_.
 
-Mapchete takes care about resampling and reprojecting geodata, applying your Python code to the tiles and writing the output into a WMTS_-like tile pyramid.
+Mapchete takes care about resampling and reprojecting geodata, applying your
+Python code to the tiles and writing the output into a WMTS_-like tile pyramid.
 
 .. _shapely: http://toblerity.org/shapely/
 .. _numpy: http://www.numpy.org/
 .. _WMTS: https://en.wikipedia.org/wiki/Web_Map_Tile_Service
 
--------------
-Documentation
--------------
-
-* Installation_
-* `Command Line Tools`_
-* `Write a Process`_
-* `Special functions`_
-* `Configure a Process`_
-* `Run a Process`_
-* Changelog_
-
-.. _Installation: doc/installation.rst
-.. _`Command Line Tools`: doc/cli.rst
-.. _`Write a Process`: doc/processes.rst
-.. _`Special functions`: doc/common_functions.rst
-.. _`Configure a Process`: doc/configuration.rst
-.. _`Run a Process`: doc/run_process.rst
-.. _Changelog: CHANGELOG.rst
 
--------
-Example
--------
+Enjoy the documentation_ for deeper insights.
+
+.. _documentation: http://mapchete.readthedocs.io/en/latest/index.html
+
+-----
+Usage
+-----
 
 Mapchete is used in many preprocessing steps for the `EOX Maps`_ layers:
 

doc/source/index.rst

@@ -3,15 +3,79 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Mapchete documentation
-======================
+Mapchete: geospatial processing
+===============================
+
+Mapchete processes raster and vector geodata.
+
+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_.
+
+Mapchete takes care about resampling and reprojecting geodata, applying your
+Python code to the tiles and writing the output into a WMTS_-like tile pyramid.
+Details on tiling scheme and available map projections are outlined in
+:doc:`tiling`.
+
+.. _shapely: http://toblerity.org/shapely/
+.. _numpy: http://www.numpy.org/
+.. _WMTS: https://en.wikipedia.org/wiki/Web_Map_Tile_Service
+
+
+Example
+=======
+
+A process creating a hillshade from an elevation model and clipping it with a
+vector dataset could look like this:
+
+.. code-block:: python
+
+    from mapchete import MapcheteProcess
+
+    class Process(MapcheteProcess):
+
+        def __init__(self, **kwargs):
+            MapcheteProcess.__init__(self, **kwargs)
+            self.identifier = "my_process_id",
+            self.title = "My long process title",
+            self.version = "0.1",
+            self.abstract = "short description on what my process does"
+
+        def execute(self):
+            # Open elevation model.
+            with self.open("DEM_file", resampling="cubic_spline") as dem_file:
+                # Skip tile if there is no data available.
+                if dem_file.is_empty(1):
+                    return "empty"
+                dem = dem_file.read(1)
+            # Create hillshade.
+            hillshade = self.hillshade(dem)
+            # Clip with polygons and return result.
+            with self.open("land_polygons") as land_file:
+                return self.clip(hillshade, land_file.read())
+
+
+Examine the result in your browser by serving the process by pointing it to
+``localhost:5000``:
+
+.. code-block:: shell
+
+    mapchete serve my_hillshade.mapchete
+
+If the result looks fine, seed zoom levels 0 to 12:
+
+.. code-block:: shell
+
+    mapchete execute my_hillshade.mapchete --zoom 0 12
+
 
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
 
    installation
    cli
+   tiling
    processes
    common_functions
    configuration

doc/source/tiling.rst

@@ -0,0 +1,60 @@
+Tiling and projections
+======================
+
+This tool was intended to be used to preprocess data like creating hillshades
+which is used for web maps afterwards. Therefore the output projections
+supported are `Web Mercator`_ (``mercator``) and the geodetic projection based
+on WGS84_ (``geodetic``). For the tiles within these projections, a tiling scheme based on the
+WMTS_-tiling is used.
+
+.. _`Web Mercator`: https://epsg.io/3857
+.. _WGS84: https://epsg.io/4326
+.. _WMTS: https://en.wikipedia.org/wiki/Web_Map_Tile_Service
+
+Tile pyramids
+-------------
+
+Every tiling a web framework uses is based on a pyramid of multiple zoom levels
+(tile matrices). Each tile matrix consists of tiles arranged in rows and
+colums.
+
+Every tile within a tile pyramid can be described by three numbers: the zoom
+level, row and column. As these numbers are used in the WMTS protocol, Mapchete
+can easily map them to the desired tiles to be processed.
+
+Most web maps use the ``mercator`` scheme (or pyramid), the second most used
+scheme is the ``geodetic`` scheme which also covers the polar regions but shows
+distortions especially in higher lattitudes which are unfamiliar to most users.
+
+Properties of supported pyramids
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+=============   ============    =================
+property        ``geodetic``    ``mercator``
+=============   ============    =================
+EPSG code       4326            3857
+left            -180            -20037508.3427892
+bottom          90              20037508.3427892
+right           180             20037508.3427892
+top             90              -20037508.3427892
+zoom 0 rows     1               1
+zoom 0 cols     2               1
+=============   ============    =================
+
+If you want to dig deeper into the topic, there is a more detailed description
+on the `ẀMTS Simple`_ profile standard by the OGC.
+
+.. _`ẀMTS Simple`: http://docs.opengeospatial.org/is/13-082r2/13-082r2.html
+
+
+Internally, Mapchete uses tilematrix_, a python tool handling tiles and tile
+pyramids. It is not planned to support other projections or tiling schemes yet,
+but if there is demand and resources, tilematrix would be the starting point.
+
+.. _tilematrix: https://github.com/ungarj/tilematrix
+
+Metatiles
+---------
+
+Depending on the process it sometimes makes sense to increase the tile size.
+This is called metatiling.