Travia: a TRAffic VIsualization and Annotation tool

In recent years many open datasets have been published that contain vehicle trajectories of human drivers on public roads. Such datasets can be useful for all kinds of research targeting traffic, e.g. traffic-flow studies and the development of autonomous vehicles. These datasets contain very large amounts of valuable data, however, they often focus on collecting data in one country and one situation, e.g. highway traffic in Germany. To broaden the scope of a research project, it can be valuable to include data from different datasets. This is often difficult because traffic data comes in *.csv files, often without a way to visualize and annotate the data for a quick start of your project. This is why Travia was created to combine the potential of different datasets by bringing them together in one tool for visualization and annotation.

Datasets from four different projects can currently be visualized using Travia. The NGSIM project collected data using cameras on tall buildings next to roads in the USA. The PNeuma project captured all traffic during the morning rush hour in the business district of Athens, for 5 days. To maximize precision and coverage this was done using drones. Finally, the HighD and ExiD projects also used drones to record traffic at different locations on German highways.

TraViA was built as a broad basis for visualization and manual annotation, it can easily be extended to incorporate the specific needs of your research project. Three examples of such specific implementations are included in Travia to illustrate the possibilities and provide a starting point for other developers. The first example considers automatically detecting and annotating specific situations in the HighD datasets. The second example is the plotting of heatmap overlays, to aid with the design of reward functions for autonomous driving. Finally, it includes an example of plotting vehicle signals on an annotated selection of data.

Travia was tested with Python 3.12 on Windows and Ubuntu.

Installation

To install TraViA, simply clone the repository and install all requirements from the requirements.txt file using pip (run pip install -r requirements.txt in the terminal from the travia folder). That's all!

To use TraViA, you'll need some traffic data, this data is not included in the repository. Follow the steps below to get started and test if TraViA is functioning properly.

Getting started, visualize data in 3 steps

To get started, you only need to execute the next 3 steps.

1. acquire data
2. extract in the correct folder
3. run

Acquire data

The data to visualize is not included in Travia, you need to acquire the data and a valid license to use it yourself. All implemented datasets are free for use for scientific purposes. In this example we will acquire the NGSim data set, but if you already have a copy of one of the supported datasets you can skip this step. To acquire a copy of NGSim data, open a browser and navigate to this page. Scroll down to find the attachments section under "about this dataset". Locate the attachment called "US-101-LosAngeles-CA.zip" and click it to start the download. This contains data recorded on the US-101 highway.

Extract in the right folder

To use the data, it has to be placed in the travia/data folder to be found automatically when loading the dataset. The data folder has three sub-folders, one for each data source. For our example, we need the NGSim sub-folder, but if you have data from another project please see the README.txt file in the corresponding sub-folder for instructions. For now, navigate to your freshly downloaded data and extract the contents of US-101-LosAngeles-CA.zip to travia/data/NGSim. This should create a new folder, travia/data/NGSim/US-101-LosAngeles-CA, which contains more zip files. Extract the contents of aerial-ortho-photos.zip and vehicle-trajectory-data.zip to this folder. This will create more sub-folders, a representation of the correct end-result can be found in the README.txt file located in travia/data/NGSim, please verify that your folder structure is correct.

Run

Now you're ready to run visualize.py, this is the main run script in TraViA. A dialog will show asking you to select which dataset you want to load, please select the NGSim dataset that you just downloaded. After this, the data will be loaded from the *.csv file and converted into a dataset object. Loading a new NGSim dataset for the first time will take a while since the data will be smoothed first. This is done to calculate headings for all vehicles because these are not included in the dataset. For more information, check out the section on "Particularities with the data". This smoothing is also needed for PNeuma datasets.

Once done, the TraViA user interface should be displayed. A screenshot of how it should look can be found below. This screenshot shows a portion of the HighD dataset, so don't worry if the traffic looks different. To verify TraViA is working correctly, a video is included with the repository (./paper/image/US101_0805_0820.mp4). You can compare the visualization of the NGSim data from the example with this video to verify TraViA is working correctly.

How to use TraViA

TraViA was built with two use cases in mind, the first being to provide a quick visualization and annotation opportunity for researchers working with open traffic data. For this use case, all interaction between the user and TraViA can take place in the GUI. An example of such use would be a researcher that performed numerical analysis on the data from the HighD dataset in a custom-made script. If this analysis shows something happening at frame x for vehicle y that is hard to explain numerically, TraViA can be used to a) investigate what is happening in a visualization and b) annotate this event for future use. For such use, the user interface of TraViA is explained below in the subsection user interface.

The second potential use-case is for researchers to extend TraViA for their use, for example, to visualise other (closed access) datasets or to implement Autonomous vehicle controllers that operate in the traffic data environment. To aid in this use case, a high-level overview of the architecture of TraViA is provided in the subsection High-Level Software Architecture.

TraViA was not designed to be imported as a module or library for use in other software projects. For that reason, TraViA has no setup.py file, is not available on PyPi and there is no API provided for software interfacing with TraViA.

User Interface

The Travia user interface consists of four parts (see the figure above for more information). From top to bottom, you'll see a vehicle information pane, displaying all data of the selected vehicle, a view of the road and traffic, the annotation overview and controls, and finally the timeline controls.

The traffic view can be panned by dragging with the mouse, zoomed by using the scroll wheel, and rotated using the knob on the top left. To display information on a single vehicle you can select it by clicking it. The same holds for annotations, they are represented by bars just above the timeline. By clicking a bar, the annotation is selected and its information is displayed. It is not possible to selected multiple annotations or vehicles at once.

The "start annotation" button will open a new annotation that starts at the current frame. After this, it is possible to edit the start and end frames, ego vehicle ID (the vehicle of interest), and add a note. The "stop annotation" button will then save the annotation.

The time can be controlled by using the play/pause button in the lower part of the interface. The time can be fast-forwarded using the >> button and reversed with the << button. The > and < buttons will execute a single frame step. The rec button will start a video recording of the visualization, this recording can be stopped by clicking the pause button and will then be exported to the user's video folder. A single frame can be saved as an image through the view menu. The buttons "Create Plots" and "Create Heatmap" are used for example function and only work with HighD datasets. Please see the section HighD example tools below for more information.

High-Level Software Architecture

There are three main objects in TraViA used for visualizing the data, a conceptual UML class diagram can be found in the figure above. The highest level object is the Graphical User Interface (GUI). This inherits from the Qt QMainWindow object and handles all user interaction. The state of the GUI is periodically updated by a visualizationMaster object. This is the object that translates the specific format of the dataset to store the data for every vehicle in a generic vehicle object. This way of working ensures that the dataset itself is used in its original format such that all original documentation can be used and other scripts based on that documentation will still work. But TraViA uses the same generic Vehicle object for all datasets such that tools developed in TraViA can easily be used on multiple datasets.

The visualization ma