source: subversion/applications/utils/export/osm2pgsql/README.txt @ 9267

Last change on this file since 9267 was 7141, checked in by martinvoosterhout, 12 years ago
Add support for a -Eproj option which allows users to use any epsg

projection that be used by proj4's +init=epsg:<num> format.

Should help all those people wanting to do maps in different projections.

File size: 7.2 KB
Line 
1osm2pgsql
2=========
3Converts OSM planet.osm data to SQL suitable for loading into
4a PostgreSQL database and then rendered into tiles by Mapnik.
5
6The format of the database is optimised for ease of rendering
7by mapnik. It may be less suitable for other general purpose
8processing.
9
10For a broader view of the whole map rendering tool chain see
11http://wiki.openstreetmap.org/index.php/Mapnik and
12http://wiki.openstreetmap.org/index.php/Slippy_Map
13
14Any questions should be directed at the osm dev list
15http://wiki.openstreetmap.org/index.php/Mailing_lists
16
17Changes
18=======
19The current version of code features several enhancements
20and changes over the previous code:
21
22- A direct connection to the Postgres database is used
23  instead of outputting SQL
24- Incorporation of setup_z_order.sql script so that
25  post-processing is no longer required
26- Able to read .gz and .bz2 files directly
27- Performs UTF8Sanitize while reading the planet.osm
28- Simplified usage: "osm2pgsql planet-xxxxxx.osm.bz2"
29- Geometries are now stored in mercator projection
30- Introduction of databased backed middle-layer for
31  systems with low RAM (normally disabled).
32- Support the choice of a few different projections
33- Configurable table names
34
35Requirements
36============
37The code is written in C and C++ and relies on the libraries
38below:
39- libxml2    http://xmlsoft.org/
40- geos       http://geos.refractions.net/
41- proj       http://www.remotesensing.org/proj/
42- bzip2      http://www.bzip.org/
43- zlib       http://www.zlib.net/
44- PostgreSQL http://www.postgresql.org/
45- PostGIS    http://postgis.refractions.net/
46
47To make use of the database generated by this tool you will
48probably also want to install:
49- Mapnik from http://mapnik.org/
50
51Building
52========
53On most Unix-like systems the program can be compiled by
54running 'make'.
55
56Note: the database connection parameters are hard coded to
57connect to Postgres on localhost with the current user to
58the database 'gis'.
59
60Operation
61=========
62
63First you must have setup Postgres with a database named 'gis'
64as per http://wiki.openstreetmap.org/index.php/Mapnik
65
661) Connects to database and creates the following 4 tables:
67   - planet_osm_point
68   - planet_osm_line
69   - planet_osm_roads
70   - planet_osm_polygon
71The prefix "planet_osm" can be changed with the --prefix option,
72the above is the default.
73
742) Runs an XML parser on the input file (typically planet.osm)
75 and processes the nodes, segments and ways.
76
773) If a node has a tag declaring one of the attributes below then
78 it is added to planet_osm_point. If it has no such tag then
79 the position is noted, but not added to the SQL.
80
81        name, place, landuse, waterway, highway,
82        railway, amenity, tourism, learning     
83
844) Segments are not output in the XML, they are used purely to
85 locate the nodes during way processing.
86
875) Ways are read in and the segments are examined to determine
88 contiguous sequences by WKT(). Each sequence is added to
89 the tables. If way consists of several dis-joint sequences of
90 segments then multiple lines will be generated with the 
91 osm_id of the original way.
92
936) Ways with the tags landuse or leisure are added to the
94 planet_osm_polygon table. Other ways are added to
95 planet_osm_line. Roads are also added to planet_osm_roads
96
977) Indexes are added to speed up the queries by Mapnik.
98
99A quick note on projections
100===========================
101
102Depending on the command-line switches you can select which projection you
103want the database in. You have three choices:
104
1053395: The WGS84 mercator projection, used in the tile output
1064326: The standard lat/long coordinates
107900913: The spherical mercator projection, used by TileCache, Google Earth etc.
108
109Depending on what you're using one or the other is appropriate. Most of the
110current Mapnik tools and style sheets are configured for 3395 and reproject
111to 900913 on the fly. But if you like you can project it correctly in one
112step, but don't forget to change the Mapnik config to match.
113
114Combining the -v and -h switches will tell about the exact definitions of
115the projections.
116
117In case you want to use some completely different projection there is the -E
118option. It will initialise the projection as +init=epsg:<num>. This allows
119you to use any projection recognised by proj4, which is useful if you want
120to make a map in a different projection. These projections are usually
121defined in /usr/share/proj/epsg.
122
123Database Access Examples
124========================
125If you wish to access the data from the database then the
126queries below should give you some hints:
127
128$ psql gis
129gis=> \d
130               List of relations
131 Schema |        Name        | Type  |  Owner
132--------+--------------------+-------+----------
133...
134 public | planet_osm_line    | table | jburgess
135 public | planet_osm_point   | table | jburgess
136 public | planet_osm_polygon | table | jburgess
137 public | planet_osm_roads   | table | jburgess
138...
139
140gis=> \d planet_osm_line
141  Table "public.planet_osm_line"
142  Column   |   Type   | Modifiers
143-----------+----------+-----------
144 osm_id    | integer  |
145 name      | text     |
146 place     | text     |
147 landuse   | text     |
148... [ lots of stuff deleted ] ...
149 way       | geometry | not null
150 z_order   | integer  | default 0
151
152
153Each of the tables contains a subset of the planet.osm file representing
154a particular geometry type
155- Point contains nodes which have interesting tags
156  e.g. place=city, name=London
157 
158- Line contains ways with interesting tags
159  e.g. highway=motorway, ref=M25
160 
161- Polygon contains ways which form an enclosed area
162  e.g. landuse=reservoir
163
164The DB columns are used as follows:
165- osm_id = the planet.osm ID of the node(point) or way(line,polygon)
166- name, place, landuse, ... = the value of the given key, if present on
167the node/way. If the tag is not present, the value is NULL. Only a
168subset of all possible tags are stored in the DB. Only ones rendered in
169the osm.xml are actually interesting to mapnik.
170- way = PostGIS geometry describing the physical layout of the object.
171
172
173Querying specific data requires knowlege of SQL and the OSM key/value
174system, e.g.
175
176gis=> select osm_id,astext(way),name from planet_osm_point where amenity='cinema' limit 5;
177  osm_id  |                  astext                   |        name
178----------+-------------------------------------------+--------------------
179 26236284 | POINT(-79.7160836579093 43.6802306464618) |
180 26206699 | POINT(51.4051989797638 35.7066045032235)  | Cinema Felestin
181 26206700 | POINT(51.3994885141459 35.7058460359352)  | Cinema Asr-e Jadid
182 20979630 | POINT(151.225781789807 -33.8943079539886) | Paris Cinema
183 20979684 | POINT(151.226855394904 -33.8946830511095) | Hoyts
184(5 rows)
185
186Mapnik renders the data in each table by applying the rules in the
187osm.xml file.
188
189
190> How could I get e.g. all highways in a given bounding box?
191
192The 'way' column contains the geo info and is the one which you need to
193use in your WHERE clause. e.g.
194
195gis=> select osm_id,highway,name from planet_osm_line where highway is not null and way && GeomFromText('POLYGON((0 52, 0.1 52, 0.1 52.1, 0 52.1, 0 52))',4326);
196 
197osm_id  |   highway    |       name
198---------+--------------+------------------
199 4273848 | unclassified |
200 3977133 | trunk        | to Royston (tbc)
201 4004841 | trunk        |
202 4019198 | trunk        |
203 4019199 | trunk        |
204 4238966 | unclassified |
205
206
207See the Postgis docs for details, e.g.
208http://postgis.refractions.net/docs/ch04.html
Note: See TracBrowser for help on using the repository browser.