A Mapnik tutorial
Starting with Python
Using XML and CSS
CartoCSS and PostGIS
010-background.png - a completely blank map
A simple way of checking that you have Mapnik set up correctly is to start with the very basics. Here we create a map with nothing on it - just a background colour.
3 # Load the Python mapnik libraries.
4 import mapnik
6 # Create a new map.
7 m = mapnik.Map(480, 320)
9 # Set the background colour.
10 m.background = mapnik.Color('ghostwhite')
12 # Save the map as a PNG image.
13 mapnik.render_to_file(m, '010-background.png', 'png')
Detailed explanation of this program
- The numbers you can see down the left-hand side of the program are not actually part of the program: they are simply line numbers, making it easier to refer to specific bits. If you copy and paste the program into your editor, the line number will not be included.
- This program is written in the Python programming language. In Python, lines of the program which start with
# are comments. They are ignored by Python, and make no difference to the way in which the program functions. They are included as brief explanations of what the program is doing.
- Line one of the program is a comment line, but is also a shebang line. Although it is not part of the program itself, it is useful to show that the program needs to be run using Python, and in certain circumstances can tell the system that it should use Python to run it.
- Line four uses the Python
import command to make the mapnik functionality available to the program. This relies on this being installed correctly. If not, you will see an error something message like:
Traceback (most recent call last):
File "010-background.py", line 4, in <module>
ImportError: No module named mapnik
- Line seven is the first line which actually does something useful.
m = mapnik.Map(480, 320) creates a new object representing a map 480 w:pixels wide by 320 pixels high, and assigns this to variable
m. All further actions specifying what should be on this map, how it should be constructed and where it should be saved will involve this map object.
- Python has several ways of interacting with an object. One is to change that object's attributes. This is what happens in line ten. The
background attribute is set to something representing the colour we want. But mapnik is quite specific about what it considers to be colours: you can't simply specify
#efefef; directly. Instead you have to create a mapnik
Color object. That is done very simply here with
mapnik.Color('ghostwhite'). Once this object has been created, it can be assigned as the map's
- Another way of interacting with an object is to pass it as a parameter to another function. In line thirteen we call the
mapnik.render_to_file method and pass it three parameters: the map we've built, the name of the file to write it to and the format. In this case the file is to be called
'010-background.png' and the format is
'png', specifying the Portable Network Graphics (PNG) image format.
Save this program in a file called
010-background.py and run it by typing:
If everything is set up correctly, you should see no error messages, and you should see a new file in your working directory called
010-background.png. This is a new map image, and should be a light-coloured rectangle 480 pixels wide by 320 pixels high, as shown above. If this works OK, you are ready to move on to the next step: plotting points.