sumo3Dviz 1.0.0

3D visualization of SUMO traffic simulations

sumo3Dviz

A three dimensional traffic visualisation

sumo3Dviz is a lightweight, open-source 3D visualisation pipeline for SUMO traffic simulations. It converts standard SUMO simulation outputs, such as vehicle trajectories and signal states, into high-quality 3D renderings using a Python-based framework.

Features:

Major OS Support

Python 3.9 Support

Table of Contents

• Highlights
• Installation
• Usage
  • Command Line Interface (CLI)
  • Python Code
• Case Study: Barcelona
  • Step 1: Prepare Sumo Simulation
  • Step 2: Prepare Visualisation Configuration
  • Step 3: Render Video Visualisation with sumo3Dviz
• Citations

Highlights

Visualisation Modes
(1) Eulerian	(2) Lagrangian	(3) Cinematic	(4) Interactive

Video Demos on YouTube:

• Eulerian: https://www.youtube.com/watch?v=XvpG5cbv7Ig
• Lagrangian: https://www.youtube.com/watch?v=DesOELXIWxc
• Cinematic: https://www.youtube.com/watch?v=wEUbjlqigyg
• Interactive: https://www.youtube.com/watch?v=dq9pH1Cj7gA

Installation

The python package sumo3Dviz can be installed using pip:

pip install sumo3Dviz

Please note: Currently only Python 3.9 is supported on all major operating systems (Windows, Mac iOS, Linux).

Usage

You can use sumo3Dviz as command line tool (CLI), configure a variety of parameters in the config YAML file, and the run four different visualisation modes:

1. Run sumo3Dviz in Eulerian mode:

sumo3Dviz --config examples/config_barcelona.yaml --mode eulerian --output examples/barcelona_simulation_eulerian.avi

2. Run sumo3Dviz in Lagrangian mode:

sumo3Dviz --config examples/config_barcelona.yaml --mode lagrangian --output examples/barcelona_simulation_lagrangian.avi

3. Run sumo3Dviz in Cinematic mode:

sumo3Dviz --config examples/config_barcelona.yaml --mode cinematic --output examples/barcelona_simulation_cinematic.avi

4. Run sumo3Dviz in Interactive mode:

sumo3Dviz --config examples/config_barcelona.yaml --mode interactive

Case Study: Barcelona

Step 1: Prepare Sumo Simulation

You can run any SUMO simulation and render it to a video. Just make sure to log vehicle positions and traffic lights (if desired for rendering). Also, if you want to place trees, fences, buildings, and other objects, please create polygon files with netedit. In the following explanations how to do it. Moreover, we provide an example (barcelona_simulation) that demos all outlined information.

(1) Log Vehicle Positions in your Configuration.sumocfg:

<!-- YOUR Configuration.sumocfg -->
<?xml version="1.0" encoding="UTF-8"?>
<configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://sumo.dlr.de/xsd/sumoConfiguration.xsd">

    <!-- ... -->

    <!-- INSERT THIS TO LOG VEHICLE POSITIONS -->
    <output>
        <fcd-output value="simulation_logs/vehicle_positions.xml"/>
        <fcd-output.attributes value="x,y,angle"/>
    </output>

    <!-- ... -->

</configuration>

(2) (Optional) Log Traffic Light States Configuration.sumocfg:

<!-- YOUR Configuration.sumocfg -->
<?xml version="1.0" encoding="UTF-8"?>
<configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://sumo.dlr.de/xsd/sumoConfiguration.xsd">

    <!-- ... -->

    <!-- INSERT THIS TO LOAD ADDITIONAL FILE tls_logging.add.xml -->
    <input>
		<additional-files value="tls_logging.add.xml"/>
    </input>

    <!-- ... -->

</configuration>

And create the additional file tls_logging.add.xml in the same folder:

<?xml version="1.0" encoding="UTF-8"?>
<additional>
    <timedEvent type="SaveTLSStates"
                dest="simulation_logs/signal_states.xml"/>
</additional>

(3) (Optional) Additional Objects (Fences, Trees, Buildings...):

You can create polygon files (POIs) with Netedit, and store them, for example following trees.add.xml:

<additional xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://sumo.dlr.de/xsd/additional_file.xsd">
    <!-- Shapes -->
    <poi id="poi_0" color="red" layer="202.00" x="19332.99" y="17853.26"/>
    <poi id="poi_1" color="red" layer="202.00" x="19398.22" y="17894.70"/>
    <poi id="poi_10" color="red" layer="202.00" x="19412.72" y="17919.65"/>
    <poi id="poi_100" color="red" layer="202.00" x="18935.17" y="17729.96"/>
    <poi id="poi_1000" color="red" layer="202.00" x="20139.72" y="18631.08"/>
    <poi id="poi_1001" color="red" layer="202.00" x="20154.28" y="18637.80"/>
    <poi id="poi_1002" color="red" layer="202.00" x="20205.22" y="18645.08"/>
    <poi id="poi_1003" color="red" layer="202.00" x="20209.14" y="18647.88"/>
    <!-- ... -->

The simulation's input files (network, POIs), and the generated output log files are then processed by sumo3Dviz to generate the visualisation.

Step 2: Prepare Visualisation Configuration

You can configure various aspects, such as textures, position of buildings, fences, trees, etc. in the configuration YAML file. Furthermore, the configuration contains possible settings for all modes, related to camera configurations. An exemplary structure for such a configuration can be found in examples/config_barcelona.yaml.

Step 3: Render Video Visualisation with sumo3Dviz

Command Line Interface (CLI)

This is one example how you can run sumo3Dviz with a CLI one line in your terminal:

sumo3Dviz --config examples/config_barcelona.yaml --mode eulerian --output examples/barcelona_simulation_eulerian.avi

Python Code

In this repository we provide four example codes to run sumo3Dviz in the four different modes as a Python script, that can be found in .examples/. These examples visualize the aforementioned case study of Barcelona.

1. Run sumo3Dviz in Eulerian mode:

python examples/demo_eulerian.py

2. Run sumo3Dviz in Lagrangian mode:

python examples/demo_lagrangian.py

3. Run sumo3Dviz in Cinematic mode:

python examples/demo_cinematic.py

4. Run sumo3Dviz in Interactive mode:

python examples/demo_interactive.py

Citations

Please cite our paper if you find sumo3Dviz useful:

@misc{riehl2026sumo3dviz,
      title={sumo3Dviz: A three dimensional traffic visualisation},
      author={Kevin Riehl and Julius Schlapbach and Anastasios Kouvelas and Michail A. Makridis},
      year={2026},
      eprint={2604.19194},
      archivePrefix={arXiv},
      primaryClass={cs.GR},
      doi={10.48550/arXiv.2604.19194},
      url={https://arxiv.org/abs/2604.19194},
}