From d17e296815038aca6488a1082dfd795e0d474ba1 Mon Sep 17 00:00:00 2001 From: Oliver Tonnhofer Date: Fri, 15 Jan 2016 14:41:25 +0100 Subject: [PATCH] document relation and relation_member --- README.md | 8 +- docs/index.rst | 1 + docs/mapping.rst | 37 +++++++++- docs/relations.rst | 180 +++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 221 insertions(+), 5 deletions(-) create mode 100644 docs/relations.rst diff --git a/README.md b/README.md index 9168292..b65566f 100644 --- a/README.md +++ b/README.md @@ -45,10 +45,13 @@ Features Automatically creates tables with lower spatial resolutions, perfect for rendering large road networks in low resolutions. - Limit to polygons: - Limit imported geometries to polygons from Shapefiles or GeoJSON, for city/state/country imports. + Limit imported geometries to polygons from GeoJSON, for city/state/country imports. - Easy deployment: - Single binary with only runtime dependencies to common libs (GEOS, SQLite and LevelDB) + Single binary with only runtime dependencies to common libs (GEOS, ProtoBuf and LevelDB) + +- Route relations: + Import all relation types including routes. - Support for table namespace (PostgreSQL schema) @@ -88,7 +91,6 @@ There are a few features we like to see in Imposm 3: * Automatic download and import of differential files * Support for other projections than EPSG:3857 or EPSG:4326 -* Support for route relations * Improved integration with tile servers (expiration of updated tiles) * Custom field/filter functions * Official releases with binaries for more platforms diff --git a/docs/index.rst b/docs/index.rst index 9859b48..7b950b9 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -58,6 +58,7 @@ Contents install tutorial mapping + relations .. Indices and tables diff --git a/docs/mapping.rst b/docs/mapping.rst index b1715b6..449152c 100644 --- a/docs/mapping.rst +++ b/docs/mapping.rst @@ -15,7 +15,7 @@ The most important part is the ``tables`` definition. Each table is a YAML objec ``type`` ~~~~~~~~ -``type`` can be ``point``, ``linestring``, ``polygon`` or ``geometry``. ``geometry`` requires a special ``mapping``. +``type`` can be ``point``, ``linestring``, ``polygon``, ``geometry``, ``relation`` and ``relation_member``. ``geometry`` requires a special ``mapping``. :doc:`Relations are described in more detail here `. ``mapping`` @@ -41,7 +41,7 @@ To import all polygons with `tourism=zoo`, `natural=wood` or `natural=land` into ``columns`` ~~~~~~~~~~~ -``columns`` is a list of columns that Imposm should create for this table. Each column is a YAML object with a ``type`` and a ``name`` and optionaly ``key`` and ``args``. +``columns`` is a list of columns that Imposm should create for this table. Each column is a YAML object with a ``type`` and a ``name`` and optionaly ``key``, ``args`` and ``from_member``. ``name`` ^^^^^^^^^ @@ -67,6 +67,11 @@ See :ref:`column_types` for documentation of all types. Some column types require additional arguments. Refer to the documentation of the type. +``from_member`` +^^^^^^^^^^^^^^^ + +``from_member`` is only valid for tables of the type ``relation_member``. If this is set to ``true``, then tags will be used from the member instead of the relation. + Example ~~~~~~~ @@ -241,6 +246,34 @@ Stores all tags in a HStore column. Requires the PostGIS HStore extension. This .. "string_suffixreplace": {"string_suffixreplace", "string", nil, MakeSuffixReplace}, +Element types for ``relation_member`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following types are only valid for tables of the type ``relation_member``. + +``relation_member_id`` +^^^^^^^^^^^^^^^^^^^^^^ + +The OSM ID of the relation member. + +``relation_member_type`` +^^^^^^^^^^^^^^^^^^^^^^^^ + +The type of the relation member. 0 for nodes, 1 for ways and 2 for relations. + + +``relation_member_role`` +^^^^^^^^^^^^^^^^^^^^^^^^ + +The role of the relation member as a string, e.g. `outer`, `stop`, etc. + + +``relation_member_index`` +^^^^^^^^^^^^^^^^^^^^^^^^^ + +The index of the member in the relation, starting from 0. E.g. the first member is 0, second member is 1, etc. +This can be used to query bus stops of a route relation in the right order. + Generalized Tables ------------------ diff --git a/docs/relations.rst b/docs/relations.rst new file mode 100644 index 0000000..7f61f84 --- /dev/null +++ b/docs/relations.rst @@ -0,0 +1,180 @@ +Relations +========= + +In `OpenStreetMap, relations `_ define logical or geographic relationships between other nodes, ways and relations. + +The most common relation type is a multipolygon, but all other relations can be imported as well. + +Multipolygons +------------- + +`Multipolygon relations `_ are used to represent complex polygon geometries. They are also the only way to represent holes in polygons. + + +Multipolygon relations are automatically handled by Imposm for all ``polygon`` tables. + +The following mapping:: + + tables: + buildings: + type: polygon + mapping: + building: [__any__] + + +Inserts closed ways if they have a ``building`` tag:: + + + + ... + + + + +It will also insert relations of the type ``multipolygon`` with a ``building`` tag:: + + + + + + + + +The roles are ignored by Imposm as not all holes are correctly tagged as ``inner``. Imposm uses geometry operations to verify if a member of a multipolygon is a hole, or if it is a separate polygon. + + +For compatibility, multipolygon relations without tags will use the tags from the (longest) outer way. Imposm will insert the following relation as well:: + + + + ... + + + + + + + + + + + +Other relations +--------------- + +OpenStreetMap also uses relations to map more complex features. Some examples: + + - `Administrative areas `_ with boundaries, capitals and label positions. + - `Bus/tram/train routes `_ with the route itself, stops and platforms. + - `3D buildings `_ with multiple parts that should not be computed as holes. + +These relations can not be mapped to `simple` linestrings or polygons as they can contain a mix of different geometry types, or would result in invalid geometries (overlapping polygons). + +The Imposm table types ``relation`` and ``relation_member`` allow you to import all relevant data for these relations. + +``relation_member`` +^^^^^^^^^^^^^^^^^^^ + +The ``relation_member`` table type inserts each member of the relation as a separate row. The ``relation_member`` has access to the `role` and `type` value of each member. You can also import tags from the relation `and` from the member node, way or relation. + +Example +~~~~~~~ + +You can use the following mapping:: + + route_members: + type: relation_member + columns: + - name: osm_id + type: id + - name: member + type: relation_member_id + - name: index + type: relation_member_index + - name: role + type: relation_member_role + - name: type + type: relation_member_type + - name: geometry + type: geometry + - name: relname + key: name + type: string + - name: name + key: name + type: string + from_member: true + - key: ref + name: ref + type: string + mapping: + route: [bus] + + +to import a bus relation with stops, a platform and the route itself:: + + + + + + + + + + + + + + + + +This will result in seven rows with the following columns: + +======== ====================================================================================================================================================== +Column Description +======== ====================================================================================================================================================== +osm_id The ID of the relation. 100901 for all members. +member The ID of the member. 100101, 100102, etc. +index The index of the member. From 1 for 100101 to 7 for 100503. This can be used to query the bus stops in the correct order. +role The role of the member. ``stop``, ``platform``, etc. +type 0 for nodes, 1 for ways and 2 for other relations. +geometry The geometry of the member. Point for nodes and linestring for ways. +relname The value of the ``name`` tag of the relation. ``Bus 301: A => B`` in this case. +name The value of the ``name`` tag of the member element, if it has one. Note that the mapping contains ``from_member: true`` for this column. +ref The value of the ``ref`` tag of the relation. ``301`` in this case. +======== ====================================================================================================================================================== + + +You can insert the tags of the relation in a separate ``relation`` table to avoid duplication and then use `joins` when querying the data. +Both ``osm_id`` and ``relation_member_id`` columns are indexed in PostgreSQL by default to speed up these joins. + +``relation`` +^^^^^^^^^^^^ + +The ``relation`` table type inserts the mapped element regardless of the resulting geometry. For example, this allows you to create a table with the metadata (name, reference, operator, etc.) of all available route relations. The actual geometries need to be `joined` form the members. + +Example +~~~~~~~ + +The following mapping imports the bus route relation from above:: + + routes: + type: relation + columns: + - name: osm_id + type: id + - key: ref + name: ref + type: string + - name: network + key: network + type: string + mapping: + route: [bus] + + +This will create a single row with the mapped columns. + +.. note:: ``relation`` tables do not support geometry columns. Use the geometries of the members, or use a ``polygon`` table if your relations contain multipolygons. + +