sumo3Dviz: Python 3D Traffic Visualization

• sumo3Dviz is a lightweight, open-source Python pipeline that transforms standard SUMO simulation files into rendered 3D traffic scenes.
• It employs advanced trajectory interpolation, orientation smoothing, and re-estimation methods to convert low-frequency output into smooth, continuous animations.
• The tool supports multiple rendering modes—including external, ego-centric, cinematic, and interactive views—for reproducible, automated visual communication and research.

sumo3Dviz is a lightweight, open-source, Python-based 3D visualisation pipeline for SUMO traffic simulations that directly converts standard SUMO inputs and outputs into rendered 3D traffic scenes and videos (Riehl et al., 21 Apr 2026). It is positioned between abstract 2D inspection tools such as SUMO-GUI and heavyweight Unity, Unreal, CARLA, or proprietary environments. Its stated purpose is to support applications in which microsimulation results must be interpreted from a human perspective, communicated to stakeholders, or embedded in reproducible large-scale visualisation workflows rather than used only for conventional technical analysis.

1. Motivation and conceptual niche

The development of sumo3Dviz is motivated by a specific limitation in the SUMO ecosystem: while traffic microsimulation generates rich spatio-temporal data describing trajectories, speeds, interactions, and signal states, numerical outputs and 2D visualisations are often inadequate for human interpretation, perceptual evaluation, and communication. The paper identifies this gap most explicitly in settings such as human-centred evaluation, mobility psychology and acceptance studies, virtual-experience stated-preference experiments, educational demonstrations, communication to stakeholders and decision-makers, and automated experiment and video-generation pipelines (Riehl et al., 21 Apr 2026).

The central claim is not that SUMO lacks analytical capability, but that top-down 2D renderings do not reflect how traffic is perceived from a human point of view. This is especially consequential when the visual stimulus itself is part of the scientific task, for example in studies of comfort, trust, perceived safety, or acceptance. In that context, sumo3Dviz is presented as a means of obtaining depth cues, street-level context, and ego-centric perspectives without requiring a game engine or co-simulation stack.

A common misconception would be to treat sumo3Dviz as a photorealistic simulator or as a replacement for autonomous-driving platforms. The paper instead defines it as a practical middle layer: richer and more perspective-aware than SUMO-GUI, but lighter, more scriptable, and more reproducible than Unity-, Unreal-, or CARLA-based workflows. This suggests that its contribution is primarily infrastructural and methodological rather than photorealistic.

2. Inputs, preprocessing, and scene construction

sumo3Dviz consumes standard SUMO files after simulation rather than modifying the simulation engine or coupling to SUMO internals. The main inputs are SUMO network and configuration files, optional polygon/POI files, a vehicle trajectory file containing time-stamped positions and headings, and optionally signal-state logs. The paper emphasizes that these are standard SUMO outputs obtainable with minor configuration changes and that no extra instrumentation or custom post-processing is required before the tool reads them (Riehl et al., 21 Apr 2026).

The preprocessing stage transforms raw, discrete simulation records into renderable scene data. Static elements such as roads, buildings, trees, fences, and other context objects are loaded once and remain fixed during rendering. Vehicle trajectories are parsed and transformed from low-temporal-resolution simulation samples into high-temporal-resolution continuous motion suitable for video. Signal logs, when present, animate traffic light states over time. The principal methodological element in this stage is the trajectory interpolation and orientation smoothing pipeline discussed below.

The 3D scene graph includes a camera, light source, sky as a textured sphere, ground as a textured floor, a road network generated from the SUMO network file, static objects such as trees, fences, traffic lights, homes, shops, and buildings, and moving vehicles, including ego and non-ego vehicles. Road rendering is implemented in three layers: a base ground layer, a road polygon layer, and road and lane demarcation lines on top. Geometrically, each SUMO road path is composed of multiple edges; each edge segment is rendered as a rectangle, adjacent segments are connected with triangular polygons, and at intersections the SUMO intersection polygon is used directly.

Static objects are positioned via SUMO polygon/POI files and can be edited using netedit. The paper presents this as a lightweight mechanism for injecting environmental context without full manual 3D world building. Vehicles are rendered using a set of ten car models, with each vehicle in the SUMO trajectory log randomly assigned one of these models. Traffic lights support time-dependent signal states from SUMO logs and are available in three designs: two-head red/green, three-head red/yellow/green, where yellow is interpolated automatically around green-to-red transitions, and countdown timer.

3. Rendering modes and perceptual viewpoints

