source: subversion/applications/utils/export/osm2pgsql-intarray/README @ 28719

Last change on this file since 28719 was 25081, checked in by jonb, 9 years ago

osm2pgsql: Document that the autoconf tools need a few more packages to be installed: autoconf automake libtool

File size: 9.5 KB
Line 
1osm2pgsql
2=========
3Converts OSM planet.osm data to a PostgreSQL database suitable
4for rendering into map 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
12http://wiki.openstreetmap.org/index.php/Osm2pgsql
13http://wiki.openstreetmap.org/index.php/Slippy_Map
14
15You may find that the wiki pages are more up to date than this
16readme and may include answers to issues not mentioned here.
17
18Any questions should be directed at the osm dev list
19http://wiki.openstreetmap.org/index.php/Mailing_lists
20
21Features
22========
23- Converts OSM files to a postgresql DB
24- Conversion of tags to columns is configurable in the style file
25- Able to read .gz and .bz2 files directly
26- Can apply diffs to keep the database up to data
27- Support the choice of output projection
28- Configurable table names
29- Gazetteer backend for Nominatim
30  http://wiki.openstreetmap.org/wiki/Nominatim
31- Support for hstore field type to store the complete set of tags in one database
32  field if desired
33
34Source code
35===========
36The latest source code is available in the OSM SVN repository
37and can be downloaded as follows:
38
39$ svn co http://svn.openstreetmap.org/applications/utils/export/osm2pgsql
40
41Build requirements
42==================
43The code is written in C and C++ and relies on the libraries
44below:
45- libxml2    http://xmlsoft.org/
46- geos       http://geos.refractions.net/
47- proj       http://www.remotesensing.org/proj/
48- bzip2      http://www.bzip.org/
49- zlib       http://www.zlib.net/
50- PostgreSQL http://www.postgresql.org/
51- PostGIS    http://postgis.refractions.net/
52
53To make use of the database generated by this tool you will
54probably also want to install:
55- Mapnik from http://mapnik.org/
56
57
58
59Building
60========
61Make sure you have installed the development packages for the
62libraries mentioned in the requirements section and a C and C++
63compiler.
64
65e.g. on Fedora:
66# yum install geos-devel proj-devel postgresql-devel libxml2-devel bzip2-devel gcc-c++
67
68on Debian:
69# aptitude install libxml2-dev libgeos-dev libpq-dev libbz2-dev proj autoconf automake libtool make g++
70
71On most Unix-like systems the program can be compiled by
72running './autogen.sh && ./configure && make'.
73
74Operation
75=========
76You must create a PostgreSQL user and a database with the
77postgis functions enabled. This requires access as the
78database administrator, normally the 'postgres' user.
79
80The default name for this database is 'gis' but this may
81be changed by using the osm2pgsql --database option.
82
83If the <username> matches the unix user id running the import
84and rendering then this allows the PostgreSQL 'ident sameuser'
85authentication to be used which avoids the need to enter a
86password when accessing the database. This is setup by default
87on many Unix installs but does not work on Windows (due to the
88lack of unix sockets).
89
90Some example commands are given below but you may find
91this wiki page has more up to data information:
92http://wiki.openstreetmap.org/wiki/Mapnik/PostGIS
93
94$ sudo -u postgres createuser <username>
95$ sudo -u postgres createdb -E UTF8 -O <username> <dbname>
96$ sudo -u postgres createlang plpgsql <dbname>
97
98Adding the postgis extensions. Note the location of the
99lwpostgis.sql file may vary.
100
101$ sudo -u postgres psql -d <dbname> -f /usr/share/postgresql-8.3-postgis/lwpostgis.sql
102
103Next we need to give the <username> access to update the postgis
104metadata tables
105
106$ sudo -u postgres psql -d <dbname> -c "ALTER TABLE geometry_columns OWNER TO <username>"
107$ sudo -u postgres psql -d <dbname> -c "ALTER TABLE spatial_ref_sys  OWNER TO <username>"
108
109The 900913 is not normally included with postgis. To add it you
110should run:
111
112$ sudo psql -u postgres psql -d <dbname> -f 900913.sql
113
114
115If you want to update your database with the diffs then you will
116need to enable the PostgreSQL intarray contrib module. These
117contrib scripts are not installed by default and are often
118supplied in an additional package (e.g. postgresql-contrib).
119
120$ sudo yum install postgresql-contrib
121$ sudo -u postgres psql -d <dbname> -f /usr/share/pgsql/contrib/_int.sql
122
123If you want to use hstore support then you will also need to enable the PostgreSQL
124hstore-new extension.
125
126$ sudo -u postgres psql -d <dbname> -f /usr/share/postgresql/8.3/contrib/hstore-new.sql
127
128Now you can run osm2pgsql to import the OSM data.
129This will perform the following actions:
130
1311) Osm2pgsql connects to database and creates the following 4 tables:
132   - planet_osm_point
133   - planet_osm_line
134   - planet_osm_roads
135   - planet_osm_polygon
136The prefix "planet_osm" can be changed with the --prefix option,
137the above is the default.
138
1392) Runs an XML parser on the input file (typically planet.osm)
140 and processes the nodes, ways and relations.
141
1423) If a node has a tag declared in the style file then it is
143 added to planet_osm_point. If it has no such tag then
144 the position is noted, but not added to the database.
145
1464) Ways are read in converted into WKT geometries by using the
147 postitions of the nodes read in earlier. If the tags on the way
148 are listed in the style file then the way will be written into
149 the line or roads tables.
150
1515) If the way has one or more tags marked as 'poloygon' and
152 forms a closed ring then it will be added to the lanet_osm_polygon
153 table.
154
1556) The relations are parsed. Osm2pgsql has special handling for a
156 limited number of types: multipolygon, route, boundary
157 The code will build the appropriate geometries by referencing the
158 members and outputing these into the database.
159
1607) Indexes are added to speed up the queries by Mapnik.
161
162
163A quick note on projections
164===========================
165
166Depending on the command-line switches you can select which projection you
167want the database in. You have three choices:
168
1694326: The standard lat/long coordinates
170900913: The spherical mercator projection, used by TileCache, Google Earth etc.
1713395: The legacy (broken) WGS84 mercator projection
172
173Depending on what you're using one or the other is appropriate. The default
174mapnik style (osm.xml) assumes that the data is stored in 900913 and this
175is the default for osm2pgsql.
176
177Combining the -v and -h switches will tell about the exact definitions of
178the projections.
179
180In case you want to use some completely different projection there is the -E
181option. It will initialise the projection as +init=epsg:<num>. This allows
182you to use any projection recognised by proj4, which is useful if you want
183to make a map in a different projection. These projections are usually
184defined in /usr/share/proj/epsg.
185
186Database Access Examples
187========================
188If you wish to access the data from the database then the
189queries below should give you some hints. Note that these
190examples all use the 'latlong' projection which is not the
191default.
192
193$ psql gis
194gis=> \d
195               List of relations
196 Schema |        Name        | Type  |  Owner
197--------+--------------------+-------+----------
198...
199 public | planet_osm_line    | table | jburgess
200 public | planet_osm_point   | table | jburgess
201 public | planet_osm_polygon | table | jburgess
202 public | planet_osm_roads   | table | jburgess
203...
204
205gis=> \d planet_osm_line
206  Table "public.planet_osm_line"
207  Column   |   Type   | Modifiers
208-----------+----------+-----------
209 osm_id    | integer  |
210 name      | text     |
211 place     | text     |
212 landuse   | text     |
213... [ lots of stuff deleted ] ...
214 way       | geometry | not null
215 z_order   | integer  | default 0
216
217
218Each of the tables contains a subset of the planet.osm file representing
219a particular geometry type
220- Point contains nodes which have interesting tags
221  e.g. place=city, name=London
222 
223- Line contains ways with interesting tags
224  e.g. highway=motorway, ref=M25
225 
226- Polygon contains ways which form an enclosed area
227  e.g. landuse=reservoir
228
229The DB columns are used as follows:
230- osm_id = the planet.osm ID of the node(point) or way(line,polygon)
231- name, place, landuse, ... = the value of the given key, if present on
232the node/way. If the tag is not present, the value is NULL. Only a
233subset of all possible tags are stored in the DB. Only ones rendered in
234the osm.xml are actually interesting to mapnik.
235- way = PostGIS geometry describing the physical layout of the object.
236
237
238Querying specific data requires knowlege of SQL and the OSM key/value
239system, e.g.
240
241gis=> select osm_id,astext(way),name from planet_osm_point where amenity='cinema' limit 5;
242  osm_id  |                  astext                   |        name
243----------+-------------------------------------------+--------------------
244 26236284 | POINT(-79.7160836579093 43.6802306464618) |
245 26206699 | POINT(51.4051989797638 35.7066045032235)  | Cinema Felestin
246 26206700 | POINT(51.3994885141459 35.7058460359352)  | Cinema Asr-e Jadid
247 20979630 | POINT(151.225781789807 -33.8943079539886) | Paris Cinema
248 20979684 | POINT(151.226855394904 -33.8946830511095) | Hoyts
249(5 rows)
250
251Mapnik renders the data in each table by applying the rules in the
252osm.xml file.
253
254
255> How could I get e.g. all highways in a given bounding box?
256
257The 'way' column contains the geo info and is the one which you need to
258use in your WHERE clause. e.g.
259
260gis=> 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);
261 
262osm_id  |   highway    |       name
263---------+--------------+------------------
264 4273848 | unclassified |
265 3977133 | trunk        | to Royston (tbc)
266 4004841 | trunk        |
267 4019198 | trunk        |
268 4019199 | trunk        |
269 4238966 | unclassified |
270
271
272See the Postgis docs for details, e.g.
273http://postgis.refractions.net/docs/ch04.html
Note: See TracBrowser for help on using the repository browser.