Seeding
=======

The MapProxy creates all tiles on demand. To improve the performance for commonly
requested views it is possible to pre-generate these tiles. The ``mapproxy-seed`` script does this task.

The tool can seed one or more polygon or BBOX areas for each cached layer.

MapProxy does not seed the image pyramid level by level, but traverses the pyramid depth-first, from bottom to top. This is optimized to work `with` the caches of your operating system and geospatial database, and not against.


mapproxy-seed
-------------

The command line script expects a seed configuration that describes which tiles from which layer should be generated. See `configuration`_ for the format of the file.


Options
^^^^^^^

.. option:: -f <mapproxy.yaml>
  
  The MapProxy configuration to use.
  
.. option:: -c N, --concurrency N
  
  The number of concurrent seed worker. Some parts of the seed tool are CPU intensive
  (image splitting and encoding), use this option to distribute that load across multiple
  CPUs. To limit the concurrent requests to the source WMS see
  :ref:`wms_source_concurrent_requests_label`

.. option:: -n, --dry-run
  
  Run the seed tool without requesting, creating or removing any tiles.



Example::

    mapproxy-seed -f etc/mapproxy.yaml -c 4 etc/seed.yaml


.. _seed_installation_label:


.. note:: You will need aditional dependencies, if you want to use polygons to define your geographical extent of the seeding area, instead of simple bounding boxes. See :doc:`coverage documentation <coverages>`.


Configuration
--------------

The configuration contains two keys: ``views`` and ``seeds``. ``views`` describes
the geographical extents that should be seeded. ``seeds`` links actual layers with
those ``views``.


Seeds
^^^^^

Contains a dictionary with layer/view mapping.::

    seeds:
        cache1:
            views: ['world', 'germany', 'oldb']
        cache2:
            views: ['world', 'germany']
            remove_before:
                time: '2009-04-01T14:45:00'
                # or 
                minutes: 15
                hours: 4
                days: 9
                weeks: 8

`remove_before`:
    If present, recreate tiles if they are older than the date or time delta. At the
    end of the seeding process all tiles that are older will be removed.
    
    You can either define a fixed time or a time delta. The `time` is a ISO-like date
    string (no time-zones, no abbreviations). To define time delta use one or more
    `minutes`, `hours`, `days`, `weeks` entries.

Views
^^^^^

Contains a dictionary with all views. Each view describes a coverage/geographical extent and the levels that should be seeded.

Coverages
*********

There are three different ways to describe the extent of the seed view.

 - a simple rectangular bounding box,
 - a text file with one or more polygons in WKT format,
 - polygons from any data source readable with OGR (e.g. Shapefile, PostGIS)

Read the :doc:`coverage documentation <coverages>` for more information.

Other options
*************

``srs``:
    A list with SRSs. If the layer contains caches for multiple SRS, only the caches
    that match one of the SRS in this list will be seeded.

``res``:
    Seed until this resolution is cached.

or

``level``:
    A number until which this layer is cached, or a tuple with a range of
    levels that should be cached.

Example configuration
^^^^^^^^^^^^^^^^^^^^^

::

  views:
    germany:
      ogr_datasource: 'shps/world_boundaries_m.shp'
      ogr_where: 'CNTRY_NAME = "Germany"'
      ogr_srs: 'EPSG:900913'
      level: [0, 14]
      srs: ['EPSG:900913', 'EPSG:4326']
    switzerland:
      polygons: 'polygons/SZ.txt'
      polygons_srs: EPSG:900913
      level: [0, 14]
      srs: ['EPSG:900913']
    austria:
      bbox: [9.36, 46.33, 17.28, 49.09]
      bbox_srs: EPSG:4326
      level: [0, 14]
      srs: ['EPSG:900913']

  seeds:
    osm:
      views: ['germany', 'switzerland', 'austria']
      remove_before:
        time: '2010-02-20T16:00:00'
    osm_roads:
      views: ['germany']
      remove_before:
        days: 30