source: subversion/applications/rendering/mapnik/README @ 29147

Last change on this file since 29147 was 29076, checked in by Dane Springmeyer, 7 years ago

add troubleshooting details + fix readme re;mapnik 2.x since the stylesheets now require it

File size: 9.9 KB
Line 
1
2Rendering OpenStreetMap with Mapnik
3-----------------------------------
4
5Welcome, if you have Mapnik and osm2pgsql installed and you want
6to render your own OSM tiles, you've come to the right place.
7
8This is the development location of the Mapnik XML stylesheets powering
9tile.openstreetmap.org.
10
11This directory also holds an assortment of helpful utility scripts for
12working with Mapnik and the OSM Mapnik XML stylesheets.
13
14The serving of the official tiles is done using mod_tile
15 * Code is located at http://svn.openstreetmap.org/applications/utils/mod_tile.
16 * Rendering is done by the 'renderd' daemon (both a python and C++ version are available).
17
18However, the easiest way to start rendering Mapnik tiles is to use the
19'generate_tiles.py' script located within this directory.
20
21
22Quick References
23----------------
24If you need additional info, please read:
25 - http://wiki.openstreetmap.org/wiki/Mapnik
26
27If you are new to Mapnik see:
28 - http://mapnik.org
29
30If you are looking for an old file that used to be here see the 'archive' directory.
31
32
33
34Required
35--------
36
37Mapnik >= 2.0.0 | The rendering library
38 * Built with the PostGIS plugin
39 * http://trac.mapnik.org/wiki/Mapnik-Installation
40
41osm2pgsql trunk | Tool for importing OSM data into PostGIS
42 * The latest trunk source is highly recommended
43 * http://svn.openstreetmap.org/applications/utils/export/osm2pgsql
44
45Coastline Shapefiles
46 * Download these locally
47 * For more info see: http://wiki.openstreetmap.org/wiki/Mapnik
48 * They come with Mapnik indexes pre-built (using shapeindex)
49
50Planet.osm data in PostGIS
51 * An extract (recommended) or the whole thing
52   - http://wiki.openstreetmap.org/wiki/Planet.osm
53 * Import this into PostGIS with osm2pgsql
54
55
56
57Quickstart
58----------
59
60The goal is to customize the Mapnik stylesheets to your local setup,
61test rendering a few images, and then get set up to render tiles.
62
63First, make sure you have downloaded the coastlines shapefiles and have set up a
64postgis enabled database with osm data imported using osm2pgsql. See
65http://wiki.openstreetmap.org/wiki/Mapnik for more info.
66
67Then customize the xml entities (the files in the inc/ directory) which are
68used by the 'osm.xml' to your setup. You can either use the 'generate_xml.py'
69script or manually edit a few files inside the 'inc' directory.
70
71Finally try rendering a few maps using either 'generate_image.py',
72'generate_tiles.py' or 'nik2img.py'.
73
74
75
76Downloading the Coastlines Shapefiles
77-------------------------------------
78 
79    All these actions are regrouped in the script file get-coastlines.sh in this directory
80
81    wget http://tile.openstreetmap.org/world_boundaries-spherical.tgz # (50M)
82    wget http://tile.openstreetmap.org/processed_p.tar.bz2 # (227M)
83    wget http://tile.openstreetmap.org/shoreline_300.tar.bz2 # (46M)
84    wget http://www.naturalearthdata.com/http//www.naturalearthdata.com/download/10m/cultural/10m-populated-places.zip # (1.5 MB)
85    wget http://www.naturalearthdata.com/http//www.naturalearthdata.com/download/110m/cultural/110m-admin-0-boundary-lines.zip # (38 KB)
86
87    tar xzf world_boundaries-spherical.tgz # creates a 'world_boundaries' folder
88    tar xjf processed_p.tar.bz2 -C world_boundaries
89    tar xjf shoreline_300.tar.bz2 -C world_boundaries
90    unzip -q 10m-populated-places.zip -d world_boundaries
91    unzip -q 110m-admin-0-boundary-lines.zip -d world_boundaries
92
93
94Using generate_xml.py
95---------------------
96
97To use the 'generate_xml.py' script simply run:
98
99    ./generate_xml.py -h  # note the optional and required parameters
100
101Most users will need to pass their database settings with something like:
102
103    ./generate_xml.py --dbname osm --host 'localhost' --user postgres --port 5432 --password ''
104
105If that command works, then you are ready to render tiles!
106
107The script will also pick up ALLCAPS global environment settings (where they must have a 'MAPNIK" prefix):
108
109    export MAPNIK_DBNAME=osm && export MAPNIK_HOST=localhost && ./generate_xml.py
110
111Note: Depending on your database configuration you may be able to leave empty values for
112parameters such as 'host', 'port', 'password', or even 'dbname'.
113
114Do do this can pass the '--accept-none' flag or empty strings:
115
116    ./generate_xml.py --dbname osm --accept-none
117
118    ./generate_xml.py --dbname osm --host '' --user '' --port '' --password ''
119
120Advanced users may want to create multiple versions of the Mapnik XML for various rendering
121scenarios, and this can be done using 'generate_xml.py' by passing the 'osm.xml' as an argument
122and then piping the resulting xml to a new file:
123
124    ./generate_xml.py osm.xml > my_osm.xml
125
126
127
128Manually editing 'inc' files
129----------------------------
130
131To manually configure your setup you will need to work with the XML snippets
132in the 'inc' directory which end with 'template'.
133
134Copy them to a new file and strip off the '.template' extension.
135
136    cp inc/datasource-settings.xml.inc.template inc/datasource-settings.xml.inc
137    cp inc/fontset-settings.xml.inc.template inc/fontset-settings.xml.inc
138    cp inc/settings.xml.inc.template inc/settings.xml.inc
139
140Then edit the settings variables (e.g. '%(value)s') in those files to match your configuration.
141Details can be found in each file. Stick with the recommended defaults unless you know better.
142
143Troubleshooting
144---------------
145
146If trying to read the XML with Mapnik (or any of the python scripts included here that use Mapnik)
147fails with an error like `XML document not well formed` or `Entity 'foo' not defined`, then try running
148xmllint, which may provide a more detailed error to help you find the syntax problem in the XML (or its
149referenced includes):
150
151    xmllint osm.xml --noout
152
153Not output from the above command indicates the stylesheet should be working fine.
154
155If you see an error like: `warning: failed to load external entity "inc/datasource-settings.xml.inc"` then this
156likely indicates that an include file is missing, which means that you forgot to follow the steps above to generate the needed includes on the fly either by using `generate_xml.py` or manually creating your inc files.
157
158
159Testing rendering
160-----------------
161
162To generate a simple image of the United Kingdom use the 'generate_image.py' script.
163
164
165    ./generate_image.py # will output and 'image.png' file...
166
167
168To try generating an image with the ability to zoom to different areas or output different formats
169then try loading the XML using nik2img. Download and install nik2img using the
170instructions from http://trac.mapnik.org/wiki/Nik2Img
171
172To zoom to the same area as generate_image.py but at level 4 do:
173
174    nik2img.py osm.xml image.png --center -2.2 54.25 --zoom 4
175
176Advanced users may want to change settings and dynamically view result of the re-generated xml.
177
178This can be accomplished by piping the XML to nik2img.py, for example:
179
180    ./generate_xml.py osm.xml | nik2img.py test.png
181
182Or, zoom into a specific layer's extent (useful when using a regional OSM extract):
183
184    ./generate_xml.py --estimate_extent true --dbname osm osm.xml --accept-none | nik2img.py --zoom-to-layer roads roads.png
185
186
187
188Rendering tiles
189---------------
190
191You are now ready to test rendering tiles.
192
193Edit the 'bbox' inside 'generate_tiles.py' and run
194
195    ./generate_tiles.py
196
197Alternatively, run
198
199    ./polytiles.py --bbox X1 Y1 X2 Y2
200
201Tiles will be written into 'tiles' directory. To see the list of all parameters,
202run this script without any.
203
204Files and Directories
205---------------------
206
207all_tiles
208    ??
209
210convert
211    OBSOLETE. Use customize-mapnik-map instead.
212
213customize-mapnik-map
214    Run this script to convert osm-template.xml into osm.xml with your
215    settings.
216
217generate_xml.py
218    A script to help customize the osm.xml. Will read parameters from the
219    users environment or via command line flags. Run ./generate_xml.py -h
220    for usage and help.
221   
222generate_image.py
223    A script to generate a map image from OSM data using Mapnik. Will
224    read mapping instructions from $MAPNIK_MAP_FILE (or 'osm.xml') and
225    write the finished map to 'image.png'. You have to change the script
226    to change the bounding box or image size.
227
228generate_tiles.py
229    A script to generate map tiles from OSM data using Mapnik. Will
230    read mapping instructions from $MAPNIK_MAP_FILE (or 'osm.xml') and
231    write the finished maps to the $MAPNIK_TILE_DIR directory. You have
232    to change the script to change the bounding boxes or zoom levels
233    for which tiles are created.
234
235polytiles.py
236    An advanced script to generate map tiles with Mapnik. Can produce
237    png files, .mbtiles or just a list. Supports not only bboxes,
238    but PostGIS polygons, .poly files and tile lists. Run the script
239    without parameters to see the full list of options.
240
241install.txt
242    An almost cut-and-paste documentation on how to use all this.
243
244legend.py
245    Script for generating a simple legend from osm-template.xml, useful
246    for visualizing existing styles and changes.
247
248mkshield.pl
249    Perl script to generate highway shield images. You normally don't
250    have to run this because prerendered images are already stored in
251    the 'symbols' directory.
252
253openstreetmap-mapnik-data
254openstreetmap-mapnik-world-boundaries
255    These directories contain the things needed to create Debian packages
256    for OSM Mapnik stuff.
257
258osm-template.xml
259    A template for the osm.xml file which contains the rules on how
260    Mapnik should render data.
261
262osm.xml
263    The file which contains the rules on how Mapnik should render data.
264    You should generate your own version from the osm-template.xml file.
265
266osm2pgsl.py
267    Older script to read OSM data into a PostgreSQL/PostGIS database. Use
268    the newer C version in ../../utils/export/osm2pgsql instead!
269
270set-mapnik-env
271    Used to customize the environment needed by the other Mapnik OSM
272    scripts.
273
274setup_z_order.sql
275    SQL commands to set up Z order for rendering. This is included in
276    the C version of osm2pgsql in ../../utils/export/osm2pgsql, so you
277    don't need this any more.
278
279symbols
280    Directory with icons and highway shield images.
281
282zoom-to-scale.txt
283    Comparison between zoom levels and the scale denominator numbers needed
284    for the Mapnik Map file.
Note: See TracBrowser for help on using the repository browser.