Open-Harbor/osrm-backend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 3 Wiki Activity

Document all options available to Lua profiles

Browse Source 
Recent improvements to OSRM have led to a lot of changes to the Lua scripting interface, and refactoring of the default profiles makes them slightly more abstract and difficult to grok for those writing profiles from scratch.

This is therefore an attempt to fully document the attributes that can be read and set from Lua profiles. I've done it from my own understanding and from reading the source, but I may well have missed things or mistaken them!
This commit is contained in:
Richard Fairhurst 2017-03-20 14:03:18 +00:00 committed by Daniel J. H
parent 3dcc7132b6
commit 88eabb98b9
1 changed files with 74 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

77
docs/profiles.md
View File

@ -25,6 +25,17 @@ As you scroll down the file you'll see local variables, and then local functions
`way_function` and `node_function` are the important functions which are called when extracting OpenStreetMap data with `osrm-extract`.
The following global properties can be set in your profile:
Attribute | Type | Notes
------------------------------|----------|----------------------------------------------------------------------------
weight_name | String | Name used in output for the routing weight property (default 'duration')
weight_precision | Unsigned | Decimal precision of edge weights (default 1)
left_hand_driving | Boolean | Are vehicles assumed to drive on the left? (used in guidance)
use_turn_restrictions | Boolean | Are turn instructions followed?
continue_straight_at_waypoint | Boolean | Must the route continue straight on at a via point, or are U-turns allowed?
max_speed_for_map_matching | Float | Maximum vehicle speed to be assumed in matching (in m/s)
## way_function
Given an OpenStreetMap way, the way_function will either return nothing (meaning we are not going to route over this way at all), or it will set up a result hash to be returned. The most important thing it will do is set the value of `result.forward_speed` and `result.backward_speed` as a suitable integer value representing the speed for traversing the way.
@ -33,15 +44,75 @@ All other calculations stem from that, including the returned timings in driving
Using the power of the scripting language you wouldn't typically see something as simple as a `result.forward_speed = 20` line within the way_function. Instead a way_function will examine the tagging (e.g. `way:get_value_by_key("highway")` and many others), process this information in various ways, calling other local functions, referencing the global variables and look-up hashes, before arriving at the result.
## Guidance
The following attributes can be set on the result in way_function:
Attribute | Type | Notes
----------------------------------------|----------|--------------------------------------------------------------------------
forward_rate | Float | Routing weight on this way per metre
backward_rate | Float | " "
forward_speed | Float | Speed on this way in km/h
backward_speed | Float | " "
forward_mode | Enum | Mode of travel (e.g. car, ferry). Defined in include/extractor/travel_mode.hpp
backward_mode | Enum | " "
duration | Float | Alternative setter for duration of the whole way in both directions
weight | Float | Alternative setter for weight of the whole way in both directions
turn_lanes_forward | String | Directions for individual lanes (normalised OSM turn:lanes value)
turn_lanes_backward | String | " "
forward_restricted | Boolean | Is this a restricted access road? (e.g. private, deliveries only)
backward_restricted | Boolean | " "
is_startpoint | Boolean | Can a journey start on this way?
roundabout | Boolean | Is this part of a roundabout?
circular | Boolean | Is this part of a non-roundabout circular junction?
name | String | Name of the way
ref | String | Road number
pronunciation | String | Name pronunciation
road_classification.motorway_class | Boolean | Guidance: way is a motorway
road_classification.link_class | Boolean | Guidance: way is a slip/link road
road_classification.road_priority_class | Enum | Guidance: order in priority list. Defined in include/extractor/guidance/road_classification.hpp
road_classification.may_be_ignored | Boolean | Guidance: way is non-highway
road_classification.num_lanes | Unsigned | Guidance: total number of lanes in way
### Guidance
The guidance parameters in profiles are currently a work in progress. They can and will change.
Please be aware of this when using guidance configuration possibilities.
### Road Classification
Guidance uses road classes to decide on when/if to emit specific instructions and to discover which road is obvious when following a route.
Classification uses three flags and a priority-category.
The flags indicate whether a road is a motorway (required for on/off ramps), a link type (the ramps itself, if also a motorway) and whether a road may be omittted in considerations (is considered purely for connectivity).
The priority-category influences the decision which road is considered the obvious choice and which roads can be seen as fork.
Forks can be emitted between roads of similar priority category only. Obvious choices follow a major priority road, if the priority difference is large.
## node_function
The following attributes can be set on the result in node_function:
Attribute | Type | Notes
----------------|---------|-------------------------------------------------------
barrier | Boolean | Is it an impassable barrier?
traffic_lights | Boolean | Is it a traffic light (incurs delay in turn_function)?
## segment_function
The following attributes can be read and set on the result in segment_function:
Attribute | Read/write? | Type | Notes
-------------------|-------------|---------|------------------------------------------------------
source.lon | Read | Float | Co-ordinates of segment start
source.lat | Read | Float | " "
target.lon | Read | Float | Co-ordinates of segment end
target.lat | Read | Float | " "
target.distance | Read | Float | Length of segment
weight | Read/write | Float | Routing weight for this segment
duration | Read/write | Float | Duration for this segment
## turn_function
The following attributes can be read and set on the result in turn_function:
Attribute | Read/write? | Type | Notes
-------------------|-------------|---------|------------------------------------------------------
direction_modifier | Read | Enum | Geometry of turn. Defined in include/extractor/guidance/turn_instruction.hpp
turn_type | Read | Enum | Priority of turn. Defined in include/extractor/guidance/turn_instruction.hpp
has_traffic_light | Read | Boolean | Traffic light present at this turn
duration | Write | Float | Penalty to be applied for this turn (s)