scenic.domains.driving.roads
Library for representing road network geometry and traffic information.
A road network is represented by an instance of the Network
class, which can
be created from a map file using Network.fromFile
.
Note
This library is a prototype under active development. We will try not to make backwardsincompatible changes, but the API may not be entirely stable.
Summary of Module Members
Module Attributes
Alias for types which can be interpreted as positions in Scenic. 
Classes
An intersection where multiple roads meet. 

A lane for cars, bicycles, or other vehicles. 

A group of parallel lanes with the same type and direction. 

Part of a lane in a single 

A part of a road network with (mostly) linear 1 or 2way flow. 

A maneuver which can be taken upon reaching the end of a lane. 

A type of 

A road network. 

Abstract class for part of a road network. 

A pedestrian crossing (crosswalk). 

A road consisting of one or more lanes. 

Part of a road with a fixed number of lanes. 

A shoulder of a road, including parking lanes by default. 

A sidewalk. 

Traffic lights, stop signs, etc. 

A type of vehicle, including pedestrians. 
Member Details
 Vectorlike
Alias for types which can be interpreted as positions in Scenic.
This includes instances of
Point
andObject
, and pairs of numbers.
 class VehicleType(value)[source]
Bases:
Enum
A type of vehicle, including pedestrians. Used to classify lanes.
 class ManeuverType(value)[source]
Bases:
Enum
A type of
Maneuver
, e.g., going straight or turning left. STRAIGHT = 1
Straight, including one lane merging into another.
 LEFT_TURN = 2
Left turn.
 RIGHT_TURN = 3
Right turn.
 U_TURN = 4
Uturn.
 class Maneuver[source]
A maneuver which can be taken upon reaching the end of a lane.
 Parameters:
type (ManeuverType) –
startLane (Lane) –
endLane (Lane) –
intersection (Optional[Intersection]) –
 type: ManeuverType
type of maneuver (straight, left turn, etc.)
 connectingLane: Optional[Lane]
connecting lane from the start to the end lane, if any (
None
for lane mergers)
 intersection: Optional[Intersection]
intersection where the maneuver takes place, if any (
None
for lane mergers)
 class NetworkElement[source]
Bases:
PolygonalRegion
Abstract class for part of a road network.
Includes roads, lane groups, lanes, sidewalks, pedestrian crossings, and intersections.
This is a subclass of
Region
, so you can do things likeCar in lane
orCar on road
iflane
androad
are elements, as well as computing distances to an element, etc. Parameters:
 uid: str
Unique identifier; from underlying format, if possible. (In OpenDRIVE, for example, ids are not necessarily unique, so we invent our own.)
 vehicleTypes: FrozenSet[VehicleType]
Which types of vehicles (car, bicycle, etc.) can be here.
 nominalDirectionsAt(point)[source]
Get nominal traffic direction(s) at a point in this element.
There must be at least one such direction. If there are multiple, we pick one arbitrarily to be the orientation of the element as a
Region
. (SoObject in element
will align by default to that orientation.)
 class LinearElement[source]
Bases:
NetworkElement
A part of a road network with (mostly) linear 1 or 2way flow.
Includes roads, lane groups, lanes, sidewalks, and pedestrian crossings, but not intersections.
LinearElements have a direction, namely from the first point on their centerline to the last point. This is called ‘forward’, even for 2way roads. The ‘left’ and ‘right’ edges are interpreted with respect to this direction.
The left/right edges are oriented along the direction of traffic near them; so for 2way roads they will point opposite directions.
 Parameters:
polygon (Union[Polygon, MultiPolygon]) –
orientation (Optional[VectorField]) –
name (str) –
uid (str) –
network (Network) –
vehicleTypes (FrozenSet[VehicleType]) –
centerline (PolylineRegion) –
leftEdge (PolylineRegion) –
rightEdge (PolylineRegion) –
successor (Union[NetworkElement, None]) –
predecessor (Union[NetworkElement, None]) –
 flowFrom(point, distance, steps=None, stepSize=5)[source]
