GTFS flex support: flag stops, deviated-route service, call-and-ride

docs/Changelog.md

@@ -7,6 +7,7 @@
 - Update onebusaway-gtfs to latest version from OBA project (#2636)
 - Remove the coupling to OneBusAway GTFS within OTP's internal model by creating new classes replacing the external classes (#2494)
 - Allow itineraries in response to be sorted by duration (#2593)
+- Add support for GTFS-flex services: flag stops, deviated-route service, and call-and-ride (#2603)
 
 ## 1.3 (2018-08-03)
 

docs/Flex.md

@@ -0,0 +1,70 @@
+# GTFS-Flex routing
+
+Many agencies run flexible services to complement their fixed-route service. "Flexible" service does
+not follow a strict timetable or route. It may include any of the following features: boardings
+or alightings outside its scheduled timetable and route; booking and scheduling in advance; or
+transit parameters which depend on customer requests ("demand-responsive transit" or DRT). These
+services are typically used in rural areas or for mobility-impaired riders.
+
+A GTFS extension called [GTFS-Flex](https://github.com/MobilityData/gtfs-flex/blob/master/spec/reference.md) defines
+how to model some kinds of flexible transit. A subset of GTFS-Flex has been implemented in 
+OpenTripPlanner as part of US DOT's [Mobility-on-Demand Sandbox Grant](https://www.transit.dot.gov/research-innovation/fiscal-year-2016-mobility-demand-mod-sandbox-program-projects).
+
+In particular, OTP now has support for these modes of GTFS-Flex:
+
+- "flag stops", in which a passenger can flag down the a vehicle along its route to board, or
+alight in between stops
+- "deviated-route service", in which a vehicle can deviate from its route within an area or radius to
+do a dropoff or pickup
+- "call-and-ride", which is an entirely deviated, point-to-point segment.
+
+These modes can co-exist with fixed-route transit, and with each other. For example, some agencies 
+have fixed-route services that start in urban areas, where passengers must board at designated
+stops, but end in rural areas where passengers can board and alight wherever they please. A
+fixed-route service may terminate in an defined area where it can drop off passengers anywhere --
+or have such an area at the beginning or middle of its route. A vehicle may be able to deviate a
+certain radius outside its scheduled route to pick up or drop off passengers. If both a pickup and
+dropoff occur in between scheduled timepoints, from the passenger's perspective, the service may
+look like a call-and-ride trip. Other call-and-ride services may operate more like taxis, in which
+all rides are independently scheduled.
+
+## Configuration
+
+In order to use flexible routing, an OTP graph must be built with a GTFS-Flex dataset and
+OpenStreetMap data. The GTFS data must include `shapes.txt`.
+
+In addition, the parameter `useFlexService: true` must be added to `router-config.json`.
+
+A number of routing parameters can be used to control aspects of flexible service. These parameters
+typically change the relative cost of using various flexible services relative to fixed-route
+transit. All flex-related parameters begin with the prefix "flex" and can be found in the Javadocs
+for `RoutingRequest.java`.
+
+The following example `router-config.json` enables flexible routing and sets some parameters:
+
+    {
+      "useFlexService": true,
+      "routingDefaults": {
+        "flexCallAndRideReluctance": 3,
+        "flexMaxCallAndRideSeconds": 7200,
+        "flexFlagStopExtraPenalty": 180
+      }
+    }
+
+## Implementation
+
+The general approach of the GTFS-Flex implementation is as follows: prior to the main graph search,
+special searches are run around the origin and destination to discover possible flexible options.
+One search is with the WALK mode, to find flag stops, and the other is in the CAR mode, to find
+deviated-route and call-and-ride options. These searches result in the creation of temporary, 
+request-specific vertices and edges. Then, the graph search proceeds as normal. Temporary graph
+structures are disposed at the end of the request's lifecycle.
+
+For flag stops and deviated-route service, timepoints in between scheduled locations are determined
+via linear interpolation. For example, say a particular trip departs stop A at 9:00am and arrives
+at stop B at 9:30am. A passenger would be able to board 20% of the way in between stop A and stop B
+at 9:06am, since 20% of 30 minutes is 6 minutes.
+
+For deviated-route service and call-and-ride service, the most pessimistic assumptions of vehicle
+travel time are used -- e.g. vehicle travel time is calculated via the `drt_max_travel_time`
+formula in the GTFS-Flex (see the spec [here](https://github.com/MobilityData/gtfs-flex/blob/master/spec/reference.md#defining-service-parameters)).

mkdocs.yml

@@ -32,6 +32,7 @@ pages:
     - Scripting: 'Scripting.md'
     - Security: 'Security.md'
     - Troubleshooting: 'Troubleshooting-Routing.md'
+    - GTFS-Flex Routing: 'Flex.md'
 - Development:
     - "Developers' Guide": 'Developers-Guide.md'
     - Architecture: 'Architecture.md'

src/main/java/org/opentripplanner/api/common/RoutingResource.java

@@ -346,6 +346,36 @@ public abstract class RoutingResource {
     @QueryParam("disableRemainingWeightHeuristic")
     protected Boolean disableRemainingWeightHeuristic;
 
+    /*
+     * Control the size of flag-stop buffer returned in API response. This parameter only applies
+     * to GTFS-Flex routing, which must be explicitly turned on via the useFlexService parameter in
+     * router-config.json.
+     */
+    @QueryParam("flexFlagStopBufferSize")
+    protected Double flexFlagStopBufferSize;
+
+    /**
+     * Whether to use reservation-based services
+     */
+    @QueryParam("flexUseReservationServices")
+    protected Boolean flexUseReservationServices = true;
+
+    /**
+     * Whether to use eligibility-based services
+     */
+    @QueryParam("flexUseEligibilityServices")
+    protected Boolean flexUseEligibilityServices = true;
+
+    /**
+     * Whether to ignore DRT time limits.
+     *
+     * According to the GTFS-flex spec, demand-response transit (DRT) service must be reserved
+     * at least `drt_advance_book_min` minutes in advance. OTP not allow DRT service to be used
+     * inside that time window, unless this parameter is set to true.
+     */
+    @QueryParam("flexIgnoreDrtAdvanceBookMin")
+    protected Boolean flexIgnoreDrtAdvanceBookMin;
+
     @QueryParam("maxHours")
     private Double maxHours;
 
@@ -418,6 +448,8 @@ protected RoutingRequest buildRequest() throws ParameterException {
             } else {
                 request.setDateTime(date, time, tz);
             }
+
+            request.resetClockTime();
         }
 
         if (wheelchair != null)
@@ -595,6 +627,18 @@ protected RoutingRequest buildRequest() throws ParameterException {
         if (disableRemainingWeightHeuristic != null)
             request.disableRemainingWeightHeuristic = disableRemainingWeightHeuristic;
 
+        if (flexFlagStopBufferSize != null)
+            request.flexFlagStopBufferSize = flexFlagStopBufferSize;
+
+        if (flexUseReservationServices != null)
+            request.flexUseReservationServices = flexUseReservationServices;
+
+        if (flexUseEligibilityServices != null)
+            request.flexUseEligibilityServices = flexUseEligibilityServices;
+
+        if (flexIgnoreDrtAdvanceBookMin != null)
+            request.flexIgnoreDrtAdvanceBookMin = flexIgnoreDrtAdvanceBookMin;
+
         if (maxHours != null)
             request.maxHours = maxHours;
 

src/main/java/org/opentripplanner/api/model/BoardAlightType.java

@@ -0,0 +1,27 @@
+package org.opentripplanner.api.model;
+
+/**
+ * Distinguish between special ways a passenger may board or alight at a stop. The majority of
+ * boardings and alightings will be of type "default" -- a regular boarding or alighting at a
+ * regular transit stop. Currently, the only non-default types are related to GTFS-Flex, but this
+ * pattern can be extended as necessary.
+ */
+public enum BoardAlightType {
+
+    /**
+     * A regular boarding or alighting at a fixed-route transit stop.
+     */
+    DEFAULT,
+
+    /**
+     * A flag-stop boarding or alighting, e.g. flagging the bus down or a passenger asking the bus
+     * driver for a drop-off between stops. This is specific to GTFS-Flex.
+     */
+    FLAG_STOP,
+
+    /**
+     * A boarding or alighting at which the vehicle deviates from its fixed route to drop off a
+     * passenger. This is specific to GTFS-Flex.
+     */
+    DEVIATED;
+}

src/main/java/org/opentripplanner/api/model/Leg.java

@@ -247,6 +247,60 @@ public class Leg {
     @JsonSerialize
     public Boolean rentedBike;
 
+     /**
+      * True if this is a call-and-ride leg.
+      */
+    @XmlAttribute
+    @JsonSerialize
+    public Boolean callAndRide;
+
+    /* For call-n-ride leg, supply maximum start time based on calculation. */
+    @XmlAttribute
+    @JsonSerialize
+    public Calendar flexCallAndRideMaxStartTime = null;
+
+     /* For call-n-ride leg, supply minimum end time based on calculation. */
+    @XmlAttribute
+    @JsonSerialize
+    public Calendar flexCallAndRideMinEndTime = null;
+
+    /** trip.drt_advance_book_min if this is a demand-response leg */
+    @XmlAttribute
+    @JsonSerialize
+    public double flexDrtAdvanceBookMin;
+
+     /**
+      *  Agency message if this is leg has a demand-response pickup and the Trip has
+      *  `drt_pickup_message` defined.
+      */
+     @XmlAttribute
+     @JsonSerialize
+     public String flexDrtPickupMessage;
+
+     /**
+      * Agency message if this is leg has a demand-response dropoff and the Trip has
+      * `drt_drop_off_message` defined.
+      */
+     @XmlAttribute
+     @JsonSerialize
+     public String flexDrtDropOffMessage;
+
+     /**
+      * Agency message if this is leg has a flag stop pickup and the Trip has
+      * `continuous_pickup_message` defined.
+      */
+     @XmlAttribute
+     @JsonSerialize
+     public String flexFlagStopPickupMessage;
+
+     /**
+      * Agency message if this is leg has a flag stop dropoff and the Trip has
+      * `continuous_drop_off_message` defined.
+      */
+     @XmlAttribute
+     @JsonSerialize
+     public String flexFlagStopDropOffMessage;
+
     /**
      * Whether this leg is a transit leg or not.
      * @return Boolean true if the leg is a transit leg

src/main/java/org/opentripplanner/api/model/Place.java

@@ -8,6 +8,7 @@
 import org.opentripplanner.util.Constants;
 
 import com.fasterxml.jackson.databind.annotation.JsonSerialize;
+import org.opentripplanner.util.model.EncodedPolylineBean;
 
 /** 
 * A Place is where a journey starts or ends, or a transit stop along the way.
@@ -91,6 +92,19 @@ public class Place {
      */
     public String bikeShareId;
 
+    /**
+     * This is an optional field which can be used to distinguish among ways a passenger's
+     * boarding or alighting at a stop can differ among services operated by a transit agency.
+     * This will be "default" in most cases. Currently the only non-default values are for
+     * GTFS-Flex board or alight types.
+     */
+    public BoardAlightType boardAlightType;
+
+    /**
+     * Board or alight area for flag stops
+     */
+    public EncodedPolylineBean flagStopArea;
+
     /**
      * Returns the geometry in GeoJSON format
      * @return

src/main/java/org/opentripplanner/api/resource/GraphPathToTripPlanConverter.java

@@ -17,6 +17,8 @@
 import org.opentripplanner.routing.alertpatch.AlertPatch;
 import org.opentripplanner.routing.core.*;
 import org.opentripplanner.routing.edgetype.*;
+import org.opentripplanner.routing.edgetype.flex.PartialPatternHop;
+import org.opentripplanner.routing.edgetype.flex.TemporaryDirectPatternHop;
 import org.opentripplanner.routing.error.TrivialPathException;
 import org.opentripplanner.routing.graph.Edge;
 import org.opentripplanner.routing.graph.Graph;
@@ -182,9 +184,13 @@ public static Itinerary generateItinerary(GraphPath path, boolean showIntermedia
 
     private static Calendar makeCalendar(State state) {
         RoutingContext rctx = state.getContext();
-        TimeZone timeZone = rctx.graph.getTimeZone(); 
+        TimeZone timeZone = rctx.graph.getTimeZone();
+        return makeCalendar(timeZone, state.getTimeInMillis());
+    }
+
+    private static Calendar makeCalendar(TimeZone timeZone, long timeMillis) {
         Calendar calendar = Calendar.getInstance(timeZone);
-        calendar.setTimeInMillis(state.getTimeInMillis());
+        calendar.setTimeInMillis(timeMillis);
         return calendar;
     }
 
@@ -194,11 +200,11 @@ private static Calendar makeCalendar(State state) {
      * @param edges The array of input edges
      * @return The coordinates of the points on the edges
      */
-    private static CoordinateArrayListSequence makeCoordinates(Edge[] edges) {
+    public static CoordinateArrayListSequence makeCoordinates(Edge[] edges) {
         CoordinateArrayListSequence coordinates = new CoordinateArrayListSequence();
 
         for (Edge edge : edges) {
-            LineString geometry = edge.getGeometry();
+            LineString geometry = edge.getDisplayGeometry();
 
             if (geometry != null) {
                 if (coordinates.size() == 0) {
@@ -585,6 +591,11 @@ private static void addTripFields(Leg leg, State[] states, Locale requestedLocal
             leg.tripId = trip.getId();
             leg.tripShortName = trip.getTripShortName();
             leg.tripBlockId = trip.getBlockId();
+            leg.flexDrtAdvanceBookMin = trip.getDrtAdvanceBookMin();
+            leg.flexDrtPickupMessage = trip.getDrtPickupMessage();
+            leg.flexDrtDropOffMessage = trip.getDrtDropOffMessage();
+            leg.flexFlagStopPickupMessage = trip.getContinuousPickupMessage();
+            leg.flexFlagStopDropOffMessage = trip.getContinuousDropOffMessage();
 
             if (serviceDay != null) {
                 leg.serviceDate = serviceDay.getServiceDate().getAsString();
@@ -593,6 +604,30 @@ private static void addTripFields(Leg leg, State[] states, Locale requestedLocal
             if (leg.headsign == null) {
                 leg.headsign = trip.getTripHeadsign();
             }
+
+            Edge edge = states[states.length - 1].backEdge;
+            if (edge instanceof TemporaryDirectPatternHop) {
+                leg.callAndRide = true;
+            }
+            if (edge instanceof PartialPatternHop) {
+                PartialPatternHop hop = (PartialPatternHop) edge;
+                int directTime = hop.getDirectVehicleTime();
+                TripTimes tt = states[states.length - 1].getTripTimes();
+                int maxTime = tt.getDemandResponseMaxTime(directTime);
+                int avgTime = tt.getDemandResponseAvgTime(directTime);
+                int delta = maxTime - avgTime;
+                if (directTime != 0 && delta > 0) {
+                    if (hop.isDeviatedRouteBoard()) {
+                        long maxStartTime = leg.startTime.getTimeInMillis() + (delta * 1000);
+                        leg.flexCallAndRideMaxStartTime = makeCalendar(leg.startTime.getTimeZone(), maxStartTime);
+                    }
+                    if (hop.isDeviatedRouteAlight()) {
+                        long minEndTime = leg.endTime.getTimeInMillis() - (delta * 1000);
+                        leg.flexCallAndRideMinEndTime = makeCalendar(leg.endTime.getTimeZone(), minEndTime);
+                    }
+                }
+            }
+
         }
     }
 
@@ -686,6 +721,22 @@ private static Place makePlace(State state, Vertex vertex, Edge edge, Stop stop,
                 place.stopSequence = tripTimes.getStopSequence(place.stopIndex);
             }
             place.vertexType = VertexType.TRANSIT;
+            place.boardAlightType = BoardAlightType.DEFAULT;
+            if (edge instanceof PartialPatternHop) {
+                PartialPatternHop hop = (PartialPatternHop) edge;
+                if (hop.hasBoardArea() && !endOfLeg) {
+                    place.flagStopArea = PolylineEncoder.createEncodings(hop.getBoardArea());
+                }
+                if (hop.hasAlightArea() && endOfLeg) {
+                    place.flagStopArea = PolylineEncoder.createEncodings(hop.getAlightArea());
+                }
+                if ((endOfLeg && hop.isFlagStopAlight()) || (!endOfLeg && hop.isFlagStopBoard())) {
+                    place.boardAlightType = BoardAlightType.FLAG_STOP;
+                }
+                if ((endOfLeg && hop.isDeviatedRouteAlight()) || (!endOfLeg && hop.isDeviatedRouteBoard())) {
+                    place.boardAlightType = BoardAlightType.DEVIATED;
+                }
+            }
         } else if(vertex instanceof BikeRentalStationVertex) {
             place.bikeShareId = ((BikeRentalStationVertex) vertex).getId();
             LOG.trace("Added bike share Id {} to place", place.bikeShareId);

src/main/java/org/opentripplanner/common/geometry/GeometryUtils.java

@@ -1,6 +1,8 @@
 package org.opentripplanner.common.geometry;
 
 import com.vividsolutions.jts.geom.*;
+import com.vividsolutions.jts.io.ParseException;
+import com.vividsolutions.jts.io.WKTReader;
 import com.vividsolutions.jts.linearref.LengthLocationMap;
 import com.vividsolutions.jts.linearref.LinearLocation;
 import com.vividsolutions.jts.linearref.LocationIndexedLine;
@@ -181,4 +183,13 @@ private static Coordinate[] convertPath(List<LngLatAlt> path) {
         }
         return coords;
     }
+
+    public static Geometry parseWkt(String wkt) {
+        try {
+            return new WKTReader(GeometryUtils.getGeometryFactory()).read(wkt);
+        } catch(ParseException e) {
+            LOG.error("Unable to parse wkt: " + e);
+        }
+        return null;
+    }
 }