Chapter 4. Network Generation

4.1. Introduction

As SUMO uses an own road network description, networks must be converted from an existing dataset. Although being readable (xml) by human beings, the format of road networks used by SUMO is not meant to be edited by hand and will also not be described herein due to its complexity. SUMO networks can be build by either converting an existing map or by using NETGEN to generate basic, abstract road maps. The following figure shows the function of NETCONVERT and NETGEN within the procedure of building and running a simulation.

Figure 4.1. Building a network

Building a network

Having data describing a road network, you may convert them into a network description readable by SUMO using the NETCONVERT tool. By now, NETCONVERT is capable to parse the following formats:

In most of these cases, NETCOVERT needs only two parameter: the option named as the source application/format followed by the name of the file to convert and the name of the output file (using the --output-file option). So if you want to import a file generated by the VISUM simulation package, simply write the following:

netconvert --visum=MyVisumNet.inp --output-file=MySUMONet.net.xml

The parameter --output-file has the default value "net.net.xml". That means that both NETCONVERT and NETGEN will save the generated file as "net.net.xml" if the option is not set. Please note, that NETCONVERT has to be started from the command line. There is no graphical interface available, yet.

The following subchapters will describe more deeply how NETCONVERT and NETGEN are used, also discussing some problems with each of the import formats NETCONVERT supports. Please remind the option to name the output generated by both applications:

( --output-file | --output | -o ) <OUTPUT_FILE>

Defines the file to write the computed network into. This file will contain the generated network if the conversion could be accomplished. Optional (pregiven), type:filename, default: "net.net.xml"

Recent changes:

  • ARTEMIS network import is was removed from version 0.9.7

4.2. Building Networks from own XML-descriptions

All examples within the distribution were made by hand. For doing this, you need at least two files: one file for nodes and another one for the streets between them. Please notice that herein, "node" and "junction" mean the same as well as "edge" and "street" do. Besides defining the nodes and edges, you can also join edges by type and set explicit connections between lanes. We will describe how each of these four file types should look like in the following chapters.

Figure 4.2. Building a network from XML-descriptions

Building a network from XML-descriptions

4.2.1. Nodes Descriptions

Within the nodes-files, normally having the extension ".nod.xml" (see Appendix "Naming Conventions"), every node is described in a single line which looks like this: <node id="<STRING>" x="<FLOAT>" y="<FLOAT>" [type="<TYPE>"]/> - the straight brackets ('[' and ']') indicate that the parameter is optional. Each of these attributes has a certain meaning and value range:

  • id: The name of the node; may be any character string

  • x: The x-position of the node on the plane in meters; must be a floating point number

  • y: The y-position of the node on the plane in meters; must be a floating point number

  • type: An optional type for the node. If you leave out the type of the node, it is automatically guessed by NETCOVERT but may not be the one you intentionally thought of. The following types are possible, any other string is counted as an error and will yield in a program stop:

    • priority: Vehicles have to wait until vehicles right to them have passed the junction.

    • traffic_light: The junction is controlled by a traffic light.

When writing your nodes-file, please do not forget to embed your node definitions into an opening and a closing "tag". A complete file should like the example below, which is the node file "cross3l.nod.xml" for the examples "<SUMO_DIST>/data/examples/netbuild/types/cross_usingtypes/" and "<SUMO_DIST>/data/examples/netbuild/types/cross_notypes/" example.

<nodes> <!-- The opening tag -->

   <node id="0" x="0.0" y="0.0" type="traffic_light"/> <!-- def. of node "0" -->

   <node id="1" x="-500.0" y="0.0" type="priority"/> <!-- def. of node "1" -->
   <node id="2" x="+500.0" y="0.0" type="priority"/> <!-- def. of node "2" -->
   <node id="3" x="0.0" y="-500.0" type="priority"/> <!-- def. of node "3" -->
   <node id="4" x="0.0" y="+500.0" type="priority"/> <!-- def. of node "4" -->

   <node id="m1" x="-250.0" y="0.0" type="priority"/> <!-- def. of node "m1" -->
   <node id="m2" x="+250.0" y="0.0" type="priority"/> <!-- def. of node "m2" -->
   <node id="m3" x="0.0" y="-250.0" type="priority"/> <!-- def. of node "m3" -->
   <node id="m4" x="0.0" y="+250.0" type="priority"/> <!-- def. of node "m4" -->

</nodes> <!-- The closing tag -->

As you may notice, only the first node named "0", which is the node in the middle of the network, is a traffic light controlled junction. All other nodes are uncontrolled. You may also notice, that each of both ends of a street needs an according node. This is not really necessary as you may see soon, but it eases the understanding of the concept: every edge (street/road) is a connection between two nodes (junctions).

You should also know something about the coordinate system: the higher a node on the screen shall be (the nearer to the top of your monitor), the higher his y-value must be. The more to left it shall be, the higher his x-value.

Figure 4.3. Coordinate system used in SUMO

Coordinate system used in SUMO

Since version 0.9.4 you can also give the x- and y-coordinates using geocoordinates. In this case, the coordinates will be interpreted as long/lat in degrees. Read more on this in "Converting from Geocoordinates".

4.2.2. Edges Descriptions

Edges are described quite the same way as nodes, but posses other parameter. Within the edges file, each description of a single edge looks like this: <edge id="<STRING>" (fromnode="<NODE_ID>" tonode="<NODE_ID>" | xfrom="<FLOAT>" yfrom="<FLOAT>" xto="<FLOAT>" yto="<FLOAT>") [type="<STRING>" | nolanes="<INT>" speed="<FLOAT>" priority="<UINT>" length="<FLOAT>")] [shape="<2D_POINT> [ <2D_POINT>]*"] [spread_type="center"]/>.

What does it mean? Every one who knows how XML-files look like should have noticed brackets ('(' and ')') and pipes ('|') within the definition and these characters are not allowed within XML... What we wanted to show which parameter is optional. So for the definition of the origin and the destination node, you can either give their names using fromnode="<NODE_ID>" tonode="<NODE_ID>" or you give their positions using xfrom="<FLOAT>" yfrom="<FLOAT> xto="<FLOAT>" yto="<FLOAT>". In the second case, nodes will be build automatically at the given positions. Each edge is unidirectional and starts at the "from"-node and ends at the "to"-node. If a name of one of the nodes can not be dereferenced (because they have not been defined within the nodes file) an error is generated (see also the documentation on "--dismiss-loading-errors" in subchapter "Building the Network").

For each edge, some further attributes should be supplied, being the number of lanes the edge has, the maximum speed allowed on the edge, the length the edge has (in meters). Furthermore, the priority may be defined optionally. All these values - beside the length in fact - may either be given for each edge using according attributes or you can omit them by giving the edge a "type". In this case, you should also write a type-file (see subchapter "Types Descriptions"). A type with this name should of course be within the generated type-file, otherwise an error is reported. Even if you supply a type, you can still override the type's values by supplying any of the parameter nolanes, speed and priority. You may also leave the edge parameter completely unset. In this case, default-values will be used and the edge will have a single lane, a default (unset) priority and the maximum allowed speed on this edge will be 13.9m/s being around 50km/h. The length of this edge will be computed as the distance between the starting and the end point.

As an edge may have a more complicated geometry, you may supply the edge's shape within the shape tag. If the length of the edge is not given otherwise, the distances of the shape elements will be summed. The information spread_type="center" forces NETCONVERT to spread lanes to both sides of the connection between the begin node and the end node or from the list of lines making up the shape. If not given, lanes are spread to right, as default.

Let's list an edge's attributes again:

  • id: The name of the edge; may be any character string

  • Origin and destination node descriptions

    Either:

    • fromnode: The name of a node within the nodes-file the edge shall start at

    • tonode: The name of a node within the nodes-file the edge shall end at

    or:

    • xfrom: The x-position of the node the edge shall start at in meters; must be a floating point number

    • yfrom: The y-position of the node the edge shall start at in meters; must be a floating point number

    • xto: The x-position of the node the edge shall end at in meters; must be a floating point number

    • yto: The y-position of the node the edge shall end at in meters; must be a floating point number

  • Descriptions of the edge's type and atomic attributes:

    Either:

    • type: The name of a type within the types-file

    or/and:

    • nolanes: The number of lanes of the edge; must be an integer value

    • speed: The maximum speed allowed on the edge in m/s; must be a floating point number (see also "Using Edges' maximum Speed Definitions in km/h")

    • priority: The priority of the edge; must be a positive integer value

    • length: The length of the edge in meter; must be an float value

  • The edges shape:

    • shape: List of positions; each position is encoded in x,y (do not separate the numbers with a space!) in meters; the start and end node are omitted from the shape definition; an example: <edge id="e1" fromnode="0" tonode="1" shape="0,0 0,100"/> describes an edge that after starting at node 0, first visits position 0,0 than goes one hundred meters to the right before finally reaching the position of node 1.

    • spread_type: The description of how to spread the lanes; "center" spreads lanes to both directions of the shape, any other value will be interpreted as "right".

