StreetLayer (r5 4.6.1-SNAPSHOT API)

java.lang.Object
- com.conveyal.r5.streets.StreetLayer

All Implemented Interfaces:

Serializable, Cloneable
```
public class StreetLayer
extends Object
implements Serializable, Cloneable
```
This class stores the street network. Information about public transit is in a separate layer. Is is currently implemented as a column store. We could also use something like https://github.com/RichardWarburton/slab which simulates Java objects in a chunk of memory that could be mapped to a file. This could be useful for routing across continents or large countries. While the transit search is very fast (probably because it tends to search in order over contiguous arrays) the street searches can be surprisingly slow. We suspect this is due to the vertices being in somewhat random order in memory. The solution would be to order the vertices in memory according to their proximity in the graph, then sort edges according to from-vertex order. Really what you want to do is embed the distance metric defined by the graph in 1D space. This is a 'metric embedding' or multidimensional scaling, analagous to force-directed graph layout. http://ceur-ws.org/Vol-733/paper_pacher.pdf You could do something similar using their geographic coordinates (Morton-code-sort the vertices).

See Also:

Serialized Form

Field Summary

Fields
Modifier and Type	Field and Description
`static EnumSet<EdgeStore.EdgeFlag>`	`ALL_PERMISSIONS`
`StreetLayer`	`baseStreetLayer` Some StreetLayers are created by applying a scenario to an existing StreetLayer.
`gnu.trove.map.TIntObjectMap<BikeRentalStation>`	`bikeRentalStationMap`
`boolean`	`bikeSharing`
`EdgeStore`	`edgeStore`
`com.vividsolutions.jts.geom.Envelope`	`envelope` Envelope of this street layer, in decimal degrees (floating, not fixed-point)
`List<gnu.trove.list.TIntList>`	`incomingEdges`
`static int`	`INITIAL_LINK_RADIUS_METERS` Searching for streets takes a fair amount of computation, and the number of streets examined grows roughly as the square of the radius.
`static double`	`LINK_RADIUS_METERS` The radius of a circle in meters within which to search for nearby streets.
`static int`	`MIN_SUBGRAPH_SIZE` Minimum allowable size (in number of vertices) for a disconnected subgraph; subgraphs smaller than these will be removed.
`List<gnu.trove.list.TIntList>`	`outgoingEdges`
`TransportNetwork`	`parentNetwork` The TransportNetwork containing this StreetLayer.
`gnu.trove.map.TIntObjectMap<ParkRideParking>`	`parkRideLocationsMap`
`String`	`scenarioId` A string uniquely identifying the contents of this StreetLayer among all StreetLayers.
`IntHashGrid`	`spatialIndex` A spatial index of all street network edges, using fixed-point WGS84 coordinates.
`List<TurnRestriction>`	`turnRestrictions` Turn restrictions can potentially affect (include) several edges, so they are stored here and referenced by index within all edges that are affected by them.
`VertexStore`	`vertexStore`
`IndexedPolygonCollection`	`waitTimePolygons` This set of polygons specifies a spatially varying wait time to use a ride hailing service.

Constructor Summary

Constructors
Constructor and Description

StreetLayer(TNBuilderConfig tnBuilderConfig)

