DeepScenario Toolkit

A Python toolkit for visualizing and working with DeepScenario datasets, which can be downloaded at app.deepscenario.com.

Overview

DeepScenario provides a platform to virtualize real-world recordings into:

• a 3D reconstruction of the static environment
• 3D trajectories of the dynamic objects

This toolkit provides easy-to-use tools for visualizing and working with DeepScenario datasets, including:

• visualization of the object annotations in 3D or in OpenStreetMap
• creation of an orthophoto from the 3D reconstruction

Installation

From PyPI (Recommended)

pip install dsc-toolkit

From Source (Development)

This project uses uv for dependency management. Make sure you have uv installed first.

# Clone the repository
git clone https://github.com/deepscenario/dsc-toolkit.git
cd dsc-toolkit

# Install the package and dependencies
uv sync

Quick Start

The toolkit provides a command-line tool with several commands. Each command has detailed help available using the --help option, for example:

dsc-toolkit plot_annotations_3d --help

plot_annotations_3d

Interactive 3D visualization of the object annotations:

dsc-toolkit plot_annotations_3d \
	--data_dir tests/assets/data \
	--recording 2000-12-31T23-59-59 \
	--mesh tests/assets/data/textured_mesh/textured_mesh.obj

plot_annotations_georeferenced

Interactive visualization of the object annotations in OpenStreetMap:

dsc-toolkit plot_annotations_georeferenced \
	--data_dir tests/assets/data \
	--recording 2000-12-31T23-59-59 \
	--save_dir /tmp/output

render_orthophoto

Render a georeferenced orthophoto from the textured mesh:

dsc-toolkit render_orthophoto \
	--data_dir tests/assets/data \
	--mesh tests/assets/data/textured_mesh/textured_mesh.obj \
	--save_dir /tmp/output

OpenDRIVE Map Visualization

To visualize an OpenDRIVE map in plot_annotations_3d, you need to first convert it to OBJ format. Choose one of the following methods:

Method 1: Online Conversion

1. Navigate to odrviewer.io
2. In "Parse Options", disable "Center Map"
3. Click "Open .xodr" and select your OpenDRIVE file
4. Click "Export .obj" to download the converted file

Method 2: Offline Conversion

This method relies on esmini and OpenSceneGraph:

Prerequisites

# Install OpenSceneGraph
sudo apt install openscenegraph

# Download and set up esmini
wget https://github.com/esmini/esmini/releases/latest/download/esmini-demo_ubuntu-latest.zip
unzip esmini-demo_ubuntu-latest.zip
export PATH=$PATH:$(pwd)/esmini/bin

Conversion Steps

1. Generate OpenSceneGraph model from your OpenDRIVE file:

   odrviewer --odr map.xodr --save_generated_model --headless --duration 0 --disable_log --disable_stdout

2. Convert to OBJ format:

   osgconv generated_road.osgb map.obj --use-world-frame

The resulting map.obj file can now be used with plot_annotations_3d.

License

This project is licensed under the Apache License 2.0. See LICENSE.txt for details.

Support

For questions, issues, or contributions, please:

• open an issue in this repository
• contact DeepScenario at info@deepscenario.com