Chapter 8. Tips, Tricks and Tools


Prev		Next

Chapter 8. Tips, Tricks and Tools

Table of Contents

8.1. Using Configuration Files

8.2. Additional Meta-Information

8.3. Additional Tools

8.3.1. Polygon Conversion
8.3.2. Helpers for DUA-Computation
8.3.3. Handling Routes and Route Alternatives

We want to supply some additional information that did not fit into the descriptions within the previous chapters. The next chapters are possibly the most interesting ones of this document as they describe some possibilities to ease the work.

8.1. Using Configuration Files

Most simulations have to be executed more than only one time. Furthermore, some experiments require the execution of similar, slightly different settings, for example the same network with a different route set. To avoid retyping of all parameter at the input line, all of the main applications can be fed with a configuration file. This configuration file contains the values the user normally would give to the program at the command line. For example, instead of typing

duarouter --cell=myCellFile --net=mySUMONet.net.xml --output-file=MySUMORoutes.rou.xml \
   -b 0 -e 3600

you can start the router with a configuration file only:

duarouter -c=myConfig.rou.cfg

The -c <FILE> - option may be passed to all of the package's main applications.

Of course, you have to build the configuration file "myConfig.rou.cfg" first. You can find templates for configuration files within the data/cfg_templates - folder and all examples coming with the release contain configuration files, too.

A configuration file is a simple XML-file in which each of the command line parameters is represented as a XML-element with the parameter's value being given as text between the begin and end tag of this parameter. So if you want to set a parameter "foo" to the value "bar" within your configuration file, write <foo>bar<foo/> into the configuration file. Do not forget that each XML-file has to have a root element, so that the whole configuration file would look like this:

<configuration>
   <foo>bar<foo/>
</configuration>

Between the starting at the ending tag, any type of values may be set, use a 'x' to mark boolean values as set. If a parameter allows a set of values (normally separated by a ';'), you have to use a single element and embed these value into it as you would on command line. A different approach will maybe be invented in future. You can find the templates for each of the package's application's configuration files within the folder "<SUMO_DIST>/data/cfg_templates".

8.2. Additional Meta-Information

All applications of the SUMO-package print a help-screen is printed including all options the application knows when the application is started with the --help (-? for short) option. You can also list all current option settings using --print-options (or -p for short).

Recent changes:

This chapter has been moved to this place while working on version 0.9.5
The option --version that printed the currnt build number was removed in version 0.9.5. As we assume our users to build the software by themselves, a build number does not really make sense.
The description of --print-options was added in version 0.9.5.

8.3. Additional Tools

You can some find helpful tools within the <SUMO_DIST>/tools - folder. We will now introduce some of them. The following chapters are devided by the topic the tools cover.

8.3.1. Polygon Conversion

Since version 0.9.5 a further application was added to the suite: POLYCONVERT, a tool which allows you to convert polygons from Elmar's format into a description that may be used by SUMO. As the offset that was applied (automatically, see!!!) to the network during the conversion using NETCONVERT is needed, one has to supply the network name using --net-file <SUMO_NET> (--net or -n for short). Additionally the name of the file that contains the polygons to import must be given using --elmar <ELMAR_POLYGON_FILE>. The conversion from geocoordinates to cartesian is recommended, initiated using --use-projection and defined using --proj <PROJ_DEFINITION> (see also "Converting from Geocoordinates").

Defaults for the polygon's color and layer as well as a name prefix and the name of the type to assign can be given using the options --color <COLORDEF>, --layer <LAYER_NO>, --prefix <PREFIX>, and --type <TYPENAME>, respectively. As some inputs may contain different polygon types, you can also use a file which contains a type map which defines which values shall be set in dependance to the type. A single entry for this typemap should look like this: <polytype id="<PREVIOUS_NAME>" name="<NEW_NAME>" color="<COLORDEF>" fill="<BOOL>" layer="<LAYER_NO>" discard="<BOOL>"/>. The values are:

id: The name of the type as read from the input file
name: The name to use for the type in the output (type-name replacement)
color: Definition of the color to assign
fill: Information whether a filling of the polygon must be prohibited
layer: Layer to use for this type of polygons
discard: Information whether polygons of this type shall not be written to output

An example type-map for Elmar's polygons can be found in <SUMO_DIST>/data/add/elmar_type_map.xml. It is given to POLYCONVERT using the --typemap <TYPEMAP_FILE> option.

Since version 0.9.6, POLYCONVERT can also import single points of interest from Elmar's pointcollection files. To import such a file use the option --elmar-points <FILENAME>, where <FILENAME> is the name of the file to import. You can use a type map in this case, too. In this case, the attribute "filled" will be ignored, all other attributes are processed as in the case of importing polygons.

Also since this version, POLYCONVERT can import polygons and pois from Visum-networks. The options herefore are --visum <VISUM_NET> and --visum-points <VISUM_NET>. In the first case, polygons from "BEZIRK" and "GEBIET" are imported, in the second "POI". "POIKATEGORIE" is parsed in the second steps and the values stored herein are used as type names; for "BEZIRK", the type name "district" is used, "area" for "GEBIET". These type names may be references in the type map file.