The priority plays a role during the computation of the way-giving rules of a node. Normally, the allowed speed on the edge and the edge's number of lanes are used to compute which edge has a greater priority on a junction. Using the priority attribute, you may increase the priority of the edge making more lanes yielding in it or making vehicles coming from this edge into the junction not wait.

Also the definitions of edges must be embedded into an opening and a closing tag and for the example "<SUMO_DIST>/data/examples/netbuild/types/cross_notypes/" the whole edges-file looks like this ("cross3l.edg.xml"):

<edges>

   <edge id="1fi" fromnode="1" tonode="m1" priority="2" nolanes="2" speed="11.11"/>
   <edge id="1si" fromnode="m1" tonode="0" priority="3" nolanes="3" speed="13.89"/>
   <edge id="1o" fromnode="0" tonode="1" priority="1" nolanes="1" speed="11.11"/>

   <edge id="2fi" fromnode="2" tonode="m2" priority="2" nolanes="2" speed="11.11"/>
   <edge id="2si" fromnode="m2" tonode="0" priority="3" nolanes="3" speed="13.89"/>
   <edge id="2o" fromnode="0" tonode="2" priority="1" nolanes="1" speed="11.11"/>

   <edge id="3fi" fromnode="3" tonode="m3" priority="2" nolanes="2" speed="11.11"/>
   <edge id="3si" fromnode="m3" tonode="0" priority="3" nolanes="3" speed="13.89"/>
   <edge id="3o" fromnode="0" tonode="3" priority="1" nolanes="1" speed="11.11"/>

   <edge id="4fi" fromnode="4" tonode="m4" priority="2" nolanes="2" speed="11.11"/>
   <edge id="4si" fromnode="m4" tonode="0" priority="3" nolanes="3" speed="13.89"/>
   <edge id="4o" fromnode="0" tonode="4" priority="1" nolanes="1" speed="11.11"/>

</edges>

Within this example, we have used explicit definitions of edges. An example for using types is described in the chapter "Types Descriptions".

[Caution]Caution

There are some constraints about the streets' ids. They must not contain any of the following characters: '_' (underline - used for lane ids), '[' and ']' (used for enumerations), ' ' (space - used as list divider), '*' (star, used as wildcard), ':' (used as marker for internal lanes).

Recent changes:

  • The function-tag was added for version 0.9.4 and was revalidated for version 0.9.5

  • 11.03.2008: False documentation updated: --omit-corrupt-edges is outdated; use --dismiss-loading-errors instead

  • The function-tag was removed for version 0.9.9; a warning is generated when this attribute is used

4.2.2.1. Defining allowed Vehicle Types

Since version 0.9.5 you may allow/forbid explicite vehicle classes to use a lane. The information which vehicle classes are allowed on a lane may be specified within an edges descriptions file by embedding the list of lanes together with vehicle classes allowed/forbidden on them into these lanes' edge. Assume you want to allow only busses to use the leftmost lane of edge "2si" from the example above. Simply change this edge's definition into:

... previous definitions ...
   <edge id="2si" fromnode="m2" tonode="0" priority="3" nolanes="3" speed="13.89">
      <lane id="2" allow="bus"/>
   <edge>
... further definitions ...

If you would like to disallow passenger cars and taxis, the following snipplet would do it:

... previous definitions ...
   <edge id="2si" fromnode="m2" tonode="0" priority="3" nolanes="3" speed="13.89">
      <lane id="2" disallow="passenger;taxis"/>
   <edge>
... further definitions ...

The definition of a lane contains by now the following attributes:

  • id: The enumeration id of the lane (0 is the rightmost lane, <NUMBER_LANES>-1 is the leftmost one)

  • allow: The list of explicitely allowed vehicle classes

  • disallow: The list of explicitely disallowed vehicle classes

Both the allowed and the disallowed attributes assume to get a list of vehicle class names devided by a ';'. See "Vehicle Classes" for further information about allowed vehicle classes and their usage.

[Caution]Caution

This is a new feature. Its usage and the way it works will surely change in the future.

Examples: none yet

Recent changes:

  • The possibility to define which vehicle classes are allowed on a lane was added in version 0.9.5

4.2.3. Types Descriptions

As mentioned, road types are meant to be used to ease the definition of edges. As described above, the description of an edge should include information about the number of lanes, the maximum speed allowed on this edge and the edge's priority. To avoid the explicit definition of each parameter for every edge, one can use road types, which encapsulate these parameter under a given name. The format of this definition is: <type id="<STRING>" nolanes="<INT>" speed="<FLOAT>" priority="<UINT>"/>.

The attributes of a type are of course exactly the same as for edges themselves:

  • id: The name of the road type; may be any character string

  • nolanes: The number of lanes of the referencing must be an integer value

  • speed: The maximum speed allowed on the referencing edge in m/s; must be a floating point number

  • priority: The priority of the referencing edge; must be a positive integer value

The information about the nodes the edge starts and ends at is not given within the types' descriptions. They can only be set within the edge's attributes. Here's an example on referencing types in edge definitions:

<edges>

   <edge id="1fi" fromnode="1" tonode="m1" type="b"/>
   <edge id="1si" fromnode="m1" tonode="0" type="a"/>
   <edge id="1o" fromnode="0" tonode="1" type="c"/>

   <edge id="2fi" fromnode="2" tonode="m2" type="b"/>
   <edge id="2si" fromnode="m2" tonode="0" type="a"/>
   <edge id="2o" fromnode="0" tonode="2" type="c"/>

   <edge id="3fi" fromnode="3" tonode="m3" type="b"/>
   <edge id="3si" fromnode="m3" tonode="0" type="a"/>
   <edge id="3o" fromnode="0" tonode="3" type="c"/>

   <edge id="4fi" fromnode="4" tonode="m4" type="b"/>
   <edge id="4si" fromnode="m4" tonode="0" type="a"/>
   <edge id="4o" fromnode="0" tonode="4" type="c"/>

</edges>

The according types file looks like this:

<types>

   <type id="a" priority="3" nolanes="3" speed="13.889"/>
   <type id="b" priority="2" nolanes="2" speed="11.111"/>
   <type id="c" priority="1" nolanes="1" speed="11.111"/>

</types>

As you can see, we have joined the edges into three classes "a", "b", and "c" and have generated a description for each of these classes. Doing this, the generated net is similar to the one generated using the settings described above (example "<SUMO_DIST>/data/examples/netbuild/types/cross_notypes/" ).

Examples:

  • The basic usage of types is shown in <SUMO_DIST>/data/examples/netbuild/types/cross_notypes/ where the same network is constructed once not using types (subfolder "cross_notypes") and once using them (subfolder "cross_usingtypes").

Recent changes:

  • The function-tag was added for version 0.9.5

  • The function-tag was removed for version 0.9.9; a warning is generated when this attribute is used

4.2.4. Connection Descriptions

4.2.4.1. Explicite setting which Edge / Lane is connected to which

If you have tried the version 0.7 you have possibly missed the possibility to specify the connections between the edges for yourself. This is now possible using a further file, the connections file. The connection file specifies which edges outgoing from a junction may be reached by a certain edge incoming into this junction and optionally also which lanes shall be used on both sides.

If you only want to describe which edges may be reached from a certain edge, this definition could look something like this: <connection from="<FROM_EDGE_ID>" to="<T0_EDGE_ID>"/>. This tells NETCONVERT not only that vehicles shall be allowed to drive from the edge named <FROM_EDGE_ID> to the edge named <TO_EDGE_ID>, but also prohibits all movements to other edges from <FROM_EDGE_ID>, unless they are specified within this file. Let's repeat the parameters:

  • from: The name of the edge the vehicles leave

  • to: The name of the edge the vehicles may reach when leaving "from"

