Online manual of renderd

Manual page

Name

renderd - Rendering daemon for rendering OpenStreetMap tiles.

Synopsis

renderd [ options ]

Description

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.

Options

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

Author

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

This manual page was written by OpenStreetMap authors.

Supplementary information

Control

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 .. 2^zoom-1)
0C	4	Y index of tile (0 .. 2^zoom-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.

Output

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 .. 2^zoom-1)
00C	4	Y index of first metatile (0 .. 2^zoom-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 4^z 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
x = AAAABBBBCCCCDDDDEMMM
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.

Tools

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