Skip to content

Commit fab4e0b

Browse files
takbtakb
committed
docs: custom model description
1 parent 2517480 commit fab4e0b

File tree

2 files changed

+200
-14
lines changed

2 files changed

+200
-14
lines changed

‎docs/api-reference/endpoints/directions/custom-models.md

+199-13
Original file line numberDiff line numberDiff line change
@@ -4,12 +4,17 @@ The request body parameter `custom_model` allows setting specific parameters inf
44
route calculation.
55

66
This parameter is available for directions requests only on profiles that have been created using the required encoder
7-
option set at graph build time. **This feature is still in experimental stat and is currently not available on our public API for any profile**. You can use this feature on your [own openrouteservice instance](/run-instance/) by [enabling it for the profile](/run-instance/configuration/engine/profiles/build.md#encoder-options) in the `encoder_options`.
7+
option set at graph build time. **This feature is still in experimental state and is currently not available on our
8+
public API for any profile**. You can use this feature on your [own openrouteservice instance](/run-instance/)
9+
by [enabling it for the profile](/run-instance/configuration/engine/profiles/build.md#encoder-options) in the
10+
`encoder_options`.
811

9-
The `custom_model` parameter is a JSON object, the following example shows the structure:
12+
The `custom_model` parameter is a JSON object, the following example shows the structure within a request body for the
13+
directions endpoint:
1014

1115
```json
1216
{
17+
"preference": "custom",
1318
"coordinates": [
1419
[
1520
8.681495,
@@ -40,16 +45,180 @@ The `custom_model` parameter is a JSON object, the following example shows the s
4045

4146
## Available parameters
4247

43-
| Parameter | Type | Description |
44-
|----------------------|--------|-------------|
45-
| `distance_influence` | Number | |
46-
| `speed` | Array | |
47-
| `priority` | Array | |
48-
| `areas` | Array | |
48+
| Parameter | Type | Description |
49+
|----------------------|--------|----------------------------------------------------------------------------------------------|
50+
| `distance_influence` | Number | Time in seconds to require for each kilometer of [detour accepted](#weighting-function) |
51+
| `speed` | Array | Set of [rules](#speed-and-priority-rules) determining [speed factor](#weighting-function) |
52+
| `priority` | Array | Set of [rules](#speed-and-priority-rules) determining [priority factor](#weighting-function) |
53+
| `areas` | Object | Map of [geojson features](#areas) used in area-based [rules](#speed-and-priority-rules) |
4954

50-
## Examples
55+
## Basic principle
5156

52-
### general speed limit of 80 km/h, e.g. for car profiles
57+
Custom models invoke a special weighting function for each edge in the graph and replaces the `shortest` or `fastest`
58+
weightings normally used during calculations with a combined weighting function that takes into account the custom model
59+
parameters.
60+
61+
The priority weightings of openrouteservice for foot and bike profiles (that represent preference of designated
62+
footpaths or designated bicycle paths over car roads and so on) can be combined "on top" of the custom model weighting.
63+
Therefore, possible values for the `preference` parameter of a route request with a custom model are `custom` and
64+
`recommended`. If a request is made with the `shortest` or `fastest` preference AND a custom model value, the preference
65+
value will be IGNORED.
66+
67+
## Weighting function
68+
69+
The weighting function for each edge is calculated as follows:
70+
71+
```
72+
weight = [edge distance] / ([edge speed] * speed * priority) + [edge distance] * distance_influence
73+
```
74+
75+
where `speed`, `priority` and `distance_influence` are the values derived from the custom model, and `[edge distance]`
76+
and `[edge speed]` are valued stored in the graph.
77+
78+
The `distance_influence` parameter is a factor that influences the weight of the edge based on the travel distance. If
79+
set to zero, the distance will not be taken into account in the weighting function. If set to a value greater than zero,
80+
the distance will be multiplied by this factor before being added to the weight. The result of this is that a ratio of
81+
preference between distance and speed can be set. The value provided in the custom model is used such that it
82+
corresponds to the required time saved in seconds per kilometer of detour. If you e.g. set a value of `60`, that means a
83+
faster route by travel time is only returned if it saves at least a minute for every additional kilometer of distance
84+
travelled, therefore a detour to take the highway instead of ordinary roads that adds, say, 2 kilometers, is only
85+
returned as "better" route if this saves at least 2 minutes of time.
86+
87+
The factors `speed` and `priority` are multiplied with the edge speed. Both are calculated based on the rules provided
88+
in the custom model, the difference being that the `speed` factor also changes the travel time computation, while the
89+
`priority` factor is only used to influence the weight of the edge during route computation and does not change the
90+
travel time. Both parameters expect an array of objects, where each object is a rule consisting of a condition and an
91+
operation to be applied. These are described in more detail in the next section.
92+
93+
## Speed and Priority Rules
94+
95+
The parameters `speed` and `priority` are arrays of rules that are applied to the edge speed and priority, respectively.
96+
All rules within the arrays are applied in the order they are provided. Rules are defined as objects of the following
97+
structure:
98+
99+
```json
100+
{
101+
"condition_key": "condition_value",
102+
"operation_key": "operation_value"
103+
}
104+
```
105+
106+
### Operations
107+
108+
The `operation_key` is a string with two possible values. The `operation_value` is a number.
109+
110+
| `operation_key` | `operation_value` |
111+
|-----------------|-------------------------------------------------------------|
112+
| `multiply_by` | Factor to multiply with travel speed, e.g. `0`, `0.5`, etc. |
113+
| `limit_to` | Speed limit in km/h, e.g. `70` |
114+
115+
If the key is `multiply_by`, the value is interpreted as a factor that gets multiplied to the speed stored on the edge
116+
for determining the weight of the edge.
117+
118+
If the rule is in the `speed` array, the factor is also applied to the speed value used in the travel time calculation,
119+
so a value of `0.5` would mean to travel at half the normal speed on the affected edges.
120+
121+
If the rule is in the `priority` array, the factor is only applied to the weight of the edge, not to the time
122+
calculation, and you can think of the number as a factor determining how favorable the affected edge is. A `0` would
123+
mean to avoid the edge completely, a `1` would mean indeterminate; any number in between can denote degrees of
124+
favorability, smaller numbers meaning less favorable.
125+
126+
If the key is `limit_to`, the value is interpreted as a maximum speed that can be travelled on the affected edges. Edges
127+
with a lower travel speed stored in the graph will not be affected by this rule.
128+
129+
### Conditions
130+
131+
The `condition_key` is a string with the possible values `if`, `else_if` and `else`. `else_if` and `else` require a
132+
preceding rule with `if`, `else_if` as condition key, and are applied only if the preceding rule's condition did NOT
133+
match.
134+
135+
The `condition_value` can be a string or boolean value. If it is a string, it can either have the form
136+
`in_[AREA_NAME]` (see [section below](#areas) for details) OR describe a logical statement that can evaluate as true or
137+
false. The logical statement can be a simple comparison of a variable and a value, e.g. `road_class == MOTORWAY`, or a
138+
more complex statement using Java boolean operators, e.g. `max_width <= 2.2 && (road_environment == TUNNEL || roundabout)`.
139+
140+
The variables that can be used in those statements are called 'encoded values', and different ones are available for
141+
different profiles. The available encoded values can be found in the response to the `status` endpoint, in the array
142+
`profiles.<PROFILE NAME>.encoded_values`. Below is a list of example 'encoded values' and their possible values that are
143+
available. Note that this list is incomplete and the available variables depend on the profile in question.
144+
145+
| name | Type | Description |
146+
|--------------------|-----------|---------------------------------------------------------------------------|
147+
| `road_class` | Enum | MOTORWAY, TRUNK, PRIMARY, SECONDARY, TRACK, STEPS, CYCLEWAY, FOOTWAY, ... |
148+
| `road_environment` | Enum | ROAD, FERRY, BRIDGE, TUNNEL, ... |
149+
| `road_access` | Enum | DESTINATION, DELIVERY, PRIVATE, NO, ... |
150+
| `surface` | Enum | PAVED, DIRT, SAND, GRAVEL, ... |
151+
| `smoothness` | Enum | EXCELLENT, GOOD, INTERMEDIATE, ... |
152+
| `toll` | Enum | NO, ALL, HGV |
153+
| `roundabout` | Boolean | Whether edge is part of a roundabout |
154+
| `get_off_bike` | Boolean | Whether edge is marked as "requiring to get off bike" |
155+
| `max_speed` | Numerical | Max speed in km/h |
156+
| `max_height` | Numerical | Max height in m |
157+
| `max_width` | Numerical | Max width in m |
158+
159+
Enum type encoded values can be used with the `==` and `!=` operators, while numerical encoded values can be used with the
160+
`==`, `!=`, `<`, `<=`, `>`, `>=` operators. Boolean encoded valued do not require an operator, but can be used with the
161+
`==`, `!=` and `!` operators.
162+
163+
### Areas
164+
165+
Area-based rules are defined by using a `condition_value` in the form `in_[AREA_NAME]` in the `priority` ond/or `speed`
166+
arrays and providing a corresponding named object in the `areas` object of the custom model.
167+
168+
Each area object is required to be a GeoJSON `Feature` object. The `bbox` member and other foreign members such as
169+
`properties` are NOT supported. The `geometry` member of the feature object must be of `"type": "Polygon"`.
170+
171+
The following is an example of a custom model with an area-based rule that sets the priority to zero (avoid completely)
172+
for all edges within the area defined by the polygon:
173+
174+
```json
175+
{
176+
"priority": [
177+
{
178+
"if": "in_custom_area_1",
179+
"multiply_by": 0
180+
}
181+
],
182+
"areas": {
183+
"custom_area_1": {
184+
"type": "Feature",
185+
"geometry": {
186+
"type": "Polygon",
187+
"coordinates": [
188+
[
189+
[
190+
8.7062144,
191+
49.4077481
192+
],
193+
[
194+
8.7068045,
195+
49.4108196
196+
],
197+
[
198+
8.7132203,
199+
49.4117201
200+
],
201+
[
202+
8.7139713,
203+
49.4084322
204+
],
205+
[
206+
8.7062144,
207+
49.4077481
208+
]
209+
]
210+
]
211+
}
212+
}
213+
}
214+
}
215+
```
216+
217+
## Further Examples
218+
219+
Below are some examples of custom models that illustrate how the `custom_model` parameter can be used.
220+
221+
#### A general speed limit of 80 km/h, e.g. for car profiles
53222

54223
```json
55224
{
@@ -62,15 +231,32 @@ The `custom_model` parameter is a JSON object, the following example shows the s
62231
}
63232
```
64233

65-
### avoid motorways and tunnels
234+
#### Try to avoid motorways and tunnels (even more), avoid applying both rules to motorways within tunnels
66235

67236
```json
68237
{
69238
"priority": [
70239
{
71-
"if": "road_class == PRIMARY || road_environment == TUNNEL",
240+
"if": "road_class == MOTORWAY",
72241
"multiply_by": 0.7
242+
},
243+
{
244+
"else_if": "road_environment == TUNNEL",
245+
"multiply_by": 0.5
73246
}
74247
]
75248
}
76-
```
249+
```
250+
251+
#### Avoid having to get off the bike
252+
253+
```json
254+
{
255+
"priority": [
256+
{
257+
"if": "get_off_bike",
258+
"multiply_by": 0
259+
}
260+
]
261+
}
262+
```

‎docs/run-instance/configuration/engine/profiles/service.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ need to be set specifically for each profile. More parameters relevant at query
1616
| maximum_snapping_radius | number | Maximum distance around a given coordinate to find connectable edges | `400` |
1717
| maximum_visited_nodes | number | Only for `public-transport` profile: maximum allowed number of visited nodes in shortest path computation | `1000000` |
1818
| force_turn_costs | boolean | Should turn restrictions be obeyed | `false` |
19-
| allow_custom_models | boolean | Allows custom model requests on this profile. Requires that `encoder_options.enable_custom_models` is set to true in the [build](build.md#encoder_options) section of this profile. | `false` |
19+
| allow_custom_models | boolean | Allows custom model requests on this profile. Requires that `encoder_options.enable_custom_models` is set to true in the [build](build.md#encoder_options) section of this profile. | `true` |
2020
| execution | object | [Execution settings](#execution) relevant when querying services | |
2121

2222
## `execution`

0 commit comments

Comments
 (0)