Merge pull request #182 from ibi-group/upstream-merge-2023-09-01

Upstream merge 2023-09-01

doc-templates/BuildConfiguration.md

@@ -108,25 +108,6 @@ general better than trying to be exact. The period and date format follow the IS
 }
 ```
 
-
-<h2 id="transferring-within-stations">Transferring within stations</h2>
-
-Subway systems tend to exist in their own layer of the city separate from the surface, though there
-are exceptions where tracks lie right below the street and transfers happen via the surface. In
-systems where the subway is quite deep and transfers happen via tunnels, the time required for an
-in-station transfer is often less than that for a surface transfer.
-
-One way to resolve this problem is by ensuring that the GTFS feed codes each platform as a separate
-stop, then micro-mapping stations in OSM. When OSM data contains a detailed description of walkways,
-stairs, and platforms within a station, GTFS stops can be linked to the nearest platform and
-transfers will happen via the OSM ways, which should yield very realistic transfer time
-expectations. This works particularly well in above-ground train stations where the layering of
-non-intersecting ways is less prevalent. See [BoardingLocations](BoardingLocations.md) for more 
-details.
-
-An alternative approach is to use GTFS pathways to model entrances and platforms within stations.
-
-
 ## OpenStreetMap(OSM) configuration
 
 It is possible to adjust how OSM data is interpreted by OpenTripPlanner when building the road part

doc-templates/RoutingModes.md

@@ -0,0 +1,7 @@
+This page is intended as an exhaustive listing of what OTP's routing engine is capable of and 
+therefore documents internal names. Since OTP has multiple APIs where each works slightly differently,
+please consult your API documentation on how to select the appropriate mode.
+
+<!-- INSERT: street-modes -->
+
+<!-- INSERT: transit-modes -->

docs/Apis.md

@@ -4,18 +4,19 @@ Several services are built upon OTP's routing and transit data indexing engines.
 
 The [GTFS GraphQL API](sandbox/GtfsGraphQlApi.md) has been used by the Digitransit and otp-react-redux 
 projects as a general purpose routing and transit data API in production for many years. 
-If your input data is mostly GTFS then this is probably your best choice as it uses the same vocabulary.
+If your input data is mostly GTFS then this is probably the best choice as it uses the same vocabulary.
 
-The [Transmodel GraphQL API](sandbox/TransmodelApi.md) is the Transmodel API is used at
-Entur in production since 2020. If your input data is mostly NeTeX then you might want to investigate
-this API as it uses the [Transmodel vocabulary](https://en.wikipedia.org/wiki/Transmodel) to describe transit entities.
-Like the GTFS GraphQL API it is also a general purpose API.
+The [Transmodel GraphQL API](sandbox/TransmodelApi.md) is used at
+Entur in production since 2020. Like the GTFS GraphQL API it is also a general purpose API.
+If your input data is mostly NeTeX then you might want to investigate
+this API as it uses the [Transmodel vocabulary](https://en.wikipedia.org/wiki/Transmodel) to describe 
+its entities.
 
 The [Vector tiles API](sandbox/MapboxVectorTilesApi.md) is a special purpose API for displaying
 entities on a vector map.
 
 The [Actuator API](sandbox/ActuatorAPI.md) provides endpoints for checking the health status of the
-OTP instance. It can be useful when running OTP in a container.
+OTP instance and reading live application metrics. 
 
 The [Geocoder API](sandbox/GeocoderAPI.md) allows you to geocode street corners and stop names.
 

docs/BoardingLocations.md

@@ -3,8 +3,7 @@
 It is often the case that the coordinates of stops are relatively far away from where the passengers
 are expected to the wait for the vehicle.
 
-A good example of this is [Buckhead subway station](https://www.openstreetmap.org/way/319512573) in 
-Atlanta.
+A good example of this is [Buckhead subway station](https://www.openstreetmap.org/way/319512573) in Atlanta.
 
 ![Buckhead station](images/buckhead-station.png)
 
@@ -34,6 +33,10 @@ have one of the following tag combinations:
   the place where the train stops, not the waiting area.
 - The `railway` key is deprecated (even though still widespread) and you should use `public_transport` 
   instead.
+- OTP does not process isolated nodes, but only nodes, which are part of routable ways. Therefore, adding a single , 
+isloated boarding location node to OSM has no effect. There is an exception, though: isolated nodes, which are members of
+`public_transport=stop_area` relation, will be considered and automatically linked with the street graph.
+For more information, check the [stop area](StopAreas.md) documentation.
 
 ## Cross-referencing
 

docs/BuildConfiguration.md

@@ -207,25 +207,6 @@ general better than trying to be exact. The period and date format follow the IS
 }
 ```
 
