OTFVis is a visualizer for MATSim. It can be used to replay snapshots of simulations, or run a simulation and interact with it. The visualizer makes use of hardware acceleration (Open GL) and is thus also suitable for visualizing large scenarios. For the hardware acceleration to work, (i) the OpenGL graphic card driver installed on you machine must be at least of version 2.0 and (ii) native libraries are required, which must be correctly set up.

Check and Update Graphic Card Driver

Either you use check and update mechanims / software already installed (e.g. NVIDIA software, ATI update manager, etc...) or download and install OpenGL Extension Viewer. After starting this little tool, it show all necessary information abour your graphic card including OpenGL version. Please be sure that at least OpenGL version 2.0 is installed. Otherwise try to find approriate driver updates of your graphic card (the read circles in the Figure below shows the important featrues / information).

Starting the Visualizer

The main class for the visualizer is org.matsim.run.OTFVis. If it is invoked without any arguments, a short description is displayed how the visualizer can be used. The different ways to start OTFVis will be described in more details below.

The visualizer may require a lot of memory, it is thus advised to start it with the corresponding Java options:

java -Xmx500m -cp MATSim.jar org.matsim.run.OTFVis arguments

This sets the memory limit for Java to 500 MB.

In addition, OTFVis requires native libraries to provide the required hardware acceleration. Native libraries contain source code that can only run on some specific machines and operating systems. We provide the native libraries for the most common operating systems in libs/jogl-1.1.1. You may also check for the newest versions of the native libraries at the Java OpenGL website. There are several ways to include the native library when starting OTFVis:

• specify on the command line. Example:

  java -Djava.library.path=libs/jogl-1.1.1/jogl-1.1.1-linux-amd64/lib/ -cp MATSim.jar org.matsim.run.OTFVis arguments
  
  

• install the corresponding native library as a java extension. The location where the library must be installed differs from one operating system to the next one. Please check the documentation at java.sun.com for general information about Java Extensions or at Apple for Macintosh-specific installation instructions.

• specify the native library location in Eclipse. If you use the Eclipse IDE for MATSim development, you can specify in the buildpath-settings which native library should be used. Open the Project Properties in Eclipse, and go to Java Build Path > Libraries. Select the jogl.jar in the list of libraries, and expand its display. There should be an entry "Native libary location" that you can set to the corresponding library for your operating system.
• I (KN) had also success with putting it somewhere and then adding the path to the library path:
  

      export LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:${CORRECT_PATH}/libs/jogl-1.1.1/jogl-1.1.1-macosx-universal/lib  # linux 
      export DYLD_LIBRARY_PATH=${LD_LIBRARY_PATH}:${CORRECT_PATH}/libs/jogl-1.1.1/jogl-1.1.1-macosx-universal/lib  # mac os x
      

Creating snapshots (mvi-files) from Events

Use the following arguments:

-convert event-file network-file mvi-file [snapshot-period]

to record a snapshot of all vehicles' positions every snapshot-period seconds, based on the events and network given in the corresponding files.

Example call:

java -cp MATSim.jar org.matsim.run.OTFVis -convert output/50.events.txt.gz input/network.xml.gz output/50.visualization.mvi 300

This will create a snapshot of every 5th minute and store it in the file output/50.visualization.mvi.

Displaying MATSim Visualization Snapshots (mvi-files)

Just pass the file as first argument. Example call:

java -cp MATSim.jar org.matsim.run.OTFVis output/0.visualization.mvi

Displaying TRANSIMS Vehicle files

For reasons of backward compatibility, OTFVis can display vehicles files traditionally generated by TRANSIMS. As the vehicle file does not include any network information, the network must be passed as well. Example call:

java -cp MATSim.jar org.matsim.run.OTFVis output/0.T.veh input/network.xml.gz

Displaying MATSim Network files

OTFVis can display just a network. This is useful when building a scenario, and a network converted from other data must be inspected. Example call:

java -cp MATSim.jar org.matsim.run.OTFVis input/network.xml.gz

(Note: Currently only available in Nightly Builds since revision r5821)

Start Interactive Simulation

OTFVis can directly start a simulation and visualize it in real time. As in that case, all data (esp. the population) is loaded into memory, interactive queries about agents and link states can be issued from the visualizer. To start OTFVis in this interactive, live mode, just pass it the config-file you would otherwise pass to the Controler:

java -cp MATSim.jar org.matsim.run.OTFVis input/config.xml

Please note that this will require even more resources (memory, cpu-speed) than only running the simulation with the Controler.

Running OTFVis from within a windows systems

As shown by the Nightly Builds tutorial OTFVis and other classes can be run by using the command line or a shell script respectively. As the Unix based way is already described by the tutorial, this is about the windows user.

The windows command line call looks similiar to the Unix based one. Finally, you should end with something like that

java -Xmx1500m -Djava.library.path=libs/jogl-1.1.1/jogl-1.1.1-windows-i586/lib -cp MATSim_r6508.jar org.matsim.run.OTFVis %*

which can be saved as a *.bat file, e.g. otfvis.bat. Please note that the example is based on the assumption that otfvis.bat is saved in the same folder as the matsim.jar and the libs folder. The placeholder %* will be substitued by the parameters you've specified when calling otfvis.bat from the command line, e.g.

otfvis.bat -convert event-file network-file mvi-file

To call the OTFVis from any folder, put the otfvis.bat into your PATH environment.

If your are more familiar with the point and click behaviour of win systems, you can create a shortcut pointing to your otfvis.bat.

1. By putting it on your desktop, you can drop any file on it, to call OTFVis with the file dropped, e.g. a network.
2. Move the shortcut to your SendTo folder and rename it to something like OTFVis.lnk. Depending on the system you use, the SendTo folder should be located in your home directory. Now you can start the OTFVis by rightclicking at any file within your system, e.g. rightclick a mvi-file, from the context menu select SendTo -> OTFVis.