Merge branch 'master' into patch-bkg-enforce-turn-cost

CHANGELOG.md

@@ -34,6 +34,30 @@ RELEASING:
  -->
 
 ## [Unreleased]
+### Added
+- backend documentation about encoded polylines without elevation data ([#1094](https://github.com/GIScience/openrouteservice/issues/1094))
+- python code on decoding polylines including elevation data
+- Czech language support (thanks to [trendspotter](https://github.com/trendspotter) for the translation)
+- Pedestrian and hiking support for time dependent routing
+- Esperanto language support (thanks to [ecxod](https://github.com/ecxod) for the translation)
+- Romanian language support (thanks to [ecxod](https://github.com/ecxod) for the translation)
+- link to YouTube docker setup guide to docs (thanks to SyntaxByte)
+- prototype of generic CSV-based routing to be used for heat stress
+- Shadow Routing 
+### Fixed
+- allow bridleways with bicycle=yes for bike profiles ([#1167](https://github.com/GIScience/openrouteservice/issues/1167))
+- improved log file settings error message ([#1110](https://github.com/GIScience/openrouteservice/issues/1110)) 
+- Dockerfile now creates intermediate directories if they are not present ([#1109](https://github.com/GIScience/openrouteservice/issues/1109))
+- internal properties of `IsochronesRequest` model not ignored for swagger file generation
+- remove non-parameter `metricsStrings` from API documentation ([#756](https://github.com/GIScience/openrouteservice/issues/756))
+- set default vehicle type for HGV profile ([#816](https://github.com/GIScience/openrouteservice/issues/816))
+- added missing matchTraffic override ([#1133](https://github.com/GIScience/openrouteservice/issues/1133))
+- typo in docker documentation
+- foot routing via `waterway=lock_gate` ([#1177](https://github.com/GIScience/openrouteservice/issues/1177))
+- graph builder for routing over open areas ([#1186](https://github.com/GIScience/openrouteservice/issues/1186))
+- address data alignment issue in hgv extended storage which occasionally caused `ArrayIndexOutOfBoundsException` ([#1181](https://github.com/GIScience/openrouteservice/issues/1181))
+- fix minor spelling errors in Places.md ([#1196](https://github.com/GIScience/openrouteservice/issues/1196))
+- address matrix failures for HGV profile ([#1198](https://github.com/GIScience/openrouteservice/issues/1198))
 
 ## [6.7.1] - 2022-10-05
 ### Added

Dockerfile

@@ -13,7 +13,7 @@ ARG TOMCAT_VERSION=8.5.69
 RUN useradd -u $UID -md /ors-core ors
 
 # Create directories
-RUN mkdir /usr/local/tomcat /ors-conf /var/log/ors && \
+RUN mkdir -p /usr/local/tomcat /ors-conf /var/log/ors && \
     chown ors:ors /usr/local/tomcat /ors-conf /var/log/ors
 
 # Install dependencies and locales

docs/Frequently-Asked-Questions.md

@@ -0,0 +1,78 @@
+---
+title: FAQ
+nav_order: 6
+has_toc: true
+---
+
+# Frequently Asked Questions
+ {: .no_toc }
+
+1. TOC
+{:toc}
+
+---
+
+## Why is my ors reporting `Could not find point`?
+
+This is a frequently encountered error message:
+```
+Could not find point 0: 25.3531986 51.5214311 within a radius of 350.0 meters.;
+Could not find point 1: 25.3524229 51.4627229 within a radius of 350.0 meters.
+```
+
+There are three main reasons for this problem, listed in order of most to least common.
+
+1. If both points are not found you probably just mixed up Lat and Long. Our
+   API expects coordinates in [lon,lat] order as described in our documentation
+   (check help button for parameter info). Output is also [lon,lat] as by the
+   GeoJSON Specification.
+
+2. The given start and endpoint are further than 350m away from any routable
+   road. The maximum distance for snapping to road segments in our API is 350m.
+ This can be customized for local installations via the
+  `maximum_snapping_radius` and `location_index_resolution` config-parameter. See
+  [configuration](Installation/Configuration) for details.
+
+3. The start and enpoint are passed with correct lon,lat-order and are within
+   350m of a routable road. This should only happen with a local installation.
+   Usually, this means that ors is trying to route in an area that graphs have not
+   been built for.
+   If routes in Heidelberg(Germany) can be found, the ors is still running on the
+   default dataset.
+
+---
+
+## When does the OSM data update in the openrouteservice?
+
+The openrouteservice builds its data from the `planet.osm.pbf`-files. According
+to [the osm-wiki](https://wiki.openstreetmap.org/wiki/Planet.osm), these files
+take two days to build and are updated weekly.
+
+Since the `planet`-files are rather large (currently over 60GB), there is a bit
+of work involved to make sure the download went right and the file is not
+corrupted in any way and in fact new. Parts of this process are in the hands of
+the OSM, parts are done by the openrouteservice.
+
+Once the newest `planet`-file is on the openrouteservice-servers, it needs to
+be preprocessed before the openrouteservice can start building the graphs used
+for routing.
+
+The build process in itself is [rather
+resource-intensive](Installation/System-Requirements). It takes roughly two
+days for any one of the nine profiles. For the mentioned resource requirements,
+this means that it will take roughly a week for all profiles to be re-built.
+
+Once the graphs are built, the production instances have to load them. Since
+this should happen in a low-traffic timeslot, it is also scheduled to happen
+once per week.
+
+To sum up: if you change anything in the OSM, it will therefore take roughly a
+week until it's included in the `planet`-file. This gets read once a week, the
+build takes a week and reloading graphs happens once a week.
+
+If everything aligns as it should, changes should be reflected in the
+openrouteservice within two to three weeks.
+
+If, however, anything goes wrong anywhere, this will usually mean a delay of at
+least a week, assuming it gets noticed and fixed immediately. It is no sign of
+concern, if changes are not reflected within a month.

docs/documentation/Geometry-Decoding.md

@@ -7,9 +7,11 @@ title: Geometry Decoding
 # Geometry Decoding
 {: .no_toc }
 
-When a response includes a geometry the data might be encoded as single string.
-When you request additional elevation data, this encoded string can not be decoded with a the standard polyline decoders available (e.g. from Mapbox).
-The reason for that is, that the elevation data is included (additionally to the lat & lng values).
+When a response includes a geometry the data might be encoded as single string. This is a so-called [encoded polyline](https://developers.google.com/maps/documentation/utilities/polylinealgorithm).
+If no additional elevation data is requested, this can be decoded with a standard polyline decoder, available e.g. from Mapbox or others.
+
+When you request additional elevation data, this encoded string can not be decoded with a standard polyline decoder.
+The reason for that is, that the elevation data is included in the polyline in addition to the latitude and longitude values.
 To decode _X,Y_ and _X,Y,Z_ polylines the decoder needs to know whether the geometry has elevation information.
 Examples on how to decode _X,Y,Z_ polylines can be found below:
 
@@ -139,3 +141,72 @@ public class GeometryDecoder {
     return points
   }
 ```
+
+## Python
+
+```python
+def decode_polyline(polyline, is3d=False):
+    """Decodes a Polyline string into a GeoJSON geometry.
+    :param polyline: An encoded polyline, only the geometry.
+    :type polyline: string
+    :param is3d: Specifies if geometry contains Z component.
+    :type is3d: boolean
+    :returns: GeoJSON Linestring geometry
+    :rtype: dict
+    """
+    points = []
+    index = lat = lng = z = 0
+
+    while index < len(polyline):
+        result = 1
+        shift = 0
+        while True:
+            b = ord(polyline[index]) - 63 - 1
+            index += 1
+            result += b << shift
+            shift += 5
+            if b < 0x1F:
+                break
+        lat += (~result >> 1) if (result & 1) != 0 else (result >> 1)
+
+        result = 1
+        shift = 0
+        while True:
+            b = ord(polyline[index]) - 63 - 1
+            index += 1
+            result += b << shift
+            shift += 5
+            if b < 0x1F:
+                break
+        lng += ~(result >> 1) if (result & 1) != 0 else (result >> 1)
+
+        if is3d:
+            result = 1
+            shift = 0
+            while True:
+                b = ord(polyline[index]) - 63 - 1
+                index += 1
+                result += b << shift
+                shift += 5
+                if b < 0x1F:
+                    break
+            if (result & 1) != 0:
+                z += ~(result >> 1)
+            else:
+                z += result >> 1
+
+            points.append(
+                [
+                    round(lng * 1e-5, 6),
+                    round(lat * 1e-5, 6),
+                    round(z * 1e-2, 1),
+                ]
+            )
+
+        else:
+            points.append([round(lng * 1e-5, 6), round(lat * 1e-5, 6)])
+
+    geojson = {u"type": u"LineString", u"coordinates": points}
+
+    return geojson
+```

docs/documentation/Places.md

@@ -14,7 +14,7 @@ Category groups
 
 |                             Name                             | Value |
 |:------------------------------------------------------------:|:-----:|
-| [accomodation](#accomodation--100)                           | 100   |
+| [accommodation](#accommodation--100)                         | 100   |
 | [animals](#animals--120)                                     | 120   |
 | [arts_and_culture](#arts_and_culture--130)                   | 130   |
 | [education](#education--150)                                 | 150   |
@@ -35,12 +35,12 @@ Category groups
 
 Categories listed by group
 
-### accomodation : 100
+### accommodation : 100
 
 |      Name      | Value |
 |:--------------:|:-----:|
 | alpine_hut     | 101   |
-| apparmtent     | 102   |
+| apartment      | 102   |
 | camp_site      | 103   |
 | caravan_site   | 104   |
 | chalet         | 105   |
@@ -77,7 +77,7 @@ Categories listed by group
 | college        | 151   |
 | driving_school | 152   |
 | kindergarten   | 153   |
-| lanuage_school | 154   |
+| language_school| 154   |
 | music_school   | 155   |
 | school         | 156   |
 | university     | 157   |
@@ -206,15 +206,15 @@ Categories listed by group
 |        Name       | Value | Name             | Value | Name                | Value | Name                  | Value | Name          | Value | Name            | Value |
 |:-----------------:|:-----:|------------------|-------|---------------------|-------|-----------------------|-------|---------------|-------|-----------------|-------|
 | agrarian          | 421   | curtain          | 441   | e-cigarette         | 461   | hifi                  | 481   | optician      | 502   | tiles           | 522   |
-| alkohol           | 422   | cheese           | 442   | farm                | 462   | houseware             | 482   | organic       | 503   | tobacco         | 523   |
+| alcohol           | 422   | cheese           | 442   | farm                | 462   | houseware             | 482   | organic       | 503   | tobacco         | 523   |
 | antiques          | 423   | chemist          | 443   | fashion             | 463   | hunting               | 483   | outdoor       | 504   | toys            | 524   |
 | art               | 424   | chocolate        | 444   | fishing             | 464   | jewelry               | 485   | paint         | 505   | trophy          | 525   |
 | bag               | 425   | clock            | 445   | florist             | 465   | leather               | 486   | pastry        | 506   | tyres           | 526   |
 | bakery            | 426   | clocks           | 446   | funeral_directors   | 466   | locksmith             | 487   | perfumery     | 507   | variety_store   | 527   |
 | bed               | 427   | clothes          | 447   | furniture           | 467   | kiosk                 | 488   | photo         | 508   | vending_machine | 528   |
 | beverages         | 428   | coffee           | 448   | games               | 468   | kitchen               | 489   | pyrotechnics  | 509   | video           | 529   |
 | bicycle           | 429   | computer         | 449   | garden_centre       | 469   | lamps                 | 490   | radiotechnics | 510   | video_games     | 530   |
-| books             | 430   | confectionery    | 450   | garden_furniture    | 470   | lottery               | 491   | seefood       | 511   | watches         | 531   |
+| books             | 430   | confectionery    | 450   | garden_furniture    | 470   | lottery               | 491   | seafood       | 511   | watches         | 531   |
 | boutique          | 431   | convenience      | 451   | gas                 | 471   | mall                  | 492   | second_hand   | 512   | weapons         | 532   |
 | brewing_supplies  | 432   | copyshop         | 452   | general             | 472   | marketplace           | 493   | security      | 513   | wine            | 533   |
 | business_machines | 433   | cosmetics        | 453   | gift                | 473   | medical_supply        | 494   | shoes         | 514   |                 |       |

docs/index.md

@@ -40,6 +40,7 @@ If that doesn't work, the sidebar has you covered:
   [translations](contributing/Contributing-Translations)
 * [Documentation](documentation/Documentation) contains all sorts of
   explanation about the internal workings of the openrouteservice.
+* [FAQ](Frequently-Asked-Questions) contains answers to frequently asked questions.
 
 If you prefer a dark theme, click on the *dark* button next to the search bar.
 

docs/installation/Advanced-Docker-Setup.md

@@ -49,7 +49,7 @@ To change the OSM data that is used, you need to uncomment out the following lin
 ```
 and then modify the `./your_osm.pbf` part to point to the osm file that you want to use. This will tell docker to overwrite the current osm file in the container with the one that you are providing. 
 
-One thing to be aware of is the size of the data and how much RAM is given to Java inside the container. We generally [recommend](System-Requirements) at least twice the amount of RAM as the file size, but to tell Java this, you need to update the `JAVA_OPTS` in the `environment` section of the `docker-compose` file. In that line, you will see the `-Xmx1g` and `-Xmx2g` items. These tell Java that it should start with 1GB RAM assigned to it, and go no higher than 2 GB of usage. If your pbf file is 1.5 GB in size then you would update the `-Xmx` item to be **AT LEAST** `-Xmx3g`. In general, we would recommend adding a bit more to the RAM value if possible to reduce the chances of hitting an out of memory exception towards the end of the graph building.
+One thing to be aware of is the size of the data and how much RAM is given to Java inside the container. We generally [recommend](System-Requirements) at least twice the amount of RAM as the file size, but to tell Java this, you need to update the `JAVA_OPTS` in the `environment` section of the `docker-compose` file. In that line, you will see the `-Xms1g` and `-Xmx2g` items. These tell Java that it should start with 1GB RAM assigned to it, and go no higher than 2 GB of usage. If your pbf file is 1.5 GB in size then you would update the `-Xmx` item to be **AT LEAST** `-Xmx3g`. In general, we would recommend adding a bit more to the RAM value if possible to reduce the chances of hitting an out of memory exception towards the end of the graph building.
 
 To change any configuration settings, all you need to do is modify the `ors-config.json` file found in the `conf` folder and then restart the container as mentioned above. There are a number of configurations that can be changed, with information available on the [configuration wiki page](Configuration) about what each of these are. As a quick example, by default the openrouteservice docker container only builds the car profile. If you want to add another profile, for example the hiking profile, all you need to do is modify the
 ```json

docs/installation/Building-from-Source.md

@@ -53,7 +53,7 @@ To run the project from within your IDE, you have to:
      For IntelliJ Idea, have a look at [these instructions](Opening-Project-in-IntelliJ).
 
   2. Configure your IDE to run `tomcat7:run-war` as the maven goal, setting the
-     environment variable `ORS_CONIFG=ors-config-test.json`.
+     environment variable `ORS_CONFIG=ors-config-test.json`.
 
   3. You can run API tests via JUnit.
 

docs/installation/Running-with-Docker.md

@@ -8,6 +8,8 @@ title: Running with Docker
 
 ## Install and run openrouteservice with docker
 
+> For a step by step guide check out [this YouTube video](https://www.youtube.com/watch?v=VQXlbqKArFk) (Thanks a lot SyntaxByte <3).
+
 Installing the openrouteservice backend service with Docker is quite straightforward. All you need is an OSM extract, e.g. from [Geofabrik](http://download.geofabrik.de), and a working [docker installation](https://www.digitalocean.com/community/tutorial_collections/how-to-install-and-use-docker).
 
 Use [Dockerhub's hosted Openrouteservice image](https://hub.docker.com/r/openrouteservice/openrouteservice) or build your own image

openrouteservice-api-tests/conf/ors-config-test.json

@@ -347,6 +347,12 @@
                 "NoiseIndex": {
                   "filepath": "openrouteservice-api-tests/data/noise_data_hd.csv"
                 },
+                "csv": {
+                     "filepath": "openrouteservice-api-tests/data/csv_data_hd.csv"
+                },
+                "ShadowIndex": {
+                  "filepath": "openrouteservice-api-tests/data/shadow_index_hd.csv"
+                },
                 "WayCategory": {},
                 "WaySurfaceType": {},
                 "HillIndex": {},
@@ -367,6 +373,9 @@
                 "NoiseIndex": {
                   "filepath": "openrouteservice-api-tests/data/noise_data_hd.csv"
                 },
+                "ShadowIndex": {
+                  "filepath": "openrouteservice-api-tests/data/shadow_index_hd.csv"
+                },
                 "WayCategory": {},
                 "WaySurfaceType": {},
                 "HillIndex": {},