Document all options available to Lua profiles #3842
Conversation
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!
docs/profiles.md
Outdated
| 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? |
There was a problem hiding this comment.
Maybe add a note that it is used for snapping / to filter out what is in the rtree
docs/profiles.md
Outdated
| 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) |
There was a problem hiding this comment.
Maybe add a note re. what restricted actually means https://www.openstreetmap.org/user/happygo/diary/40564
docs/profiles.md
Outdated
| 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) | ||
|
|
docs/profiles.md
Outdated
|
|
||
| Attribute | Type | Notes | ||
| ----------------------------------------|----------|-------------------------------------------------------------------------- | ||
| forward_rate | Float | Routing weight on this way per metre |
There was a problem hiding this comment.
The unit for rate is actually weirder. Speed is meter per seconds, this is a fake speed quantity so the unit is meter per {weight}.
| 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) | ||
| max_turn_weight | Float | Maximum turn penalty weight | ||
|
|
||
| ## 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. |
There was a problem hiding this comment.
it's just as important to set forward/backward mode
There was a problem hiding this comment.
Yes, agreed. I've not looked at the narrative text (which I think was originally written by @harry-wood) in this PR; this is just to list out the parameters.
There was a problem hiding this comment.
Yeah. I remember at the time I noted the need for more detail on what the global variables mean, so this looks like a very useful improvement to the docs
Incidentally from a narrative point of view, it might read more flowingly if you insert this table two paragraphs earlier no? Well doesn't really matter.
docs/profiles.md
Outdated
| 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) |
There was a problem hiding this comment.
I think there are a few properties missing here, most importantly the angle. Also it would be great to document the angle's range and what it represents.
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!