Usage

Requirements

• Gradle 4.7
  Note: Gradle doesn't need to be installed if the project's gradle wrapper is used instead.
• Java 1.8.0_172
Java 1.8.0_201
  Note: With higher Java version on our systems, the software doesn't run without exceptions. So setting the JAVA_HOME variable accordingly is recommended. It may help to add ${JAVA_HOME}/bin to your PATH variable. You can check the version used by gradle with ./gradlew -version. The entry JVM depends on your JAVA_HOME variable.
• python3
  Note: Since python2 is not supported, only python3 (and not python referencing python3) is supported.
  Note: Only needed for python scripts. Additional python packages may be required depending on the executed script.

Setup, Demonstration and Examples

Demonstrations and examples can be executed using gradle. This project contains a gradle wrapper file, so you don't need to install it.

Before running a simulation, map data is needed.

Map Data

All OpenStreetMap (OSM) files need to be in the OSM XML format, as, for example, provided by the OpenStreetMap web interface. The project's python tool osmloader can be used to download such map files (e.g. if your file is too large for OSM), but the OSM web interface helps finding the right coordinates. If you like to download bigger maps, take a look at Geofabrik.

You can execute the script via

./gradlew :tools:osmloader:run -Dexec.args="<args>"

where <args> should be -h at first.

1D Single Laned Example

This little python-subproject is kind of the "hello world" project for a simulation of the Nagel-Schreckenberg-Model. It can be executed using

./gradlew :examples:circlestreet1D:run

or

./gradlew :examples:circlestreet1D:run -Dexec.args="<args>"

where <args> is depending on the script and can change simulation parameters (e.g. colormap). For more information about <args>, set it to -h.

Main UI

The main UI provides an overview of the simulation. The scenario is currently fixed (random routes), however various simulation parameters, as well as the number of vehicles and the used map, can be adjusted. Please know that the OSM parser needs some time to finish (for reference: a capital city like Stuttgart could take a minute). Per default, a small city called "Backnang" is loaded, which lays in microtrafficsim-ui/data. (Note: The window background could flicker until the first map has loaded) Some arguments are supported via cmdline. For further information, call the second command replacing <args> by -h.

./gradlew :microtrafficsim-ui:run
./gradlew :microtrafficsim-ui:run -Dexec.args="<args>"

A (somewhat) stable demonstration can be executed from the master-branch.

Fixed Simulation Example

The fixed simulation example features a fixed scenario and fixed parameters, It represents a former state of development, therefore the simulation parameters can't be changed without changing code. It can be executed using

./gradlew :examples:simulation:run -Dexec.args="<path to OSM-XML file>"

Map-Viewer Example

The map-viewer example can be executed using

./gradlew :examples:mapviewer:run -Dexec.args="<path to OSM-XML file>"

Controls

This chapter details the keyboard and mouse-controls for the specific components of this program, as well as the main UI, Map Viewer Example, and the Simulation Example.

Note: As of now, some of the described functionality may only be available in the wip/serialization branch.

Common Controls: Movement

Input	Action
Right Mouse Down + Mouse Drag	Move map
Middle Mouse Down + Mouse Drag	Move map

Components and Overlays: Scenario Area Overlay

Selection

Pressing Ctrl in combination with any of the following input options will keep the previously selected elements selected, not doing so will reset the selection. Vertices can only be selected (and modified) after the respective area has been selected.

Input	Action
Right Mouse Click	Select area or vertex of (selected) area beneath cursor
Left Mouse Down + Mouse Drag + Mouse Release	Select multiple areas using a selection-rectangle

Area and Vertex Modification

The Property Window can be used to change specific properties of the selected areas. It will open automatically upon selection.

Input	Action
Right Mouse Down + Mouse Drag	Move the vertex beneath the cursor (if any) and reset selection
Ctrl + Right Mouse Down + Mouse Drag	Move the selected areas (if the cursor is over an area) or the selected vertices (if cursor is over a vertex), keep selection
Shift + Right Mouse Click	Create a new vertex, either starting a new area or adding it to an existing area if the cursor is close to the edge of a selected area (indicated)
Delete	Remove selected vertices, if any, else remove selected areas (if any). Any area with less than 3 vertices will be removed automatically

Interface Specific Controls: Main UI

Input	Action
M	Open OpenStreetMap XML file
N	Create new scenario
,	Update current scenario
Space	Run/Pause simulation
→	Advance simulation one step

Interface Specific Controls: Map Viewer Example

Input	Action
Esc or Q	Close application
W or Ctrl + S	Save map as binary file
E or Ctrl + O	Open OpenStreetMap XML or binary file
C	Reset (center) view

Interface Specific Controls: Simulation Example

Input	Action
Esc or Q	Close application
W or Ctrl + S	Save map as binary file
E or Ctrl + O	Open OpenStreetMap XML or binary file
C	Reset (center) view
Space	Run/Pause simulation
→	Advance simulation one step
R	Reset simulation