Skip to content

Commit

Permalink
docs: custom model description
Browse files Browse the repository at this point in the history
  • Loading branch information
@takb
takb committed Jan 27, 2025
1 parent 2517480 commit fab4e0b
Show file tree
Hide file tree
Showing 2 changed files with 200 additions and 14 deletions.
212 changes: 199 additions & 13 deletions docs/api-reference/endpoints/directions/custom-models.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,12 +4,17 @@ The request body parameter `custom_model` allows setting specific parameters inf
route calculation.

This parameter is available for directions requests only on profiles that have been created using the required encoder
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`.
option set at graph build time. **This feature is still in experimental state 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`.

The `custom_model` parameter is a JSON object, the following example shows the structure:
The `custom_model` parameter is a JSON object, the following example shows the structure within a request body for the
directions endpoint:

```json
{
"preference": "custom",
"coordinates": [
[
8.681495,
Expand Down Expand Up @@ -40,16 +45,180 @@ The `custom_model` parameter is a JSON object, the following example shows the s

## Available parameters

| Parameter | Type | Description |
|----------------------|--------|-------------|
| `distance_influence` | Number | |
| `speed` | Array | |
| `priority` | Array | |
| `areas` | Array | |
| Parameter | Type | Description |
|----------------------|--------|----------------------------------------------------------------------------------------------|
| `distance_influence` | Number | Time in seconds to require for each kilometer of [detour accepted](#weighting-function) |
| `speed` | Array | Set of [rules](#speed-and-priority-rules) determining [speed factor](#weighting-function) |
| `priority` | Array | Set of [rules](#speed-and-priority-rules) determining [priority factor](#weighting-function) |
| `areas` | Object | Map of [geojson features](#areas) used in area-based [rules](#speed-and-priority-rules) |

## Examples
## Basic principle

### general speed limit of 80 km/h, e.g. for car profiles
Custom models invoke a special weighting function for each edge in the graph and replaces the `shortest` or `fastest`
weightings normally used during calculations with a combined weighting function that takes into account the custom model
parameters.

The priority weightings of openrouteservice for foot and bike profiles (that represent preference of designated
footpaths or designated bicycle paths over car roads and so on) can be combined "on top" of the custom model weighting.
Therefore, possible values for the `preference` parameter of a route request with a custom model are `custom` and
`recommended`. If a request is made with the `shortest` or `fastest` preference AND a custom model value, the preference
value will be IGNORED.

## Weighting function

The weighting function for each edge is calculated as follows:

```
weight = [edge distance] / ([edge speed] * speed * priority) + [edge distance] * distance_influence
```

where `speed`, `priority` and `distance_influence` are the values derived from the custom model, and `[edge distance]`
and `[edge speed]` are valued stored in the graph.

The `distance_influence` parameter is a factor that influences the weight of the edge based on the travel distance. If
set to zero, the distance will not be taken into account in the weighting function. If set to a value greater than zero,
the distance will be multiplied by this factor before being added to the weight. The result of this is that a ratio of
preference between distance and speed can be set. The value provided in the custom model is used such that it
corresponds to the required time saved in seconds per kilometer of detour. If you e.g. set a value of `60`, that means a
faster route by travel time is only returned if it saves at least a minute for every additional kilometer of distance
travelled, therefore a detour to take the highway instead of ordinary roads that adds, say, 2 kilometers, is only
returned as "better" route if this saves at least 2 minutes of time.

The factors `speed` and `priority` are multiplied with the edge speed. Both are calculated based on the rules provided
in the custom model, the difference being that the `speed` factor also changes the travel time computation, while the
`priority` factor is only used to influence the weight of the edge during route computation and does not change the
travel time. Both parameters expect an array of objects, where each object is a rule consisting of a condition and an
operation to be applied. These are described in more detail in the next section.

## Speed and Priority Rules

The parameters `speed` and `priority` are arrays of rules that are applied to the edge speed and priority, respectively.
All rules within the arrays are applied in the order they are provided. Rules are defined as objects of the following
structure:

```json
{
"condition_key": "condition_value",
"operation_key": "operation_value"
}
```

### Operations

The `operation_key` is a string with two possible values. The `operation_value` is a number.

| `operation_key` | `operation_value` |
|-----------------|-------------------------------------------------------------|
| `multiply_by` | Factor to multiply with travel speed, e.g. `0`, `0.5`, etc. |
| `limit_to` | Speed limit in km/h, e.g. `70` |

If the key is `multiply_by`, the value is interpreted as a factor that gets multiplied to the speed stored on the edge
for determining the weight of the edge.

If the rule is in the `speed` array, the factor is also applied to the speed value used in the travel time calculation,
so a value of `0.5` would mean to travel at half the normal speed on the affected edges.

If the rule is in the `priority` array, the factor is only applied to the weight of the edge, not to the time
calculation, and you can think of the number as a factor determining how favorable the affected edge is. A `0` would
mean to avoid the edge completely, a `1` would mean indeterminate; any number in between can denote degrees of
favorability, smaller numbers meaning less favorable.

If the key is `limit_to`, the value is interpreted as a maximum speed that can be travelled on the affected edges. Edges
with a lower travel speed stored in the graph will not be affected by this rule.

### Conditions

The `condition_key` is a string with the possible values `if`, `else_if` and `else`. `else_if` and `else` require a
preceding rule with `if`, `else_if` as condition key, and are applied only if the preceding rule's condition did NOT
match.

The `condition_value` can be a string or boolean value. If it is a string, it can either have the form
`in_[AREA_NAME]` (see [section below](#areas) for details) OR describe a logical statement that can evaluate as true or
false. The logical statement can be a simple comparison of a variable and a value, e.g. `road_class == MOTORWAY`, or a
more complex statement using Java boolean operators, e.g. `max_width <= 2.2 && (road_environment == TUNNEL || roundabout)`.

The variables that can be used in those statements are called 'encoded values', and different ones are available for
different profiles. The available encoded values can be found in the response to the `status` endpoint, in the array
`profiles.<PROFILE NAME>.encoded_values`. Below is a list of example 'encoded values' and their possible values that are
available. Note that this list is incomplete and the available variables depend on the profile in question.

| name | Type | Description |
|--------------------|-----------|---------------------------------------------------------------------------|
| `road_class` | Enum | MOTORWAY, TRUNK, PRIMARY, SECONDARY, TRACK, STEPS, CYCLEWAY, FOOTWAY, ... |
| `road_environment` | Enum | ROAD, FERRY, BRIDGE, TUNNEL, ... |
| `road_access` | Enum | DESTINATION, DELIVERY, PRIVATE, NO, ... |
| `surface` | Enum | PAVED, DIRT, SAND, GRAVEL, ... |
| `smoothness` | Enum | EXCELLENT, GOOD, INTERMEDIATE, ... |
| `toll` | Enum | NO, ALL, HGV |
| `roundabout` | Boolean | Whether edge is part of a roundabout |
| `get_off_bike` | Boolean | Whether edge is marked as "requiring to get off bike" |
| `max_speed` | Numerical | Max speed in km/h |
| `max_height` | Numerical | Max height in m |
| `max_width` | Numerical | Max width in m |

Enum type encoded values can be used with the `==` and `!=` operators, while numerical encoded values can be used with the
`==`, `!=`, `<`, `<=`, `>`, `>=` operators. Boolean encoded valued do not require an operator, but can be used with the
`==`, `!=` and `!` operators.

### Areas

Area-based rules are defined by using a `condition_value` in the form `in_[AREA_NAME]` in the `priority` ond/or `speed`
arrays and providing a corresponding named object in the `areas` object of the custom model.

Each area object is required to be a GeoJSON `Feature` object. The `bbox` member and other foreign members such as
`properties` are NOT supported. The `geometry` member of the feature object must be of `"type": "Polygon"`.

The following is an example of a custom model with an area-based rule that sets the priority to zero (avoid completely)
for all edges within the area defined by the polygon:

```json
{
"priority": [
{
"if": "in_custom_area_1",
"multiply_by": 0
}
],
"areas": {
"custom_area_1": {
"type": "Feature",
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
8.7062144,
49.4077481
],
[
8.7068045,
49.4108196
],
[
8.7132203,
49.4117201
],
[
8.7139713,
49.4084322
],
[
8.7062144,
49.4077481
]
]
]
}
}
}
}
```

## Further Examples

Below are some examples of custom models that illustrate how the `custom_model` parameter can be used.

#### A general speed limit of 80 km/h, e.g. for car profiles

```json
{
Expand All @@ -62,15 +231,32 @@ The `custom_model` parameter is a JSON object, the following example shows the s
}
```

### avoid motorways and tunnels
#### Try to avoid motorways and tunnels (even more), avoid applying both rules to motorways within tunnels

```json
{
"priority": [
{
"if": "road_class == PRIMARY || road_environment == TUNNEL",
"if": "road_class == MOTORWAY",
"multiply_by": 0.7
},
{
"else_if": "road_environment == TUNNEL",
"multiply_by": 0.5
}
]
}
```
```

#### Avoid having to get off the bike

```json
{
"priority": [
{
"if": "get_off_bike",
"multiply_by": 0
}
]
}
```
2 changes: 1 addition & 1 deletion docs/run-instance/configuration/engine/profiles/service.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ need to be set specifically for each profile. More parameters relevant at query
| maximum_snapping_radius | number | Maximum distance around a given coordinate to find connectable edges | `400` |
| maximum_visited_nodes | number | Only for `public-transport` profile: maximum allowed number of visited nodes in shortest path computation | `1000000` |
| force_turn_costs | boolean | Should turn restrictions be obeyed | `false` |
| 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` |
| 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` |
| execution | object | [Execution settings](#execution) relevant when querying services | |

## `execution`
Expand Down

0 comments on commit fab4e0b

Please sign in to comment.