All the previous posts where rather
technical so I would like to talk about applications and show some beautiful
images in this post.
First of all: If you live in a region where names are spelled using only
characters from the ASCII set you will not notice this work very much.
It was one design goal not to change the behavior for texts that are already
correctly rendered. There are some minor differences but nothing big. However
it is still worth to read on as I added many more cool features.
Rendering complex scripts
Mapnik can render any script supported by HarfBuzz now. If something is
rendered incorrectly check if the font supports the characters you want
to use, as this is the most likely cause of any problems. Especially do not use
Unifont! It doesn’t support any of the features required for correct rendering
of most complex scripts.
I don’t publish example images here because I can’t judge which images would
show the most improvement. If a native speaker wants to add samples where
text that was broken before is really good now please open an
issue on Github.com and
I will publish it here.
There are some new features and bug fixes not related to complex scripts
Improved line placements
Since a long time Mapnik is able to handle line breaks in the text (either
automatically created or supplied in the input data) but this feature never
worked for line placements. You could render a long town name very well, but
long street names were a problem so far. This situation is improved by
enabling this for line placements as well.
However there is one important
limitation: You have to set wrap-width to a certain value or provide input text
with line break characters (‘\n’). There is no function to automatically select
the right wrap-width value depending on the line length yet. Automatic hyphenation
of long text is also not available yet. This will be implemented at some later
Mapnik already supported offsetting text on lines, but the algorithm was very
simple and only worked well for almost straight lines.
The new code uses the offset converter class to produce real offsets which
works for every line shape.
This feature can be used to produce labels for e.g. borders.
For certain applications it is desirable to have a fixed orientation of the
text with respect to the line direction. In the “offsets” example above you
might have noticed that “Country 2” changes the text direction at one point
in order to keep it upright.
This is useful behavior in most cases, but there are applications (like contour
lines) where you don’t want to switch the direction. Therefore a new
parameter “upright” was added to TextSymbolizer to choose the desired function.
Mapnik supports rotating text via the orientation parameter to TextSymbolizer.
As long as the text is centered on the point being labeled the question which
center to use for rotation is trivial. But once the text is moved from this
position there are different possible points.
Up to now Mapnik always rotated around the label’s center but now one can also
select to include the displacement when rotating text. This feature is best
described by the following two images:
Rotate displacement: Off (default)
Rotate displacement: On
Kerning & Ligatures
two features you probably won’t notice if you don’t
know about them. But they improve the text rending in subtle ways:
Kerning reduces the spacing between characters when one of them is top-heavy and
the other one is bottom-heavy.
A ligature is the combination of two or more characters into a single glyph for
improved visual appearance.
This feature is always enabled.
ShieldSymbolizer syntax was
and updated to reflect actual behavior. However it was noticed that the current
syntax is rather counter-intuitive so a new, better one was defined.
Previously “shield-dx” moved shield and text and “dx” moved text only. This was
reversed so that “shield-dx” moves the shield only.
For “dx” (and “dy”) the behavior depends on the value of “unlock-image” (which had
an undefined function before).
unlock-image=”false”: dx moves text and image
unlock-image=”true”: dx moves text only
This parameter is especially useful with the alternate positions functions
Label position tolerance
Mapnik moves labels a bit when there is a collision at the designated place,
however this feature only worked for TextSymbolizer but not for ShieldSymbolizer.
This is fixed now.
This feature can be used for better labeling of highways with multiple names.
or automatically enabled for Symbolizers with non-zero spacing:
ShieldSymbolizer was extended to support the alternate placements mechanism already
implemented in TextSymbolizer. This feature is similar to the one above, but has
different uses. It doesn’t simply move the shield along the way, but allows
to set completely different parameters. You can change the font, offset,
position, etc. (Selecting a different shield image or shield-offset is not supported, yet but will
be in the future. You can use dx and dy in combination with unlock-image to
get the desired effect in most cases.)
Labeling multiple bus routes at the same bus stop:
This syntax is not optimal but an placement algorithm supporting grid placements
will be added some time.