-
-<h2 id="transferring-within-stations">Transferring within stations</h2>
-
-Subway systems tend to exist in their own layer of the city separate from the surface, though there
-are exceptions where tracks lie right below the street and transfers happen via the surface. In
-systems where the subway is quite deep and transfers happen via tunnels, the time required for an
-in-station transfer is often less than that for a surface transfer.
-
-One way to resolve this problem is by ensuring that the GTFS feed codes each platform as a separate
-stop, then micro-mapping stations in OSM. When OSM data contains a detailed description of walkways,
-stairs, and platforms within a station, GTFS stops can be linked to the nearest platform and
-transfers will happen via the OSM ways, which should yield very realistic transfer time
-expectations. This works particularly well in above-ground train stations where the layering of
-non-intersecting ways is less prevalent. See [BoardingLocations](BoardingLocations.md) for more 
-details.
-
-An alternative approach is to use GTFS pathways to model entrances and platforms within stations.
-
-
 ## OpenStreetMap(OSM) configuration
 
 It is possible to adjust how OSM data is interpreted by OpenTripPlanner when building the road part
@@ -585,7 +566,7 @@ The file is created or overwritten if OTP saves the graph to the file
 Minutes necessary to reach stops served by trips on routes of route_type=1 (subway) from the street.
 
 Note! The preferred way to do this is to update the OSM data.
