Create a New Scenario

For creating new scenarios, but also for importing and exporting data from external sources like OpenStreetMap, SUMO etc into your existing scenarios, we provide the tool Scenario Convert.

scenario-convert is part of MOSAIC Extended.

However, you can use scenario-convert for free to generate scenarios which are executable with Eclipse MOSAIC. Get it here.

Download scenario-convert from DCAITI mirror
  1. Download scenario-convert via the link above
  2. Extract the .zip and go to the extracted folder
  3. To use the commands listed later, rename the extracted scenario-convert-<version>.jar (e.g. scenario-convert-20.0) into scenario-convert
  4. Move scenario-convert to an arbitrary location where you want to create your scenario

scenario-convert will create a database, which is the basis for all map-related tasks performed by Eclipse MOSAIC (e.g. navigation, route calculation…).
Based on a MOSAIC database, scenario-convert can export the data to SUMO-conform formats. Furthermore one can choose, whether to use routes generated by scenario-convert, use existing routes or build own routes via route generation tools (e.g. DUAROUTER by SUMO).

This chapter intends to highlight the most common workflows for the work with scenario-convert. We will be using steglitz.osm OSM-file for most of the use cases. Best is to save steglitz.osm in the same directory where scenario-convert is located. So feel free follow along with the steps to get a better understanding on how the scenario-convert-script functions.

Here you can find a complete reference to all options scenario-convert offers.

OSM-File of Steglitz

Creating a complete Eclipse MOSAIC-scenario from an OSM-file with one command

This is the most straight forward way to create a scenario from your OSM-file. We will use the option --osm2mosaic, which is a combination of the options --osm2db and --db2mosaic.
Let’s start off by showing you how a complete call could look like:

java -jar scenario-convert.jar --osm2mosaic -i steglitz.osm

In this section we use the scenario name steglitz.* as synonym for path/to/steglitz.*.

Please be aware that the scenario generated with the call above contains no routes yet, see Import Routes for more details. The complete call achieves a couple of things. First off the script is going to create a SQLite-database, which is used by Eclipse MOSAIC. Furthermore, a directory will be created, which should look like this:

└─ <working-directory>
   └─ steglitz
       ├─ steglitz.osm
       ├─ application
       |  └─ steglitz.db
       ├─ cell
       |  ├─ cell_config.json
       |  ├─ network.json
       |  └─ regions.json
       ├─ environment
       |  └─ environment_config.json
       ├─ mapping
       |  └─ mapping_config.json
       ├─ ns3
       |  ├─ ns3_config.json
       |  └─ ns3_federate_config.xml
       ├─ omnetpp
       |  ├─ omnetpp_config.json
       |  └─ omnetpp.ini      
       ├─ output
       |  └─ output_config.xml
       ├─ sns
       |  └─ sns_config.json
       ├─ sumo
       |  ├─ steglitz.net.xml
       |  └─ steglitz.sumocfg
       └─ scenario_config.json .................. General configuration of the simulation scenario

Let’s walk through all these files:

  1. First the steglitz.db will be created using the steglitz.osm-file.
  2. The steglitz.db will be used to create steglitz.con.xml, steglitz.edg.xml and steglitz.nod.xml, which are files used by SUMO.
  3. SUMO Netconvert is used to create steglitz.net.xml, which is a network representation in SUMO.
  4. Now the SUMO-configuration steglitz.sumo.cfg is written.
  5. Afterwards the mapping_config.json and scenario_config.json are created and all files are moved to the right place. In the scenario_config.json values like the center coordinate will automatically be set using data from the SUMO related files.

While this is technically sufficient to start working on your scenario, like importing routes to it, there are a couple of other things you can do to achieve better results.

Clean the OSM-file using Osmosis

Osmosis will automatically be used to create a new OSM-file with the suffix _cleaned. The created file will contain much less clutter and usually is better suited for simulation purposes. Check the images below to see the difference the clean-up process can make.

java -jar scenario-convert.jar --osm2mosaic -i steglitz.osm
Uncleaned OSM-file
Cleaned OSM-file
Uncleaned Net-file
Cleaned Net-file

To avoid “cleaning” the OSM-file, please use the option “skip-osm-filter”.

java -jar scenario-convert.jar --osm2mosaic -i steglitz.osm --skip-osm-filter

Generating Routes

The scenario-convert also offers the option --generate-routes, which will generate a route-file, given some additional information. For example purposes we will run the command below. In case you generated the steglitz scenario in one of the steps above already, please delete or rename the steglitz directory and run:

java -jar scenario-convert.jar --osm2mosaic -i steglitz.osm --generate-routes
--route-begin-latlon 52.4551693,13.3193474 --route-end-latlon 52.4643101,13.3206834 --number-of-routes 3

This will calculate three routes between the two given coordinates.

Alternatively you can use the following command in order to generate routes with node-id’s as start and end point, which can be found in the steglitz.nod.xml file.

