Mapnik

Mapnik is a freely-available library for building mapping applications. Mapnik takes geospatial data from a PostGIS database, shapefile, or any other format supported by GDAL/OGR, and turns it into clearly-rendered, good-looking images.

There are a lot of complex issues involved in rendering images well, and Mapnik does a good job of allowing the application developer to control the rendering process. Rules control which features should appear on the map, while "symbolizers" control the visual appearance of these features.

Mapnik allows developers to create XML stylesheets that control the map-creation process. Just as with CSS stylesheets, Mapnik's stylesheets allow you complete control over the way geospatial data is rendered. Alternatively, you can create the various styles by hand.

Mapnik itself is written in C++, though bindings are included that allow access to almost all of the Mapnik functionality via Python. Because these bindings are included in the main code base rather than being added by a third-party developer, support for Python is built right into Mapnik. This makes Python eminently suited to developing Mapnik-based applications.

Mapnik is heavily used by OpenStreetMap (http://openstreetmap.org) and EveryBlock (http://everyblock.com), among others. Since the output of Mapnik is simply an image, it is easy to include Mapnik as part of a web-based application, or you can display the output directly in a window as part of a desktop-based application. Mapnik works equally well on desktop and web platforms.

Installing Mapnik

Mapnik runs on all major operating systems, including MS Windows, Mac OS X, and Linux. The main Mapnik web site can be found at http://mapnik.org.

To install Mapnik onto your computer, follow these instructions:

Once you have installed Mapnik, you can check that your installation is working by opening up the Python shell and typing the following:

import mapnik
print(mapnik.mapnik_version())

The result should be an integer representing Mapnik's version number. For example, 200200 corresponds to Mapnik version 2.2.

If an error occurs, you may need to change your Python settings so that the Mapnik Python bindings can find the underlying Mapnik library. For example, you may need to edit your PYTHONPATH environment variable so that Mapnik can be found.

Understanding Mapnik

When using Mapnik, the main object you are dealing with is called a Map. This diagram shows the parts of a Map object:

When creating a Map object, you tell it:

You then define one or more Layers, which hold the map's contents. Each layer has:

Finally, you define one or more Styles, which tell Mapnik how to draw the various layers. Each Style has a name and of a list of Rules that make up the main part of the style's definition. Each Rule has:

Mapnik implements a number of different types of Symbolizers, including:

When you instantiate a Symbolizer and add it to a style (either directly in code or via an XML stylesheet), you provide a number of parameters that define how the Symbolizer should work. For example, when using a PolygonSymbolizer, you can specify the fill color, the opacity, and a "gamma" value that helps draw adjacent polygons of the same color without the boundary being shown. For example:

p = mapnik.PolygonSymbolizer(mapnik.Color(127, 127, 0))
p.fill_opacity = 0.8
p.gamma = 0.65

If the Rule that uses this Symbolizer matches one or more polygons, those polygons will be drawn using the given color, opacity, and gamma value.

Different rules can, of course, have different Symbolizers as well as different filter values. For example, you might set up rules that draw countries in different colors depending on their population.

Mapnik example code

The following example program displays a simple world map using Mapnik:

import mapnik

symbolizer = mapnik.PolygonSymbolizer(
                        mapnik.Color("darkgreen"))

rule = mapnik.Rule()
rule.symbols.append(symbolizer)

style = mapnik.Style()
style.rules.append(rule)

layer = mapnik.Layer("mapLayer")
layer.datasource = mapnik.Shapefile(
                            file="TM_WORLD_BORDERS-0.3.shp")
layer.styles.append("mapStyle")

map = mapnik.Map(800, 400)
map.background = mapnik.Color("steelblue")
map.append_style("mapStyle", style)
map.layers.append(layer)

map.zoom_all()
mapnik.render_to_file(map, "map.png", "png")

Notice that this program creates a PolygonSymbolizer to display the country polygons, and it then attaches the symbolizer to a Mapnik Rule object. The Rule then becomes part of a Mapnik Style object. We then create a Mapnik Layer object, reading the layer's map data from a shapefile data source. Finally, a Mapnik Map object is created, the layer is attached, and the resulting map is rendered to a PNG-format image file:

Mapnik documentation

Unfortunately, Mapnik's web site makes it difficult to find the online documentation. The Mapnik wiki can be found at https://github.com/mapnik/mapnik/wiki and is an excellent source of useful information.

There is a set of Python-specific documentation for Mapnik available at http://mapnik.org/docs, though unfortunately, this documentation is rather sparse and confusing for Python programmers. Because the Python documentation is derived from the C++ documentation and concentrates on describing how the Python bindings are implemented rather than how an end user would work with Mapnik using Python, there are a lot of technical details that aren't relevant to a Python programmer, and it does not have enough Python-specific descriptions to be all that useful.

The best way to get started with Mapnik is to follow the installation instructions and then work your way through the two supplied tutorials. You can then check out the Learning Mapnik page on the Mapnik wiki (https://github.com/mapnik/mapnik/wiki/LearningMapnik)—the notes on these pages are rather brief and cryptic, but there is useful information here if you're willing to dig.

It is worth looking at the Python API documentation, despite its limitations. The main page lists the various classes available and a number of useful functions, many of which are documented. The classes themselves list the methods and properties (attributes) you can access, and even though many of these lack Python-specific documentation, you can generally guess what they do.