Advance a point along this element by a given distance.
Equivalent to
follow element.orientation from point for distance
, but possibly more accurate. The default implementation uses the forward Euler approximation with a step size of 5 meters; subclasses may ignore the steps and stepSize parameters if they can compute the flow exactly. Parameters:
point (`scenic.domains.driving.roads.Vectorlike`) – point to start from.
distance (float) – distance to travel.
steps (Optional[int]) – number of steps to take, or
None
to compute the number of steps based on the distance (defaultNone
).stepSize (float) – length used to compute how many steps to take, if steps is not specified (default 5 meters).
 Return type:
 class Road[source]
Bases:
LinearElement
A road consisting of one or more lanes.
Lanes are grouped into 1 or 2 instances of
LaneGroup
:forwardLanes: the lanes going the same direction as the road
backwardLanes: the lanes going the opposite direction
One of these may be None if there are no lanes in that direction.
Because of splits and mergers, the Lanes of a
Road
do not necessarily start or end at the same point as theRoad
. Such intermediate branching points cause theRoad
to be partitioned into multiple road sections, within which the configuration of lanes is fixed. Parameters:
polygon (Union[Polygon, MultiPolygon]) –
orientation (Optional[VectorField]) –
name (str) –
uid (str) –
network (Network) –
vehicleTypes (FrozenSet[VehicleType]) –
centerline (PolylineRegion) –
leftEdge (PolylineRegion) –
rightEdge (PolylineRegion) –
successor (Union[NetworkElement, None]) –
predecessor (Union[NetworkElement, None]) –
sections (Tuple[RoadSection]) –
crossings (Tuple[PedestrianCrossing]) –
sidewalkRegion (PolygonalRegion) –
 lanes: Tuple[Lane]
All lanes of this road, in either direction.
The order of the lanes is arbitrary. To access lanes in order according to their geometry, use
LaneGroup.lanes
.
 laneGroups: Tuple[LaneGroup]
All LaneGroups of this road, with
forwardLanes
being first if it exists.
 sections: Tuple[RoadSection]
All sections of this road, ordered from start to end.
 crossings: Tuple[PedestrianCrossing]
All crosswalks of this road, ordered from start to end.
 sidewalks: Tuple[Sidewalk]
All sidewalks of this road, with the one adjacent to
forwardLanes
being first.
 sidewalkRegion: PolygonalRegion
Possiblyempty region consisting of all sidewalks of this road.
 sectionAt(point, reject=False)[source]
Get the
RoadSection
passing through a given point. Parameters:
point (`scenic.domains.driving.roads.Vectorlike`) –
 Return type:
 laneSectionAt(point, reject=False)[source]
Get the
LaneSection
passing through a given point. Parameters:
point (`scenic.domains.driving.roads.Vectorlike`) –
 Return type:
 crossingAt(point, reject=False)[source]
Get the
PedestrianCrossing
passing through a given point. Parameters:
point (`scenic.domains.driving.roads.Vectorlike`) –
 Return type:
 class LaneGroup[source]
Bases:
LinearElement
A group of parallel lanes with the same type and direction.
 Parameters:
polygon (Union[Polygon, MultiPolygon]) –
orientation (Optional[VectorField]) –
name (str) –
uid (str) –
network (Network) –
vehicleTypes (FrozenSet[VehicleType]) –
centerline (PolylineRegion) –
leftEdge (PolylineRegion) –
rightEdge (PolylineRegion) –
successor (Union[NetworkElement, None]) –
predecessor (Union[NetworkElement, None]) –
road (Road) –
curb (PolylineRegion) –
sidewalk (Union[Sidewalk, None]) –
bikeLane (Union[Lane, None]) –
shoulder (Union[Shoulder, None]) –
opposite (Union[LaneGroup, None]) –
 curb: PolylineRegion