java -jar scenario-convert.jar --osm2mosaic -i steglitz.osm --generate-routes
--route-begin-node-id 267350668 --route-end-node-id 313139970 --number-of-routes 3

See below for all command line options.

Conclusion

This wraps up one of the main workflows with the scenario-convert-script. A quick reminder on what we achieved:

  • Cleaned up an OSM-file to only contain relevant data.
  • Converted that OSM-file to formats that Eclipse MOSAIC/SUMO can handle.
  • Created the project structure for a scenario.
  • Calculated routes between two coordinates.

With all of this you can now start further developing your scenario. For a more detailed description on the next steps please have a look at Additional Scenario Configuration and Application Development.

You can now move your steglitz directory to /scenarios and test it by running ./mosaic.sh -s steglitz on Linux or .\mosaic.bat -s steglitz on Windows.

While this is the ‘happy world’ workflow, it is often necessary to manually adapt routes and insert them into your scenario. The following workflow will explain how that is done and you will also get a more detailed overview of the scenario-convert-functions.

Importing Routes to your scenario

As mentioned above your routes won’t always be created by the scenario-convert script. We generated some routes for the steglitz-scenario using SUMO’s duarouter, which you can find here. We’ll start with only the steglitz.osm and steglitz.rou.xml files:

└─ <working-directory>
   ├─ steglitz.osm
   └─ steglitz.rou.xml

Creating the database

We’ll start off by solely creating the database and applying OSMOSIS with the following command:

java -jar scenario-convert.jar --osm2db -i steglitz.osm

The directory should look like this:

└─ <working-directory>
   ├─ steglitz.db
   ├─ steglitz.osm
   ├─ steglitz.rou.xml
   └─ steglitz_cleaned.osm

Importing the route-file

Let’s import our routes into the database.
We achieve this by calling:

java -jar scenario-convert.jar --sumo2db -i steglitz.rou.xml -d .\steglitz.db

Now all new routes are imported into our database. The following image shows a visualization of one of the created routes.

Visualization of one of the routes

Creating the scenario

The final step is to create the scenario from the files we created so far.

java -jar scenario-convert.jar --db2mosaic -d .\steglitz.db

Instead of copying our SUMO-files this will generate all necessary files and move them into a Eclipse MOSAIC-conform folder structure:

└─ <working-directory>
   ├─ steglitz.osm
   └─ steglitz
      ├─ application
      |  └─ steglitz.db
      ├─ mapping
      |  └─ mapping_config.json
      ├─ sumo
      |  ├─ steglitz.net.xml
      |  └─ steglitz.sumocfg
      └─ scenario_config.json

As you can see the resulting folder structure looks just like the final output from the first workflow described.

Conclusion

You should now know how you can manually add routes to your scenario and have a deeper understanding of the way that some of the script parameters work.

Attached Files

A list of all attached files in this chapter:

Reference documentation for scenario-convert

Usage of scenario-convert

The following listing shows an overview for the usage of scenario-convert:

usage: scenario-convert [OPERATION] [OPTIONS]

Examples:
1. Import an osm file and write data into database
   > scenario-convert --osm2db -i <OSMFILE> [-d <DATABASE>]
2. Export database content to SUMO-readable files
   > scenario-convert --db2sumo -d <DATABASE> [-s <SUMOPREFIX>]
3. Import a SUMO routefile into a database
   > scenario-convert --sumo2db -d <DATABASE> -i <ROUTEFILE>.rou.xml
4. Combine steps 1 and 2
   > scenario-convert --osm2sumo -d <DATABASE> -i <OSMFILE> [-s <SUMOPREFIX>]
5. Export db content to Shapefile format
   > scenario-convert --db2shp -d <DATABASE>
6. Import an srtm file and write elevation data to nodes of an existing database
   > scenario-convert --srtm2db -i <SRTMFILE> -d <DATABASE>
7. Create a complete MOSAIC scenario from an osm file
   > scenario-convert --osm2mosaic -i <OSMFILE>
8. Create a scenario database from an SUMO net file
   > scenario-convert --sumo2db -i <NETFILE>.net.xml
9. Calculate a route from node 123 to node 456
   > scenario-convert --generate-routes -d <DATABASE> --route-begin-node-id 123 --route-end-node-id 456

