Networks/SUMO Road Networks



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.

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:

projParameter may have one of the following values:

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 option. An example of an internal edge may look like this: " function="internal"> ... one lane ...

The id of an internal edge is composed as :_ where  is the ID of the node the edge is located within and  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.

Normal Edges
A "normal" edge is a connection between two nodes ("junctions"). " from="" to="" priority=""> ... one or more lanes ...

Here, the 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:

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. " from="" to="" priority=""> _0" index="0" 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"/>

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, too. @note: this is highly duplicate

The attributes of a lane are:

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".

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

The junction itself is described by the following attributes:

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 its foes. The attributes of a request element are:

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:

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: When creating these connections without Netconvert (not recommended) it should be taken into account that a connection with an internal lane follows a special pattern. For example when lane 1_f_0 needs to be connected to 1_t_0 through 1_v_0, the following connection entries exist: [from=1_f_0, to=1_t_0 via=1_v_0] and [from=1_v_0 to=1_t_0]. If the latter is omitted, SUMO will not load the network. It will also not load if next to the necessary connections a connection [from=1_f_0 to=1_v_0] exists.

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

 * Network Import
 * Defining own networks using XML and NETCONVERT
 * Importing networks from other applications using NETCONVERT
 * NETCONVERT manual
 * Generation of abstract road networks
 * Generating abstract networks using NETGENERATE
 * NETGENERATE manual
 * NETEDIT manual
 * Developer/Network Building Process