From Sumo
Revision as of 13:38, 2 March 2012 by Dkrajzew (talk | contribs) (Options)
Jump to navigation Jump to search

From 30.000 feet

NETCONVERT imports digital road networks from different sources and generates road networks that can be used by other tools from the package.

Purpose: Road networks import and conversion
System: portable (Linux/Windows is tested); runs on command line
Input (mandatory): Definition of a road network
Output: A generated SUMO-road network; optionally also other outputs
Programming Language: c++

Usage Description

NETCONVERT is a command line application. It assumes at least one parameter - the combination of the name of the file type to import as parameter name and the name of the file to import as parameter value. So, for importing a network from OpenStreetMap one could simply write:

netconvert --osm my_osm_net.xml

and for importing a VISUM-network:

netconvert --visum

In both cases, as no output name is given, the SUMO network generated from the imported data is written into the file "". To write the network into a different file, use the option -o <OUTPUT_FILE>. If you want to save the imported VISUM-network into a file named "", write:

netconvert --visum -o

Many further parameter steer how the network is imported and how the resulting SUMO-network is generated.

Supported Formats

NETCONVERT is able to import road networks from the following formats:


You may use a XML schema definition file for setting up a NETCONVERT configuration: netconvertConfiguration.xsd.


All applications of the SUMO-suite handle configuration options the same way. These options are discussed at Basics/Using the Command Line Applications#Configuration Files.

Option Description
-c <FILE>
--configuration-file <FILE>
Loads the named config on startup
--save-configuration <FILE> Saves current configuration into FILE
--save-template <FILE> Saves a configuration template (empty) into FILE
--save-schema <FILE> Saves the configuration schema into FILE
--save-commented Adds comments to saved template, configuration, or schema; default: false


Option Description
-s <FILE>
--sumo-net-file <FILE>
Read SUMO network from FILE
-n <FILE>
--node-files <FILE>
Read XML node definitions from FILE
-e <FILE>
--edge-files <FILE>
Read XML edge definitions from FILE
-x <FILE>
--connection-files <FILE>
Read XML connection definitions from FILE
-t <FILE>
--type-files <FILE>
Read XML type definitions from FILE
--shapefile-prefix <FILE> Read shapefiles (ArcView, Tiger, ...) from files starting with 'FILE'
--dlr-navteq-prefix <FILE> Read converted Navteq GDF data (unsplitted Elmar-network) from path 'FILE'
--osm-files <FILE> Read OpenStreetMap network from path 'FILE(s)'
--opendrive-files <FILE> Read openDrive-network from FILE
--visum-file <FILE> Read VISUM-net from FILE
--vissim-file <FILE> Read VISSIM-net from FILE
--robocup-dir <FILE> Read RoboCup-net from DIR
--matsim-files <FILE> Read MATSim-net from FILE


Option Description
-o <FILE>
--output-file <FILE>
The generated net will be written to FILE
--plain-output-prefix <FILE> Prefix of files to write plain xml nodes, edges and connections to
--map-output <FILE>
Writes joined edges information to FILE
--matsim-output <FILE> The generated net will be written to FILE using MATSIM format.
--output.street-names Street names will be included in the output (if available); default: false


Most data of real world networks has locations and shapes of streets and junctions specified with geocoordinates. This is especially true for OSM, Tiger networks (and most of the other shapefiles) and Navteq GDF and derivatives. Since SUMO works with cartesian coordinates only, you need to perform a projection of the geo coordinates into the plane. Unfortunately there are plenty of projections available but fortunately there exists the Proj library which is used by NETCONVERT to handle almost all of them. There are several options to use geo projection (and proj) together with NETCONVERT:

Option Description
--simple-projection Uses a simple method for projection; default: false
--proj.scale <INT> Number of places to shift decimal point to right in geo-coordinates; default: 0
--proj.utm Determine the UTM zone (for a universal transversal mercator projection based on the WGS84 ellipsoid); default: false
--proj.dhdn Determine the DHDN zone (for a transversal mercator projection based on the bessel ellipsoid); default: false
--proj <STRING> Uses STR as proj.4 definition for projection; default: !
--proj.inverse Inverses projection; default: false