The following arguments are available:
 -h,--help                                 Prints this help screen.

 -c,--config-file <PATH>                   Optional, refers to a configuration file which contains all parameters in
                                           JSON format.
    --osm2db                               Converts a OpenStreetMap file to a new scenario database.
    --sumo2db                              Imports a SUMO Network/Routefile. Be aware that you may have to re-export an
                                           imported network.
    --srtm2db                              Imports an SRTM file and writes elevation data to nodes.
    --db2sumo                              Exports the network to SUMO node and edge files.
    --db2shp                               Exports the database into Shapefile format.
    --db2mosaic                            Creates directory structure for a MOSAIC scenario based on the database
                                           contents.
    --osm2sumo                             Combination of osm2db and db2sumo.
    --osm2mosaic                           Combination of osm2db and db2mosaic.
    --update                               Updates the database to the current scheme.

 -d,--database <PATH>                      The path to the database.
                                           For import: File to import to. If not given, a new file is created.
                                           For export: File to load from.
                                           For update operations: file to update.
 -i,--input <PATH>                         Defines an input file to use in an import. File type depends on the import
                                           operation (OSM File/Database file/SUMO net file/SUMO rou file).
 -s,--sumo-prefix <STRING>                 Prefix for the generated sumo files  (uses database name when not defined).
 -f,--force                                Force overwrite of existing files instead of incrementing file names.
 -m,--mapping-file <PATH>                  Uses the given mapping configuration to export existing vehicleTypes and
                                           vehicles data to *.rou.xml.
    --import-lat <DOUBLE>                  Center latitude of imported region to project coordinates.
    --import-lon <DOUBLE>                  Center longitude of imported region to project coordinates.
    --import-zone <STRING>                 UTM zone of location for projecting coords in default format (e.g. 32n).

 -g,--generate-routes                      Generates route(s) from one point to another. The begin and end for the route
                                           must be known (see below options).
    --route-begin-lat <DOUBLE>             Latitude of the starting point, needs --route-begin-lon as well.
    --route-begin-lon <DOUBLE>             Longitude of the starting point, needs --route-begin-lat as well.
    --route-begin-latlon <DOUBLE,DOUBLE>   [latitude],[longitude] of the starting point.
    --route-begin-node-id <STRING>         OSM node id of the starting point (use instead of lat/lon).
    --route-end-lat <DOUBLE>               Latitude of the starting point, needs --route-end-lon as well.
    --route-end-lon <DOUBLE>               Longitude of the starting point, needs --route-end-lat as well.
    --route-end-latlon <DOUBLE,DOUBLE>     [latitude],[longitude] of the ending point.
    --route-end-node-id <STRING>           OSM node id of the ending point (use instead of lat/lon).
    --route-matrix <STRING,STRING,...>     Calculates all possible routes starting and ending at the given nodes, given
                                           as comma-separated list (e.g. 12345,87123,89123)
    --number-of-routes <INTEGER>           Defines the number of alternative routes to be calculated (default=1).

    --import-buildings                     Activates import of building information (only with osm2xxx).
    --skip-osm-filter                      Skips automatic filtering of the OSM file (only with osm2xxx).
    --skip-turn-restrictions               Ignore all defined turn restrictions on OSM import.
    --skip-graph-cleanup                   Turns off the removal of unconnected parts from the main traffic network
                                           graph . Since several components of MOSAIC require one main graph without
                                           disconnected ways and nodes, this option should be used only if the cleanup
                                           procedure is faulty.
    --skip-netconvert                      Skips starting sumo netconvert for creating netfile (only with xxx2sumo).
    --skip-traffic-lights-export           Skips exporting traffic light information for nodes (only with xxx2sumo).
    --osm-speeds-file <PATH>               Define a property file which contains speed information which are used to set
                                           the speed for OSM ways without a max speed tag (only with osm2xxx).
    --osm-speeds-overwrite                 If set to true , the maxspeed tags of ways are ignored and replaced by either
                                           default values , or by speed information defined via the --osm-speeds-file
                                           option (only with osm2xxx).

Configuration-files for scenario-convert

Scenario-convert offers a way to safe your conversion-parameters in a JSON configuration file using the option -c or --config-file.
The following listing shows how to save the options used in the example above:

{
  "operatingMode": "osm2mosaic",
  "inputFile": "steglitz.osm",
  "executeOsmosis": true,
  "generateRoutes": true,
  "routeBeginLatLon": "52.457616,13.318392",
  "routeEndLatLon": "52.454774,13.333554",
  "numberOfRoutes": 3
}

Speed-files

Below you can find a properties file which can be used during the import of OSM data in order to define speeds for ways, which do not have a maxspeeds-tag defined. For this purpose use the option --osm-speeds-file <FILE>. In the speed properties file, for each way type a speed value can be defined, according to the OSM highway key.

# the unit the speed values are defined in [kmh, ms]
speed.unit = kmh

# the default speed for all way types which are not defined here
speed.default = 30
        
# autobahn
highway.motorway = 130
highway.motorway_link = 70

# bundesstrasse (germany)
highway.trunk = 70
highway.trunk_link = 65

# linking bigger town
highway.primary = 65
highway.primary_link = 60

# linking towns + villages
highway.secondary = 60
highway.secondary_link = 50

#streets without middle line separation
highway.tertiary = 50
highway.tertiary_link = 40
highway.residential = 30

#special roads
highway.living_street = 5
highway.service = 20

# unclassified roads
highway.unclassified = 30
highway.road = 20

# forest tracks
highway.track 15
Previous
Next