-See [Transferring within stations](#transferring-within-stations).
+See [In-station navigation](In-Station-Navigation.md).
 
 The ride locations for some modes of transport such as subways can be slow to reach from the street.
 When planning a trip, we need to allow additional time to reach these locations to properly inform

docs/Changelog.md

@@ -77,6 +77,13 @@ based on merged pull requests. Search GitHub issues and pull requests for smalle
 - Support Fares v2 FareMedium and update spec implementation [#5227](https://github.com/opentripplanner/OpenTripPlanner/pull/5227)
 - Replace DoubleFunction with linear function [#5267](https://github.com/opentripplanner/OpenTripPlanner/pull/5267)
 - Improve walk step narrative for entering/exiting stations and signposted pathways [#5285](https://github.com/opentripplanner/OpenTripPlanner/pull/5285)
+- Fix walk board cost comparison and add escalatorReluctance to hash [#5310](https://github.com/opentripplanner/OpenTripPlanner/pull/5310)
+- Stop count limit for access/egress routing and new accessEgress configuration object [#5214](https://github.com/opentripplanner/OpenTripPlanner/pull/5214)
+- Remove pathway id from REST API [#5303](https://github.com/opentripplanner/OpenTripPlanner/pull/5303)
+- Remove Winkki street note updater [#5305](https://github.com/opentripplanner/OpenTripPlanner/pull/5305)
+- Extend stop area relation linking to include bus stop and platform nodes [#5319](https://github.com/opentripplanner/OpenTripPlanner/pull/5319)
+- Document in-station navigation [#5321](https://github.com/opentripplanner/OpenTripPlanner/pull/5321)
+- Add access/egress penalty transmodel api [#5268](https://github.com/opentripplanner/OpenTripPlanner/pull/5268)
 [](AUTOMATIC_CHANGELOG_PLACEHOLDER_DO_NOT_REMOVE)
 
 

docs/Deployments.md

@@ -20,21 +20,22 @@ The following are known deployments of OTP in a government- or agency-sponsored
   real-time component.
 * **Finland Intercity** The Finnish intercity coach
   service [Matkahuolto](https://en.wikipedia.org/wiki/Matkahuolto)
-  has [developed a trip planner in partnership with Kyyti](https://www.kyyti.com/matkahuoltos-new-app-brings-real-travel-chains-within-the-reach-of-citizens-in-addition-to-coach-travel-hsl-tickets-are-also-available/)
-  .
-* **Lower Saxony, Germany** The [VBN](https://www.vbn.de/en/) transportation authority offers an [OTP instance](https://www.vbn.de/en/service/developer-information/opendata-and-openservice) as alternative to the [Hafas](https://www.hacon.de/en/portfolio/information-ticketing/#section_8294) passenger information system.
-* **Leipzig, Germany** As of summer 2020 [Leipzig Move](https://leipzig-move.de/) has been using
-  OpenTripPlanner.
+  has [developed a trip planner in partnership with Kyyti](https://www.kyyti.com/matkahuoltos-new-app-brings-real-travel-chains-within-the-reach-of-citizens-in-addition-to-coach-travel-hsl-tickets-are-also-available/).
+* **Skåne, Sweden**, the JourneyPlanner and mobile app for the regional transit agency [Skånetrafiken](https://www.skanetrafiken.se/)
+  uses OTP2 with the nordic profile of NeTEx and SIRI for realtime updates.
+* [**Northern Colorado**](https://discover.rideno.co/)
+* [**Philadelphia and surrounding areas**](https://plan.septa.org)
 * **Portland, Oregon** TriMet is the agency that originally started the OpenTripPlanner project.
   Their [Regional Trip Planner](http://ride.trimet.org) is based on OTP and provides about 40,000
   trip plans on a typical weekday.
+* [**New York City**](https://new.mta.info/)
 * **New York State** The State Department of
   Transportation's [transit trip planner](https://511ny.org/#TransitRegion-1) provides itineraries
   for public transit systems throughout the state in a single unified OTP instance.
 * **Los Angeles, California** The new [metro.net trip planner](https://www.metro.net/).
 * **Atlanta, Georgia** The Metropolitan Atlanta Rapid Transit Authority's (
   MARTA) [trip planner](http://itsmarta.com/planatrip.aspx) and the Atlanta region's transit
-  information hub [atltransit.org](https://atltransit.org/) both use OTP to power their website trip
+  information hub [https://atlrides.com/](https://atlrides.com/) both use OTP to power their website trip
   planners.
 * **Boston, Massachusetts**
   The [Massachusetts Bay Transportation Authority trip planner](https://www.mbta.com/trip-planner).
@@ -74,8 +75,9 @@ The following are known deployments of OTP in a government- or agency-sponsored
   around the campus using multiple modes of transportation, including the USF Bull Runner campus
   shuttle, Share-A-Bull bike share, and pedestrian pathways.
   Open-sourced [on Github](https://github.com/CUTR-at-USF/usf-mobullity).
-* **Skåne, Sweden**, the JourneyPlanner and mobile app for the regional transit agency [Skånetrafiken](https://www.skanetrafiken.se/) 
-  uses OTP2 with the nordic profile of NeTEx and SIRI for realtime updates.
+* **Lower Saxony, Germany** The [VBN](https://www.vbn.de/en/) transportation authority offers an [OTP instance](https://www.vbn.de/en/service/developer-information/opendata-and-openservice) as alternative to the [Hafas](https://www.hacon.de/en/portfolio/information-ticketing/#section_8294) passenger information system.
+* **Leipzig, Germany** As of summer 2020 [Leipzig Move](https://leipzig-move.de/) has been using
+  OpenTripPlanner.
 
 ## Independent Production
 

docs/In-Station-Navigation.md

@@ -0,0 +1,109 @@
+OTP offers a variety of ways to produce precise walking instructions
+for walking inside a station or between transit stops.
+
+### OSM generated navigation
+
+In the most common case, the walking instructions for reaching a transit stop are generated from the
+available OSM data. For this reason it is important that the coordinate of the stop is as close as 
+possible to where the passenger is expected to wait for the vehicle, not where the vehicle will stop.
+
+It is therefore a good idea to place the stop coordinates at a bus shelter or railway platform
+rather than at the middle of the road or the railway tracks.
+
+Of course you also want the data in OSM as precise as possible: data for railway platforms, stairs,
+tunnels and other infrastructure help OTP to generate good walking instructions.
+
+#### Example: exiting a railway platform
+
+The train arrives in a [railway station in Stuttgart](https://www.openstreetmap.org/#map=19/48.73761/9.11627)
+(green line), the passenger alights and is instructed (grey line) to walk along the platform,
+up the stairs and across a [bridge](https://www.openstreetmap.org/way/22908778) to continue to 
+their final destination.
+
+![Exiting Oesterfeld station](images/exiting-oesterfeld.png)
+
+### Boarding locations
+
+If your stop coordinates are not very well-placed, OTP may direct passengers to the wrong waiting
+location or offer incorrect transfer paths and time. As this a common problem and stop coordinates 
+can be hard to change due to upstream systems, OTP offers a 
+[way to derive the waiting coordinates](BoardingLocations.md) from OSM data.
+
+Even if your stop coordinates are good, some stations are underground and to get correct walking 
+instructions it's required to use this feature so that correct instructions for using entrances and
+stairs are generated.
+
+#### Example: walking downstairs to underground stations
+
+This shows an underground [subway station in Stuttgart](https://www.openstreetmap.org/way/122569371)
+which can only be reached by using entrances at either end walking down to the platform via
+a series of stairs and walkways. OTP can only generate these detailed instructions because the platform
+has a tag `ref:IFOPT` which identifies it in the German national stop register.
+
+![Boarding Schwabstrasse](images/boarding-schwabstrasse.png)
+
+### GTFS pathways
+
+If your GTFS input file contains [pathways](https://github.com/google/transit/blob/master/gtfs/spec/en/reference.md#pathwaystxt)
+this will override the OSM-generated instructions. It is therefore important that the pathways
+contain as much precision as possible.
+
+One advantage that pathways offer is the possibility to add information like "follow signs for X"
+which OTP adds to the textual turn-by-turn instructions.
+
+#### Example: Transferring at Südkreuz
+
+Here the pathways don't offer a lot of precision: In a [railway hub in Berlin](https://www.openstreetmap.org/#map=18/52.47572/13.36534&layers=T) 
+there are suboptimal instructions on how to move from one platform to another because the pathways 
+only contain rudimentary information about how to move inside the station. (The red lines represent 
+train lines with the grey line showing the walking path.)
+
+![Transferring at Suedkreuz](images/transfer-suedkreuz.png)
+
+### Transfers
+
+The above precedence rules of 
+
+- GTFS pathways, if it exists
+- then OSM data 
+
+also apply when computing transfers from one stop to another.
+
+#### Example: transferring from tram to rail at Oslo Central
+
+Here the passenger arrives in a local tram (blue line) near the [main station in Oslo](https://www.openstreetmap.org/#map=17/59.90964/10.75503). They are 
+instructed (grey line) to walk into the station right onto the correct platform and leave
+on a long-distance train (red line).
+
+![Transferring at Oslo 1](images/transfer-oslo-1.png)
+
+#### Example: transferring between platforms at Oslo Central
+
+This example instructs the passenger to get off a train, then walking down the stairs and via a tunnel
+to another platform.
+
+![Transferring at Oslo 2](images/transfer-oslo-2.png)
+
+### Transfer time
+
+The routing engine calculates the time to move from one stop to another by how long it thinks the
+walking takes based on the navigation instructions outlined above. So, if OTP thinks that
+it takes 5 minutes to walk from platform 1 to platform 8, then the routing algorithm will not suggest
+a transit connection that departs less than 5 minutes after arriving at platform 1.
+
+However, how fast the passenger is assumed to walk is controllable through the walk speed parameter.
+This can be configured per installation or passed as an API call parameter.
+
+The parameters [`alightSlack`](RouteRequest.md#rd_alightSlack), [`transferSlack`](RouteRequest.md#rd_transferSlack) 
+and [`boardSlack`](RouteRequest.md#rd_boardSlack) also allow you to define extra buffer time
+for transferring.
+
+[GTFS minimum transfer times](https://github.com/google/transit/blob/master/gtfs/spec/en/reference.md#transferstxt) 
+are also supported but generally not advised. It is preferable to micromap your stations and
+improve the stop coordinates rather than force specific transfer times by adding this data.
+
+### Common data errors
+
+- Stop coordinates not where passengers are expected to board
+- All stops/platforms in a railway station having the same coordinates
+- OSM platforms [not connected to the street network](https://github.com/opentripplanner/OpenTripPlanner/issues/5029)