JOSM/Plugins/PT Assistant
Documentation for JOSM's Public Transport Assistant plugin: Introduction
The plugin validates public transport routes against a set of criteria and, where possible, suggests ways to fix them.
The plugin has no dedicated user interface, it is fully integrated in the core JOSM validator.
This page is edited and only reflects the current state of the plugin. Development issues can be found here in chronological order.
There is a presentation about the plugin for the FOSS4G conference (Brussels, 22.09.2016) available here.
The plugin source code is in JOSM github repository.
See also JOSM/Plugins/PT Assistant/Goals
Scope
Route relations for which it's possible to report errors and propose fixes
There are two public transport schema versions, and some route types are mapped differently than others.
A route relation is tested by the plugin if it:
- has the tag public_transport:version=2
AND
- has one of the tags:
AND
- does not have the tag bus=on_demand - The on_demand buses don't have fixed itineraries, but generally have a list of stations they can join (additional stops may be served by some network operators after specific reservation and authorization, if the security of the stop and local trafic conditions permit it). So no ways can be added to describe those routes.
Relevant route relation members
Criteria for platforms and stop_positions (PTStop):
- The relation member role is
stop, stop_entry_only, stop_exit_only, platform, platform_entry_only or platform_exit_only. - If the OsmPrimitiveType is Node, then the relation member should have tags public_transport=stop_position, highway=bus_stop, public_transport=platform, highway=platform or railway=platform
- If the OsmPrimitiveType is Way, then the relation members should have tags public_transport=platform, highway=platform or railway=platform
- If the OsmPrimitiveType is Relation, this relation member cannot be a PTStop.
Each stop corresponds to a plugin class PTStop. If a route relation has two consecutive members that belong to the same stop (a platform and a stop_position), they will form one PTStop.
Criteria for ways (PTWay):
- Cannot be of OsmPrimitiveType Node
- If the OsmPrimitiveType is Way, then the relation member may not have tags public_transport=platform, highway=platform or railway=platform
- If the OsmPrimitiveType is Relation, this nested relation is only allowed to have Ways as members.
If a route relation member does not fulfill these criteria, it is not added to the model, instead a "PT: Relation member roles do not match tags" warning appears.
Currently available tests
| # | Warning message | What is the problem? | What happens if I press the "Fix" button? | Author |
|---|---|---|---|---|
| 1 | PT: Route type does not match the type of the road it passes on | The route type (e.g. bus/tram/train etc.) has to pass on a way that matches that type, e.g. trains need rails and buses should not pass on streets that are for pedestrians or bicycles only. | JOSM zooms in to the problem, selects the problematic way(s) and opens a relation editor for the corresponding route. | darya |
| 2 | PT: Road is under construction | There is a road that is tagged as under construction. | JOSM zooms in to the problem, selects the problematic way(s) and opens a relation editor for the corresponding route. | darya |
| 3 | PT: Route passes a oneway road in wrong direction | The way is tagged as oneway, and the route passes it in the wrong direction. This test only works for single ways but does not detect more complex sequences of wrongly directed ways and roundabout parts. | JOSM zooms in to the problem, selects the problematic way(s) and opens a relation editor for the corresponding route. | darya |
| 4 | PT: Route contains a gap that can be fixed by sorting | If the route relation members are parsed in the current order, there is a break in the continuity (a fictitious gap). If sorting were performed, there would be no break. Also, this message indicates that there are no further problems detected in this route, because in the case of real gaps (absent ways) sorting would not be enough to eliminate the gaps. | The route relation members are sorted. | darya |
| 5 | PT: Relation member roles do not match tags | A route relation member does not fulfill the criteria for PTStop or PTWay listed above under "Relevant route relation members". | No fix available. | darya |
| 6 | PT: Route should start and end with a stop_position | There is no stop_position at the beginning or at the end or the route. | No fix available. | darya |
| 7 | PT: First or last way needs to be split | The stop_position at the beginning/end of the route exists but it is not a first or last node of the way. | No fix available. | darya |
| 8 | PT: Stop_position is not part of a way | The stop_position is not referred by any way with a public-transport-related tag (such as platform, railway, etc.). | The user is asked if they want to change the node tag value to "platform". If the user presses "yes", the tag is corrected. | darya |
| 9 | PT: Platform should not be part of a way | The platform is referred by a way. | The user is asked if they want to change the node tag value to "stop_position". If the user presses "yes", the tag is corrected. | darya |
| 10 | PT: Stop not served | The stop (and its elements platform and/or stop_position) are located too far away (>=0.002 degrees) from any way of the given route. | No fix available. | darya |
| 11 | PT: Problem in the route segment with one automatic fix | The ways between two consecutive stops (as listed in the route relation) are not continuous. This may be for a variety of reasons: segments absent or unnecessary segments present, wrong sorting, unsplit ways, etc. | The ways of the route segment (i.e. the part of route between two consecutive stop) are substituted with ways from the corresponding correct segment or from the ways that constitute the given route. JOSM zooms in to the problem. | darya |
| 12 | PT: Problem in the route segment with several automatic fixes | The ways between two consecutive stops (as listed in the route relation) are not continuous. This may be for a variety of reasons: segments absent or unnecessary segments present, wrong sorting, unsplit ways, etc. | The fix variants are displayed in different colors and JOSM zooms in to the problem. The first 5 variants can be displayed and marked with letters A-E. The user can either select the corresponding letter or press Esc for no fix. Once a fix variant is selected, the route is modified and a Relation Editor window opens, with the problematic ways selected. | darya |
| 13 | PT: Problem in the route segment with no automatic fix | The ways between two consecutive stops (as listed in the route relation) are not continuous. This may be for a variety of reasons: segments absent or unnecessary segments present, wrong sorting, unsplit ways, etc. | Fix disabled | darya |
| 14 | PT: Stop area relation has no stop position | There is a stop area relation without any given stop position. | No fix available. | xamanu |
| 15 | PT: Stop area relation has no platform | There is a stop area relation without any given platform. | No fix available. | xamanu |
| 16 | PT: Stop position or platform is not part of a stop area relation | All elements marked as stop position and platforms should be ideally part of a stop relation. | No fix available. | xamanu |
| 17 | PT: Route relations of stop position(s) and platform(s) of stop area members diverge | There is a discrepancy of public transport route relations assigned to stop position(s) and platform(s) which are part of one stop area relation. | No fix available. | xamanu |
Recommendations
- Activate the "Use error layer" option for a better visualization of the problematic primitives (Preferences => Data Validator => Tests => Use error layer).
- If you activate the "Download incomplete route relation members" option in the Preferences => Data Validator => PT_Assistant) while working on a large dataset, select the desired route relations before validating, otherwise the download of incomplete members may take too long.
- Open the "Command Stack" window in JOSM, especially if you are using the automated fixes for route-segment-related warnings ("PT: Problem in the route segment..."). It will help you see which changes have been carried out and revert them if necessary.
pt_assistant layer
The plugin adds an extra layer named "pt_assistant" to the layer list. The layer will be shown as soon as the user selects a route relation. Though primarily aimed at public transport relations, it will activate for bicycle or hiking relations as well. Once at least one relevant route relation has been selected, it receives a purple coloring. The stops are numbered according to their order in the relation.
Stop-by-stop tests and multiple fix variants
Tests #11-13 in the table use the stop-by-stop approach. This means they look separately at each part of the route between two consecutive stops (referred to as 'route segment' in this documentation). If no error was found in a route segment, that segment is added to the list of correct segments. These tests search for fix variants in the following order:
- Search in the list of correct segments for a segment whose first/last ways equal the first/last ways of the given problematic route segment
- Try to re-order and remove ways of the problematic segment itself in order to achieve a continuous sequence of ways between the two stops
- Search in the list of correct segments for a segment whose first/last stops equal the first/last stops of the given problematic route segment (in this case, the notification "Warning: the displayed fix variants are based on less strict criteria" is displayed)
The stop-by-stop tests (#11-13) may have several fix suggestions. If the fix button is pressed in such cases, the suggestions are displayed using different colors in the pt_assistant layer. Up to 5 fix variants can be displayed. They are labeled using the letters A-E. The user can select the desired fix by typing the corresponding letter on the keyboard. The Esc key can be pressed for no fix.
Data model
The plugin classifies the route relation members into PTStops (class PTStop) and PTWays (class PTWay).
A PTStop is designed to model a consecutive stop_position and platform as a single stop if they are close enough (<0.002 degrees) to each other. A PTStop can store the stop_position and/or platform as its elements.
A PTWay represents the way-related members of a route relation. The relation member can be a way or a relation.
The criteria for both PTStop and PTWay are listed above (Scope). If a route relation member does not fit the definition of either of these classes, it results in a "PT: Relation member roles do not match tags" (#5 in the table) warning.
Although not (widely) used in the current set of validator tests and fixes, the plugin has the potential to handle nested relation members, i.e. cases when a member of a route relation is itself a relation. The prerequisites are that the nested relation may only include ways (no stops) and the order of the ways inside the nested relation must be correct (because it is not further validated). The basis for this has been implemented in the classes PTWay and PTDataManager.
Stop-to-way assigner
Stops need to be linked to the relevant way of their route relation. Typically, that is the way closest to the stop in question. The search for the relevant way takes place in the following order:
- Check if this stop has already been assigned to a way. The assigned stops are stored in a table (HashMap).
- If the stop has a stop_position, use it to find the way that stop_position belongs to.
- If the stop elements belong to a stop_area relation, search if that stop_area contains a stop_position and use its referring way.
- Search for a stop_position in the vicinity of the stop (distance threshold 0.002 degrees).
- Use a growing-bounding-boxes algorithm. Find nodes inside a bounding box of a given size (which increases after each unsuccessful search loop), then find the ways of the current route to which those nodes belong. If there are multiple potential a way, the closest way is selected by calculating the distance from a point to a line. This calculation is based on the formulas for triangle area (Heron's formula and 1/2 * base * height).
Two items have been added to JOSM Tools menu from the pt_assistant plugin:
- Repeat last fix: allows to apply the last fix of the stop-by-stop test to other routes that share the same route segment. The menu item is deactivated if the last fix is not available (e.g. no stop-by-stop error has been fixed yet) or if no other problematic routes share the same route segment.
- Split roundabout: Roundabouts can be made up of 1 closed way, but this looks ugly when representing the route visually. The ways are split on those nodes that have ways, which are members of route relations (except when it's route=road). Then each route relation is treated and those ways of the roundabout that aren't needed are removed.
- Sort stops: If the ways are ordered and continuous, this will sort the stops as they appear along the ways of the route.
New map modes
- Add stop position: adds a stop_position node at a specified location, includes tags. If this is the first or the last way of the itinerary the way is split and only the part that really belongs to the route is kept.
- Edge selection: Select several connected ways that are suitable for the mode of transport, for which the relation editor window has focus. An edge is a continuous set of ways between 'forks' or between a fork and where a stop_position is the end node of a way.
Preferences
User settings are stored under Edit => Preferences => Data validator => PT_Assistant:
- The user can select if the incomplete relation members should be downloaded. In case a route relation has incomplete members that were not downloaded, that relation is skipped without validation.
- The user can decide to exclude tests that enforce the addition of stop_area relations for each stop.