When using this kind of input, NETCONVERT will compute which lanes shall be used if any of the connected edges has more than one lane. If you also want to override this computation and set the lanes by hand, use the following: <connection from="<FROM_EDGE_ID>" to="<T0_EDGE_ID>" lane="<INT_1>:<INT_2>"/>. Here, a connection from the edge's "<FROM_EDGE_ID>" lane with the number <INT_1> is build to the lane <INT_2> of the edge "<TO_EDGE_ID>". Lanes are counted from the right (outer) to the left (inner) side of the road beginning with 0. Again the parameter:

  • from: The name of the edge the vehicles leave

  • to: The name of the edge the vehicles may reach when leaving "from"

  • lane: the numbers of the connected lanes, separated with ':'; lanes are counter from right to left beginning with 0

There are two examples within the distribution. Both use the nodes and edges descriptions from the example located in "<SUMO_DIST>/data/examples/netbuild/types/cross_notypes/". The junction in the center of this example looks like shown within the next figure. We will now call it the "unconstrained network" because all connections and turnarounds are computed using the default values.

Figure 4.4. Unconstrained Network (zoom=2200)

Unconstrained Network (zoom=2200)

The example <SUMO_DIST>/data/examples/netbuild/connections/cross3l_edge2edge_conns/" shows what happens when one uses connections to limit the number of reachable edges. To do this we built a connections file where we say that the horizontal edges ("1si" and "2si") have only connections to the edges right to them and the edge in straight direction. The file looks like this:

<connections>

   <connection from="1si" to="3o"/>
   <connection from="1si" to="2o"/>

   <connection from="2si" to="4o"/>
   <connection from="2si" to="1o"/>

</connections>

As you may see in the next picture, the horizontal edges within the result network contain no left-moving connections.

Figure 4.5. Network with explicit edge-2-edge connections

Network with explicit edge-2-edge connections

In the second example located in <SUMO_DIST>/data/examples/netbuild/connections/cross3l_laneslane_conns/" we additionally describe which lanes shall be connected. The according connections file says that the connections going straight shall be start at the second lane of the incoming edges:

<connections>

   <connection from="1si" to="3o" lane="0:0"/>
   <connection from="1si" to="2o" lane="2:0"/>

   <connection from="2si" to="4o" lane="0:0"/>
   <connection from="2si" to="1o" lane="2:0"/>

</connections>

The built network looks like this:

Figure 4.6. Network with explicit lane-2-lane connections

Network with explicit lane-2-lane connections

[Warning]Warning

Please do not use both types of connection declarations (those with an lane attribute and those without) for the same from-edge! The behaviour is not verified and tested for these settings.

Examples (compare both to <SUMO_DIST>/data/examples/netbuild/connections/cross3l_unconstrained/):

  • <SUMO_DIST>/data/examples/netbuild/connections/cross3l_edge2edge_conns/ shows how edge-to-edge connections may be specified

  • <SUMO_DIST>/data/examples/netbuild/connections/cross3l_lane2lane_conns/ shows how lane-to-lane connections may be specified

Recent Changes:

  • A bug which sometimes yielded in a reassignment of connections is patched in version 0.9.3

4.2.4.2. Setting Connection Priorities

Since version 0.9.6 you can also let vehicles passing a connection between two edges wait for another stream. Let's take another look at "Network with explicit edge-2-edge connections" above. Here, all right-moving vehicles may drive. The following definition within the connections file lets vehicles on vertical edges moving right wait for those which move straight on horizontal edges:

<connections>

   <!-- The next four connection definitions are same as in 
        "Network with explicit edge-2-edge connections" -->
   <connection from="1si" to="3o"/>
   <connection from="1si" to="2o"/>

   <connection from="2si" to="4o"/>
   <connection from="2si" to="1o"/>

   <!-- now, let's prohibit the vertical connections by the horizontal -->
   <!-- prohibit moving right from top to left by straight from right to left -->
   <prohibition prohibitor="2si->1o" prohibited="4si->1o"/>
   <!-- prohibit moving straight from top to bottom by straight from right to left -->
   <prohibition prohibitor="2si->1o" prohibited="4si->3o"/>
   <!-- prohibit moving left from top to right by straight from right to left -->
   <prohibition prohibitor="2si->1o" prohibited="4si->2o"/>

   <!-- prohibit moving right from bottom to right by straight from left to right -->
   <prohibition prohibitor="1si->2o" prohibited="3si->2o"/>
   <!-- prohibit moving straight from bottom to top by straight from left to right -->
   <prohibition prohibitor="1si->2o" prohibited="3si->4o"/>
   <!-- prohibit moving left from bottom to right by straight from left to right -->
   <prohibition prohibitor="1si->2o" prohibited="3si->1o"/>

</connections>

As one may see, it was necessary to prohibit all connections from a vertical edge by the counter-clockwise straight connection on a horizontal edge because otherwise the vehicles on the horizontal edge want to wait due to right-before-left - rule. The network looks like this:

Figure 4.7. Network with explicite prohibitions

Network with explicite prohibitions

The syntax of a prohibition-tag is: <prohibition prohibitor="<PROHIBITING_FROM_EDGE_ID>-><PROHIBITING_TO_EDGE_ID>" prohibited="<PROHIBITED_FROM_EDGE_ID>-><PROHIBITED_TO_EDGE_ID>"/>. This means we define two connections (edge-to-edge), the prohibiting one (prohibitor) and the prohibited (prohibited). Each connection is defined by a from-edge and a to-edge, divided by "->".

Examples (compare to <SUMO_DIST>/data/examples/netbuild/connections/cross3l_unconstrained/):

  • <SUMO_DIST>/data/examples/netbuild/connections/cross3l_prohibitions/ shows how prohibitions may be specified

Recent Changes:

  • The possibility to add prohibitions was implemented for version 0.9.6

4.2.5. Building the Network

After you have generated the files you need being at least the edges and the nodes-files and optionally also a type and/or a connections file you should run NETCONVERT to build the network. The call should look like:

netconvert --xml-node-files=MyNodes.nod.xml --xml-edge-files=MyEdges.edg.xml \
   --output-file=MySUMONet.net.xml

if you only use edges and nodes. Types and connections may be given as:

netconvert --xml-node-files=MyNodes.nod.xml --xml-edge-files=MyEdges.edg.xml \
   --xml-connection-files=MyConnections.con.xml --xml-type-files=MyTypes.typ.xml \
   --output-file=MySUMONet.net.xml

Maybe your edge definitions are incomplete or buggy. If you still want to import your network, you can try passing "--dismiss-loading-errors" to NETCONVERT. In this case, edges which are not defined properly, are omitted, but NETCONVERT tries to build the network anyway. You may also flip the network around the horizontal axis. Use option "--flip-y" for this.

You may also use abbreviations for the option names. These abbreviations and options used when building SUMO-networks from own XML-descriptions are:

( --xml-node-files | --xml-nodes | -n ) <NODES_FILE>

Uses the given file as the source of specification node positions and types. Optional, type:filename, default: none

( --xml-edge-files | --xml-edges | -e ) <EDGES_FILE>

Uses the given file as the source of specification of roads connecting nodes. Optional, type:filename, default: none

( --xml-connection-files | --xml-connections | -x ) <CONNECTIONS_FILE>

Uses the given file as the source of specification how roads are connected (which lanes may be reached from which lanes). Optional, type:filename, default: none

( --xml-type-files | --types | -t ) <TYPES_FILE>

Uses the given file as the source of edge types. Optional, type:filename, default: none

--dismiss-loading-errors

Continues with parsing although a corrupt edge occurred. This edge is not inserted and a warning is printed. Optional (pregiven), type:bool, default: false

--flip-y

Flips the y-position of nodes (and edges) along the y=zero-line. Optional (pregiven), type:bool, default: false

See also:

Examples:

Almost all networks within the <SUMO_DIST>/data/ - folder. Additionally some examples that cover the mentioned topics are:

  • On using types:

    • <SUMO_DIST>/data/examples/netbuild/types/cross_notypes/

    • <SUMO_DIST>/data/examples/netbuild/types/cross_usingtypes/

  • On using speed definition in km/h

    • <SUMO_DIST>/data/examples/netbuild/cross_notypes_kmh/

    • <SUMO_DIST>/data/examples/netbuild/cross_usingtypes_kmh/

  • On using edge shapes

    • <SUMO_DIST>/data/examples/netbuild/shapes/hokkaido-japan/

