It is easy to use a shapefile as a Mapnik data source. All you need to do is supply the name and directory path for the desired shapefile to the mapnik.Shapefile() convenience constructor:

datasource = mapnik.Shapefile(file="path/to/shapefile.shp")

The optional encoding parameter can be used to specify the character encoding to use for the shapefile's attributes, like this, for example:

datasource = mapnik.Shapefile(file="shapefile.shp",
                              encoding="latin1")

If you don't set the encoding parameter, the shapefile is assumed to use UTF-8 character encoding.

A PostGIS data source allows you to include data from a PostGIS database:

datasource = mapnik.PostGIS(user="..." password="...",
                            dbname="...", table="...")

Notice that you supply the username and password used to access the PostGIS database, the name of the database, and the name of the table that contains the spatial data you want to display on your map.

There are some performance issues to be aware of when retrieving data from a PostGIS database. If you use a mapnik.Filter object to selectively display features taken from a large database table, your map may take a long time to generate. This is because Mapnik needs to load every feature from the database table in turn to see whether it matches the filter expression. A much more efficient way to do this is to use what is called a sub-select query in order to limit the set of data that Mapnik retrieves from the database.

To use a sub-select query, you replace the table name with an SQL SELECT statement that does the filtering and returns the information needed by Mapnik to generate the map's layer. Here's an example:

query = "(SELECT geom FROM myBigTable WHERE level=1) AS data"
datasource = mapnik.PostGIS(user="...", password="...",
                            dbname="...", table=query)

We've replaced the table name with a PostGIS sub-select query that filters out all records with a level value not equal to 1 and returns just the geom field for the matching records.

Note that if you use a sub-select query, it is important that you include all the fields you want to refer to in your SELECT statement. If you don't include a field in the SELECT portion of the sub-select query, it won't be available for Mapnik to use.

The Gdal data source allows you to include any GDAL-compatible raster image data file within your map. It is straightforward to use:

datasource = mapnik.Gdal(file="myRasterImage.tiff")

Once you have a Gdal data source, you can use a RasterSymbolizer to draw it onto the map:

layer = mapnik.Layer("myLayer")
layer.datasource = datasource
layer.styles.append("myLayerStyle")

symbol = mapnik.RasterSymbolizer()

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

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

map.append_style("myLayerStyle", style)

A MemoryDatasource allows you to manually define the geospatial data that appears on the map. To use a MemoryDatasource, you first create the data source object itself:

datasource = mapnik.MemoryDatasource()

You then define a mapnik.Context object that lists the attributes you want to associate with each of the data source's features:

context = mapnik.Context()
context.push("NAME")
context.push("ELEVATION")

Next, you create a mapnik.Feature object for each of the features you want to include on the map:

feature = mapnik.Feature(context, id)

Note that the id parameter should be a unique integer value identifying this feature within the memory data source.

Once the feature has been created, you then set the feature's attributes. This is done in the same way you define entries within a Python dictionary:

feature['NAME'] = "Hawkins Hill"
feature['ELEVATION'] = 1624

These attributes can be used by rules to select which features to display, and they can also be used by a TextSymbolizer to draw an attribute's value onto the map.

Each feature can have one or more geometries associated with it. The easiest way to set the feature's geometry is to use the add_geometries_from_wkt() method, like this:

feature.add_geometries_from_wkt("POINT (174.73 -41.33)")

Finally, you add the feature to the MemoryDatasource using the add_feature() method:

datasource.add_feature(feature)

Once your MemoryDatasource has been set up, you can add it to a map layer and use any of the vector-format symbolizers to draw the features onto the map.

Mapnik's Filter() constructor takes a single parameter, which is a string defining an expression that the feature must match if the rule is to apply. You then store the returned Filter object in the rule's filter attribute:

rule.filter = mapnik.Filter("...")

Let's consider a very simple filter expression, comparing a field or attribute against a specific value:

filter = mapnik.Filter("[level] = 1")

String values can be compared by putting single quote marks around the value, like this:

filter = mapnik.Filter("[type] = 'CITY'")

Notice that the field name and value are both case-sensitive and that you must surround the field or attribute name with square brackets.

Of course, simply comparing a field with a value is the most basic type of comparison you can do. Filter expressions have their own powerful and flexible syntax for defining conditions, similar in concept to an SQL WHERE expression. The following syntax diagram describes all the options for writing filter expression strings:

Mapnik also allows you to filter based on the type of geometry, using the following special syntax:

filter = mapnik.Filter("[mapnik::geometry_type] = point")

The following geometry type values are supported by this kind of filter expression:

Imagine that you want to draw some features in one color and all other features in a different color. One way to achieve this is by using Mapnik filters, like this:

rule1.filter = mapnik.Filter("[level] = 1")
...
rule2.filter = mapnik.Filter("[level] != 1")

This is fine for simple filter expressions, but when the expressions get more complicated, it is a lot easier to use an "else" rule, like this:

rule.set_else(True)

If you call set_else(True) for a rule, then this rule is to be used if and only if no previous rule in the same style has had its filter conditions met.

