Mapnik Stylesheet Generator

General

Each sheet contains a different type of data (for example: areas, lines, points) that has different columns to define what is to be drawn.
Each row within a sheet contains the information required to draw one type of object for a range of zoom levels.

Some information is common to all objects:
	LAYER - The name of the layer which corresponds to one database query and can contain many styles.
	STYLE - The name of the style which corresponds to drawing one group of things for each matching object.
	FILTER - The primary database comparison which limits what is drawn for the style and also is used to minimise the amount selected from the database.  Only keys matching the values in the filter column will be selected from the database.
	SUB-FILTER - An additional filter that can be applied which does not influence the data selected from the database like it does in the 'filter' column.
	MIN_ZOOM - The first zoom level (lowest numbered) that matches this style; additional 'MIN-ZOOM-*' columns are used for extra features.
	MAX-ZOOM - The last zoom level (highest numbered) that matches this style; additional 'MAX-ZOOM-*' columns are used for extra features.

When drawing the objects they are drawn in the following order:
	Sheet order - Shapefiles are drawn before areas which are drawn before lines which are drawn before points.
	Layer order - The first layer on a sheet is drawn completely before the second layer before the third layer ...
	Reverse style order - The first style within a layer is drawn on top of the second on top of the third ... (or you can consider the last style is drawn first, then the second last, ...).
	Line order - Within a style only one line will be drawn for each object, if the first one matches (zoom and filters) then it is drawn, else if the second matches it is drawn, else if the third matches ... ; therefore the most restrictive filter should be placed before the least restrictive filters.

Objects are only drawn for the zoom levels which match the specified range, by using more than one line with the same LAYER, STYLE and FILTER for different zoom ranges the styling of an object can be changed at each zoom level.

In the object definitions in the spreadsheets the database columns must be enclosed in square brackets where they are used (for example: [highway]) and the text values that they are compared against should use single or double quotes (for example: "motorway" or 'motorway').

In the object definitions the additional styles defined by the "*-STYLE" column will override any automatically generated styles (for example: line widths can be fixed not automatically scale in the "lines" sheet).  The styles should be appropriate for the symboliser type and consist of a name, an equals sign and a value; if there are multiple style options then they should be separated by a semi-colon (for example: "stroke-width=1 ; opacity=0.5").

Shapefiles

These are for reading data from a file, generally used for low zoom (to avoid database accesses) or for coastlines.
The columns for the shapefile sheet are the simplest possible to allow implementation of the standard OSM shapefiles.
Each row is implemented as a separate layer so the rules for layer names described above does not apply here.

Areas

These are areas or polygons in the data (for example: landuse, natural, buildings) and they can be filled with a plain colour or a symbol and/or have a line drawn round them and/or have a label placed in them.

There are four sections for each area object drawn in this order (bottom to top as seen in the final image):
	A plain colour fill controlled by the MIN-ZOOM-FILL, MAX-ZOOM-FILL, FILL-COLOUR and FILL-STYLE columns.
	A pattern fill controlled by the MIN-ZOOM-SYMBOL, MAX-ZOOM-SYMBOL and FILL-SYMBOL columns.
	A border around the object controlled by the MIN-ZOOM-LINE, MAX-ZOOM-LINE, LINE-COLOUR and LINE-STYLE columns.
	A label for the area controlled by the MIN-ZOOM-LABEL, MAX-ZOOM-LABEL, LABEL-COLOUR, LABEL-SIZE, LABEL-STYLE and LABEL columns.

A label is only drawn on objects that are "large enough" which is automatically controlled by additional filtering on the 'way_area' database column.  The labels are drawn after the lines so that they are not obscured.

Lines

These are linear objects (for example: highway, railway, boundaries) and they can be drawn with a casing (normally used on roads) and/or an underlay (a solid colour for under a dashed line) and/or a fill colour or pattern, and can optionally have tunnel and/or bridge markings and/or oneway markings and/or one or two labels along them.

There are six sections for each line object which will be drawn in order (bottom to top as seen in the final image):
	A casing controlled by the MIN-ZOOM, MAX-ZOOM, MIN-ZOOM-CASING and CASING-COLOUR columns and with a width controlled by the WIDTH-Z18 column (see below).
		If the line is on a bridge and the zoom is more than MIN-ZOOM-TUNNEL-BRIDGE then the casing colour is changed to BRIDGE-CASING-COLOUR.
		If the line is in a tunnel and the zoom is more than MIN-ZOOM-TUNNEL-BRIDGE then the casing colour is changed to TUNNEL-CASING-COLOUR and drawn as a dashed line.
	A fill controlled by the MIN-ZOOM, MAX-ZOOM, FILL-COLOUR, FILL-STYLE, FILL-PATTERN and WIDTH-Z18 (see below) columns.
		If there is an UNDERLAY-COLOUR then this is drawn before the fill to allow a dashed line to be drawn above it.
		If the line is in a tunnel and the zoom is more than MIN-ZOOM-TUNNEL-BRIDGE then the fill colour is changed to TUNNEL-FILL-COLOUR and drawn as a dashed line.
		If there is a FILL-PATTERN selected then this is used instead of the FILL-COLOUR.
	Direction arrows (using a specific arrow pattern) controlled by the MIN-ZOOM, MAX-ZOOM and MIN-ZOOM-ONEWAY columns.
	A label drawn along the line controlled by the MIN-ZOOM, MAX-ZOOM, MIN-ZOOM-LABEL, LABEL-COLOUR, LABEL-SIZE, LABEL-STYLE and LABEL columns (if SHIELD-SYMBOL is not set).
	A shield drawn on the line controlled by the MIN-ZOOM, MAX-ZOOM, MIN-ZOOM-LABEL, LABEL-COLOUR, LABEL-SIZE, LABEL-STYLE and LABEL columns (if SHIELD-SYMBOL is set).
	A second label drawn on the line controlled by the MIN-ZOOM, MAX-ZOOM, MIN-ZOOM-LABEL2, LABEL2-COLOUR, LABEL2-SIZE, LABEL2-STYLE and LABEL2 columns.

The width of the line fill is set by the value of WIDTH-Z18 when the zoom is 18; for smaller zooms the width halves for each change of 2 in the zoom level and for larger zooms the width doubles for each change of 2 in the zoom level.  The width of the casing is generally 1.5 times the width of the filled section but always between 1 and 3 pixels wider.

Points

These are point objects (for example: barriers, amenities) which are drawn with a symbol and/or one or two labels.

There are three sections for each point:
	A symbol for the object controlled by the MIN-ZOOM-SYMBOL, MAX-ZOOM-SYMBOL and SYMBOL columns.
	A label for the object controlled by the MIN-ZOOM-LABEL, MAX-ZOOM-LABEL, LABEL-COLOUR, LABEL-SIZE, LABEL-STYLE and LABEL columns.
	A second label for the object controlled by the MIN-ZOOM-LABEL2, MAX-ZOOM-LABEL2, LABEL2-COLOUR, LABEL2-SIZE, LABEL2-STYLE and LABEL2 columns.

In addition the same symbol and label(s) can be used for polygons if the POLYGON column specifies this is to happen.  This allows the same map marking for an object (e.g. A shop) that has been marked with a point and one that has been marked with a polygon.

Generating The Stylesheet

The sheets must be exported from the spreadsheet in TAB separated format without quotes to files named after each of the sheet names (for example: shapefiles.txt, areas.txt ...).

The Mapnik stylesheets (one for each zoom level and one containing all information) are generated by running the Perl script called "mapnik.pl".