-
Notifications
You must be signed in to change notification settings - Fork 67
Transitive Conceptual Overview
Routes: A route is a specific public transport service; the Transitive route definition aligns closely with the corresponding concept in both GTFS and OpenTripPlanner. Routes are defined in the routes array in the Transitive input data, with each route described by the following attributes:
{
"agency_id": "DC",
"route_id": "BLUE",
"route_short_name": "Blue",
"route_long_name": "Metrorail Blue Line",
"route_type": 1,
"route_color": "0d7bba"
}
Stops: A stop is a specific geographic point served by a route pattern; the Transitive stop aligns closely with the corresponding concept in both GTFS and OTP. Stops are defined in the stops array in the Transitive input data, with each stop described by the following attributes:
{
"stop_id": "7588",
"stop_name": "METRO CENTER METRO STATION",
"stop_lat": 38.898327,
"stop_lon": -77.027777
}
Patterns: A pattern is a unique sequence of stops served by a transit vehicle; routes are composed of one or more patterns. The concept of a pattern in Transitive is the same as that used by OpenTripPlanner in the TransitIndex API. Patterns are defined in the patterns array in the Transitive input data, with each pattern described by a list of stops and other attribures as following:
{
"pattern_id": "4e499fd0",
"pattern_name": "Blue to LARGO TOWN CENTER METRO STATION (DC_4697)",
"route_id": "BLUE"
"stops": [{
"stop_id": "3666"
}, {
"stop_id": "32057"
}, ... ]
}
Places: A Transitive place is a geographic point of interest, other than a stop, that can be described by a lat/lon coordinate pair. Currently, it is most commonly used to represent the origin and destination endpoints of a journey (described below), such as a person’s home and work locations. Places are defined in the places array in the Transitive inputs, and each place is described by name and coordinate pair:
{
"place_id": "to",
"place_name": "End: Union Station",
"place_lat": 38.89788,
"place_lon": -77.00597
}
Journeys: A journey is a linear trip from one point to another in the transportation system, and are typically produced by a journey planner such as OTP. Journeys consist of a sequence of mode-specific segments; a given segment may either be walking, cycling, driving, or riding a specific transit service. Walking, cycling, and driving segments consist of “from” and “to” locations, referencing stops or places as defined above. Transit segments reference a route pattern, and also specify the range of the pattern’s stops traversed. Journeys are defined in the journeys array; a typical journey definition may look like the following:
{
"journey_id": "option_1",
"journey_name": "routes Blue, Red via METRO CENTER METRO STATION",
"segments": [{
"type": "WALK",
"from": {
"type": "PLACE",
"place_id": "from"
},
"to": {
"type": "STOP",
"stop_id": "11332"
}
}, {
"type": "TRANSIT",
"pattern_id": "22e60626",
"from_stop_index": 9,
"to_stop_index": 13
}, {
"type": "TRANSIT",
"pattern_id": "77312cf9",
"from_stop_index": 14,
"to_stop_index": 17
}, {
"type": "WALK",
"from": {
"type": "STOP",
"stop_id": "12872"
},
"to": {
"type": "PLACE",
"place_id": "to"
}
}]
}
The Network refers to Transitive’s internal model of the transport elements being rendered. The main network classes are defined in lib/core and lib/graph.
The Graph: At the heart of Transitive’s representation of the transport network is the two-dimensional NetworkGraph. The graph models the underlying topological structure of the network, represented by vertices and edges. Vertices typically correspond to major transfer/intersection points in the transport network, and edges represent the transit/street corridors that connect them.
Paths & Segments: The NetworkPath class represents any linear path through the NetworkGraph, such as a transit line, or a walking route between two points. NetworkPaths consist of a sequence of one or more mode-specific PathSegment classes, where each PathSegment consists of a sequence of graph edges.
A note about graph directionality: This is a nuanced issue in Transitive. Technically speaking, the Transitive graph is a directed graph, as each edge has defined “from” and “to” vertices. This is necessary for rendering purposes; we want to be able to offset rendered lines on either side of a graph edge, and need the concept of edge directionality in order to perform positive and negative offsetting.
That said, we generally only want one edge connecting a given pair of vertices; we want to avoid a situation where there is both an A->B and B->A edge; otherwise the line bunding and offset-based rendering may produce unintended results. For this reason, paths are allowed to traverse graph edges in either direction, and the PathSegment class keeps track of whether each edge in its edge sequence is being traversed in the “forward” or “reverse” direction.
Journeys: The concept of a Journey is discussed under “data inputs” above. From an implementation standpoint, a Journey is a special type of path, and the Journey class (defined in lib/core/journey.js) functions largely as a wrapper around a NetworkPath instance, adding Journey-specific functionality (e.g. the ability to highlight a specific journey).
Points: A Point is any specific geographic location represented by a pair of world coordinates. Points are often associated with a Vertex of the graph, though non-vertex Points are also allowable (e.g. inline transit stops along a graph edge). All points can be rendered and styled as visual elements.
An abstract Point superclass is defined in lib/points/index.js, and the following subclasses, also defined in lib/points, are available for use:
-
Stop - A Stop point corresponds to a transit stop object as defined in the input data (see above).
-
Place - A Place point corresponds to a place object as defined in the input data (see above).
-
TurnPoint - A TurnPoint is a location where the user is instructed to switch from one street to another in turn-by-turn directions, which may be associated with a walking, cycling, or driving segment.
-
MultiPoint - A MultiPoint is a point object that contains multiple other points (Stops, Places, or TurnPoints) but is treated as a single point for rendering purposes. A typical use case is when several nearby stops are “merged” and displayed as a single icon. The
lib/pointfolder also contains the PointCluster and PointClusterMap classes, which are used to identify and construct MultiPoints in the graph-creation process.
Rendering the network consists of converting the internal graph-based model of Paths and Points to SVG elements that can be displayed on the screen. This job is handled by the Renderer class, defined in lib/renderer, with the help of two classes that represent the rendered network:
-
RenderedEdge - A graph edge that has been rendered as a visual element. While a graph edge is defined in terms of “world” coordinates (typically Spherical Mercator), a RenderedEdge defines the actual path of the SVG element as screen coordinates, factoring in any offsetting that has been applied. Note that a single graph edge may have multiple corresponding RenderedEdges, as we may be separately rendering multiple services that follow a single edge in the graph.
-
RenderedSegment - A rendered PathSegment. Just as a PathSegment is a sequence of graph edges, a RenderedSegment is a sequence of RenderedEdges. While most of the line rendering logic is contained in the RenderedEdge class, RenderedSegment contains rendering functionality that is better performed at the segment level, such as the labeling of transit route(s).
SVG-based styling can be applied to rendered paths, points, and labels based on attributes of both the elements themselves (e.g. transit mode) and the display (e.g. the current zoom level). Default styles are defined in lib/styler/styles.js, and custom styles can be provided via the styles property of the main Transitive constructor options.
[detailed styling docs to be added]