Region representing the associated curb, which is not necessarily adjacent if there are parking lanes or some other kind of shoulder.
 class Lane[source]
Bases:
LinearElement
A lane for cars, bicycles, or other vehicles.
 Parameters:
polygon (Union[Polygon, MultiPolygon]) –
orientation (Optional[VectorField]) –
name (str) –
uid (str) –
network (Network) –
vehicleTypes (FrozenSet[VehicleType]) –
centerline (PolylineRegion) –
leftEdge (PolylineRegion) –
rightEdge (PolylineRegion) –
successor (Union[NetworkElement, None]) –
predecessor (Union[NetworkElement, None]) –
group (LaneGroup) –
road (Road) –
sections (Tuple[LaneSection]) –
 class RoadSection[source]
Bases:
LinearElement
Part of a road with a fixed number of lanes.
A RoadSection has a fixed number of lanes: when a lane begins or ends, we move to a new section (which will be the successor of the current one).
 Parameters:
polygon (Union[Polygon, MultiPolygon]) –
orientation (Optional[VectorField]) –
name (str) –
uid (str) –
id (Optional[str]) –
network (Network) –
vehicleTypes (FrozenSet[VehicleType]) –
speedLimit (Union[float, None]) –
tags (FrozenSet[str]) –
centerline (PolylineRegion) –
leftEdge (PolylineRegion) –
rightEdge (PolylineRegion) –
successor (Union[NetworkElement, None]) –
predecessor (Union[NetworkElement, None]) –
road (Road) –
lanes (Tuple[LaneSection]) –
forwardLanes (Tuple[LaneSection]) –
backwardLanes (Tuple[LaneSection]) –
lanesByOpenDriveID (Dict[LaneSection]) –
 class LaneSection[source]
Bases:
LinearElement
Part of a lane in a single
RoadSection
.Since the lane configuration in a
RoadSection
is fixed, aLaneSection
can have at most one adjacent lane to left or right. These are accessible using thelaneToLeft
andlaneToRight
properties, which for convenience reject the simulation if the desired lane does not exist. If rejection is not desired (for example if you want to handle the case where there is no lane to the left yourself), you can use the_laneToLeft
and_laneToRight
properties instead. Parameters:
polygon (Union[Polygon, MultiPolygon]) –
orientation (Optional[VectorField]) –
name (str) –
uid (str) –
network (Network) –
vehicleTypes (FrozenSet[VehicleType]) –
centerline (PolylineRegion) –
leftEdge (PolylineRegion) –
rightEdge (PolylineRegion) –
successor (Union[NetworkElement, None]) –
predecessor (Union[NetworkElement, None]) –
lane (Lane) –
group (LaneGroup) –
road (Road) –
openDriveID (int) –
isForward (bool) –
adjacentLanes (Tuple[LaneSection]) –
laneToLeft (Union[LaneSection, None]) –
laneToRight (Union[LaneSection, None]) –
fasterLane (Union[LaneSection, None]) –
slowerLane (Union[LaneSection, None]) –
 adjacentLanes: Tuple[LaneSection]
Adjacent lanes of the same type, if any.
 _laneToLeft: Optional[LaneSection]
Adjacent lane of same type to the left, if any.
 _laneToRight: Optional[LaneSection]
Adjacent lane of same type to the right, if any.
 _fasterLane: Optional[LaneSection]
Faster adjacent lane of same type, if any. Could be to left or right depending on the country.
 _slowerLane: Optional[LaneSection]
Slower adjacent lane of same type, if any.
 property laneToLeft: LaneSection
The adjacent lane of the same type to the left; rejects if there is none.
 property laneToRight: LaneSection
The adjacent lane of the same type to the right; rejects if there is none.
 property fasterLane: LaneSection
The faster adjacent lane of the same type; rejects if there is none.
 property slowerLane: LaneSection