In case you (or your network supplier) are already familiar with the use of proj you can pass the correct parameters directly to NETCONVERT using --proj. Sometimes also the EPSG number of a projection is known, which together with this list (coming also with most proj installations) helps to find the correct proj parameters. Most of the networks have however WGS84 data, which is usually converted using UTM. In order to support this often used projection NETCONVERT provides another option --proj.utm which determines the correct UTM zone to use from the longitude of the first point in the network. --proj.dhdn does essentially the same for data referring to the "Deutsches HauptDreiecksNetz" which used to be the basis for most of the administrative data in germany.

If you want to "undo" a projection for instance if you need to modify an existing sumo network, you can do an inverse projection by giving --proj.inverse. If you don't have proj available but desperately need a projection of some kind, you can try --proj.simple. This should be a last resort only, if you have proj, you should always prefer --proj.utm.

TLS Building

Option Description
--tls.set <STRING> Interprets STR as list of junctions to be controlled by TLS
--tls.unset <STRING> Interprets STR as list of junctions to be not controlled by TLS
--tls.guess Turns on TLS guessing; default: false
--tls.taz-nodes Sets district nodes as tls-controlled; default: false
--tls-guess.joining Includes node clusters into guess; default: false
--tls.join Tries to cluster tls-controlled nodes; default: false <INT> Use INT as green phase duration; default: 31
--tls.yellow.min-decel <FLOAT>
Defines smallest vehicle deceleration; default: 3
--tls.yellow.patch-small Given yellow times are patched even if being too short; default: false
--tls.yellow.time <INT> Set INT as fixed time for yellow phase durations
--tls.half-offset <STRING> TLSs in STR will be shifted by half-phase
--tls.quarter-offset <STRING> TLSs in STR will be shifted by quarter-phase

Ramp Guessing

Option Description
--ramps.guess Enable ramp-guessing; default: false
--ramps.max-ramp-speed <FLOAT> Treat edges with speed > FLOAT as no ramps; default: -1
--ramps.min-highway-speed <FLOAT> Treat edges with speed < FLOAT as no highways; default: 21.94
--ramps.ramp-length <FLOAT> Use FLOAT as ramp-length; default: 100
--ramps.set <STRING> Tries to handle the given edges as ramps

Edge Removal

Option Description
--keep-edges.min-speed <FLOAT> Remove edges with speed < FLOAT
--remove-edges.explicit <STRING> Remove edges in STR
--keep-edges.explicit <STRING> Remove edges not in STR
--keep-edges.input-file <FILE> Removed edges not in FILE
--keep-edges.postload Remove edges after joining; default: false <STRING> Keeps edges which are located within the given boundary <STRING> Keep edges that allow any of the vclasss in STR <STRING> Remove edges where vclass def is not in STR
--remove-edges.isolated Removes isolated edges; default: false

Unregulated Nodes

Option Description
--keep-nodes-unregulated All nodes will be not regulated; default: false
--keep-nodes-unregulated.explicit <STRING> Do not regulate nodes in STR
--keep-nodes-unregulated.district-nodes Do not regulate district nodes; default: false


Normally, both NETCONVERT and NETGEN translate the read network so that the left- and down-most node are at coordinate (0,0). The following options allow to disable this and to apply different offsets for both the x- and the y-axis. If there are explicit offsets given, the normalization is disabled automatically (thus there is no need to give --disable-normalize-node-positions if there is at least one of the offsets given).

