Skip to content

Commit

Permalink
add section about geometry building to manual
Browse files Browse the repository at this point in the history
  • Loading branch information
tyrasd committed Dec 22, 2021
1 parent ae0e7bb commit 64bc0d8
Show file tree
Hide file tree
Showing 5 changed files with 31 additions and 3 deletions.
1 change: 1 addition & 0 deletions documentation/manual/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@ Contents
* [OSHDB API Manual](api.md) <br>
Shows the different features of the OSHDB API and how they can be used to efficiently query the OSM history data.
* [Data Views](views.md)
* [OSM Feature Geometries](geometries.md)
* [Filtering of OSM data](filters.md)
* [Map and Reduce](map-reduce.md)
* [Data Aggregation](aggregation.md)
Expand Down
1 change: 1 addition & 0 deletions documentation/manual/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ The OSHDB API provides a library that can be used to write custom analysis queri
The [first steps tutorial](../first-steps) explains the main components of the OSHDB API and how they can be used to perform a simple analysis query. On the following sub-pages, the different parts of the API are described in more detail.

* [Data Views](views.md)
* [OSM Feature Geometries](geometries.md)
* [Filtering of OSM data](filters.md)
* [Map and Reduce](map-reduce.md)
* [Data Aggregation](aggregation.md)
Expand Down
4 changes: 2 additions & 2 deletions documentation/manual/filters.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,9 +15,9 @@ The output of this filter will keep only OSM entities whose geometry lie within

> For example, a large forest polygon in OSM that completely encompasses a small area of interest _is_ returned by the OSHDB API.
The resulting geometries produced by the different OSHDB [views](views.md) are by default clipped to the specified area of interest. This makes it possible to directly calculate the length or area of linear or polygonal OSM features within the given query region, without having to consider the fact that some features might only partially lie within the region. It is, at the same time, still possible to access full extent of the respective OSM features' [unclipped](https://docs.ohsome.org/java/oshdb/0.7.2/aggregated/org/heigit/ohsome/oshdb/util/mappable/OSMEntitySnapshot.html#getGeometryUnclipped()) [geometries](https://docs.ohsome.org/java/oshdb/0.7.2/aggregated/org/heigit/ohsome/oshdb/util/mappable/OSMContribution.html#getGeometryUnclippedBefore()).
The resulting geometries produced by the different OSHDB [views](views.md) are by default clipped to the specified area of interest. This makes it possible to directly calculate the length or area of linear or polygonal OSM features within the given query region, without having to consider the fact that some features might only partially lie within the region. It is, at the same time, still possible to access full extent of the respective OSM features' [unclipped](https://docs.ohsome.org/java/oshdb/0.7.2/aggregated/org/heigit/ohsome/oshdb/util/mappable/OSMEntitySnapshot.html#getGeometryUnclipped()) [geometries](https://docs.ohsome.org/java/oshdb/0.7.2/aggregated/org/heigit/ohsome/oshdb/util/mappable/OSMContribution.html#getGeometryUnclippedBefore()). You can find further information in the section about how the OSHDB [builds geometries](geometries.md) from OSM data.

The OSHDB is able to cope well even with complex polygons that have many vertices, but keep in mind that using simpler geometries will generally result in higher query performance: For example a bounding-box query is executed slightly faster than a polygon-areaOfInterest query with a rectangular polygon.
The OSHDB is able to cope well even with complex polygons that have many vertices as areas of interest, but keep in mind that using simpler geometries will generally result in higher query performance: For example a bounding-box query is executed slightly faster than a polygon-areaOfInterest query with a rectangular polygon.

<!-- todo: link to blog post with spatial filtering performance benchmarks -->

Expand Down
26 changes: 26 additions & 0 deletions documentation/manual/geometries.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
OSM Feature Geometries
======================

