Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: improvements to external storage documentation #1811

Merged
merged 5 commits into from
Sep 30, 2024
Merged

docs: improvements to external storage documentation #1811

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
3c8dfcd
docs: improvements to external storage documentation
aoles Jun 25, 2024
208729d
docs: apply suggestions from code review
aoles Jul 3, 2024
0b25887
docs: improvements to external storage documentation (continued)
aoles Sep 27, 2024
3fb0dab
chore: add changelog entry
aoles Sep 30, 2024
b4f17be
chore(config): automatic conversion of application.yml to ors-config.…
aoles Sep 30, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,7 @@ RELEASING:
### Added
### Changed
- refactor: cleanup routing profile management ([#1850](https://github.com/GIScience/openrouteservice/pull/1850)
- improved documentation on the configuration of external storages ([#1811](https://github.com/GIScience/openrouteservice/pull/1811)))
### Deprecated
### Removed
### Fixed
Expand Down
1 change: 1 addition & 0 deletions docs/api-reference/endpoints/directions/extra-info/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,7 @@ Some values are not available in all routing profiles:
| cycling-regular | x | x | x | x | x | | x | | | | | | |
| cycling-mountain | x | x | x | x | x | | x | | | | | | |
| cycling-road | x | x | x | x | x | | x | | | | | | |
| cycling-electric | x | x | x | x | x | | x | | | | | | |
| foot-walking | x | x | x | x | x | | x | | | | x | x | x |
| foot-hiking | x | x | x | x | x | | x | | | | x | x | x |
| wheelchair | x | x | x | x | x | | x | x | | | | | |
Expand Down
3 changes: 3 additions & 0 deletions docs/api-reference/endpoints/directions/routing-options.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,9 @@ With the request body parameter `options`, advanced routing options can be speci
The `options` parameter is a JSON object, multiple of the here mentioned parameters can be set.
For structure refer to the [examples](#examples).

::: warning
Some of the options below rely on auxiliary data included in the graph, see [External storages](../../../run-instance/configuration/ors/engine/profiles.md#ext_storages)
:::

## Available parameters

Expand Down
67 changes: 48 additions & 19 deletions docs/run-instance/configuration/ors/engine/profiles.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -160,28 +160,51 @@ Properties beneath `ors.engine.profiles.*.execution.methods.core`:

## ext_storages

For each profile it can be defined which external storages for extra info should be included in the graph.
This makes those information available as `extra_info` in a routing response.

It can be defined for each profile which auxiliary metadata should be included in the graph.
This information is made available as `extra_info` in a routing response.
To do so, add a key from the list below.
Leave its value empty, unless you want to specify further options (currently only available for
`RoadAccessRestrictions`, `Borders` and `Wheelchair`).

Properties beneath `ors.engine.profiles.*.ext_storages`:
[RoadAccessRestrictions](#roadaccessrestrictions), [Borders](#borders), [Wheelchair](#wheelchair) and [HeavyVehicle](#heavyvehicle)).

| key | type | description | example value |
|------------------------|--------|------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------|
| WayCategory | object | Returns the way category in the route response, Compatible for any profile type | |
| WaySurfaceType | object | Returns the way surface in the route response, Compatible for any profile type | |
| HillIndex | object | Returns the ascent/descent in the route response, Compatible for any profile type | |
| TrailDifficulty | object | Returns the trail difficulty in the route response, Compatible for profile-hiking | |
| RoadAccessRestrictions | object | RoadAccessRestrictions are where roads are restricted to certain vehicles to certain circumstances, e.g. access=destination. | [RoadAccessRestrictions](#roadaccessrestrictions) |
| Wheelchair | object | Compatible for wheelchair | [Wheelchair](#wheelchair) |
| OsmId | object | Returns the OsmId of the way, Compatible for wheelchair | |
| Borders | object | Borders allows the restriction of routes to not cross country borders, compatible for any profile type | [Borders](#borders) |
::: warning
In addition to providing the information in query response, data from `WayCategory` and `Tollways` storages is being
used to filter out certain roads via the
[`options.avoid_features`](../../../../api-reference/endpoints/directions/routing-options.md#options-avoid-features)
query parameter, and `Borders` is necessary for the functionality behind
[`options.avoid_borders`](../../../../api-reference/endpoints/directions/routing-options.md#options-avoid-borders) and
[`options.avoid_countries`](../../../../api-reference/endpoints/directions/routing-options.md#options-avoid-countries)
query parameters. Options from
[`options.profile_params.restrictions`](../../../../api-reference/endpoints/directions/routing-options.md#options-profile-params-restrictions)
require `HeavyVehicle` or `Wheelchair` storages being enabled. Furthermore, hgv profile-specific access restrictions specified in
[`options.vehicle_type`](../../../../api-reference/endpoints/directions/routing-options.md#options-vehicle-type) parameter
rely on the `HeavyVehicle` storage.
:::

Properties beneath `ors.engine.profiles.*.ext_storages`:

Have a look at [this table](../../../../api-reference/endpoints/directions/extra-info/index.md#extra-info-availability) to check which external storages are enabled for the which profile by default.
| key | type | description | example value |
|------------------------|--------|--------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------|
| WayCategory | object | Returns the way category in the route response, compatible with any profile type | |
| WaySurfaceType | object | Returns the way surface in the route response, compatible with any profile type | |
| Tollways | object | Returns way tolls in the route response, compatible with driving profiles | |
| Borders | object | Borders allows the restriction of routes to not cross country borders, compatible with any profile type | [Borders](#borders) |
| RoadAccessRestrictions | object | Information on restriction of roads to certain vehicles or circumstances, e.g. `access=destination` | [RoadAccessRestrictions](#roadaccessrestrictions) |
| HeavyVehicle | object | Heavy vehicle-specific storage compatible only with that profile; it contains weight and size limits as well as vehicle-type access restrictions | [HeavyVehicle](#heavyvehicle) |
| HillIndex | object | Returns the ascent/descent in the route response, compatible with any profile type | |
| TrailDifficulty | object | Returns the trail difficulty in the route response, compatible with walking and cycling profiles | |
| Wheelchair | object | Wheelchair-specific attributes compatible only with that profile | [Wheelchair](#wheelchair) |
| OsmId | object | Returns the OsmId of the way, compatible only with wheelchair profile | |

Check [this table](../../../../api-reference/endpoints/directions/extra-info/index.md#extra-info-availability) for extra info availability.
The following table summarizes which storages are enabled for which profile by default.

| | WayCategory | WaySurfaceType | Tollways | Borders | RoadAccessRestrictions | HeavyVehicle | HillIndex | TrailDifficulty | Wheelchair | OsmId |
|:------------|:-----------:|:--------------:|:--------:|---------|:----------------------:|:------------:|:---------:|:---------------:|:----------:|:-----:|
| driving-car | x | x | x | | x | | | | | |
| driving-hgv | x | x | x | | | x | | | | |
| cycling-* | x | x | | | | | x | x | | |
| foot-* | x | x | | | | | x | x | | |
| wheelchair | x | x | | | | | | | x | x |


### RoadAccessRestrictions
Expand All @@ -199,10 +222,16 @@ The `use_for_warnings` parameter tells the ors that this storage can be used for

### Borders

Properties beneath `ors.engine.profiles.*.ext_storages.Borders` allows to define restriction of routes to not cross country borders, compatible for any profile type.:
Properties beneath `ors.engine.profiles.*.ext_storages.Borders` allows to define restriction of routes to not cross country borders, compatible with any profile type.

| key | type | description | example value |
|-------------|--------|-----------------------------------------------------------------------------------------------------|--------------------------|
| boundaries | string | The path to a file containing geojson data representing the borders of countries | `borders.geojson.tar.gz` |
| boundaries | string | The path to a geojson file containing polygons representing country borders | `borders.geojson.tar.gz` |
| ids | string | Path to a csv file containing a unique id for each country, its local name and its English name | `ids.csv` |
| openborders | string | Path to a csv file containing pairs of countries where the borders are open (i.e. Schengen borders) | `openborders.csv` |

### HeavyVehicle

| key | type | description | example value |
|--------------|---------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------|
| restrictions | boolean | Encode certain size and weight limits such as ones contained in `maxheight`, `maxlength`, `maxwidth`, `maxweight` and `maxaxleload` OSM way tags. Includes also access restrictions for vehicles carrying hazardous materials as provided by the `hazmat` tag. | `true` |
2 changes: 2 additions & 0 deletions ors-api/src/main/resources/application.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -189,6 +189,7 @@ ors:
WayCategory:
HeavyVehicle:
WaySurfaceType:
Tollways:
RoadAccessRestrictions:
use_for_warnings: true
hgv:
Expand Down Expand Up @@ -219,6 +220,7 @@ ors:
HeavyVehicle:
restrictions: true
WaySurfaceType:
Tollways:
bike-regular:
profile: cycling-regular
encoder_options:
Expand Down
2 changes: 2 additions & 0 deletions ors-config.env
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -119,6 +119,7 @@ ors.engine.source_file=ors-api/src/test/files/heidelberg.osm.gz
#ors.engine.profiles.car.ext_storages.WayCategory=
#ors.engine.profiles.car.ext_storages.HeavyVehicle=
#ors.engine.profiles.car.ext_storages.WaySurfaceType=
#ors.engine.profiles.car.ext_storages.Tollways=
#ors.engine.profiles.car.ext_storages.RoadAccessRestrictions.use_for_warnings=true
ors.engine.profiles.car.enabled=true
#ors.engine.profiles.hgv.profile=driving-hgv
Expand All @@ -138,6 +139,7 @@ ors.engine.profiles.car.enabled=true
#ors.engine.profiles.hgv.ext_storages.WayCategory=
#ors.engine.profiles.hgv.ext_storages.HeavyVehicle.restrictions=true
#ors.engine.profiles.hgv.ext_storages.WaySurfaceType=
#ors.engine.profiles.hgv.ext_storages.Tollways=
#ors.engine.profiles.bike-regular.profile=cycling-regular
#ors.engine.profiles.bike-regular.encoder_options.consider_elevation=true
#ors.engine.profiles.bike-regular.encoder_options.turn_costs=true
Expand Down
2 changes: 2 additions & 0 deletions ors-config.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -182,6 +182,7 @@ ors:
# WayCategory:
# HeavyVehicle:
# WaySurfaceType:
# Tollways:
# RoadAccessRestrictions:
# use_for_warnings: true
enabled: true
Expand Down Expand Up @@ -213,6 +214,7 @@ ors:
# HeavyVehicle:
# restrictions: true
# WaySurfaceType:
# Tollways:
# bike-regular:
# profile: cycling-regular
# encoder_options:
Expand Down
Loading