generate-tiles Command

Usage
Performance And Storage Considerations
Web Maps
Tiles Transparency
Uploading Tiles And Tiles Fingerprinting
Using The Tiles
Examples

Generates map tiles which can be used by a web map server. As opposed to generate-mbtiles Command, this command generates each tile as a separate image file on the disk. The tiles are generated using the scheme compatible with OpenLayers and OpenStreetMap.

Usage

generate-tiles [parameters]

All parameters are optional:

bounds: optionally specifies the exact geometry bounds of the area to generate the tiles for. If this parameter is not specified, the current map view bounds will be used (or if geometry bounds are set, these boundaries will be used).
minzoom, maxzoom: the minimum and the maximum zoom level for which tiles should be generated. If not specified, the command will decide on its own.
tilesdir: specifies the root directory of the tile storage. If not specified, Tiles directory will be used. Note that if you specify a relative path, the current directory will be used to determine the resulting path.
resolution: the rate of tile resolution (integer value >= 1; the default value 1 means standard resolution - 256x256 pixels). If you, for example, set it to 2, tiles will have 512x512 pixels, but will cover the same map area - this is useful for generating tiles for Retina displays.
subpixel: a positive integer value that is used as a scaling factor when rendering. The bitmap is then downscaled back to the original width and height, but with improved subpixel accuracy. The default value is 1 (no scaling and thus no subpixel accuracy). Recommended values are 2 or 3, anything larger increases the time and resources needed to generate the bitmap. See Maperitive Beta: Subpixel Accuracy article for more info.
color-depth: the color depth of the generated tiles. Can be either 8 or 32 bits. The default is 32 bits. The lower color depths require less storage, but you loose the quality and transparency. Only works for PNGs and it doesn't work when running Maperitive on Mono.
min-tile-file-size: specifies the minimum file size (in bytes) of a tile. If the tile file is smaller than this limit, it will not be saved on the disk. This allows skipping of empty or sparse tiles. By default no tiles are skipped.
exclude-partial: specifies whether to use exclude tiles which are only partially covered by the generation bounds (these tiles are included by default).
use-fprint: specifies whether to use tile fingerprinting to determine if a tile has changed. Fingerprinting is disabled by default.

The command records a list of generated files. This list can be automatically forwarded to subsequent file commands like ftp-upload Command and zip Command.

Performance And Storage Considerations

Be careful when specifying zoom levels. Each zoom level needs about four times as many tiles as the previous one, so you can very quickly reach pretty large numbers of tiles which can take a very long time to generate and require a lot of disk space.

Let's say we have a map that on zoom level 10 roughly covers the whole computer screen (this would approximately be the area of London and its immediate surroundings). That means about 15 tiles for the zoom level 10. What happens if we want to generate tiles for the whole map up to the zoom level 19?

zoom level 11: 60 tiles
zoom level 12: 240 tiles
zoom level 13: 960 tiles
...
zoom level 17: 245,760 tiles (cca. 80 minutes of work, cca. 10 GB of disk space)
zoom level 18: 983,040 tiles (more than 5 hours of work, cca. 40 GB of disk space)
zoom level 19: 3,932,160 tiles (almost a full day of work, cca. 160 GB of disk space)

NOTE: These numbers are a very rough estimate. When calculating the time needed, an average speed of 50 tiles per second was used, which may vary substantially depending on the map complexity and on the computer hardware performance.

Web Maps

generate-tiles Command uses all the map sources currently registered in the map. This includes web maps (like OSM base map or Osmarender), so if you have one of those, be warned that tiles generation will take a very long time since the generator has to download each tile from the web before it can generate a tile itself. In order not to overload OSM servers, Maperitive limits how fast web tiles can be downloaded.

Tiles Transparency

There are various ways of achieving transparency of map tiles. The most common way is to make the background transparent, while all the other rendered content opaque. This is achieved by setting the MapBackgroundOpacity (TODO) in your rules to a value other than 1 (which represents a fully opaque color), usually by setting the background to be fully transparent:

properties
	...
	map-background-opacity : 0
	...

NOTE: This works only if all of the map sources on the map support transparency. Once you have web maps, for example, map-background-opacity will not be able to keep the background transparent.

The map on the screen will be drawn using a black background (since it is completely transparent) - this is normal behavior.

Uploading Tiles And Tiles Fingerprinting

Once you have generated your tiles, you can use commands like ftp-upload Command and zip Command to upload or copy all the generated tile images to a remote server. The generate-tiles Command records a list of all generated image file names and this list can be automatically forwarded to a subsequent file command. For example:

 generate-tiles
 ftp-upload host=myftp.com user=me pwd=secret remote-dir=uploadplace

will generate tiles and then upload them to the specified FTP server.

If you are maintaining a Web map of a certain area and you want to periodically update the tiles, you probably want to avoid uploading tiles that haven't changed since the last time. In order to achieve this, you can turn on tile fingerprinting:

 generate-tiles use-fprint=true
 ftp-upload host=myftp.com user=me pwd=secret remote-dir=uploadplace

Tile fingerprint is a small file which contains a numerical "fingerprint" of a tile. If fingerprinting is turned on, each tile will have its own corresponding .finger file. When the generate-tiles Command is executed more than once, it compares the fingerprint of the existing tile on the disk with the newly created one. If the two fingerprints are the same, this tells Maperitive that the tile contents have not changed so the tile will not be added to the list of generated files. This means the tile will not be included in the subsequent calls of ftp-upload or zip commands so you will save time and your server bandwidth.

One thing to note is that fingerprint files are not included in the generated file list - they are not needed on the remote server.

Using The Tiles

For more information on how to use these tiles, please visit http://wiki.openstreetmap.org/wiki/OpenLayers_Simple_Example#Extensions.

Examples

generate-tiles

Generates tiles using the default behavior.

generate-tiles minzoom=5 maxzoom=8

Generates tiles from the zoom level 5 up to the zoom level 8.