In some cases, it is wished not to import all polygons/pois. You can constrain which polygons/pois shall be written using the by assigning the attribute "discard" to certain types of polygons(pois within the type-map. You can also prune those polygons/pois that are not lying within a certain bounding box. This is done by calling POLYCONVERT with the option --prune.boundary <BOUNDARY>. <BOUNDARY> is in this case the bounding box in which a polygon/poi must be located in order to be written into the output. It is a list of four floats, separated using ',' that describe the minimum x-value, the minimum y-value, the maximum x-value, and the maximum y-value of the bounding box. If one wishes to use the network's dimensions as the bounding box, he/she can do this using the option --prune.on-net. Additionally, one can supply offsets to the network's dimensions using --prune.on-net.offsets <BOUNDARY>.

All options (#TBD excluded loading configuration and output options, see #):

( --net-file | --net | -n ) <SUMO_NET>: The SUMO-net to use as reference. Mandatory, type:filename, default: none
--elmar <ELMAR_POLYGON_FILE>: Reads polygons from the given Elmar polygon file. Optional, type:filename, default: none
--elmar-points <ELMAR_POI_FILE>: Reads pois from the given Elmar pointcollection file. Optional, type:filename, default: none
--visum <VISUM_NET>: Reads polygons from the given VISUM net. Optional, type:filename, default: none
--visum-points <VISUM_NET>: Reads pois from the given VISUM net. Optional, type:filename, default: none
--typemap <TYPEMAP_FILE>: Reads type maps from the given file. Optional, type:filename, default: none
--use-projection: Enables conversion from geocoordinates to cartesian. Optional, type:bool, default: false
--proj <PROJ_DEFINITION>: Defines the projection to use. Optional, type:string, default: "+proj=utm +zone=33 +ellps=bessel +units=m"
--color <COLORDEF>: Defines the color to use as default. Optional (pregiven), type:color, default: "0.2,0.5,1." (light blue)
--layer <LAYER_NO>: Defines into which layer the polygons shall be put by default. Optional (pregiven), type:int, default: -1 (one layer below the road network)
--prefix <PREFIX>: Defines the type-dependant prefix to apply to polygons. Optional (pregiven), type:string, default: <empty>
--type <TYPENAME>: Defines the name of the type to set for the polygons. Optional (pregiven), type:string, default: "water"
--prune.boundary <BOUNDARY>: Defines the clipping bounding box in which a polygon/pois must lie in order to be written to the output. Optional, type:boundary definition, default: none
--prune.on-net: Let POLYCONVERT use the network dimensions as the clipping bounding box. Optional (pregiven), type:bool, default: false
--prune.on-net.offsets <BOUNDARY>: Defines additional offsets that are added to the network dimensions' components. Optional, type:boundary definition, default: "0,0,0,0"

Recent changes:

POLYCONVERT is available since version 0.9.5
Since version 0.9.6, POLYCONVERT is able to import Elmar's pointcollection files
The possibility to constrain the imported points using bounding boxes was introduced in version 0.9.6
Since version 0.9.6, POLYCONVERT is able to import Visum polygons and points

8.3.2. Helpers for DUA-Computation

8.3.2.1. dua-iterate.pl

This script performs a dua computation by runing the DUAROUTER and SUMO a given number of times and using the previous outputs. A detailed description may be found in the subchapter "Automatic Iteration using 'dua-iterate.pl'".

Usage: dua-iterate.pl <PATH_TO_SUMO_BINARIES>[[<BEGIN_ITERATION_STEP>]]<END_ITERATION_STEP>

Output: see "Automatic Iteration using 'dua-iterate.pl'"

Location: <SUMO_DIST>/tools/dua_tools

8.3.3. Handling Routes and Route Alternatives

8.3.3.1. oldStyle2newStyle_Routes.pl

This tool converts route files as generated by DUAROUTER/JTRROUTER from their old-style representation where the route and the according vehicle where in separate tags into the new style where the route-description is.

Usage: oldStyle2newStyle_Routes.pl <SUMO_ROUTES_FILE>

Output: The tool prints the modified route file in the new-style on the command line

Location: <SUMO_DIST>/tools/route_tools

8.3.3.2. randomizeDepart.pl

This tool randomizes the departure time of vehicles within a given route/route alternatives file.

Usage: randomizeDepart.pl <SUMO_ROUTES_FILE> <MAX_DEPARTURE_TIME>

Output: The tool prints the modified route / route alternatives file in the new-style on the command line

Location: <SUMO_DIST>/tools/route_tools

	Caution
	This tool is meant to be used for tests only - routes in randomized order may yield in an unexpected behaviour!

8.3.3.3. removeRouteId.pl

Removes the ids of routes from their description within the given route file.

Usage: removeRouteId.pl <SUMO_ROUTES_FILE>

Output: The tool prints the modified route file in the new-style on the command line

Location: <SUMO_DIST>/tools/route_tools

	Caution
	This tool is meant to be used for tests only - you may get an unexpected behaviour if you delete route ids which are still needed!

8.3.3.4. removeRouteReference.pl

Removes the references to routes from the descriptions of vehicles within the given route file.

Usage: removeRouteReference.pl <SUMO_ROUTES_FILE>

Output: The tool prints the modified route file in the new-style on the command line

Location: <SUMO_DIST>/tools/route_tools

	Caution
	This tool is meant to be used for tests only - you may get an unexpected behaviour if you delete the information which route shall be used if it still needed!

Prev	Up	Next
Chapter 7. Simulation-GUI	Home	Appendix A. Naming Conventions