Recent changes:

  • --xml-type-files was named --type-file in versions earlier than 0.9.2

  • In the previous examples the option for nodes inclusion was misspelled (--xml-nodes-files is incorrect, --xml-node-files is right). Thanks to Leander Verhofstadt to recognize this.

  • An error in this documentation has been removed for version 0.9.5

  • 11.03.2008: False documentation updated: --omit-corrupt-edges is outdated; use --dismiss-loading-errors instead

4.3. Converting other Input Data

Large maps cannot be written by hand. We use maps from NavTech stored in the ArcView database format and maps from other simulation suppliers such as ptv within our projects and both are too large for this. We will now explain how to convert such data. We will not give any introduction into the formats/simulations themselves or compare their quality, but we will describe what is being imported and what problems may arise during the conversion.

4.3.1. Importing ArcView-databases

NETCONVERT is able to directly read binary NavTech's ArcView databases. To convert such databases, you need at least three files: a file with the extension ".dbf", one with the extension ".shp" and one with the extension ".shx". Additionally, having a projection file with the extension ".proj" is of benefit. Since version 0.9.2 we do not suply the possibility to use different names for the files, so all files should have the same name besides the extension. To build your network from an ArcView-database use the option "--arcview=<FILENAME_WITHOUT_EXTENSION>":

netconvert --arcview=MyArcViewDB --output-file=MySUMONet.net.xml