Constructors
Constructor and Description
`StreetLayer(TNBuilderConfig tnBuilderConfig)`

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`associateBikeSharing(TNBuilderConfig tnBuilderConfig)` Creates vertices to represent each bike rental station.
`void`	`associateStops(TransitLayer transitLayer)` For every stop in a TransitLayer, find or create a nearby vertex in the street layer and record the connection between the two.
`void`	`buildEdgeLists()` The edge lists (which edges go out of and come into each vertex) are derived from the edges in the EdgeStore.
`StreetLayer`	`clone()`
`int`	`createAndLinkVertex(double lat, double lon)` Create a street-layer vertex representing a transit stop, and connect that new vertex to the street network if possible.
`List<BikeRentalStation>`	`findBikeSharesInEnvelope(com.vividsolutions.jts.geom.Envelope env)` Finds all the bike share stations in given envelope.
`gnu.trove.set.TIntSet`	`findEdgesInEnvelope(com.vividsolutions.jts.geom.Envelope envelope)` Rather than querying the spatial index directly, going through this method will ensure that any temporary edges not in the index are also visible.
`List<ParkRideParking>`	`findParkRidesInEnvelope(com.vividsolutions.jts.geom.Envelope env)` Finds all the P+R stations in given envelope.
`Split`	`findSplit(double lat, double lon, double radiusMeters, StreetMode streetMode)` Find a location on an existing street near the given point, without actually creating any vertices or edges.
`com.vividsolutions.jts.geom.Envelope`	`getEnvelope()`
`String`	`getNameEdgeIdx(int edgeIdx, Locale locale)` Gets way name from OSM name tag It uses OSM Mapdb Uses `getName(long, Locale)`
`int`	`getOrCreateVertexNear(double lat, double lon, StreetMode streetMode)` Find an existing street vertex near the supplied coordinates, or create a new one if there are no vertices near enough.
`int`	`getVertexCount()`
`int`	`getWaitTime(double lat, double lon)`
`String`	`getWayTags(EdgeStore.Edge edge)` Gets all the OSM tags of specified OSM way Tags are returned as tag=value separated with ; AKA same format that `OSMEntity.setTagsFromString(String)` accepts
`void`	`indexStreets()`
`boolean`	`isScenarioCopy()`
`void`	`loadFromOsm(com.conveyal.osmlib.OSM osm)` Load street layer from an OSM-lib OSM DB
`static void`	`logFixedPointGeometry(String label, com.vividsolutions.jts.geom.Geometry fixedPointGeometry)` Given a JTS Geometry in fixed-point latitude and longitude, log it as floating-point GeoJSON.
`void`	`openOSM(File file)` TODO Javadoc.
`StreetLayer`	`scenarioCopy(TransportNetwork newScenarioNetwork, boolean willBeModified)` We intentionally avoid using clone() on EdgeStore and VertexStore so all field copying is explicit and we can clearly see whether we are accidentally shallow-copying any collections or data structures from the base graph.
`com.vividsolutions.jts.geom.Geometry`	`scenarioEdgesBoundingGeometry(int radiusMeters)` Create a geometry in FIXED POINT DEGREES containing all the points on all edges created or removed by the scenario that produced this StreetLayer, buffered by radiusMeters.
`int`	`splitEdge(Split split)` Perform destructive splitting of edges FIXME: currently used only in P+R.
`String`	`toString()`

Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - MIN_SUBGRAPH_SIZE
```
public static final int MIN_SUBGRAPH_SIZE
```
    Minimum allowable size (in number of vertices) for a disconnected subgraph; subgraphs smaller than these will be removed. There are several reasons why one might have a disconnected subgraph. The most common is poor quality OSM data. However, they also could be due to areas that really are disconnected in the street graph, and are connected only by transit. These could be literal islands (Vashon Island near Seattle comes to mind), or islands that are isolated by infrastructure (for example, airport terminals reachable only by transit or driving, for instance BWI or SFO).
    
    See Also:
    
    Constant Field Values
  - LINK_RADIUS_METERS
```
public static final double LINK_RADIUS_METERS
```
    The radius of a circle in meters within which to search for nearby streets. This should not necessarily be a constant, but even if it's made settable it should be stored in a field on this class to avoid cluttering method signatures. Generally you'd set this once at startup and always use the same value afterward. 1.6km is really far to walk off a street. But some places have offices in the middle of big parking lots.
    
    See Also:
    
    Constant Field Values
  - INITIAL_LINK_RADIUS_METERS
```
public static final int INITIAL_LINK_RADIUS_METERS
```
    Searching for streets takes a fair amount of computation, and the number of streets examined grows roughly as the square of the radius. In most cases, the closest street is close to the search center point. If the specified search radius exceeds this value, a mini-search will first be conducted to check for close-by streets before examining every street within the full specified search radius.
    
    See Also:
    
    Constant Field Values
  - outgoingEdges
```
public transient List<gnu.trove.list.TIntList> outgoingEdges
```
  - incomingEdges
```
public transient List<gnu.trove.list.TIntList> incomingEdges
```
  - spatialIndex
