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 backwards-incompatible changes, but the API may not be entirely stable.

Summary of Module Members

Module Attributes

Vectorlike

Alias for types which can be interpreted as positions in Scenic.

Classes

Intersection

An intersection where multiple roads meet.

Lane

A lane for cars, bicycles, or other vehicles.

LaneGroup

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

LaneSection

Part of a lane in a single RoadSection.

LinearElement

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

Maneuver

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

ManeuverType

A type of Maneuver, e.g., going straight or turning left.

Network

A road network.

NetworkElement

Abstract class for part of a road network.

PedestrianCrossing

A pedestrian crossing (crosswalk).

Road

A road consisting of one or more lanes.

RoadSection

Part of a road with a fixed number of lanes.

Shoulder

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

Sidewalk

A sidewalk.

Signal

Traffic lights, stop signs, etc.

VehicleType

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 and Object, and pairs of numbers.

alias of Vector | Point2D | Tuple[Real, Real]

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

U-turn.

static guessTypeFromLanes(start, end, connecting, turnThreshold=0.3490658503988659)[source]

For formats lacking turn information, guess it from the geometry.

Parameters:

  • start (Lane) – starting lane of the maneuver.

  • end (Lane) – ending lane of the maneuver.

  • connecting (Lane | None) – connecting lane of the maneuver, if any.

  • turnThreshold (float) – angle beyond which to consider a maneuver a turn.

class Maneuver[source]

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

Parameters:
type: ManeuverType

type of maneuver (straight, left turn, etc.)

startLane: Lane

starting lane of the maneuver

endLane: Lane

ending lane of the maneuver

connectingLane: Lane | None

connecting lane from the start to the end lane, if any (None for lane mergers)

intersection: Intersection | None

intersection where the maneuver takes place, if any (None for lane mergers)

property conflictingManeuvers: Tuple[Maneuver]

Maneuvers whose connecting lanes intersect this one’s.

property reverseManeuvers: Tuple[Maneuver]

Maneuvers whose start and end roads are the reverse of this one’s.

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 like Car in lane or Car on road if lane and road are elements, as well as computing distances to an element, etc.

Parameters:
name: str

Human-readable name, if any.

uid: str

Unique identifier; from underlying format, if possible. (In OpenDRIVE, for example, ids are not necessarily unique, so we invent our own.)

id: str | None

Identifier from underlying format, if any.

network: Network

Link to parent network.

vehicleTypes: FrozenSet[VehicleType]

Which types of vehicles (car, bicycle, etc.) can be here.

speedLimit: float | None

Optional speed limit, which may be inherited from parent.

tags: FrozenSet[str]

Uninterpreted semantic tags, e.g. ‘roundabout’.

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. (So Object in element will align by default to that orientation.)

Parameters:

point (`scenic.domains.driving.roads.Vectorlike`)

Return type:

Tuple[Orientation]

class LinearElement[source]

Bases: NetworkElement

A part of a road network with (mostly) linear 1- or 2-way 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 2-way 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 2-way roads they will point opposite directions.

Parameters:
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 (int | None) – number of steps to take, or None to compute the number of steps based on the distance (default None).

  • stepSize (float) – length used to compute how many steps to take, if steps is not specified (default 5 meters).

Return type:

Vector

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 the Road. Such intermediate branching points cause the Road to be partitioned into multiple road sections, within which the configuration of lanes is fixed.

Parameters:
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.

forwardLanes: LaneGroup | None

Group of lanes aligned with the direction of the road, if any.

backwardLanes: LaneGroup | None

Group of lanes going in the opposite direction, if any.

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

Possibly-empty 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:

RoadSection | None

laneSectionAt(point, reject=False)[source]

Get the LaneSection passing through a given point.

Parameters:

point (`scenic.domains.driving.roads.Vectorlike`)

Return type:

LaneSection | None

laneAt(point, reject=False)[source]

Get the Lane passing through a given point.

Parameters:

point (`scenic.domains.driving.roads.Vectorlike`)

Return type:

Lane | None

laneGroupAt(point, reject=False)[source]

Get the LaneGroup passing through a given point.

Parameters:

point (`scenic.domains.driving.roads.Vectorlike`)

Return type:

LaneGroup | None

crossingAt(point, reject=False)[source]

Get the PedestrianCrossing passing through a given point.

Parameters:

point (`scenic.domains.driving.roads.Vectorlike`)

Return type:

PedestrianCrossing | None

shiftLanes(point, offset)[source]

Find the point equivalent to this one but shifted over some # of lanes.

Parameters:

  • point (`scenic.domains.driving.roads.Vectorlike`)

  • offset (int)

Return type:

Vector | None

class LaneGroup[source]

Bases: LinearElement

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

Parameters:
road: Road

Parent road.

lanes: Tuple[Lane]

Lanes, partially ordered with lane 0 being closest to the curb.

curb: PolylineRegion

Region representing the associated curb, which is not necessarily adjacent if there are parking lanes or some other kind of shoulder.

_sidewalk: Sidewalk | None

Adjacent sidewalk, if any.

_shoulder: Shoulder | None

Adjacent shoulder, if any.

_opposite: LaneGroup | None

Opposite lane group of the same road, if any.

property sidewalk: Sidewalk

The adjacent sidewalk; rejects if there is none.

property shoulder: Shoulder

The adjacent shoulder; rejects if there is none.

property opposite: LaneGroup

The opposite lane group of the same road; rejects if there is none.

laneAt(point, reject=False)[source]

Get the Lane passing through a given point.

Parameters:

point (`scenic.domains.driving.roads.Vectorlike`)

Return type:

Lane | None

class Lane[source]

Bases: LinearElement

A lane for cars, bicycles, or other vehicles.

Parameters:
sectionAt(point, reject=False)[source]