Option Description
--ignore-errors Continue on broken input; default: false
--ignore-errors.connections Continue on invalid connections; default: false
--lanes-from-capacity.norm <FLOAT> The factor for flow to no. lanes conversion; default: 1800
--speed-in-kmh vmax is parsed as given in km/h (some); default: false
--plain.keep-edge-shape No node positions are added to the edge shape; default: false
--matsim.keep-length The edge lengths given in the MATSIM-file will be kept; default: false
--matsim.lanes-from-capacity The lane number will be computed from the capacity; default: false
--shapefile.street-id <STRING> Read edge ids from column STR
--shapefile.from-id <STRING> Read from-node ids from column STR <STRING> Read to-node ids from column STR
--shapefile.type-id <STRING> Read type ids from column STR
--shapefile.use-defaults-on-failure Uses edge type defaults on problems; default: false
--shapefile.all-bidirectional Insert edges in both directions; default: false
--shapefile.guess-projection Guess the proper projection; default: false
--vissim.join-distance <FLOAT> Structure join offset; default: 5
--vissim.default-speed <FLOAT> Use FLOAT as default speed; default: 50
--vissim.speed-norm <FLOAT> Factor for edge velocity; default: 1 Writes lanes without an explicit speed set; default: false
--visum.use-type-priority Uses priorities from types; default: false
--visum.use-type-laneno Uses lane numbers from types; default: false
--visum.use-type-speed Uses speeds from types; default: false
--visum.connector-speeds <FLOAT> Sets connector speed; default: 100
--visum.connectors-lane-number <INT> Sets connector lane number; default: 3 Excludes connectors; default: false
--visum.recompute-lane-number Computes the number of lanes from the edges' capacities; default: false
--visum.verbose-warnings Prints all warnings, some of which are due to VISUM misbehaviour; default: false
--osm.skip-duplicates-check Skips the check for duplicate nodes and edges; default: false
--osm.discard-tls Discards all traffic lights from OSM file(s); default: false
--no-internal-links Omits internal links; default: false
--dismiss-vclasses Removes vehicle class restrictions from imported edges; default: false
--no-turnarounds Disables building turnarounds; default: false
--no-turnarounds.tls Disables building turnarounds at tls-controlled junctions; default: false
--no-left-connections Disables building connections to left; default: false
--geometry.split Splits edges across geometry nodes; default: false
Removes geometry information from edges; default: false
--offset.disable-normalization Turn off normalizing node positions; default: false
--offset.x <FLOAT> Adds FLOAT to net x-positions; default: 0
--offset.y <FLOAT> Adds FLOAT to net y-positions; default: 0
--flip-y-axis Flips the y-coordinate along zero; default: false
--roundabouts.guess Enable roundabout-guessing; default: false
--lefthand Assumes left-hand traffic on the network; default: false
--junctions.join Joins junctions that are close to each other (recommended for OSM import); default: false
--junctions.join-dist <FLOAT> Determines the maximal distance for joining junctions; default: 15
--junctions.join-exclude <STRING>[,<STRING>]* Interprets argument as a list of junctions to exclude from joining
--speed.offset <FLOAT> Modifies all edge speeds by adding FLOAT
--speed.factor <FLOAT> Modifies all edge speeds by multiplying FLOAT

Building Defaults

Option Description
-L <INT>
--default.lanenumber <INT>
The default number of lanes in an edge; default: 1
--default.speed <FLOAT>
The default speed on an edge (in m/s); default: 13.9
-P <INT>
--default.priority <INT>
The default priority of an edge; default: -1


All applications of the SUMO-suite handle most of the reporting options the same way. These options are discussed at Basics/Using the Command Line Applications#Reporting Options.

Option Description
Switches to verbose output; default: false
Prints option values before processing; default: false
Prints this screen; default: false
Prints the current version; default: false
Disables output of warnings; default: false
-l <FILE>
--log <FILE>
Writes all messages to FILE
--message-log <FILE> Writes all non-error messages to FILE
--error-log <FILE> Writes all warnings and errors to FILE

Random Number

All applications of the SUMO-suite handle randomisation options the same way. These options are discussed at Basics/Using the Command Line Applications#Random Number Options.

Option Description
--random Initialises the random number generator with the current system time; default: false
--seed <INT> Initialises the random number generator with the given value; default: 23423