Else rules are particularly useful if you have a number of filter conditions and want to have a catch-all rule at the end. This catch-all rule will apply if no other rule has been used to draw the feature, like this:

rule1.filter = mapnik.Filter("[type] = 'city'")
rule2.filter = mapnik.Filter("[type] = 'town'")
rule3.filter = mapnik.Filter("[type] = 'village'")
rule4.filter.set_else(True)

A Mapnik style is nothing more than a list of rules. To define a style, create a new mapnik.Style object and add the rules to it one at a time, like this:

style = mapnik.Style()
style.rules.append(rule1)
style.rules.append(rule2)
...

For each feature, the rules are processed one after the other, with each rule's conditions being checked in turn to see whether the feature matches the rule. If it does, the rule's associated symbolizers will be used to draw that feature. If none of the rules match the feature, then the feature won't be displayed at all.

Once you have created the Style object, you add the style to your mapnik.Map object, giving the style a name. You then refer to that style by name from within your map layers, for example:

map.append_style("style_name", style)
layer.styles.append("style_name")

To draw a point geometry, you use a PointSymbolizer. This draws an image at the specified point. The default constructor takes no arguments and displays each point as a black square of 4 x 4 pixels:

symbolizer = PointSymbolizer()

Alternatively, you can supply a path to an image file, which the PointSymbolizer will use to draw each point:

path = mapnik.PathExpression("path/to/image.png")
symbolizer = PointSymbolizer(path)

You can modify the behavior of the PointSymbolizer by setting the following attributes:

A LineSymbolizer draws linear features and traces around the outline of polygons, as shown in the following diagram:

The LineSymbolizer is one of the most useful of the Mapnik symbolizers. For example, the dashed line in the previous image was created using the following Python code:

stroke = mapnik.Stroke()
stroke.color = mapnik.Color("#008000")
stroke.width = 1.0
stroke.add_dash(5, 10)
symbolizer = mapnik.LineSymbolizer(stroke)

As you can see, a LineSymbolizer uses a Mapnik Stroke object to define how the line will be drawn. To use a LineSymbolizer, you first create the Stroke object and set the various options for how you want the line to be drawn. You then create your LineSymbolizer instance, passing the Stroke object to the LineSymbolizer object's constructor:

symbolizer = mapnik.LineSymbolizer(stroke)

You can customize the Stroke object in the following ways:

Note that you can call add_dash() more than once. This allows you to create alternating patterns of dots or dashes, for example:

stroke.add_dash(10, 2)
stroke.add_dash(2, 2)
stroke.add_dash(2, 2)

This would result in the following repeating line pattern:

One thing that may not be immediately obvious when you start working with symbolizers is that you can use multiple symbolizers for a single feature. For example, consider the following code:

stroke = mapnik.Stroke()
stroke.color = mapnik.Color("#bf7a3a")
stroke.width = 7.0
roadEdgeSymbolizer = mapnik.LineSymbolizer(stroke)

stroke = mapnik.Stroke()
stroke.color = mapnik.Color("#ffd3a9")
stroke.width = 6.0
roadInteriorSymbolizer = mapnik.LineSymbolizer(stroke)

rule.symbols.append(roadEdgeSymbolizer)
rule.symbols.append(roadInteriorSymbolizer)

The two symbolizers will be laid on top of each other to draw a LineString feature that looks like a road on a street map:

This technique can be used for more than just drawing roads; the creative use of symbolizers is one of the main tricks to achieving complex visual effects using Mapnik.

A PolygonSymbolizer fills the interior of a polygon with a single color:

You can create a PolygonSymbolizer instance like this:

symbolizer = mapnik.PolygonSymbolizer()

Once it has been created, you can configure your PolygonSymbolizer instance by setting the following attributes:

A TextSymbolizer draws textual labels onto point, line, and polygon features:

The basic usage of a TextSymbolizer is quite simple. For example, the polygon in the preceding illustration was labeled using the following code:

symbolizer = mapnik.TextSymbolizer(mapnik.Expression("[label]"),
"DejaVu Sans Book", 10, mapnik.Color("black"))

As you can see, the TextSymbolizer object's constructor takes four separate parameters:

Once it has been created, you can configure the TextSymbolizer object by setting the following attributes:

There are many more options for controlling how labels are drawn using a TextSymbolizer. For example, you can control how labels are split across multiple lines, specify character and line spacing, and even dynamically choose the attribute to display based on the length of the text and the available space. For more information on the available options, please consult the Mapnik documentation.

Raster images are often used to draw a basemap onto which your vector data is displayed. To draw a raster image, you would typically use a RasterSymbolizer. For example:

symbolizer = mapnik.RasterSymbolizer()

A RasterSymbolizer draws the contents of the layer's raster-format data source onto the map. While there are some advanced options for controlling how the raster image is displayed, in most cases, the only option you are likely to be interested in is the opacity attribute. As you might expect, this sets the opacity for the image, allowing you to display multiple semi-transparent images one on top of the other.