The [_views_](views.md) provided by the OSHDB API provide direct access to the OSM entities, but also allow to get the [JTS](https://en.wikipedia.org/wiki/JTS_Topology_Suite#Geometry_model) [geometries](https://locationtech.github.io/jts/javadoc/org/locationtech/jts/geom/Geometry.html) of the OSM features corresponding to their state at the requested _snapshot_ or _contribution_ time(s). With this geometry, further operations such as [_filtering_](filters.md#areaOfInterest) or [_aggregation_](aggregation.md#aggregateByGeometry) can be performed. It is also irreplaceable during the [_map-reduce_](map-reduce.md#geometry-helpers) step to generate useful results, such as the length of a road network for example.

For some OSM elements, such as nodes, generating geometries is straight forward, for others the conversion requires further knowledge of the [data model](https://wiki.openstreetmap.org/wiki/Elements) and [tagging schema](https://wiki.openstreetmap.org/wiki/Tags) used by OSM. The following document gives an overview of how the OSHDB handles the building of geometries of different OSM object types.

Nodes
-----

Nodes are always presented as [`Point`](https://locationtech.github.io/jts/javadoc/org/locationtech/jts/geom/Point.html)s. Note that nodes which have never had a tag and are a part of a way or relation are considered to be structural-only points (sometimes called _vertices_), and thus not returned in an OSHDB query when querying all nodes. This is because the OSHDB does not consider them to not be _map features_ by their own. They can however be fetched as members of their parent way or relation objects, if needed.

Ways
----

Ways are converted to either [`LineString`](https://locationtech.github.io/jts/javadoc/org/locationtech/jts/geom/LineString.html) or [`Polygon`](https://locationtech.github.io/jts/javadoc/org/locationtech/jts/geom/Polygon.html) geometries depending on their composition and their tags: A not closed way is always represented as a line, while it depends for a closed one. The [`TagInterpreter`](https://docs.ohsome.org/java/oshdb/0.7.2/aggregated/org/heigit/ohsome/oshdb/util/taginterpreter/TagInterpreter.html) component of the OSHDB is responsible for deciding whether a closed way results in a line or a polygon: A (closed) OSM way with the tag `building=yes` will be converted to a polygon geometry, while a `junction=roundabout` one will not.

Relations
---------

Relations are handled by the OSHDB in two different ways: [Multipolygons](https://wiki.openstreetmap.org/wiki/Multipolygon) are converted to either [`Polygon`](https://locationtech.github.io/jts/javadoc/org/locationtech/jts/geom/Polygon.html) or [`MultiPolygon`](https://locationtech.github.io/jts/javadoc/org/locationtech/jts/geom/MultiPolygon.html) geometries (depending on the number of outer rings), while all [other relation types](https://wiki.openstreetmap.org/wiki/Types_of_relation) result in a [`GeometryCollection`](https://locationtech.github.io/jts/javadoc/org/locationtech/jts/geom/GeometryCollection.html).

Invalid OSM Data
----------------

There are situations where a part of OSM's entities have either incomplete or invalid data, for example a broken multipolygon resulting from a mapping error. The OSHDB makes the best effort to return a (potentially [invalid](https://locationtech.github.io/jts/javadoc/org/locationtech/jts/geom/Geometry.html#isValid--)) geometry also for these objects. For performance reasons the OSHDB cannot check for every possible error in the input (OSM) data, and for similar reasons it also cannot correct all errors it does find. This means that the OSHDB does not provide any guaranteed outcome for all possible errors and might return an invalid or valid geometry as a result in such cases or even no result at all.
2 changes: 1 addition & 1 deletion documentation/manual/views.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
Views
=====

Two different ways of querying OSM data are available, which determine how the OSM history data is actually analyzed in a given OSHDB query:
Two different ways of querying OSM data are available, which determine how the OSM history data is actually analyzed in a given OSHDB query:

* The **snapshot view** ([`OSMEntitySnapshotView`](https://docs.ohsome.org/java/oshdb/0.7.2/aggregated/org/heigit/ohsome/oshdb/api/mapreducer/OSMEntitySnapshotView.html)) returns the state of the OSM history data at specific given points in time.
* The **contribution view** ([`OSMContributionView`](https://docs.ohsome.org/java/oshdb/0.7.2/aggregated/org/heigit/ohsome/oshdb/api/mapreducer/OSMContributionView.html)) returns all modifications (e.g., creations, modifications or deletions) to the OSM elements within a given time period.
Expand Down

0 comments on commit 64bc0d8

Please sign in to comment.