The rendering stage produces single images or video sequences, with the primary emphasis on rendered video. The pipeline is explicitly optimized for batch processing, headless execution, and integration in automated workflows. The paper states that the rendering quality is intended to be visually coherent and useful for perception-oriented applications, but not photorealistic in the game-engine sense (Riehl et al., 21 Apr 2026).

sumo3Dviz supports four rendering modes. In Eulerian mode, the camera is fixed externally, yielding overview or surveillance-like views of a traffic location. In Lagrangian mode, the camera is attached to a specific vehicle, producing the ego-centric or first-person-style perspective that the paper associates with driver-level or vehicle-following experiences. In Cinematic mode, the camera follows a predefined 3D trajectory, enabling fly-throughs and controlled cinematic viewpoints. In Interactive mode, users navigate a static scene using keyboard controls, with dynamic objects disabled.

The distinction between external views and first-person or ego-centric views is one of the tool’s defining features. Eulerian and Cinematic modes provide broad overviews suitable for communication, demonstration, or narrative framing, whereas Lagrangian mode is intended for user-perspective experiences relevant to virtual-experience stated-preference experiments and other human-centred evaluations. Interactive mode serves exploratory inspection of the environment rather than animated traffic playback.

This division of viewpoints clarifies the intended scope of the system. sumo3Dviz is not restricted to diagnostic rendering of network states; it is also designed to produce stimuli that approximate how scenes are perceived from within the traffic environment. A plausible implication is that the same simulation output can be repurposed for both technical inspection and perceptual experimentation without changing the underlying simulation model.

4. Trajectory interpolation and orientation smoothing

The paper’s most detailed technical contribution is the processing of coarse SUMO trajectories into visually coherent frame-by-frame animation (Riehl et al., 21 Apr 2026). SUMO outputs may be sampled at relatively low temporal resolution, such as $1\ \mathrm{Hz}$, whereas video generation requires much finer sampling, for example $25\ \mathrm{Hz}$. Naïve interpolation would produce unnatural motion and heading discontinuities, especially at the $0^\circ/360^\circ$ boundary.

For vehicle $i$, at simulation steps $k \in \{0,1,\dots,K\}$, the discrete trajectory is defined as

$$\mathbf{X}_k^i = \begin{pmatrix} x_k^i \ y_k^i \ \alpha_k^i \end{pmatrix},$$

where $x_k^i$ and $y_k^i$ are 2D coordinates and $\alpha_k^i \in [0^\circ,360^\circ)$ is the orientation angle. The rendering step size is

$\Delta t = 1/\mathrm{FPS}.$

The first stage is angle unwrapping,

$25\ \mathrm{Hz}$0

which removes artificial $25\ \mathrm{Hz}$1 jumps in the orientation signal. The second stage is linear interpolation between adjacent coarse samples: $25\ \mathrm{Hz}$2 This produces continuous but piecewise-linear motion.

The third stage applies a centred moving average: $25\ \mathrm{Hz}$3 Here $25\ \mathrm{Hz}$4 is the centered smoothing window around frame $25\ \mathrm{Hz}$5, $25\ \mathrm{Hz}$6 is its cardinality, and $25\ \mathrm{Hz}$7 is the smoothing window size. The paper reports that $25\ \mathrm{Hz}$8 works well for $25\ \mathrm{Hz}$9 rendering.

Orientation is then re-estimated from local motion increments rather than taken directly from the tangent of the smoothed path. The positional increments are

$0^\circ/360^\circ$0

with step distance

$0^\circ/360^\circ$1

If motion is sufficiently large, heading is estimated by

$0^\circ/360^\circ$2

If $0^\circ/360^\circ$3, the motion direction is trusted; if $0^\circ/360^\circ$4, the orientation is retained from the smoothed interpolated signal to avoid numerical noise when the vehicle barely moves. A second centred moving average then smooths the estimated orientation: $0^\circ/360^\circ$5

The paper reports the empirical values $0^\circ/360^\circ$6 and $0^\circ/360^\circ$7. The notation $0^\circ/360^\circ$8 appears dimensionally unusual for a window size; this suggests an apparent inconsistency or typographical issue in the text, but the stated value remains part of the paper’s specification. The final rendered state is

$0^\circ/360^\circ$9

In substantive terms, the method combines interpolation to rendering rate, smoothing of position, velocity-informed re-estimation of heading, and additional heading smoothing in order to reduce visually distracting orientation artifacts.

5. Operation, configuration, and reproducibility

sumo3Dviz supports both non-programmatic and programmatic use. Its operation is centered on YAML configuration files specifying input paths, rendering modes, camera parameters, visual styles, and output settings. The paper presents this YAML-first design as a major mechanism for reproducibility, because a rendering can be regenerated from the same configuration and the same SUMO outputs (Riehl et al., 21 Apr 2026).

