source: subversion/applications/utils/export/osm2pgsql/readme.txt @ 3210

Last change on this file since 3210 was 2827, checked in by jonb, 13 years ago

osm2pgsql - make experimental version current, move previous implementation to legacy

File size: 6.0 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
33Requirements
34============
35The code is written in C and C++ and relies on the libraries
36below:
37- libxml2    http://xmlsoft.org/
38- geos       http://geos.refractions.net/
39- proj       http://www.remotesensing.org/proj/
40- bzip2      http://www.bzip.org/
41- zlib       http://www.zlib.net/
42- PostgreSQL http://www.postgresql.org/
43- PostGIS    http://postgis.refractions.net/
44
45To make use of the database generated by this tool you will
46probably also want to install:
47- Mapnik from http://mapnik.org/
48
49Building
50========
51On most Unix-like systems the program can be compiled by
52running 'make'.
53
54Note: the database connection parameters are hard coded to
55connect to Postgres on localhost with the current user to
56the database 'gis'.
57
58Operation
59=========
60
61First you must have setup Postgres with a database named 'gis'
62as per http://wiki.openstreetmap.org/index.php/Mapnik
63
641) Connects to database and creates the following 4 tables:
65   - planet_osm_point
66   - planet_osm_line
67   - planet_osm_roads
68   - planet_osm_polygon
69
702) Runs an XML parser on the input file (typically planet.osm)
71 and processes the nodes, segments and ways.
72
733) If a node has a tag declaring one of the attributes below then
74 it is added to planet_osm_point. If it has no such tag then
75 the position is noted, but not added to the SQL.
76
77        name, place, landuse, waterway, highway,
78        railway, amenity, tourism, learning     
79
804) Segments are not output in the XML, they are used purely to
81 locate the nodes during way processing.
82
835) Ways are read in and the segments are examined to determine
84 contiguous sequences by WKT(). Each sequence is added to
85 the tables. If way consists of several dis-joint sequences of
86 segments then multiple lines will be generated with the 
87 osm_id of the original way.
88
896) Ways with the tags landuse or leisure are added to the
90 planet_osm_polygon table. Other ways are added to
91 planet_osm_line. Roads are also added to planet_osm_roads
92
937) Indexes are added to speed up the queries by Mapnik.
94
95
96Database Access Examples
97========================
98If you wish to access the data from the database then the
99queries below should give you some hints:
100
101$ psql gis
102gis=> \d
103               List of relations
104 Schema |        Name        | Type  |  Owner
105--------+--------------------+-------+----------
106...
107 public | planet_osm_line    | table | jburgess
108 public | planet_osm_point   | table | jburgess
109 public | planet_osm_polygon | table | jburgess
110 public | planet_osm_roads   | table | jburgess
111...
112
113gis=> \d planet_osm_line
114  Table "public.planet_osm_line"
115  Column   |   Type   | Modifiers
116-----------+----------+-----------
117 osm_id    | integer  |
118 name      | text     |
119 place     | text     |
120 landuse   | text     |
121... [ lots of stuff deleted ] ...
122 way       | geometry | not null
123 z_order   | integer  | default 0
124
125
126Each of the tables contains a subset of the planet.osm file representing
127a particular geometry type
128- Point contains nodes which have interesting tags
129  e.g. place=city, name=London
130 
131- Line contains ways with interesting tags
132  e.g. highway=motorway, ref=M25
133 
134- Polygon contains ways which form an enclosed area
135  e.g. landuse=reservoir
136
137The DB columns are used as follows:
138- osm_id = the planet.osm ID of the node(point) or way(line,polygon)
139- name, place, landuse, ... = the value of the given key, if present on
140the node/way. If the tag is not present, the value is NULL. Only a
141subset of all possible tags are stored in the DB. Only ones rendered in
142the osm.xml are actually interesting to mapnik.
143- way = PostGIS geometry describing the physical layout of the object.
144
145
146Querying specific data requires knowlege of SQL and the OSM key/value
147system, e.g.
148
149gis=> select osm_id,astext(way),name from planet_osm_point where amenity='cinema' limit 5;
150  osm_id  |                  astext                   |        name
151----------+-------------------------------------------+--------------------
152 26236284 | POINT(-79.7160836579093 43.6802306464618) |
153 26206699 | POINT(51.4051989797638 35.7066045032235)  | Cinema Felestin
154 26206700 | POINT(51.3994885141459 35.7058460359352)  | Cinema Asr-e Jadid
155 20979630 | POINT(151.225781789807 -33.8943079539886) | Paris Cinema
156 20979684 | POINT(151.226855394904 -33.8946830511095) | Hoyts
157(5 rows)
158
159Mapnik renders the data in each table by applying the rules in the
160osm.xml file.
161
162
163> How could I get e.g. all highways in a given bounding box?
164
165The 'way' column contains the geo info and is the one which you need to
166use in your WHERE clause. e.g.
167
168gis=> 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);
169 
170osm_id  |   highway    |       name
171---------+--------------+------------------
172 4273848 | unclassified |
173 3977133 | trunk        | to Royston (tbc)
174 4004841 | trunk        |
175 4019198 | trunk        |
176 4019199 | trunk        |
177 4238966 | unclassified |
178
179
180See the Postgis docs for details, e.g.
181http://postgis.refractions.net/docs/ch04.html
Note: See TracBrowser for help on using the repository browser.