Metadata-Version: 2.4
Name: sumo3Dviz
Version: 0.4.2
Summary: 3D visualization of SUMO traffic simulations
Author-email: Kevin Riehl <kriehl@ethz.ch>, Julius Schlapbach <juliussc@ethz.ch>
Project-URL: Homepage, https://github.com/DerKevinRiehl/sumo3Dviz
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy==1.24.4
Requires-Dist: opencv-python==4.9.0.80
Requires-Dist: pandas==2.1.1
Requires-Dist: panda3d==1.10.15
Requires-Dist: sumolib==1.25.0
Requires-Dist: PyYAML==6.0.3
Requires-Dist: pandera==0.26.1
Requires-Dist: jsonschema==4.25.1
Requires-Dist: tqdm==4.67.3
Requires-Dist: scipy==1.13.1
Provides-Extra: dev
Requires-Dist: pytest<9.0.0,>=8.0.0; extra == "dev"
Requires-Dist: pylint<4.0.0,>=3.0.0; extra == "dev"
Requires-Dist: git-cliff<3.0.0,>=2.11.0; extra == "dev"
Dynamic: license-file

<h1>
    <center>
    <table width="100%">
        <tr>
            <td align="center">
                <img src="resources/Figure_Banner.PNG"
                    alt="sumo3Dviz"
                    style="height: 3.5em; vertical-align: middle; margin-right: 0.4em;">
                sumo3Dviz <img src="resources/Figure_Banner.PNG"
                    alt="sumo3Dviz"
                    style="height: 3.5em; vertical-align: middle; margin-left: 0.4em;">
            </td>
        </tr>
        <tr>
            <td align="center">
                A three dimensional traffic visualisation
            </td>
        </tr>
    </table>
    </center>
</h1>

[![PyPI version](https://img.shields.io/pypi/v/sumo3Dviz)](https://pypi.org/project/sumo3Dviz/)
[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
[![Build](https://github.com/DerKevinRiehl/sumo3Dviz/actions/workflows/build.yml/badge.svg)](https://github.com/DerKevinRiehl/sumo3Dviz/actions/workflows/build.yml)
[![CLI](https://github.com/DerKevinRiehl/sumo3Dviz/actions/workflows/test_rendering.yml/badge.svg)](https://github.com/DerKevinRiehl/sumo3Dviz/actions/workflows/test_rendering.yml)

**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.

<table>
    <tr>
        <td><b>Features:</b></td>
        <td><img src="resources/Figure_OSLogo.png" style="height: 2.5em"/></td>
        <td>Major OS Support</td>
        <td><img src="resources/Figure_PythonLogo.png" style="height: 2.5em"/></td>
        <td>Python 3.9 Support</td>
    </tr>
</table>

<details>
<summary><strong>Table of Contents</strong></summary>

- [Highlights](#highlights)
- [Installation](#installation)
- [Usage](#usage)
  - [Command Line Interface (CLI)](#command-line-interface-cli)
  - [Python Code](#python-code)
- [Case Study: Barcelona](#case-study-barcelona)
  - [Step 1: Prepare Sumo Simulation](#step-1-prepare-sumo-simulation)
  - [Step 2: Prepare Visualisation Configuration](#step-2-prepare-visualisation-configuration)
  - [Step 3: Render Video Visualisation with sumo3Dviz](#step-3-render-video-visualisation-with-sumo3dviz)
- [Citations](#citations)
</details>

## Highlights

<table>
    <tr>
        <td colspan="4"><b><center>Visualisation Modes</center></b></td>
    </tr>
    <tr>
        <td><center>(1) Eulerian</center></td>
        <td><center>(2) Lagrangian</center></td>
        <td><center>(3) Cinematic</center></td>
        <td><center>(4) Interactive</center></td>
    </tr>
    <tr>
        <td><img src="resources/Figure_DemoVis_Euler.png" style="height: 120px"/></td>
        <td><img src="resources/Figure_DemoVis_Lagrang.png" style="height: 120px"/></td>
        <td><img src="resources/Figure_DemoVis_Cinematic.png" style="height: 120px"/></td>
        <td><img src="resources/Figure_DemoVis_Interactive.png" style="height: 120px"/></td>
    </tr>
    <tr>
        <td><img src="resources/video_eulerian.gif" style="height: 120px"/></td>
        <td><img src="resources/video_lagrangian.gif" style="height: 120px"/></td>
        <td><img src="resources/video_cinematic.gif" style="height: 120px"/></td>
        <td><img src="resources/video_interactive.gif" style="height: 120px"/></td>
    </tr>
</table>

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:

```bash
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`:**

```xml
<!-- 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`:**

```xml
<!-- 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
<?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`:

```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:
```bash
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:

```
@inproceedings{riehl2026sumo3Dviz,
  title={sumo3Dviz: A three dimensional traffic visualisation},
  author={Riehl, Kevin and Schlapbach, Julius and Kouvelas, Anastasios and Makridis, Michail A.},
  booktitle={SUMO Conference Proceedings},
  year={2026}
}
```
