Basic job configuration

A job consists of one job configuration file responsible for telling the MapRender basic configurations like the database, which area to render and where to put the rendered tiles.

It does not tell the MapRender how to render but it points to the style XML file containing the rendering directives.

 

Basic configuration layout

The basic configuration layout is fairly simple and structured:

<?xml version='1.0' encoding='UTF-8' ?>

<maprender>
 
    <datasource>
        <db>
            <connection>jdbc:postgresql://192.168.0.20:5432/gis</connection>
            <user>dbUsername</user>
            <password>dbPassword</password>
        </db>
        <fonts>
            <folder>C:\maprender\fonts\osm-fonts\noto-fonts-slim</folder>
        </fonts>
        <symbols>
            <folder>C:\maprender\symbols\osm-symbols</folder>
        </symbols>
    </datasource>

    <bounds>
        <!-- Karlsruhe, coordinate order is: left, top, right, bottom -->
        <boundingbox>8.3166,49.045,8.5144,48.9585</boundingbox>
        <minzoom>1</minzoom>
        <maxzoom>17</maxzoom>
    </bounds>

    <processing>
        <threads>1</threads>
    </processing>

    <jobs>
        <job name="demo">
            <configuration>C:\maprender\configs\osm-styles\style-demo.xml</configuration>
            <output>
                <file folder="C:\maprender\output\tiles\demo"></file>
            </output>
        </job>
    </jobs>

</maprender>

Let’s have a look at the different parts of the configuration…

 

Datasource

The datasource tag contains (like you already have guessed) all the necessary information about where the MapRender can get his required information. In the above example this contains the database connection, a folder containing the required font files and a folder containing the required icons.

<datasource>
    <db>
        <connection>jdbc:postgresql://192.168.0.20:5432/gis</connection>
        <user>dbUsername</user>
        <password>dbPassword</password>
    </db>
    <fonts>
        <folder>C:\maprender\fonts\osm-fonts\noto-fonts-slim</folder>
    </fonts>
    <symbols>
        <folder>C:\maprender\symbols\osm-symbols</folder>
    </symbols>
</datasource>
  1. <db>: Configuration of the database connection, pretty much self-explainatory.
  2. <fonts>: The folder tag must point to a directory containing the required font files in .ttf format. MapRender will load all these font files during startup so that the fonts are available for the TextSymbolizer to use.
  3. <symbols>: The folder tag must point to a directory containing the required icons and symbols. This folder configurations acts as a base directory.
    An example: you have configured the above folder “C:\maprender\symbols\osm-symbols“.
    In the style file you have a PolygonPatternSymbolizer trying to use a texture:
    <PolygonPatternSymbolizer file=”symbols/wetland.png” alignment=”global” />
    The value of the file-attribute is appended to the configured symbols folder. So MapRender will look for the wetland.png file in “C:\maprender\symbols\osm-symbols\symbols\wetland.png”

If you are using custom Symbolizers like the SrtmSymbolizer you have to add additional datasource entries like the <srtm> configuration. These will be explained in the documentation of the corresponding Symbolizer.

 

Bounds

The bounds tag tells MapRender which area to render and what zoom levels to use.

<bounds> 
    <!-- Karlsruhe, coordinate order is: left, top, right, bottom --> 
    <boundingbox>8.3166,49.045,8.5144,48.9585</boundingbox> 
    <minzoom>1</minzoom> 
    <maxzoom>17</maxzoom> 
</bounds>
  1. <boundingbox>: The corrdinates must be given as Lat-Lon coordinates in the order of left, top, right, bottom.
  2. <minzoom>: The minimum zoom level to render. Minimum zoom level means that you look at the map from a higher altitude. Or in other words you have not zoom into the map. Zoom level 1 is basically the whole world seen from space.
  3. <maxzoom>: the maximum zoom level to render. Maximum zoom level means that you look at the map from very close distance. Zoom level 17 is very up close on the level of a single street.
    Be aware that high zoom levels also mean high tiles count. Basically the space required for the map quadrupels for each additional zoom level.

 

Processing

The processing tag gives MapRender additional information on how to work on a job.

<processing> 
    <threads>1</threads> 
</processing>

This tag has several optional configurations which can be used if needed:

  1. <threads>: The number of parallel threads to be used for rendering. Each thread will work on a single tile so in theory more threads mean faster overall rendering speed.
    However this is only true if your computer also has a fitting physical CPU. It does not make sense to use more threads the the CPU has available cores. You have to experiment a little to find the best configuration for optimal performance. Be aware that higher thread counts also increase the amount of used RAM! A quick way to basically freeze your computer is to configure a high number of threads on a single-core CPU.
  2. <debugmeta>: Can be true or false (default). If set to true the tile will contain additional debug information like bounds, rendertime, etc. Only for testing purposes!
  3. <debugtiles>: Can be true or false (default). If set to true the tile will be painted with a border which can be helpfull for testing purposes.
  4. <metrics>: Can be true (default) or false. If set to false no statistic data about tile rendering durations will be logged.
  5. <tilelogmodulo>: Can be set to positive Integer number, default is 1. With this values you can reduce the logging output during rendering. If set to 1 every tile will be logged. If set to another value, for example 1000, only every 1000th tile will be logged.
  6. <exitafter>: Can be set to positive Integer number, default is 0. If set to a value greater than 0 Maprender will exit after having rendered this amount of tiles. For testing purposes only!
  7. <skiprendering>: Can be true or false (default). If set to true the rendering of the tiles will be skipped completely. Might sound a bit strange for a renderer but there are scenarios where you actually don’t want to render but only build up a dbcache file. In these cases performance will be improved by deactivating rendering altogether.
  8. <layers>: Another tag usable for testing. With it you can exclude layers from rendering without messing the the style XML file itself. You have to add the name of the layer to ignore in <skip> tag in the layers tag (see next code block for an example that would prevent the layers admin-low-zoom, admin-mid-zoom and admin-high-zoom from rendering).

A fully configured processing tag might look something like this:

<processing>
    <threads>3</threads>
    <debugmeta>false</debugmeta>
    <debugtiles>false</debugtiles>
    <metrics>true</metrics>
    <tilelogmodulo>1000</tilelogmodulo>
    <exitafter>0</exitafter>
    <skiprendering>false</skiprendering>
    <layers>
        <skip>admin-low-zoom</skip>
        <skip>admin-mid-zoom</skip>
        <skip>admin-high-zoom</skip>
    </layers>
</processing>

 

Jobs

The jobs part of the configuration tells the MapRender which rendering stylesheet to use and into which output formats to render the tiles into.

<jobs> 
    <job name="demo"> 
        <configuration>C:\maprender\configs\osm-styles\style-demo.xml</configuration> 
        <output> 
            <file folder="C:\maprender\output\tiles\demo"></file> 
        </output> 
    </job> 
</jobs>
  1. <job>: you can configure multiple sub-jobs if you want to, however this is not yet throroughly tested and it is recommended to only use one sub-job. The job itself can and should be named. The name you choose is up to you.
  2. <configuration>: This is mandatory and points to the rendering stylesheet XML file also used by other renderers like Mapnik.
  3. <output>: Here you can define what should happen with the rendered tile. Multiple output providers are currently provided.
    The <file> output provider is the most common as it will just save the rendered tile into an image-file inside a slippymap compatible folder structure. The given folder will be the root folder in which the slippymap folder structure will be generated. Learn more about supported outputs in the Output Providers page.