```
public transient IntHashGrid spatialIndex
```
    A spatial index of all street network edges, using fixed-point WGS84 coordinates.
  - bikeRentalStationMap
```
public gnu.trove.map.TIntObjectMap<BikeRentalStation> bikeRentalStationMap
```
  - parkRideLocationsMap
```
public gnu.trove.map.TIntObjectMap<ParkRideParking> parkRideLocationsMap
```
  - envelope
```
public com.vividsolutions.jts.geom.Envelope envelope
```
    Envelope of this street layer, in decimal degrees (floating, not fixed-point)
  - vertexStore
```
public VertexStore vertexStore
```
  - edgeStore
```
public EdgeStore edgeStore
```
  - turnRestrictions
```
public List<TurnRestriction> turnRestrictions
```
    Turn restrictions can potentially affect (include) several edges, so they are stored here and referenced by index within all edges that are affected by them. TODO what if an edge is affected by multiple restrictions?
  - parentNetwork
```
public TransportNetwork parentNetwork
```
    The TransportNetwork containing this StreetLayer. This link up the object tree also allows us to access the TransitLayer associated with this StreetLayer of the same TransportNetwork without maintaining bidirectional references between the two layers.
  - scenarioId
```
public String scenarioId
```
    A string uniquely identifying the contents of this StreetLayer among all StreetLayers. When no scenario has been applied, this field will contain the ID of the enclosing TransportNetwork. When a scenario has modified this StreetLayer, this field will be changed to that scenario's ID. We need a way to know what information is in the network independent of object identity, which is lost in a round trip through serialization. This also allows re-using cached linkages for several scenarios as long as they don't modify the street network.
  - baseStreetLayer
```
public StreetLayer baseStreetLayer
```
    Some StreetLayers are created by applying a scenario to an existing StreetLayer. All the contents of the base StreetLayer are not copied, they are wrapped to make them extensible. These are called "scenario copies". If this StreetLayer is such a scenario copy, this field points to the original StreetLayer it was based upon. Otherwise this field should be null.
  - waitTimePolygons
```
public IndexedPolygonCollection waitTimePolygons
```
    This set of polygons specifies a spatially varying wait time to use a ride hailing service. Negative wait times mean the service is not available at a particular location. If this reference is null, no wait time is applied.
  - ALL_PERMISSIONS
```
public static final EnumSet<EdgeStore.EdgeFlag> ALL_PERMISSIONS
```
  - bikeSharing
```
public boolean bikeSharing
```
- Constructor Detail
  - StreetLayer
```
public StreetLayer(TNBuilderConfig tnBuilderConfig)
```
- Method Detail
  - loadFromOsm
```
public void loadFromOsm(com.conveyal.osmlib.OSM osm)
```
    Load street layer from an OSM-lib OSM DB
  - openOSM
```
public void openOSM(File file)
```
    TODO Javadoc. What is this for?
  - getNameEdgeIdx
```
public String getNameEdgeIdx(int edgeIdx,
                             Locale locale)
```
    Gets way name from OSM name tag It uses OSM Mapdb Uses getName(long, Locale)
    
    Parameters:
    
    edgeIdx - edgeStore EdgeIDX
    
    locale - which locale to use
    
    Returns:
    
    null if edge doesn't have name tag or if OSM data isn't loaded
  - getWayTags
```
public String getWayTags(EdgeStore.Edge edge)
```
    Gets all the OSM tags of specified OSM way Tags are returned as tag=value separated with ; AKA same format that OSMEntity.setTagsFromString(String) accepts
    
    Parameters:
    
    edge - for which to get tags
    
    Returns:
    
    String with all the tags or null
  - indexStreets
```
public void indexStreets()
```
  - findEdgesInEnvelope
```
public gnu.trove.set.TIntSet findEdgesInEnvelope(com.vividsolutions.jts.geom.Envelope envelope)
```
    Rather than querying the spatial index directly, going through this method will ensure that any temporary edges not in the index are also visible. Temporary edges, created when applying a scenario in a single thread, are not added to the spatial index, which is read by all threads. Note: the spatial index can and will return false positives, but should not produce false negatives. We return the unfiltered results including false positives because calculating the true distance to each edge is quite a slow operation. The caller must post-filter the set of edges if more distance information is needed, including knowledge of whether an edge passes inside the query envelope at all.
  - buildEdgeLists
