Networks/SUMO Road Networks

SUMO road network
Filename extension .net.xml
Type of content Map
Open format? Yes
SUMO specific? Yes
XML Schema net_file.xsd
Screenshot of a SUMO net file opened in sumo-gui. It shows the map of the German city Eichstätt.

A SUMO network file describes the traffic-related part of a map, the roads and intersections the simulated vehicles run along or across. At a coarse scale, a SUMO network is a directed graph. Nodes, usually named "junctions" in SUMO-context, represent intersections, and "edges" roads or streets. Note that edges are unidirectional. Specifically, the SUMO network contains the following information:

  • every street (edge) as a collection of lanes, including the position, shape and speed limit of every lane,
  • traffic light logics referenced by junctions,
  • junctions, including their right of way regulation,
  • connections between lanes at junctions (nodes).

Also, depending on the used input formats and set processing options, one can also find

  • districts,
  • roundabout descriptions.

Although being readable (XML) by human beings, a SUMO network file is not meant to be edited by hand. Rather you should use SUMO XML description files together with NETCONVERT. You can also convert an existing map from various formats using NETCONVERT or generate geometrically simple, abstract road maps with NETGENERATE. You may also use NETEDIT for building own road networks or for reworking the ones obtained from NETCONVERT or NETGENERATE.

Contents

Network Format

SUMO road networks are encoded as XML files. The contents are grouped by the instances in the following order:

  • cartographic projection valid for this network
  • edges; at first, internal edges are given, then plain edges; each edge contains the list of lanes that belong to it
  • traffic light logics
  • junctions, including their right-of-way definitions; plain junctions first, then internal junctions
  • connections, plain first, then internal
  • optionally roundabouts

Coordinates and alignment

The networks are using cartesian, metric coordinates where the leftmost node is at x=0 and the node being most at the bottom is at y=0. This means that when being imported, NETCONVERT and NETGENERATE are projecting the network, first, if the original network was not using cartesian and/or metric coordinates. Then, they move the road network to the origin at (0,0).

This process is documented within the generated network within the element location. You may find here the following attributes:

Name Type Description
netOffset offset (<2D-POSITION>) The offset applied for moving the network to (0,0)
convBoundary boundary (<2D-BOUNDING_BOX>) The boundary spanning over the nodes of the converted network (the network as now given)
origBoundary boundary (<2D-BOUNDING_BOX>) The network's initial boundary before projecting and translating it
projParameter projection parameter Information how the network was projected (see below)


projParameter may have one of the following values:

Encoding Description
'!' No projection was applied.
'-' "Simple" projection was applied
'.'  ?
proj-definition (<PROJ_DEFINITION>) The projection was done using proj, initialising it using these parameter.


For obtaining the original coordinates from the x/y-coordinates SUMO reports, one has to subtract the network offset first. Then, one has to apply an inverse transformation of the initial projection, regarding projParameter. For proj-projected networks, one can use proj's function named pj_inv which performs the inverse transformation. proj has to be initialised with the projection parameters from projParameter, first. For proj-projected networks this would look like: 

Position2D cartesian = sumoXY(x, y);
projPJ myProjection = pj_init_plus(projParameter.c_str());
cartesian.sub(netOffset);
projUV p;
p.u = cartesian.x();
p.v = cartesian.y();
p = pj_inv(p, myProjection);
p.u *= RAD_TO_DEG;
p.v *= RAD_TO_DEG;
cartesian.set((SUMOReal) p.u, (SUMOReal) p.v);

For networks with no projection (projParameter='!'), only the offset must be applied. For networks with "simple" projection (projParameter='-'), a back-projection method is currently not known.

SUMO road networks are meant to be aligned to the north. Of course, it is up to the user how he defines a road network, but when being imported from sources as Open Street Map or shape files, the up-direction is meant to correspond to north.

Edges and Lanes

"plain" and "internal" edges are encoded almost the same way, but they differ by the mandatory and used attributes.

Internal Edges

Internal edges are not included if the network was built using the --no-internal-links option. An example of an internal edge may look like this: 

    <edge id="<ID>" function="internal">
        ... one lane ...
    </edge>

The id of an internal edge is composed as :<NODE_ID>_<CONNECTION_NUMBER> where <NODE_ID> is the ID of the node the edge is located within and <CONNECTION_NUMBER> is a running number. Please note that the ID has a ':' as prefix. Currently, an internal edge has only one lane - the connection it represents. This is assumed to be a candidate for future changes, mainly for reducing the file size.

The attributes are given in the following table.

Name Type Description
id id (string) The id of the internal edge
function "internal" Always "internal" for an internal edge

Normal Edges