The slower adjacent lane of the same type; rejects if there is none.
 class Sidewalk[source]
Bases:
LinearElement
A sidewalk.
 Parameters:
polygon (Union[Polygon, MultiPolygon]) –
orientation (Optional[VectorField]) –
name (str) –
uid (str) –
network (Network) –
vehicleTypes (FrozenSet[VehicleType]) –
centerline (PolylineRegion) –
leftEdge (PolylineRegion) –
rightEdge (PolylineRegion) –
successor (Union[NetworkElement, None]) –
predecessor (Union[NetworkElement, None]) –
road (Road) –
crossings (Tuple[PedestrianCrossing]) –
 class PedestrianCrossing[source]
Bases:
LinearElement
A pedestrian crossing (crosswalk).
 Parameters:
polygon (Union[Polygon, MultiPolygon]) –
orientation (Optional[VectorField]) –
name (str) –
uid (str) –
network (Network) –
vehicleTypes (FrozenSet[VehicleType]) –
centerline (PolylineRegion) –
leftEdge (PolylineRegion) –
rightEdge (PolylineRegion) –
successor (Union[NetworkElement, None]) –
predecessor (Union[NetworkElement, None]) –
parent (Union[Road, Intersection]) –
startSidewalk (Sidewalk) –
endSidewalk (Sidewalk) –
 class Shoulder[source]
Bases:
LinearElement
A shoulder of a road, including parking lanes by default.
 Parameters:
polygon (Union[Polygon, MultiPolygon]) –
orientation (Optional[VectorField]) –
name (str) –
uid (str) –
network (Network) –
vehicleTypes (FrozenSet[VehicleType]) –
centerline (PolylineRegion) –
leftEdge (PolylineRegion) –
rightEdge (PolylineRegion) –
successor (Union[NetworkElement, None]) –
predecessor (Union[NetworkElement, None]) –
road (Road) –
 class Intersection[source]
Bases:
NetworkElement
An intersection where multiple roads meet.
 Parameters:
polygon (Union[Polygon, MultiPolygon]) –
orientation (Optional[VectorField]) –
name (str) –
uid (str) –
network (Network) –
vehicleTypes (FrozenSet[VehicleType]) –
crossings (Tuple[PedestrianCrossing]) –
 class Signal(*, uid=None, openDriveID, country, type)[source]
Traffic lights, stop signs, etc.
Warning
Signal parsing is a work in progress and the API is likely to change in the future.
 class Network[source]
A road network.
Networks are composed of roads, intersections, sidewalks, etc., which are all instances of
NetworkElement
.Road networks can be loaded from standard formats using
Network.fromFile
. Parameters:
elements (Dict[str, NetworkElement]) –
roads (Tuple[Road]) –
connectingRoads (Tuple[Road]) –
allRoads (Tuple[Road]) –
laneGroups (Tuple[LaneGroup]) –
lanes (Tuple[Lane]) –
intersections (Tuple[Intersection]) –
crossings (Tuple[PedestrianCrossing]) –
sidewalks (Tuple[Sidewalk]) –
shoulders (Tuple[Shoulder]) –
roadSections (Tuple[RoadSection]) –
laneSections (Tuple[LaneSection]) –
driveOnLeft (bool) –
tolerance (float) –
drivableRegion (PolygonalRegion) –
walkableRegion (PolygonalRegion) –
roadRegion (PolygonalRegion) –
laneRegion (PolygonalRegion) –
intersectionRegion (PolygonalRegion) –
crossingRegion (PolygonalRegion) –
sidewalkRegion (PolygonalRegion) –
curbRegion (PolylineRegion) –
shoulderRegion (PolygonalRegion) –
roadDirection (VectorField) –
 elements: Dict[str, NetworkElement]
All network elements, indexed by unique ID.
 intersections: Tuple[Intersection]
All intersections in the network.
 crossings: Tuple[PedestrianCrossing]
All pedestrian crossings in the network.
 roadSections: Tuple[RoadSection]
