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

Last change on this file since 34655 was 30030, checked in by harrywood, 6 years ago

Update the description. Now superceded

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