```
public void buildEdgeLists()
```
    The edge lists (which edges go out of and come into each vertex) are derived from the edges in the EdgeStore. So any time you add edges or change their endpoints, you need to rebuild the edge index. TODO some way to signal that a few new edges have been added, rather than rebuilding the whole lists.
  - getOrCreateVertexNear
```
public int getOrCreateVertexNear(double lat,
                                 double lon,
                                 StreetMode streetMode)
```
    Find an existing street vertex near the supplied coordinates, or create a new one if there are no vertices near enough. Note that calling this method is potentially destructive (it can modify the street network). This uses findSplit(double, double, double, StreetMode) and Split which require the spatial index to already be built. In other works indexStreets() needs to be called before this is used. TODO potential refactor: rename this method Split.perform(), and store a ref to streetLayer in Split.
    
    Parameters:
    
    lat - latitude in floating point geographic (not fixed point) degrees.
    
    lon - longitude in floating point geographic (not fixed point) degrees.
    
    streetMode - Link to edges which have permission for StreetMode
    
    Returns:
    
    the index of a street vertex very close to the supplied location, or -1 if no such vertex could be found or created.
  - splitEdge
```
public int splitEdge(Split split)
```
    Perform destructive splitting of edges FIXME: currently used only in P+R. This methods should probably be changed to resuse code from getOrCreateVertexNear.
  - createAndLinkVertex
```
public int createAndLinkVertex(double lat,
                               double lon)
```
    Create a street-layer vertex representing a transit stop, and connect that new vertex to the street network if possible. The vertex will be created and assigned an index whether or not it is successfully linked to the streets. This is intended for transit stop linking. It always creates a new vertex in the street layer exactly at the coordinates provided. You can be sure to receive a unique vertex index each time it's called on the same street layer. Once it has created this new vertex, it will look for the nearest edge in the street network and link the newly created vertex to the closest point on that nearby edge. The process of linking to that edge may or may not create a second new splitter vertex along that edge. If the newly created vertex is near an intersection or another splitter vertex, the existing vertex will be reused. So in sum, this will create one or two new vertices, and all necessary edge pairs to properly connect these new vertices. TODO store street-to-stop distance in a table in TransitLayer, or change the link edge length. This also allows adjusting for subway entrances etc.
    
    Returns:
    
    the vertex of the newly created vertex at the supplied coordinates.
  - findSplit
```
public Split findSplit(double lat,
                       double lon,
                       double radiusMeters,
                       StreetMode streetMode)
```
    Find a location on an existing street near the given point, without actually creating any vertices or edges. This is a nondestructive operation: it simply finds a candidate split point without modifying anything. This function starts with a small search envelope and expands it as needed under the assumption that most search points will be close to a road. TODO favor transit station platforms and pedestrian paths when requested
    
    Parameters:
    
    lat - latitude in floating point geographic coordinates (not fixed point int coordinates)
    
    lon - longitude in floating point geographic coordinates (not fixed point int coordinates)
    
    streetMode - a mode of travel that the street must allow
    
    Returns:
    
    a Split object representing a point along a sub-segment of a specific edge, or null if there are no streets nearby allowing the specified mode of travel.
  - associateStops
```
public void associateStops(TransitLayer transitLayer)
```
    For every stop in a TransitLayer, find or create a nearby vertex in the street layer and record the connection between the two.
  - getVertexCount
```
public int getVertexCount()
```
  - getEnvelope
```
public com.vividsolutions.jts.geom.Envelope getEnvelope()
```
  - scenarioCopy