Basic usage is available through a command-line interface, allowing visualisation generation without writing code. For advanced scenarios, the package can be imported as a Python module and extended programmatically, with options passed as function parameters. The paper does not document the API in detail, but it explicitly notes that module-based components can be used in custom scripts.

Practical accessibility is treated as part of the contribution. The tool is installable via pip in a standard Python environment, supports Windows, macOS, and Linux distributions, and works independently of proprietary software or licenses. Source code, materials, examples, and documentation are hosted on GitHub, and the package is also available on PyPI. The paper explicitly provides the repository https://github.com/DerKevinRiehl/sumo3dviz/ and the package page https://pypi.org/project/sumo3Dviz/.

The system also exposes a configurable visual layer. Users can set sky textures, ground textures, road colours and widths, static object appearance, vehicle models, camera settings, time interval, frame rate, image resolution, and output settings. Listed sky textures include sky_blue, sky_daycloud1, sky_daycloud2, sky_daycloud3, sky_night1, sky_night2, sky_night3, and sky_halloween. Ground textures include ground_grass, ground_stone, ground_sand, ground_chess, ground_chesslarge, and ground_halloween. Supported static-object categories include trees, freeway fences, traffic lights, shops, homes, and building blocks.

These design choices collectively define the reproducibility model of sumo3Dviz. Rather than relying on manual scene assembly in a game engine, it encodes rendering choices in configuration files and scriptable execution paths. This suggests a closer fit to automated experiment pipelines and large-scale scenario visualisation than to artisanal scene authoring.

6. Comparative position, demonstration, and limitations

The paper situates sumo3Dviz against several categories of alternatives (Riehl et al., 21 Apr 2026). Relative to SUMO-GUI and similar 2D lightweight tools, its claimed advantage is the addition of 3D, external and ego views, and richer context while preserving lightweight scripting and open-source accessibility. Relative to dedicated 3D SUMO renderers such as AURELION, SUMO3D, Traffic3D, and Sumonity, the paper argues that existing tools often involve higher setup complexity, specialized environments, poor documentation, limited maintainability, lack of maintained scripting interfaces, or less emphasis on reproducible pipelines. Relative to Unity- and Unreal-based pipelines such as Sumo2Unity and Sumo2Unreal, the trade-off is explicit: more modest realism in exchange for lighter deployment, simpler automation, and operation without proprietary dependence. Relative to CARLA plus SUMO co-simulation, the distinction is that CARLA is highly realistic and sensor-rich but computationally intensive and excessive for many traffic visualisation tasks. Relative to VISSIM and AIMSUN, the contrast concerns closed, licensed ecosystems versus open-source scripted workflows.

The paper’s core positioning statement is that there was no open-source, platform-independent, pip-installable Python tool directly consuming SUMO outputs and producing lightweight 3D renderings optimized for scripting and batch video generation. In that sense, sumo3Dviz is defined less by maximal realism than by a particular balance of openness, portability, scriptability, and support for both external and ego-centric visualisation.

The demonstration case study uses a SUMO microsimulation of the Ronda de Dalt metropolitan highway in Barcelona. The scenario is approximately $i$0, has three lanes per direction, five on- and off-ramps, and one hour of peak traffic simulation, with static context added via POIs/polygons and standard SUMO vehicle position logging and signal-state logging. The case study demonstrates all four rendering modes: fixed external overview, vehicle-following ego-centric view, cinematic fly-through, and interactive static-scene navigation.

The reported performance figures are an initial loading time of around $i$1 and rendering time between $i$2 per frame on a conventional state-of-the-art laptop. As stated, the “per frame” figure is extremely slow; this suggests either a typographical issue or a particularly expensive rendering setup, but no systematic benchmark table or scaling study is provided in the paper.

Several limitations are explicit or readily implied by the text. The system is not aiming for full game-engine-level realism and does not focus on advanced photorealism, VR, or sensor simulation. Interactive mode disables dynamic objects. Scene realism depends on manually supplied POIs/polygon files for context. Vehicle models are randomly assigned rather than matched to exact SUMO vehicle classes in the described text. No extensive quantitative benchmark or user-study validation is included, no detailed API or package-structure specification is provided, and the orientation-smoothing notation contains at least one apparent inconsistency. Taken together, these limitations clarify the intended domain: sumo3Dviz is a practical infrastructure contribution for human-centred traffic visualisation, communication, and automated research workflows, not a full replacement for immersive game-engine ecosystems or autonomous-driving simulators.