With the Mapnik 3.0.0 release there have been important changes that impact cartographers. It is possible to write a stylesheet that works with both 2.2 and 3.0, but it some attention to the changes.
The clip property now defaults to false. This fixes many problems with cut-off labels when rendering map tiles, but can require special considerations of performance in some cases.
When features are likely to be
often mostly or entirely off-screen, while still bounding box overlapping the rendered area; and
using slow rendering rules
Don’t assume that turning clip on will result in performance gains. In some cases it is faster to not clip.
Clip should not generally be turned off for features being labeled or lines with a dasharray.
Lines labeled with infrequent labels may need text-spacing adjusted.
Line offset from polygons
line-offset on polygons no longer depends on winding order of the polygon. For polygons following the right-hand rule, the behavior has not changed. For polygons following the left-hand rule, the stylesheet will need to have line-offset properties multiplied by -1.
For PostGIS datasources with polygons that follow the left-hand rule instead, if compatibility is needed between 2.2 and 3.0, this can be achieved with SQL like
The existing line-offset in the stylesheet will need to be inverted.
Offsetting from lines
Direction of all offsets from lines is inverted. These properties have to be changed to achieve compatibility between 2.2 and 3.0:
TextSymbolizer with line placement
swap top and bottom values in vertical-alignment
multiple dy by -1
Take care of vertical-alignment and dy in Layout and Placement nodes.
LineSymbolizer, LinePatternSymbolizer, MarkersSymbolizer with line placement
multiple offset by -1
Special attention should be taken to TextSymbolizer when dy is not zero and vertical-alignment is not set. In such situation vertical-alignment="middle" needs to be set to get consistent behavior between 2.2 and 3.0.
Mapnik now uses harfbuzz for text layout. This offers far superior support for complex scripts, particularly some southeast Asian languages. Generally this requires no changes on the part of the cartographer, but should be tested as part of any 3.0 upgrade plan.
Where maps have only Latin text and do not need shaping, kerning, or ligatures, harfbuzz can be disabled by setting export HB_SHAPER_LIST=fallback, resulting in up to 15% performance gains in text rendering.