Mapnik 3.0.0 notes for cartographers

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.

Major changes

Clipping

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

• complex;
• 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.

Most polygons follow the right-hand rule, including those produced by https://github.com/openstreetmap/osm2pgsql. If using a different data source and line-offset, this should be checked.

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

(SELECT
    ST_ForceRHR(the_geom) AS the_geom
  FROM foo
  WHERE the_geom && !bbox!) AS p

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.

Harfbuzz support

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.

Character placement

Character placement has been improved, resulting in overall superior kerning. The need for workarounds to get placement right on SVGs has been eliminated.

Rotated point and polygon text

Label collision bounding boxes for point and polygon labels are now per label, not per character. This means when a label is rotated, the bounding box can become substantially larger.

This can substantially reduce label density for point placements when orientation other than a multiple of 90 is used. It does not impact line placements, which is the common case of rotated labels.

New features

Besides these changes, there are lots of other new features which can be found in the changelog

Paul Norman

Consultant and OpenStreetMap Developer