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

Revision 22191, 8.5 KB checked in by springmeyer, 4 years ago (diff)

add notes about downloading natural earth shapefiles to README for mapnik styles

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