```
public StreetLayer scenarioCopy(TransportNetwork newScenarioNetwork,
                                boolean willBeModified)
```
    We intentionally avoid using clone() on EdgeStore and VertexStore so all field copying is explicit and we can clearly see whether we are accidentally shallow-copying any collections or data structures from the base graph. StreetLayer has a lot more fields and most of them can be shallow-copied, so here we use clone() for convenience.
    
    Parameters:
    
    willBeModified - must be true if the scenario to be applied will make any changes to the new StreetLayer copy. This allows some optimizations (the lists in the StreetLayer will not be wrapped).
    
    Returns:
    
    a copy of this StreetLayer to which Scenarios can be applied without affecting the original StreetLayer. It's questionable whether the willBeModified optimization actually affects routing speed, but in theory it saves a comparison and an extra dereference every time we use the edge/vertex stores. TODO check whether this actually affects speed. If not, just wrap the lists in every scenario copy. Why would you clone the StreetLayer at all if it's not going to be modified? Because there are circular references between the street and transit layers, so if you don't clone both, you could end up at the wrong transit or street layer by chaining together those references.
  - associateBikeSharing
```
public void associateBikeSharing(TNBuilderConfig tnBuilderConfig)
```
    Creates vertices to represent each bike rental station.
  - clone
```
public StreetLayer clone()
```
    Overrides:
    
    clone in class Object
  - isScenarioCopy
```
public boolean isScenarioCopy()
```
    Returns:
    
    true if this StreetLayer was created by a scenario, and is therefore wrapping a base StreetLayer.
  - scenarioEdgesBoundingGeometry
```
public com.vividsolutions.jts.geom.Geometry scenarioEdgesBoundingGeometry(int radiusMeters)
```
    Create a geometry in FIXED POINT DEGREES containing all the points on all edges created or removed by the scenario that produced this StreetLayer, buffered by radiusMeters. This is a MultiPolygon or GeometryCollection. When there are no created or removed edges, returns an empty geometry rather than null, because we test whether transit stops are contained within the resulting geometry.
  - logFixedPointGeometry
```
public static void logFixedPointGeometry(String label,
                                         com.vividsolutions.jts.geom.Geometry fixedPointGeometry)
```
    Given a JTS Geometry in fixed-point latitude and longitude, log it as floating-point GeoJSON.
  - findParkRidesInEnvelope
```
public List<ParkRideParking> findParkRidesInEnvelope(com.vividsolutions.jts.geom.Envelope env)
```
    Finds all the P+R stations in given envelope. This might overselect (doesn't filter the objects from the spatial index) but it's only used in visualizations.
    
    Parameters:
    
    env - Envelope in float degrees
    
    Returns:
    
    empty list if none are found or no P+R stations are in graph
  - findBikeSharesInEnvelope
```
public List<BikeRentalStation> findBikeSharesInEnvelope(com.vividsolutions.jts.geom.Envelope env)
```
    Finds all the bike share stations in given envelope. Might overselect from the spatial index but this is only used for visualizations.
    
    Parameters:
    
    env - Envelope in float degrees
    
    Returns:
    
    BikeRentalStations, or empty list if none are found or there are no bike stations in the graph.
  - getWaitTime
```
public int getWaitTime(double lat,
                       double lon)
```
    Parameters:
    
    lat - latitude of the starting point in floating point degrees
    
    lon - longitude the starting point in floating point degrees
    
    Returns:
    
    the waiting time in seconds to begin driving on the street network (waiting to be picked up by a car)
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object

Class StreetLayer

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

MIN_SUBGRAPH_SIZE

LINK_RADIUS_METERS

INITIAL_LINK_RADIUS_METERS

outgoingEdges

incomingEdges

spatialIndex

bikeRentalStationMap

parkRideLocationsMap

envelope

vertexStore

edgeStore

turnRestrictions

parentNetwork

scenarioId

baseStreetLayer

waitTimePolygons

ALL_PERMISSIONS

bikeSharing

Constructor Detail

StreetLayer

Method Detail

loadFromOsm

openOSM

getNameEdgeIdx

getWayTags

indexStreets

findEdgesInEnvelope

buildEdgeLists

getOrCreateVertexNear

splitEdge

createAndLinkVertex

findSplit

associateStops

getVertexCount

getEnvelope

scenarioCopy

associateBikeSharing

clone

isScenarioCopy

scenarioEdgesBoundingGeometry

logFixedPointGeometry

findParkRidesInEnvelope

findBikeSharesInEnvelope

getWaitTime

toString