Get the LaneSection passing through a given point.

Parameters:

point (`scenic.domains.driving.roads.Vectorlike`)

Return type:

LaneSection | None

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:
laneAt(point, reject=False)[source]

Get the lane section passing through a given point.

Parameters:

point (`scenic.domains.driving.roads.Vectorlike`)

Return type:

LaneSection | None

class LaneSection[source]

Bases: LinearElement

Part of a lane in a single RoadSection.

Since the lane configuration in a RoadSection is fixed, a LaneSection can have at most one adjacent lane to left or right. These are accessible using the laneToLeft and laneToRight 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:
lane: Lane

Parent lane.

group: LaneGroup

Grandparent lane group.

road: Road

Great-grandparent road.

isForward: bool

Whether this lane has the same direction as its parent road.

adjacentLanes: Tuple[LaneSection]

Adjacent lanes of the same type, if any.

_laneToLeft: LaneSection | None

Adjacent lane of same type to the left, if any.

_laneToRight: LaneSection | None

Adjacent lane of same type to the right, if any.

_fasterLane: LaneSection | None

Faster adjacent lane of same type, if any. Could be to left or right depending on the country.

_slowerLane: LaneSection | None

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.

shiftedBy(offset)[source]

Find the lane a given number of lanes over from this lane.

Parameters:

offset (int)

Return type:

LaneSection | None

class Sidewalk[source]

Bases: LinearElement

A sidewalk.

Parameters:
class PedestrianCrossing[source]

Bases: LinearElement

A pedestrian crossing (crosswalk).

Parameters:
class Shoulder[source]

Bases: LinearElement

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

Parameters:
class Intersection[source]

Bases: NetworkElement

An intersection where multiple roads meet.

Parameters:
property is3Way: bool

Whether or not this is a 3-way intersection.

Type:

bool

property is4Way: bool

Whether or not this is a 4-way intersection.

Type:

bool

property isSignalized: bool

Whether or not this is a signalized intersection.

Type:

bool

maneuversAt(point)[source]

Get all maneuvers possible at a given point in the intersection.

Parameters:

point (`scenic.domains.driving.roads.Vectorlike`)

Return type:

List[Maneuver]

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.

Parameters:
openDriveID: int

ID number as in OpenDRIVE (unique ID of the signal within the database)

country: str

Country code of the signal

type: str

Type identifier according to country code.

property isTrafficLight: bool

Whether or not this signal is a traffic light.

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]

All network elements, indexed by unique ID.

roads: Tuple[Road]

All ordinary roads in the network (i.e. those not part of an intersection).

connectingRoads: Tuple[Road]

All roads connecting one exit of an intersection to another.

allRoads: Tuple[Road]

All roads of either type.

laneGroups: Tuple[LaneGroup]

All lane groups in the network.

lanes: Tuple[Lane]

All lanes in the network.

intersections: Tuple[Intersection]

All intersections in the network.

crossings: Tuple[PedestrianCrossing]

All pedestrian crossings in the network.

sidewalks: Tuple[Sidewalk]

All sidewalks in the network.

shoulders: Tuple[Shoulder]

All shoulders in the network (by default, includes parking lanes).

roadSections: Tuple[RoadSection]

All sections of ordinary roads in the network.

laneSections: Tuple[LaneSection]

All sections of lanes in the network.

driveOnLeft: bool

Whether or not cars drive on the left in this network.

tolerance: float

Distance tolerance for testing inclusion in network elements.

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:

See the functions listed above for format-specific 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 path-like 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:
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:
Return type:

NetworkElement | None

elementAt(point, reject=False)[source]

Get the highest-level NetworkElement at a given point, if any.

If the point lies in an element, return it. Otherwise, if the point lies within self.tolerance of an element, return the first match using this priority order: Intersection → Road → Shoulder → Sidewalk. If nothing matches, return None (or reject if reject=True).

Parameters:

point (`scenic.domains.driving.roads.Vectorlike`)

Return type:

NetworkElement | None

roadAt(point, reject=False)[source]

Get the Road passing through a given point.

Parameters:

point (`scenic.domains.driving.roads.Vectorlike`)

Return type:

Road | None

laneAt(point, reject=False)[source]

Get the Lane passing through a given point.

Parameters:

point (`scenic.domains.driving.roads.Vectorlike`)

Return type:

Lane | None

laneSectionAt(point, reject=False)[source]

Get the LaneSection passing through a given point.

Parameters:

point (`scenic.domains.driving.roads.Vectorlike`)

Return type:

LaneSection | None

laneGroupAt(point, reject=False)[source]

Get the LaneGroup passing through a given point.

Parameters:

point (`scenic.domains.driving.roads.Vectorlike`)

Return type:

LaneGroup | None

crossingAt(point, reject=False)[source]

Get the PedestrianCrossing passing through a given point.

Parameters:

point (`scenic.domains.driving.roads.Vectorlike`)

Return type:

PedestrianCrossing | None

intersectionAt(point, reject=False)[source]

Get the Intersection at a given point.

Parameters:

point (`scenic.domains.driving.roads.Vectorlike`)

Return type:

Intersection | None

sidewalkAt(point, reject=False)[source]

Get the Sidewalk at a given point.

Parameters:

point (`scenic.domains.driving.roads.Vectorlike`)

Return type:

Sidewalk | None

shoulderAt(point, reject=False)[source]

Get the Shoulder at a given point.

Parameters:

point (`scenic.domains.driving.roads.Vectorlike`)

Return type:

Shoulder | None

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.

Parameters:

point (`scenic.domains.driving.roads.Vectorlike`)

Return type:

Tuple[Orientation]

show(labelIncomingLanes=False, showCurbArrows=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.

  • showCurbArrows (bool) – Whether to draw arrows along the curb to show orientation