A "normal" edge is a connection between two nodes ("junctions"). 

    <edge id="<ID>" from="<FROM_NODE_ID>" to="<TO_NODE_ID>" priority="<PRIORITY>">
        ... one or more lanes ...
    </edge>

Here, the ID (<ID> in the example above) is an ID as read during the network import. Both the IDs of the begin and the end node are given within the attributes from and to, respectively. The priority is an abstract ordinal number that determines right-of-way rules. The function attribute was omitted in the example above, as it defaults to "normal", which is the example edge's function value.

The attributes of an edge are:

Name Type Description
id id (string) The id of the edge
from id (string) The id of the node it starts at
to id (string) The id of the node it ends at
priority integer Indicates how important the road is (optional)
function enum ( "normal", "internal", "connector" ) An abstract edge purpose (optional with default "normal")

For the simulation, only the "function" attribute is of interest. It describes how the edge is used, and whether it is an edge that can be found within the real world or only a helper construct used for assignment. The following purposes are defined:

  • normal: The edge is a plain part of a road network, like a highway or a normal street which connects two roads
  • connector: The edge is a macroscopic connector - not a part of the real world road network. Still, within the simulation, no distinction is made between "connector" roads and "normal" nodes. Only SUMO-GUI allows to hide connector edges.
  • internal: The edge is a part of an intersection (is located within the intersection), see above.

Lanes

Each edge includes the definitions of lanes it consists of. The following example shows a single edge with two lanes. 

    <edge id="<ID>" from="<FROM_NODE_ID>" to="<TO_NODE_ID>" priority="<PRIORITY>">
        <lane id="<ID>_0" index="0" speed="<SPEED>" length="<LENGTH>" shape="0.00,495.05 248.50,495.05"/>
        <lane id="<ID>_1" index="1" speed="<SPEED>" length="<LENGTH>" shape="0.00,498.35 248.50,498.35"/>
    </edge>

As one can see, the id is composed by the ID of the edge the lane belongs to and a running number, both divided by an underline ('_'). The running number starts at zero for the right-most lane. The same number is also given in the "index" attribute. The lanes are sorted by this number, to. @note: this is highly duplicate

The attributes of a lane are:

Name Type Description
id id (string) The id of the lane
index running number (unsigned int) A running number, starting with zero at the right-most lane
speed float The maximum speed allowed on this lane [m/s]
length float The length of this lane [m]
shape position vector The geometry of the lane, given by a polyline that describes the lane's centre line; must not be empty or have less than two positions

It should be noted, that currently all lanes of an edge have the same length, even if it differs from the geometrical length of the shape. NETCONVERT even explicitly allows to override the geometrical lengths. Additionally, even though the network is shifted to start at (0,0), it is not guaranteed that all of the network's parts have positive coordinates.

Traffic Light Programs

A traffic light program defines the phases of a traffic light. 

    <tlLogic id="<ID>" type="<ALGORITHM_ID>" programID="<PROGRAM_ID>" offset="<TIME_OFFSET>">
        <phase duration="<DURATION#1>" state="<STATE#1>"/>
        <phase duration="<DURATION#1>" state="<STATE#1>"/>
        ... further states ...
        <phase duration="<DURATION#n>" state="<STATE#n>"/>
    </tlLogic>

For an explanation of the attributes and semantics, please consult Simulation/Traffic Lights. Please note that usually, the generated program has the ID "0".

Junctions and Right-of-Way

Plain Junctions

Junctions represent the area where different streams cross, including the right-of-way rules vehicles have to follow when crossing the intersection. An example may be: 

    <junction id="<ID>" type="<JUNCTION_TYPE>" x="<X-POSITION>" y="<Y-POSITION>" 
              incLanes="<INCOMING_LANES>" intLanes="<INTERNAL_LANES>" 
              shape="<SHAPE>">
        ... requests ...
    </junction>

The junction itself is described by the following attributes:

Name Type Description
id id (string) The id of the junction; please note, that a traffic light definition must use the same ID when controlling this intersection.
x x-position (real) The x-coordinate of the intersection
y y-position (real) The y-coordinate of the intersection
incLanes id list The ids of the lanes that end at the intersection; sorted by direction, clockwise, with direction up = 0
intLanes id list The IDs of the lanes within the intersection
shape position list A polygon describing the road boundaries of the intersection

Please note, that the x/y-positions of the junction describe the given, not the computed centre of the junction. It is allowed for two nodes to have the same position.

Requests

What follows are "request"s, looking like: 

        <request index="<INDEX>" response="<RELATIVE_MAJOR_LINKS>" foes="<FOE_LINKS>" cont="<MAY_ENTER>"/>

