↑ Online manuals ↑↑ OpenStreetmap Hacker's guide  

Online manual of renderd

Manual -- More

Manual page


renderd - Rendering daemon for rendering OpenStreetMap tiles.


renderd [ options ]


renderd is a rendering daemon for map tiles with the mapnik library. It receives render requests on a socket. renderd queues requests in a number of different queues to manage load while rendering the requests with the mapnik library. By default renderd will start as a daemon. It will log information in the syslog.


This programs follow the usual GNU command line syntax, with long options starting with two dashes (`-'). A summary of options is included below.

-f, --foreground
Run renderd in the foreground for debugging purposes.
-c, --config
Set the location of the config file used to configure the various parameters of renderd, like the mapnik style sheet. The default is /etc/renderd.conf
-s, --slave
Renderd can be used in a distributed fashion accross multiple rendering servers. The master renderd handles queuing and passes requests to the slaves. This parameter specifies which of the slave sections of renderd.conf applies to this instance of renderd. The default is to use the master section
-h, --help
Print out a help text for renderd


renderd was written by Jon Burgess, and other OpenStreetMap project members.

This manual page was written by OpenStreetMap authors.

Supplementary information


renderd is controlled by binary packages sent to a UNIX domain socket, by default /var/run/renderd/renderd.sock. There are currently (2014) three versions of these binary messages, all of which seem to be accepted. The later versions contain additional textual data. They are defined in protocol.h. Status replies from renderd have the same format.

Offset (hex) Size Meaning
00 4 Version number (1, 2 or 3)
04 4 Command / reply
08 4 X index of tile (0 .. 2zoom-1)
0C 4 Y index of tile (0 .. 2zoom-1)
10 4 Zoom level of tile
14 1 or 3 * 41 Text data for versions 2 and 3

The commands / reply codes are the following:

0 1 2 3 4 5 6 7
Ignore Render Dirty Done Not done RenderPrio RenderBulk RenderLow

Reply 4 (not done) serves as an error indicator.


By default renderd generates metatiles, mini-archives of 8 by 8 tiles. The number of tiles per metatile is a compile-time parameter (#define METATILE in render_config.h). Metatile files have the following format: (All multi-byte quantities are host-endian, and have the same size on i386 and x86_64 only because int happens to be 32 bits on both.)

Offset (hex) Size Meaning
000 4 Magic string "META"
004 4 Number of tiles in this metatile (64)
008 4 X index of first metatile (0 .. 2zoom-1)
00C 4 Y index of first metatile (0 .. 2zoom-1)
010 4 Zoom level
014 64 * 2 * 4 Offsets (from start of file) and sizes of tile data for each tile in column-major order
214 Tile data in PNG format at offsets given in header

The individual tiles are in PNG format. (Exception: The metatiles served by the OpenStreetmap tile servers contain tiles in JPEG format, apparently to save network bandwidth.) Tiles seem always to be 256 by 256 pixels in size. (Though there is an entry TILESIZE in renderd.conf, the size seems also to be hardcoded in gen_tile.cpp, at least when using metatiles.) Successive zoom levels differ in scale by a factor 2, so the total number of tiles is 4z at zoom level z. The metatiles are usually stored in a deep directory structure, which is referred to as "directory hashing". Subdirectories correspond to bit fields in the tile coordinates:

<base dir>/<style>/<zoom>/<16*A+a>/<16*B+b>/<16*C+c>/<16*D+d>/<8*(16*E+e)>.meta
y = aaaabbbbccccddddemmm

The index of the tile within the metatile file is 8*M+m. The <style> directory allows generating different map appearances on the same server.


The Perl script osmmetatileinfo.pl outputs metatile header information.

The Perl script unpackmetatile.pl extracts the tiles from a metatile file. By default the x (column) index comes first in the generated files' names, but with the -t option, y is first, so that the normal name sorting order is row-major. That allows to use programs such as montage from GraphicsMagick / ImageMagick to put them together to a larger map image without ordering file arguments manually.

The Perl script osmgettile.pl extracts a tile from a tile cache directory. It detects directory hashing and the number of tiles per metatile automatically. Its usage is:

osmgettile.pl [ -n ] <base directory> <zoom> <x> <y>

The -n option prevents extracting but outputs the metatile file containing the requested tile. <base directory> has to include the map style directory here.

Licensed under the Creative Commons Attribution-Share Alike 4.0 Germany License

TOS / Impressum