All sections of ordinary roads in the network.
 laneSections: Tuple[LaneSection]
All sections of lanes in the network.
 roadDirection: VectorField
Traffic flow vector field aggregated over all roads (0 elsewhere).
 pickledExt = '.snet'
File extension for cached versions of processed networks.
 exception DigestMismatchError[source]
Bases:
Exception
Exception raised when loading a cached map not matching the original file.
 classmethod fromFile(path, useCache=True, writeCache=True, **kwargs)[source]
Create a
Network
from a map file.This function calls an appropriate parsing routine based on the extension of the given file. Supported map formats are:
OpenDRIVE (
.xodr
):Network.fromOpenDrive
See the functions listed above for formatspecific options to this function. If no file extension is given in path, this function searches for any file with the given name in one of the formats above (in order).
 Parameters:
path – A string or other pathlike object giving a path to a file. If no file extension is included, we search for any file type we know how to parse.
useCache (bool) – Whether to use a cached version of the map, if one exists and matches the given map file (default true; note that if the map file changes, the cached version will still not be used).
writeCache (bool) – Whether to save a cached version of the processed map after parsing has finished (default true).
kwargs – Additional keyword arguments specific to particular map formats.
 Raises:
FileNotFoundError – no readable map was found at the given path.
ValueError – the given map is of an unknown format.
 classmethod fromOpenDrive(path, ref_points=20, tolerance=0.05, fill_gaps=True, fill_intersections=True, elide_short_roads=False)[source]
Create a
Network
from an OpenDRIVE file. Parameters:
path – Path to the file, as in
Network.fromFile
.ref_points (int) – Number of points to discretize continuous reference lines into.
tolerance (float) – Tolerance for merging nearby geometries.
fill_gaps (bool) – Whether to attempt to fill gaps between adjacent lanes.
fill_intersections (bool) – Whether to attempt to fill gaps inside intersections.
elide_short_roads (bool) – Whether to attempt to fix geometry artifacts by eliding roads with length less than tolerance.
 findPointIn(point, elems, reject)[source]
Find the first of the given elements containing the point.
Elements which actually contain the point have priority; if none contain the point, then we search again allowing an error of up to tolerance. If there are still no matches, we return None, unless reject is true, in which case we reject the current sample.
 Parameters:
point (`scenic.domains.driving.roads.Vectorlike`) –
elems (Sequence[NetworkElement]) –
 Return type:
 elementAt(point, reject=False)[source]
Get the highestlevel
NetworkElement
at a given point, if any.If the point lies in an
Intersection
, we return that; otherwise if the point lies in aRoad
, we return that; otherwise we returnNone
, or reject the simulation if reject is true (default false). Parameters:
point (`scenic.domains.driving.roads.Vectorlike`) –
 Return type:
 laneSectionAt(point, reject=False)[source]
Get the
LaneSection
passing through a given point. Parameters:
point (`scenic.domains.driving.roads.Vectorlike`) –
 Return type:
 crossingAt(point, reject=False)[source]
Get the
PedestrianCrossing
passing through a given point. Parameters:
point (`scenic.domains.driving.roads.Vectorlike`) –
 Return type:
 intersectionAt(point, reject=False)[source]
Get the
Intersection
at a given point. Parameters:
point (`scenic.domains.driving.roads.Vectorlike`) –
 Return type:
 nominalDirectionsAt(point, reject=False)[source]
Get the nominal traffic direction(s) at a given point, if any.
There can be more than one such direction in an intersection, for example: a car at a given point could be going straight, turning left, etc.
 show(labelIncomingLanes=False)[source]
Render a schematic of the road network for debugging.
If you call this function directly, you’ll need to subsequently call
matplotlib.pyplot.show
to actually display the diagram. Parameters:
labelIncomingLanes (bool) – Whether to label the incoming lanes of intersections with their indices in
incomingLanes
.