They describe, for each link (given as "index") which streams have a higher priority ("response") and force the vehicle on link "index" to stop, and which streams are in conflict ("foes"). "foes" is a super-set of "response", adding streams that have a lower priority than the stream referenced as "index".

One can read the requests as following: the index describes a certain connection, between an incoming and an outgoing lane, over the intersection. The indices are computed connection-wise and the order is as following: first, sort edges by their direction, starting with 0° (up); second, use lane order (right-most-first); third, order by the direction the connection follows, starting by the right-most.

The same order is applied in the "response" and the "foes" field, starting from left. This means: 

        <request index="2" response="100" foes="110" cont="0"/>

The a vehicle using the connection with the index "2" has to wait for vehicles that use the connection "0". Connections "0" and "1" are it's foes. The attributes of a request element are:

Name Type Description
index index (unsigned int) The index of the described connection in the right-of-way matrix
response bitset (string) A bitset, starting at 0=left, which describes which connection (index in the bitset) prohibits the un-decelerated passing of the intersection for vehicles at this connection
foes bitset (string) A bitset, starting at 0=left, which describes which connection (index in the bitset) are foes for vehicles at this connection; "foe streams" are those streams over an intersection that collide
cont bool Whether a vehicle may enter the intersection, but may not pass it in every case; left-moving streams belong to this class, usually.

Internal Junctions

"internal" junctions do not need a right-of-way matrix but only following information

  • the lanes that are incoming into the junction the internal junction is located in and prohibit to pass the internal junction if a vehicle is approaching
  • the internal lanes that must not be occupied for crossing the internal junction

An internal junction is encoded like this: 

        <junction id="<ID>" type="internal" x="<X-POSITION>" y="<Y-POSITION>" 
                  incLanes="<INCOMING_PROHIBITING_LANES>" 
                  intLanes="<INTERNAL_PROHIBITING_LANES>"/>

The ID is the same as the lane to use when crossing the internal junction itself. The type is always "internal". Please note that an internal junction is usually encoded in one line. The attributes of an internal junction are:

Name Type Description
id id (string) The id of the junction; please note, that a traffic light definition must use the same ID when controlling this intersection.
x x-position (real) The x-coordinate of the intersection
y y-position (real) The y-coordinate of the intersection
incLanes id list The ids of the lanes that end at the intersection the internal junction is located within and prohibit to cross the internal junction
intLanes id list The ids of the lanes within the intersection the internal junction is located within and prohibit to cross the internal junction

Connections

Plain Connections

Plain connections or "links" describe which outgoing lanes can be reached from an incoming lane. Additionally, the first lane to use for passing the intersection is given. Additional information describe the direction and the "state" of the connection. If the connection is controlled by a traffic light, the name of the traffic light and the index of the signal that controls this connection within the traffic light's phase definition is given. A connection is encoded as: 

    <connection from="<FROM_EDGE_ID>" to="<TO_EDGE_ID>" fromLane="<FROM_LANE_INDEX>" toLane="<TO_LANE_INDEX>" 
                via="<VIA_LANE_ID>" tl="<FROM_EDGE_ID>" linkIndex="12" dir="r" state="o"/>

The attributes are:

Name Type Description
from edge id (string) The ID of the incoming edge at which the connection begins
to edge id (string) The ID of the outgoing edge at which the connection ends
fromLane index (unsigned int) The lane of the incoming edge at which the connection begins
toLane index (unsigned int) The lane of the outgoing edge at which the connection ends
via lane id (string) The id of the lane to use to pass this connection across the junction
tl traffic light id (string) The id of the traffic light that controls this connection; the attribute is missing if the connection is not controlled by a traffic light
linkIndex index (unsigned int) The index of the signal responsible for the connection within the traffic light; the attribute is missing if the connection is not controlled by a traffic light
dir enum (!!!) The direction of the connection
state enum (!!!) The state of the connection

Roundabouts

Missing:
Description is missing

Software for Viewing, Editing and Processing

To create a SUMO network file, NETCONVERT helps to generate it from maps in other formats and NETGENERATE constructs a new map with simple geometries. SUMO performs its simulation directly in the map of this file. Most other SUMO tools read such files to generate or import information that must be the mapped onto a road network.

The SUMO net file is not meant for direct editing. Convert it to the SUMO native XML descriptions with NETCONVERT instead. You can then process these files by hand or, for example, with eWorld.

An application for editing the networks named NETEDIT is available for project partners. It is not part of the open source release. Please ask us directly.

Further Documentation

Note:
Please see the ChangeLog when dealing with networks generated by old versions of NETCONVERT / NETGENERATE.
This page was last modified on 6 May 2013, at 20:48.