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

Last change on this file since 21597 was 18879, checked in by ldp, 10 years ago

New script, donated by springmeyer, to set up mapnik with your local settings. See generate_xml.py and README.
Also renamed .example files to .template

File size: 8.2 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://trac.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 >= 0.6.1 | The rendering library
38 * Built with the PostGIS plugin
39 * http://trac.mapnik.org/wiki/MapnikInstallation
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
63Make 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
67Customize the 'osm.xml' entities to your setup. You can either use the
68'generate_xml.py' script or manually edit a few files inside the 'inc' directory.
69
70Finally try rendering a few maps using either 'generate_image.py',
71'generate_tiles.py' or 'nik2img.py'.
72
73
74
75Downloading the Coastlines Shapefiles
76-------------------------------------
77
78    wget http://tile.openstreetmap.org/world_boundaries-spherical.tgz # (50M)
79    wget http://tile.openstreetmap.org/processed_p.tar.bz2 # (227M)
80    wget http://tile.openstreetmap.org/shoreline_300.tar.bz2 # (46M)
81   
82    tar xvf world_boundaries-spherical.tgz # creates a 'world_boundaries' folder
83    tar xvf processed_p.tar.bz2
84    mv processed_p* world_boundaries/
85    tar xvf shoreline_300.tar.bz2
86    mv shoreline_300* world_boundaries/
87
88
89
90Using generate_xml.py
91---------------------
92
93To use the 'generate_xml.py' script simply run:
94
95    ./generate_xml.py -h  # note the optional and required parameters
96
97Most users will need to pass their database settings with something like:
98
99    ./generate_xml.py --dbname osm --host 'localhost' --user postgres --port 5432 --password ''
100
101If that command works, then you are ready to render tiles!
102
103The script will also pick up ALLCAPS global environment settings (where they must have a 'MAPNIK" prefix):
104
105    export MAPNIK_DBNAME=osm && export MAPNIK_HOST=localhost && ./generate_xml.py
106
107Note: Depending on your database configuration you may be able to leave empty values for
108parameters such as 'host', 'port', 'password', or even 'dbname'.
109
110Do do this can pass the '--accept-none' flag or empty strings:
111
112    ./generate_xml.py --dbname osm --accept-none
113
114    ./generate_xml.py --dbname osm --host '' --user '' --port '' --password ''
115
116Advanced users may want to create multiple versions of the Mapnik XML for various rendering
117scenarios, and this can be done using 'generate_xml.py' by passing the 'osm.xml' as an argument
118and then piping the resulting xml to a new file:
119
120    ./generate_xml.py osm.xml > my_osm.xml
121
122
123
124Manually editing 'inc' files
125----------------------------
126
127To manually configure your setup you will need to work with the XML snippets
128in the 'inc' directory which end with 'template'.
129
130Copy them to a new file and strip off the '.template' extension.
131
132    cp inc/datasource-settings.xml.inc.template inc/datasource-settings.xml.inc
133    cp inc/fontset-settings.xml.inc.template inc/fontset-settings.xml.inc
134    cp inc/settings.xml.inc.template inc/settings.xml.inc
135
136Then edit the settings variables (e.g. '%(value)s') in those files to match your configuration.
137Details can be found in each file. Stick with the recommended defaults unless you know better.
138
139
140
141Testing rendering
142-----------------
143
144To generate a simple image of the United Kingdom use the 'generate_image.py' script.
145
146
147    ./generate_image.py # will output and 'image.png' file...
148
149
150To try generating an image with the ability to zoom to different areas or output different formats
151then try loading the XML using nik2img. Download and install nik2img using the
152instructions from http://trac.mapnik.org/wiki/Nik2Img
153
154To zoom to the same area as generate_image.py but at level 4 do:
155
156    nik2img.py osm.xml image.png --center -2.2 54.25 --zoom 4
157
158Advanced users may want to change settings and dynamically view result of the re-generated xml.
159
160This can be accomplished by piping the XML to nik2img.py, for example:
161
162    ./generate_xml.py osm.xml | nik2img.py test.png
163
164Or, zoom into a specific layer's extent (useful when using a regional OSM extract):
165
166    ./generate_xml.py --estimate_extent true --dbname osm osm.xml --accept-none | nik2img.py --zoom-to-layer roads roads.png
167
168
169
170Rendering tiles
171---------------
172
173You are now ready to test rendering tiles.
174
175Edit the 'bbox' inside 'generate_tiles.py' and run
176
177    ./generate_tiles.py
178
179
180Files and Directories
181---------------------
182
183all_tiles
184    ??
185
186convert
187    OBSOLETE. Use customize-mapnik-map instead.
188
189customize-mapnik-map
190    Run this script to convert osm-template.xml into osm.xml with your
191    settings.
192
193generate_xml.py
194    A script to help customize the osm.xml. Will read parameters from the
195    users environment or via command line flags. Run ./generate_xml.py -h
196    for usage and help.
197   
198generate_image.py
199    A script to generate a map image from OSM data using Mapnik. Will
200    read mapping instructions from $MAPNIK_MAP_FILE (or 'osm.xml') and
201    write the finished map to 'image.png'. You have to change the script
202    to change the bounding box or image size.
203
204generate_tiles.py
205    A script to generate map tiles from OSM data using Mapnik. Will
206    read mapping instructions from $MAPNIK_MAP_FILE (or 'osm.xml') and
207    write the finished maps to the $MAPNIK_TILE_DIR directory. You have
208    to change the script to change the bounding boxes or zoom levels
209    for which tiles are created.
210
211install.txt
212    An almost cut-and-paste documentation on how to use all this.
213
214legend.py
215    Script for generating a simple legend from osm-template.xml, useful
216    for visualizing existing styles and changes.
217
218mkshield.pl
219    Perl script to generate highway shield images. You normally don't
220    have to run this because prerendered images are already stored in
221    the 'symbols' directory.
222
223openstreetmap-mapnik-data
224openstreetmap-mapnik-world-boundaries
225    These directories contain the things needed to create Debian packages
226    for OSM Mapnik stuff.
227
228osm-template.xml
229    A template for the osm.xml file which contains the rules on how
230    Mapnik should render data.
231
232osm.xml
233    The file which contains the rules on how Mapnik should render data.
234    You should generate your own version from the osm-template.xml file.
235
236osm2pgsl.py
237    Older script to read OSM data into a PostgreSQL/PostGIS database. Use
238    the newer C version in ../../utils/export/osm2pgsql instead!
239
240set-mapnik-env
241    Used to customize the environment needed by the other Mapnik OSM
242    scripts.
243
244setup_z_order.sql
245    SQL commands to set up Z order for rendering. This is included in
246    the C version of osm2pgsql in ../../utils/export/osm2pgsql, so you
247    don't need this any more.
248
249symbols
250    Directory with icons and highway shield images.
251
252zoom-to-scale.txt
253    Comparison between zoom levels and the scale denominator numbers needed
254    for the Mapnik Map file.
Note: See TracBrowser for help on using the repository browser.