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

Last change on this file since 23827 was 22616, checked in by rodo, 10 years ago

Add comment on getting coastlines

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