This call will force NETCONVERT to read the files "MyArcViewDB.dbf", "MyArcViewDB.shx", and "MyArcViewDB.shp" (and possibly "MyArcViewDB.proj" and to generate a network named "MySUMONet.net.xml". We have been asked which fields are read from ArcView-files. As said before, the reader was build to read ArcView-files containing road networks from NavTech. Due to this the following fields are used as default:

Table 4.1. Entries read by NETCONVERT

Entity NameDescription
LINK_IDThe id of an edge
ST_NAMEThe name of an edge (not really used)
REF_IN_IDThe name of the node the edge starts at
NREF_IN_IDThe name of the node the edge ends at
ST_TYP_AFTThe type of the street (not really used)
SPEED_CATSpeed category
LANE_CATLane category
FUNC_CLASSRoad class, used to determine the priority

The problem is, that not all networks stored as ArcView-databases also use this naming scheme. During some further work with ArcView-networks, some further options got necessary which allow to name the fields the used database contains. The column the street name shall be read from may be specified using --arcview.street-id <STREET_NAME_COLUMN_NAME>. You can also name the columns the names of the edges' origin and destination nodes shall be read from using --arcview.from-id <START_NODE_ID_COLUMN_NAME> and --arcview.to-id <END_NODE_ID_COLUMN_NAME>. If the no information about the starting/ending nodes is given and your database does not contain the columns "REF_IN_ID" and "NREF_IN_ID", nodes will be placed into the network at the positions the streets end.

Since version 0.9.2 we also allow to override the rather "fuzzy" information about an edge's attributes from NavTech using own fields:

Table 4.2. Possible entries to override NavTech-information

Entity NameDescription
SPEEDThe speed in m/s (see also "Using Edges' maximum Speed Definitions in km/h")
NOLANESThe number of lanes
rnolThe number of lanes
PRIORITYThe priority

This idea came from John Michael Calandrino.

Some databases do not contain explicite information about the edges' attributes (number of lanes, priority, allowed speed) at all. Since version 0.9.4 you can use types as described in "Types Descriptions" to describe your edges' attributes. You have to name the column to retrieve the information about a street's type from using --arcview.type-id <TYPE_ID_COLUMN_NAME>. Of course, you have then to supply a type-file using --xml-type-files <TYPES_FILE> (or --types or -t ). If something fails with the types or the explicite values, you can catch it using --arcview.use-defaults-on-failure. Besides this, you can specify your own connections using --xml-connection-files <CONNECTIONS_FILE> (or --xml-connections or -x, see "Connection Descriptions").

ArcView-networks are (mostly?) encoded using geocoordinates which have to be converted to the cartesian coordinates system used by SUMO. Our current implementation is not yet fully developed, it works for the most cases, but you should not be surprised if it fails with a certain network. Contact us in this case, please. To describe how to convert the coordinates, you should know in which UTM-zone your network is located. Pass this to NETCONVERT using --arcview.utm <ORIGINAL_UTM_ZONE>. If the conversion can not be initialised, you may additionally use --arcview.guess-projection to let NETCONVERT guess the conversion by him own.

Specific options:

--arcview <ARCVIEW_PREFIX>

Loads definitions from "<ARCVIEW_PREFIX>.shp", "<ARCVIEW_PREFIX>.dbf" and "<ARCVIEW_PREFIX>.shx". Optional, type:filename-prefix, default: none

--arcview.street-id <STREET_NAME_COLUMN_NAME>

This option tells NETCONVERT which of the columns within the ArcView-database to read shall be used as the source of street names. If given, your database must contain this column, and the values must be unique for each street. Optional, type:string, default: none

--arcview.from-id <START_NODE_ID_COLUMN_NAME>

This option tells NETCONVERT which of the columns within the ArcView-database to read shall be used as the source of the information from which node the street starts. If given, your database must contain this column. Optional, type:string, default: none

--arcview.to-id <END_NODE_ID_COLUMN_NAME>

This option tells NETCONVERT which of the columns within the ArcView-database to read shall be used as the source of the information at which node the street ends. If given, your database must contain this column. Optional, type:string, default: none

--arcview.type-id <TYPE_ID_COLUMN_NAME>

This option tells NETCONVERT which of the columns within the ArcView-database to read shall be used as the source of the information about the edge's type. Using this information, you can use type definitions as described in "Types Descriptions" to determine your edges' attributes. If given, your database must contain this column. Optional, type:string, default: none

--arcview.use-defaults-on-failure

If a type could not be resolved or is invalid or any of the explicite information about an edge was invalid, this option forces NETCONVERT to use the default type values for the current street. If not set, and one of the cases occures, the application's behaviour is not determined. Optional, type:bool, default: false

--arcview.all-bidi

Forces NETCONVERT to insert all edges bidirectional. Optional (pregiven), type:bool, default: false

--arcview.utm <ORIGINAL_UTM_ZONE>

This value describes in which UTM-zone your network is located. The default is 32 being a place somwhere in western Germany. You should change this value if importing networks located somewhere else in the world. Optional (pregiven), type:int, default: 32

--arcview.guess-projection

If building a converter using the given UTM-zone fails, this option tries to guess the project if set. Of course, this may also fail... Optional (pregiven), type:bool, default: false

See also:

Examples: none yet

Recent changes:

  • versions earlier than 0.9.2 allow to use an explicit filename for both the .dbf and the .shp file using "--arcview-dbf" and "--arcview-shp". This was abondonned, because of the need to use .shx-files, also.

  • ArcView-import has been completely redesigned for version 0.9.4. All options but "--arcview <ARCVIEW_PREFIX>" are not available in versions prior to 0.9.4

4.3.2. Importing VISSIM-networks

Although Vissim is a microscopic simulation as SUMO is, it follows a completely different concept of modelling traffic. Due to this, the import is quite clumsy and may not work with all networks. Also, we have to insert additional edges into our networks to simulate the Vissim-parking places, originally being nodes, which we do not have. An usage example could be this one:

netconvert --vissim=<VISSIM_FILE> --output-file=MySUMOFile.net.xml

Vissim-networks do possibly not contain explicit definitions of an edge's speed. We have to propagate once set velocities, but even then some edges' speeds may not be defined. The option "--vissim.default-speed" may change the default speed used in the case an edge's speed is not defined. The default value for this parameter is 13.89m/s, being around 50km/h. The second parameter "--vissim.speed-norm" describes the factor to multiply a described flows maximum velocity to gain the velocity to use. The default value is 1.

Furthermore, as we have to use geometrical heuristics, a further factor steers the process of converting Vissim-networks: simply spoken, "--vissim.offset" holds the information how near two nodes must be (in meters) to be joined.

During import, different actions must be done which may yield in some loss of data and may be watched in part by setting the verbose option. The additional warnings the import of Vissim-networks generates will be described in a further document.

Specific options:

--vissim <FILE>

Loads definitions from the given file (should end with ".inp"). Optional, type:filename, default: none

--vissim.speed-norm <SPEED_NORM_FACTOR>

A factor that is multiplied with a streams maximum velocity to determine the velocity to use for an edge. Optional (pregiven), type:float, default: 1

--vissim.default-speed <DEFAULT_SPEED>

The default speed to use for a street when no information is available. Optional (pregiven), type:float, default: 13.89 (m/s)

--vissim.offset <MAX_JOIN_DISTANCE>

This value is used to determine whether two Vissim-structures are near enough to be joined into a node. Optional (pregiven), type:float, default: 5 (m)

Known problems:

  • Works with German networks only

  • All actuated traffic lights are mapped onto the same type of traffic light (MSActuatedTrafficLight)

  • Additional source and sink links must be build

Examples: none yet (we do not own a network we could give away for legal reasons)

Recent changes:

  • --vissim.speed-norm, --vissim.default-speed, and --vissim.offset were named --vissim-speed-norm, --vissim-default-speed, and --vissim-offset in version prior to 0.9.6.

4.3.3. Importing VISUM-networks

Visum is a macroscopic simulation developed by ptv. NETCONVERT is capable to read VISUM-networks written as .net files. An usage import call could be this one:

netconvert --visum=<VISUM_FILE> --output-file=MySUMOFile.net.xml

As the network description may not contain any information about the number of lanes, we have to generate it from the street's flow. The computation is done by dividing the flow through a fix value, 2000 by default. This yields in a realistic network but fails on 'feeder roads' where vehicles are emitted.

You can also specify your own connections using --xml-connection-files <CONNECTIONS_FILE> (or --xml-connections or -x, see "Connection Descriptions").

Not all parts of the Visum-Format are read; below you'll find a table which contains the information which Visum-tables are imported.

Table 4.3. Imported VISUM-tables

Table NameDescriptionImported values
VSYSTraffic modes
VSysCode (CODE)
VSysMode (TYP)
STRECKENTYPEdge types
Nr
v0-IV (V0IV)
Rang
Kap-IV (KAPIV)
KNOTENNodes
Nr
XKoord
YKoord
BEZIRKDistricts
Nr
NAME (unused later)
Proz_Q
Proz_Z
XKoord
YKoord
STRECKE (STRECKEN)Edges
Nr
VonKnot (VonKnotNr)
NachKnot (NachKnotNr)
Typ (TypNr)
Einbahn
ANBINDUNGDistrict connections
BezNr
KnotNr
Proz
t0-IV
Typ
Richtung
ABBIEGEBEZIEHUNG (ABBIEGER)Edge Connections
VonKnot (VonKnotNr)
UeberKnot (UeberKnotNr)
NachKnot (NachKnotNr)
VSysCode (VSYSSET)
STRECKENPOLYEdge geometries
VonKnot (VonKnotNr)
NachKnot (NachKnotNr)
INDEX
XKoord
YKoord
FAHRSTREIFENLane descriptions
KNOTNR
STRNR
FSNR
RICHTTYP
LAENGE
LSA (SIGNALANLAGE)TLS
Nr
Umlaufzeit (UMLZEIT)
StdZwischenzeit (STDZWZEIT)
PhasenBasiert
KNOTENZULSA (SIGNALANLAGEZUKNOTEN)Nodes->TLS
KnotNr
LsaNr
LSASIGNALGRUPPE (SIGNALGRUPPE)Signal groups
Nr
LsaNr
GzStart (GRUENANF)
GzEnd (GRUENENDE)
ABBZULSASIGNALGRUPPE (SIGNALGRUPPEZUABBIEGER)Edge connections->TLS
SGNR (SIGNALGRUPPENNR)
LsaNr
VonKnot / VONSTRNR
NachKnot / NACHSTRNR
UeberKnot (UeberKnotNr)
LsaNr
LSAPHASE (PHASE)Signal phases
Nr
LsaNr
GzStart (GRUENANF)
GzEnd (GRUENENDE)
LSASIGNALGRUPPEZULSAPHASESignal groups->phases
PsNr
LsaNr
SGNR
FAHRSTREIFENABBIEGERLane-to-lane descriptions
KNOT (KNOTNR)
VONSTR (VONSTRNR)
NACHSTR (NACHSTRNR)
VONFSNR
NACHFSNR

Specific options:

--visum <FILE>

Loads definitions from the given file (should end with ".net"). Optional, type:filename, default: none

See also:

Examples: none yet (we do not own a network we could give away for legal reasons)

Recent changes:

  • Since version 0.9.4, NETCONVERT can also convert VISION-networks (VISUM version 0.9.3). Please remark for this case, that we do not have a VISION-network which contains TLS-definitions and due to this the import of these may fail.

4.3.4. Importing Elmar's converted NavTech-Files

You can convert both the splitted and the unsplitted version of files generated by Elmar from NavTech-files. There seems to be no difference between the results in the networks' topologies, but the names of junctions and roads change. The option --elmar loads the splitted definitions, --elmar2 the unsplitted. Both options await the prefix as generated by Elmar's converter, an optional path is allowed. Example:

netconvert --elmar=berlin_ --output-file=MySUMOFile.net.xml

Imports the descriptions of nodes from "berlin_nodes.txt" and the edges from "berlin_links.txt".

You can also specify your own connections using --xml-connection-files <CONNECTIONS_FILE> (or --xml-connections or -x, see "Connection Descriptions").

Specific options:

--elmar <NET_PREFIX>

Loads the splitted versions of the files behind <NET_PREFIX>. Optional, type:filename-prefix, default: none

--elmar2 <NET_PREFIX>

Loads the unsplitted versions of the files behind <NET_PREFIX>. Optional, type:filename-prefix, default: none

See also:

Examples: none yet (we do not own a network we could give away for legal reasons)

4.3.5. Importing TIGER-databases

This import function is in a rather experimental state. We need someone who owns a network she/he knows and who could give us an advice whether the import work as expected. You still may try it out using the option --tiger=<FILE_PREFIX>.

You can also specify your own connections using --xml-connection-files <CONNECTIONS_FILE> (or --xml-connections or -x, see "Connection Descriptions").

See also:

Examples: none yet

4.4. Further NETCONVERT Options

NETCONVERT offers some more options to describe how the network shall be imported. The scope of some options does not cover all import types, though a list of valid import types for each option set is given.

4.4.1. Setting default Values

We have mentioned, that edge parameter may be omitted and defaults will be used in this case. You have the possibility to define these defaults using the following options:

( --type | -T ) <DEFAULT_TYPE_NAME>

The name of the default type of edges. Optional (pregiven), type:string, default: "Unknown"

( --lanenumber | -L ) <DEFAULT_LANE_NUMBER>

The number of lanes an edge has to use as default. Optional (pregiven), type:int, default: 1

( --speed | -S ) <DEFAULT_MAX_SPEED>

The maximum speed allowed on an edge in m/s to use as default. Optional (pregiven), type:float, default: 13.9

( --priority | -P ) <DEFAULT_PRIORITY>

The default priority of an edge. Optional (pregiven), type: positive int, default: -1 (unset)

These options may be used while importing the following formats:

  • XML-descriptions

Examples: none yet

4.4.2. Adding Turnarounds

Normally, turnarounds are added as a possible edge continuations and play an important role during network building (see [Krajzewicz_et_al2005_2]). Still, one may want not to add them. In this cases, it is possible to disallow their appending using option "--no-turnarounds".

Specific option:

--no-turnarounds

Optional (pregiven), type:bool, default: false

This options may be used while importing the following formats:

  • ARCVIEW-data base files

  • XML-descriptions

Recent changes:

  • in versions earlier than 0.9.3, turnarounds were not added per default. Instead the option "--append-turnarounds" has forced NETCONVERT to add them.

4.4.3. Removing Geometry Nodes

In most input networks one may find nodes where one street comes in and one with the same attributes goes out or where two parallel edges come in and two (with the same attributes) come out. Such nodes have mostly no meaning (maybe besides the additional possibility to make a U-turn) and may be removed. The removal of such nodes increases the simulation speed due to a smaller number of edges to process during each time step. To remove such nodes and join the incoming and outgoing edges use "--remove-geometry". The removal of nodes preserves the geometry of edges by ading a further geometry point at the removed node's position.

Specific option:

( --remove-geometry | -R )

Optional (pregiven), type:bool, default: false

This options may be used in conjunction with all import formats.

Recent changes:

  • in versions earlier than 0.9.3, geometry nodes were removed by default. One could change this behaviour using the "--no-node-removal" option.

4.4.4. Using Edges' maximum Speed Definitions in km/h

Some people do not like to use speed definitions in m/s. If you want to define the speeds allowed on your edges in km/h instead, you should pass the following option to NETCONVERT:

--speed-in-kmh

Optional (pregiven), type:bool, default: false

This option may be used while importing the following formats:

  • ARCView-databases

  • XML-descriptions

Examples:

  • <SUMO_DIST>\data\examples\netbuild\cross_notypes_kmh in comparison to <SUMO_DIST>\data\examples\netbuild\cross_notypes

  • <SUMO_DIST>\data\examples\netbuild\cross_usingtypes_kmh in comparison to <SUMO_DIST>\data\examples\netbuild\cross_usingtypes

Recent changes:

  • --speed-in-kmh was named --speed-in-km in versions earlier than 0.9.2

4.4.5. Importing Networks without Traffic Light Logics

Some of the supported network formats supply information about the logic of the traffic lights, other do not. Due to this, we have to compute the traffic lights by our own. Doing this, we do not only have to compute the plans, but of course also, on which junction traffic lights are positioned. There are several options steering this procedure. At first, you have to tell NETCONVERT/NETGEN that you wish him to guess positions of traffic lights. This is done using the "--guess-tls"-option. Then, you have the possibility to describe the junctions at which you think a tls shall be placed using description of incoming and outgoing edges: "--tls-guess.no-incoming-min", "--tls-guess.no-incoming-max", "--tls-guess.no-outgoing-min" and "--tls-guess.no-outgoing-max" constraint the building of a tls by the number of the lanes incoming/outgoing edges have. All these four options require an int as parameter. Furthermore, you may constraint the junctions by giving the minimum/maximum of allowed speed on edges that participate: "--tls-guess.min-incoming-speed", "--tls-guess.max-incoming-speed", "--tls-guess.min-outgoing-speed", and "--tls-guess.max-outgoing-speed".

[Caution]Caution

No, we do not have a validated set of these option's settings, yet.

You may also set junctions as tls-controlled using "--explicite-tls" or as uncontrolled using "--explicite-no-tls". Both options assume to get a list of node names divided by ',' as parameter. The behaviour when a node is in both lists is undefined.

If you want to know where traffic lights have been inserted and your network is too large to evaluate this by hand, you can force NETCONVERT to write a list of POIs where each POI is placed on a tls-controlled junction. This allows you to tae a look at all the positions tls have been inserted at. The option for doing this is --tls-poi-output <FILENAME> where <FILENAME> is the filename to write the POIs into.

Normally, only one traffic lights logic (phases definition) is computed per a traffic lights controlled junction, but the algorithm we use is able to compute several logics. To force the computation of all possible logics, use "--all-logics". Remind, that all logics will be written to the network file and that we have no tools for further procesing of these logics.

During the computation of tls-logics among other information we have to guess the duration of the phases. The options "--traffic-light-green" and "--traffic-light-yellow" allow you to give the durations of green and yellow lights. Both options assume the duration in s as an int as parameter. The duration of having red is dependant to the number of other phases and their green and yellow phase durations. The green phase length has a default of 20s, yellow lights are - if no value is set for this option - computed using the "--min-decel" - value described below.

One has to remind one thing: dead times are necessary to avoid collisions of vehicles which do not manage to break as they are too near to the traffic light when it switches to red. This time may be computed, and is, but depends on the maximum deceleration possibility of the vehicles used. As this parameter is not known to the network builder at all - the vehicle types are supported to the simulation only - the option "--min-decel" (or -D for short) is used to set the minimum deceleration of vehicles. The default is 3.0 in m/s^2.

There is no possibility to compute or estimate green light districts, yet. You have only the options to shift the computed phases by half of their duration or by a quarter of their duration. The options for this are: "--tl-logics.half-offset" and "--tl-logics.quarter-offset". Both options assume to get a list of node names divided by ',' as parameter. The behaviour when a node is in both lists or if the node is not meant to be controlled by a tls is undefined.

Specific options:

--guess-tls

Forces NETCONVERT/NETGEN to guess whether a junction is controlled by a tls or not. Optional, type:bool, default: false

--tls-guess.min-incoming-speed <SPEED>, --tls-guess.max-incoming-speed <SPEED>

Sets the minimum and the maximum of the velocity a junction's incoming edges may have if the junction shall be tls-controlled in m/s. Optional (pregiven), type:float, defaults: --tls-guess.min-incoming-speed: 40/3.6, --tls-guess.min-incoming-speed: 69/3.6

--tls-guess.min-outgoing-speed <SPEED>, --tls-guess.max-outgoing-speed <SPEED>

Sets the minimum and the maximum of the velocity a junction's outgoing edges may have if the junction shall be tls-controlled in m/s. Optional (pregiven), type:float, defaults: --tls-guess.min-outgoing-speed: 40/3.6, --tls-guess.max-outgoing-speed: 69/3.6

--tls-guess.no-incoming-min <LANE_NUMBER>, --tls-guess.no-incoming-max <LANE_NUMBER>

Sets the minimum and the maximum number of a junction's incoming edges to allow the junction to be controlled by a tls. Optional (pregiven), type:int, defaults: --tls-guess.no-incoming-min: 2, --tls-guess.no-incoming-max: 5

--tls-guess.no-outgoing-min <LANE_NUMBER>, --tls-guess.no-outgoing-max <LANE_NUMBER>

Sets the minimum and the maximum number of a junction's outgoing edges to allow the junction to be controlled by a tls. Optional (pregiven), type:int, defaults: --tls-guess.no-outgoing-min: 1, --tls-guess.no-outgoing-max: 5

--explicite-tls <JUNCTION_ID>[,<JUNCTION_ID>]*

Informs the network builder that the given junctions shall be treated as being controlled by traffic lights, even if they do not match the tls-guess rules. Optional, type:list of strings, default: none

--explicite-no-tls <JUNCTION_ID>[,<JUNCTION_ID>]*

Informs the network builder that the given junctions shall be treated as NOT being controlled by traffic lights, even if they match the tls-guess rules. Optional, type:list of strings, default: none

--all-logics

Computes and saves all possible cliques and phases for a traffic light instead of the fastest one only. Optional, type:bool, default: false

[Caution]Caution

This process may be very time consuming.

( --min-decel | -D ) <FLOAT>

he minimum deceleration value for vehicles in m/s^2. Optional (pregiven), type:float, default: 3

--traffic-light-green <DURATION>

The duration of green lights. Optional, type:int, default: none (20s internally)

--traffic-light-yellow <DURATION>

The duration of yellow lights; overrides --min-decel. Optional, type:int, default: none

--tls-poi-output <FILENAME>

If given, NETCONVERT will write position of nodes equipped with tls into <FILENAME>. Optional, type:filename, default: none

These options may be used while importing the following formats:

  • ARCVIEW-data base files

  • XML-descriptions

  • Elmar-files

  • VISUM-networks

Recent changes:

  • Since version 0.9.10, --explicite-tls and --explicite-no-tls are divided using ','.

  • Since version 0.9.10, --tl-logics.half-offset and --tl-logics.quarter-offset are divided using ','.

4.4.6. Guessing On- and Off-Ramps

Most of the imported network descriptions do not have information about highway on- and off-ramps. You can force NETCONVERT to guess where on- and off-ramps shall be build. To enable this, use the option "--guess-ramps". The algorithm assumes that an on-ramp shall be build on highway junctions with one incoming and one outgoing highway edge and one incoming minor edge and that an off-ramp shall be build on highway junctions with one incoming and one outgoing highway edge and one outgoing minor edge. You can constrain what a highway is by giving its minimum speed of this edge using "--ramp-guess.min-highway-speed" and what a minor edge is by giving its maximum speed using "--ramp-guess.max-ramp-speed". Both options assume a float parameter being the speed. Furthermore, "--ramp-guess.ramp-length" tells NETCONVERT how long the added ramp shall be in meters.

[Note]Note

Normally, we keep --ramp-guess.ramp-length unset and let the geometry computation do the rest.

Specific options:

--guess-ramps

Forces NETCONVERT/NETGEN to guess whether a junction is controlled by a tls or not. Optional, type:bool, default: false

--ramp-guess.max-ramp-speed <SPEED>

Defines the maximum speed an edge may have in order to be a ramp in m/s. The default of -1 tells NETCONVERT that all edges may be potential ramps. Optional (pregiven), type:float, default: -1

--ramp-guess.min-highway-speed <SPEED>

Defines the minimum speed an edge may have in order to be a highway in m/s. Optional (pregiven), type:float, default: 80/3.6

--ramp-guess.ramp-length <LENGTH>

Sets the length of the ramps to build in meters. Optional (pregiven), type:float, defaults: 100

These options may be used in conjunction with all import formats.

Examples: none yet

4.4.7. Converting from Geocoordinates

Most professional networks are not stored using cartesian, but geo-coordinates. Since version 0.9.4 NETCONVERT is able to deal with such positions. NETCONVERT uses herefor the projection library "PROJ.4". This is important for you as a user, because you may have to describe the original projection of your file and when doing this, you have to describe it using the options offered by PROJ.4. In order to enable the reprojection use the option --use-projection. You can then add parameter for the projection using --proj <STRING>. The default for the projection is "+proj=utm +ellps=bessel +units=m". That means, that NETCONVERT assumes the network to be encoded using "universal traverse mercator" and the Bessel ellipsoid what resembles what is known as WGS84 (as far as we have understood it). Please remark, that when giving own description, you should embed it into "" for passing all the arguments to PROJ.4.

Specific options:

--use-projection

Enables reprojection of the network's coordinates. Optional, type:bool, default: false

--proj <STRING>

Defines projection. Optional (pregiven), type:string, default: "+proj=utm +ellps=bessel +units=m"

These options may be used in conjunction with the following import formats:

  • Elmar & Elmar2

  • ArcView

  • Tiger

  • Visum

  • XML

[Caution]Caution

This is a new feature. Its usage and the way it works will surely change in the future.

Examples: none yet

Recent changes:

  • The default for the proj-option changed in 0.9.7 from "+proj=utm +zone=33 +ellps=bessel +units=m" to "+proj=utm +ellps=bessel +units=m"

4.4.8. Inner-junction Traffic

If you already know SUMO or if you have taken a look at some of the examples you may have noticed that vehicles used to "jump" over a junction instead of driving over them. This behaviour was quite appropriate for simulating large scenarios as in these cases the simulation error could be neglected (at least we have neglected it). Since version 0.10.0 SUMO will by default simulate traffic over the junctions in a way you know it from reality. Because inserting inner lanes into a network dramatically increases the network's size, you may want to return to the old behavior using the option --no-internal-links.

[Note]Note

Please note that you also have to disable the usage of internal lanes within the simulation.

Specific Options:

( --no-internal-links)

Disables building of junction-internal lanes. Optional, type:bool, default: false

Examples:

Meanwhile all of the examples included in the distribution have internal lanes.

Recent changes:

  • Inner-junction traffic was made default for version 0.10.0.

4.4.9. Constraining the Input

NETCONVERT offers you some possibillities to constrain the read edges what is quite needful if one has a large street network but only wants to simulate a part of it or only the major roads. The first possibility to constrain the input is to name all the edges you want to keep. You can either do this on the command line/within your configuration directly using --keep-edges <EDGE_ID>[,<EDGE_ID>]+ where each <EDGE_ID> represents the id of an edge you want to keep or you can save this list into a file where each id is stored in a seperate line and then let NETCONVERT read this file using --keep-edges.input-file <FILENAME>. In the case you are joining edges using --remove-geometry (see "Removing Geometry Nodes"), you may also be interested in the option --keep-edges.postload which forces NETCONVERT to join the edges first and remove the unwished afterwards.

It is also possible to constrain the imported edges by giving a minimum velocity that is allowed on an edge in order to include this edge into the generated network. Use --edges-min-speed <MIN_SPEED> for this where <MIN_SPEED> is the minimum velocity an edge must allow in order to be included in the output in m/s.

Specific options:

--keep-edges <EDGE_ID>[,<EDGE_ID>]+

Forces NETCONVERT to remove all edges not within the given list from the network. Optional, type:list of edge ids, default: none

--keep-edges.input-file <FILENAME>

Forces NETCONVERT to read the list of edge ids to keep from <FILENAME>. Optional, type:filename, default: none

--keep-edges.postload

Forces NETCONVERT to read all edges first and remove the unwished after joining. Optional (pregiven), type:bool, default: false

--edges-min-speed <MIN_SPEED>

Forces NETCONVERT to remove all edges from the input which allow a velocity below the given. Optional, type:float, default: none

Examples: none yet

Recent changes:

  • The edge file generated using plain-output contains the information about the shape, the lane spread and the basic type if differing from the defaults since version 0.9.5.

  • Since version 0.9.10, --keep-edges uses ',' as divider.

4.4.10. Additional Output

NETCONVERT and NETGEN allow to generate additional output files beside writing the network file. We will present the possibilities in the following subchapters.

4.4.10.1. Plain Network Output

Parsed node and edge definitions may be saved into a XML-files which have the same formats as the ones used for importing XML-networks (as described in "Nodes Descriptions" and "Edges Descriptions"). This shall ease processing of networks read from other formats than XML. The option --plain-output <FILENAME_PREFIX> forces NETCONVERT and NETGEN to generate a file named "<FILENAME_PREFIX>.nod.xml" which contains the previously imported nodes and a file named "<FILENAME_PREFIX>.edg.xml" which contains the previously imported edges. The edge file will contain the list of previously read edges and each edge will have the information about the edge's id, the allowed velocity, the number of lanes, and the from/to - nodes stored. Geometry information is stored only if the imported edge has a shape, meaning that it is not only a straight connection between the from/to-nodes. The lane spread type and the basic edge type are only saved if differing from defaults ("right" and "normal", respectively). Additionally, if one of the lanes prohibits/allows vehicle classes, this information is saved, too (see also "Defining allowed Vehicle Types").

Specific options:

--plain-output <PLAIN_OUTPUT_PREFIX>

Writes the files <PLAIN_OUTPUT_PREFIX>.nod.xml and <PLAIN_OUTPUT_PREFIX>.edg.xml that contain the descriptions about the nodes and the edges a network is made of. These files may be reread into the netgener using the XML-import capabilities. Optional, type:filename-prefix, default: none

Examples: none yet

Recent changes:

  • The edge file generated using --plain-output contains the information about the shape, the lane spread and the basic type if differing from the defaults since version 0.9.5.

4.4.10.2. Information about Geometry Removal

The option --map-output (or -M for short) generates a file which contains the information about which edges have been joined (see chapter "Removing Geometry Nodes").

The format is a little bit strange and should be reworked in the next time. At the begin of each line of the generated file, you will find the id of an edge from the generated network. Then, divided by tabs, you will find the list of edge ids together with the corresponding edges' lengths, the edge consists of. The id is divided from the length by a ':'. This means if that an edge that was joined from the edges 'edge1', 'edge2', 'edge3', each having the length 10, 20, and 30m, respectively, it would appear in the file encoded as following:

edge1<TAB>edge1:10<TAB>edge2:20<TAB>edge3:30

If the edge was not build by joining other edges, the list of edge ids/length will have only one value, of course:

edge<TAB>edge:100

Specific options:

( --map-output | -M ) <MAP_OUTPUT_FILE>

Writes the file <MAP_OUTPUT_FILE> which holds the list of edges that were joined to a single edge for each edge. Optional, type:filename, default: none

Examples: none yet

4.4.10.3. Node Geometries Dump and Printing Node Positions

The option --node-geometry-dump is meant to be used when debugging the geometry computation. It generates a list of points of interest as readable by guisim (see chapter "Additional Geometry Files") on the positions that were used to compute the imported nodes' geometries. The option "--print-node-positions" forces NETCONVERT and NETGEN to print the positions of the imported/build nodes on the command line.

Specific options:

--node-geometry-dump <DUMP_FILENAME>

Writes the positions that were used during geometry computation into <DUMP_FILENAME>. Optional, type:filename, default: none

--print-node-positions

Prints the node positions during building. Optional (pregiven), type:bool, default: false

Examples: none yet

4.5. Automatic Network Generation

NETGEN allows builds abstract networks. Three types of networks can be built. All of them are very easy, but may be used as examples. You are also greatly invited to extend the concepts. Available types are: grid-networks, spider-networks and random-networks. You always have to supply the name of the network to generate using --output <FILENAME> or -o <FILENAME> for short and the type of network you want to create. So, exactly one of the following switches must be supported: --grid-net, --spider-net or --random-net.

While the type-dependent options are described within the next chapters, all types share some command line options. As all networks may possess junctions, you are able to set the default type of junctions to build using the --default-junction-type-option (or -j for short). The following junction types are allowed in accordance to the junction types currently known by the simulation: priority, traffic_light, actuated, agentbased.

[Caution]Caution

traffic_light will be mapped to "static" within the generated network.

Further, you can specify the default street type by using the same options as in the netconvert-application.

4.5.1. Grid-like Networks

You are able to describe how many junctions in x- and in y-direction you want to be build and how far from each other they should be. The parameter for the number of junctions are --grid-x-number and --grid-y-number, the ones for the distance between the junctions --grid-x-length and --grid-y-length. If you want to build networks which have the same values for both axes, use --grid-number and --grid-length. The lengths are given in meters. It is possible to give another option --attach-length, which adds streets of the given length at the boundary of the grid such that all crossings have four streets (It is not yet possible to have different attach lengths for x- and y-direction).

An example usage for building could be:

Figure 4.8. netgen --grid-net --grid-number=10 --grid-length=400 --output-file=MySUMOFile.net.xml

netgen --grid-net --grid-number=10 --grid-length=400 --output-file=MySUMOFile.net.xml

Another one:

Figure 4.9. netgen --grid-net --grid-x-number=20 --grid-y-number=5 --grid-y-length=40 --grid-x-length=200 --output-file=MySUMOFile.net.xml

netgen --grid-net --grid-x-number=20 --grid-y-number=5 --grid-y-length=40 --grid-x-length=200 --output-file=MySUMOFile.net.xml

4.5.2. Spider-net-like Networks

Spider-net networks are defined by the number of axes dividing them (parameter --spider-arm-number or --arms, default is 13), the number of the circles they are made of (--spider-circle-number or --circles, default is 20) and the distance between the circles (--spider-space-rad or --radius in meters, default is 100).

[Caution]Caution

As the number of edges within the middle of the spider net may be quite large, it is often not possible to build a traffic light junction here. Due to this, this junction is always a right-of-way-junction.

Optionally you can omit the central junction of the network by specifying --spider-omit-center or --nocenter. This also gives an easy way of generating a circle network. Using for instance netgen --spider-net --spider-omit-center --output-file=MySUMOFile.net.xmlwill create a circle consisting of 13 elements with a radius of 100m.

Two examples of usage:

Figure 4.10. netgen --spider-net --spider-arm-number=10 --spider-circle-number=10 --spider-space-rad=100 --output-file=MySUMOFile.net.xml

netgen --spider-net --spider-arm-number=10 --spider-circle-number=10 --spider-space-rad=100 --output-file=MySUMOFile.net.xml

and:

Figure 4.11. netgen --spider-net --spider-arm-number=4 --spider-circle-number=3 --spider-space-rad=100 --output-file=MySUMOFile.net.xml

netgen --spider-net --spider-arm-number=4 --spider-circle-number=3 --spider-space-rad=100 --output-file=MySUMOFile.net.xml

4.5.3. Random Networks

The random network generator does just what his name says, it builds random networks... Several settings may be changed:

  • --rand-max-distance <FLOAT>: the maximum edge length

  • --rand-min-distance <FLOAT>: the minimum edge length

  • --rand-min-angle <FLOAT>: the minimum angle between two edges

  • --rand-num-tries <FLOAT>:

  • --rand-connectivity <FLOAT>:

  • --rand-neighbor-dist1 <FLOAT>:

  • --rand-neighbor-dist2 <FLOAT>:

  • --rand-neighbor-dist3 <FLOAT>:

  • --rand-neighbor-dist4 <FLOAT>:

  • --rand-neighbor-dist5 <FLOAT>:

  • --rand-neighbor-dist6 <FLOAT>:

An example:

Figure 4.12. netgen --random-net -o MySUMOFile.net.xml --rand-iterations=200 --abs-rand

netgen --random-net -o MySUMOFile.net.xml --rand-iterations=200 --abs-rand

4.6. Closing Thoughts (so far)

NETGEN allows to create networks in a very comfortable way. For some small-sized tests of rerouting strategies, tls-signals etc., this is probably the best solution to get a network one can run some simulations at. The clear naming of the streets also eases defining own routes.

Still, most examples within the data-section were written by hand for several reasons. At first, the examples are small enough and one may see the effects better than when using NETGEN. Furthermore, defining own networks using XML-data is more flexible. NETGEN is of course useless as soon as you want to simulate the reality.

Our current state-of-the-art approach for building networks is the following:

  1. Get a plain (no tls, no link-2-link-connections, etc.) network from our NavTeq database

  2. Import it using NETCONVERT and write the list of imported edges/nodes using the --plain-output option

  3. Build the network from the list of edges/nodes (normally setting the options --guess-ramps to true)

  4. Load the network into GUISIM, try to determine where tls are located and which connections between edges/lanes are false; A nice possibility to do this is to use Google Earth besides to investigate how the network looks in reality

  5. Add type="traffic_light" attribute to those nodes in your plain file which were found to be controlled by a tls

  6. Add lane-to-lane connections in a previously generated connections-file

  7. Build the network from the modified edges/nodes/connection files

  8. Continue with step 4. until the network is as it shoud be

A good idea is to let some vehicles run through the network while investigating it. This will show possible bottleneck that arised from a false modelling of the network.

When using real life networks, we really advice guessing on- and off-ramps The on- off-ramps are guessed quite well, we can not state this for the tls, because we don't have made any comparisons with real life.

4.7. Recent Changes

The following list contains recent changes in the naming or meaning of options. It has been started during the work on version 0.9.2, so earlier changes are not contained, herein. The changes list contains the version where the change occured or will occure. The changes should be valid for the next stable release.

  • Changes in version 0.9.2

    • --xml-type-files was named --type-file in versions earlier than 0.9.2; Reason: the naming does not fit into the naming scheme of other XML-input files.

    • versions earlier than 0.9.2 allow to use a filename for each of the .dbf and the .shp file using "--arcview-dbf" and "--arcview-shp"; Reason: This was abondonned, because of the need to use .shx-files, also.

    • --speed-in-kmh was named --speed-in-km in versions earlier than 0.9.2; Reason: false physical measure

  • Changes in version 0.9.3

    • in versions earlier than 0.9.3, turnarounds were not added per default. Instead the option "--append-turnarounds" has forced NETCONVERT to add them; Reason: turnarounds semm to be wished for the wider set of applications. Only sometimes it is unwished to add them.

    • in versions earlier than 0.9.3, geometry nodes were removed by default. One could change this behaviour using the "--no-node-removal" option; Reason: the same as for "--append-turnarounds"

  • Changes in version 0.9.4

    • The function-tag for edges was added for version 0.9.4

  • Changes in version 0.9.5

    • The function-tag within edges was revalidated for version 0.9.5

    • The function-tag for edge types was added for version 0.9.5

    • The edge file generated using plain-output contains the information about the shape, the lane spread and the basic type if differing from the defaults since version 0.9.5.

    • Inner-junction traffic was revalidated for version 0.9.5

    • The possibility to define which vehicle classes are allowed on a lane was added in version 0.9.5

  • Changes in version 0.9.6

    • Described our current procedure of importing networks

  • Changes in version 0.9.9

    • The function-tag within edges was removed in version 0.9.9

    • The function-tag for edge types was removed in version 0.9.9

4.8. Missing

There are some further options which were not yet described. Use at own risc.

--x-offset-to-apply, --y-offset-to-apply, --rotation-to-apply

--keep-unregulated, --keep-unregulated.nodes, --keep-unregulated.district-nodes

--guess-obscure-ramps, --obscure-ramps.add-ramp, --obscure-ramps.min-highway-speed


last change: Sunday, 11-Jan-2009 16:00:35 UTC