io.rtron:rtron-math

a road space model transformer library for OpenDRIVE, CityGML and beyond
View Demos · Report Bug · Request Feature

r:trån reads road network models in OpenDRIVE and transforms them to the virtual 3D city model standard CityGML.

This enables you to

• inspect your spatio-semantic road space models
• conduct further model transformations with tools like FME
• perform geospatial analyses on the 3D City Database
• deploy virtual globes
• load your models into a desktop GIS
• compare and validate your models with models from other data sources

:inbox_tray: Datasets

Download some sample OpenDRIVE datasets of the city of Ingolstadt from the company 3D Mapping Solutions (initial registration required). Additionally, awesome-openx provides a list of further OpenDRIVE datasets.

:rocket: Usage

There are three main variants of usage:

• edit the behaviour and execute the run scripts
• deploy the resulting run scripts (via kscript directly or docker)
• use r:trån as a library for your own project

:gear: Edit and execute the run scripts

Clone the repository:

git clone https://github.com/tum-gis/rtron.git

Actually, you can customize the run scripts of r:trån with all editors, but an IDE provides convenient suggestions and autocompletion. Thus, install the community edition of IntelliJ and open the cloned r:trån project. Navigate to the script rtron-main/src/main/resources/scripts/convert-opendrive-to-citygml2-simple.kts and execute it by hitting Menu ➔ Run ➔ Run… (or Alt+Shift+F10):

import io.rtron.main.project.processAllFiles
import io.rtron.readerwriter.citygml.CitygmlVersion

/**
 * This function iterates over all files contained in the input directory that have the
 * extension "xodr".
 */
processAllFiles(
    inInputDirectory = "/path/to/input-datasets", // TODO: adjust path
    withExtension = "xodr",
    toOutputDirectory = "/path/to/output-datasets" // TODO: adjust path
)
{
    // Within this block the transformations can be defined by the user. For example:

    // 1. Read the OpenDRIVE dataset into memory:
    val opendriveModel = readOpendriveModel(inputFilePath)

    // 2. Transform the OpenDRIVE model to an intermediary representation (the RoadSpaces model):
    val roadspacesModel = transformOpendrive2Roadspaces(opendriveModel) {
        // Within this blocks, the transformation is parametrized:

        // EPSG code of the coordinate reference system (needed by GIS applications)
        crsEpsg = 32632
    }

    // 3. Transform the RoadSpaces model to a CityGML model:
    val citygmlModel = transformRoadspaces2Citygml(roadspacesModel) {
        // true, if nested attribute lists shall be flattened out
        flattenGenericAttributeSets = true

        // distance between each discretization step for curves and surfaces
        discretizationStepSize = 0.5
    }

    // 4. Write the CityGML model to the output directory:
    writeCitygmlModel(citygmlModel) {

        // set the CityGML versions for writing
        versions = setOf(CitygmlVersion.V2_0)
    }
}

After the execution is completed, the directory /path/to/output-datasets should contain the converted CityGML2 datasets. For more details, visit the website.

:package: Deploy the run scripts via kscript

In order to run the r:trån scripts in deployment environments, kscript needs to be installed. kscript provides enhanced scripting support for Kotlin and is capable of executing the *.kts scripts contained in this directory.

sdkman is a tool for managing software development kits and conveniently installs kotlin and kscript:

curl -s "https://get.sdkman.io" | bash     # install sdkman
source "$HOME/.sdkman/bin/sdkman-init.sh"  # add sdkman to PATH

sdk install java # install java
sdk install kotlin # install Kotlin
sdk install kscript # install kscript

If you are on Windows, the deployment via docker is recommended.

Once the environment is ready, the r:trån scripts can be executed:

# download the script ...
curl https://raw.githubusercontent.com/tum-gis/rtron/main/rtron-main/src/main/resources/scripts/convert-opendrive-to-citygml2-simple.kts \ 
    --output convert-opendrive-to-citygml2-simple.kts

# and simply execute it (dependencies are resolved automatically)
kscript ./convert-opendrive-to-citygml2-simple.kts

:whale: Deploy the run scripts via docker

With a docker installation, the run scripts can be executed using the r:trån container. First, download the example script:

curl https://raw.githubusercontent.com/tum-gis/rtron/main/rtron-main/src/main/resources/scripts/convert-opendrive-to-citygml2-simple.kts \
    --output convert-opendrive-to-citygml2-simple.kts

Then, adapt /adjust/path/... to your host system's paths and run the execution:

docker run -i --name rtron --rm \
           -v /adjust/path/to/input-datasets:/project/input \
           -v /adjust/path/to/output-datasets:/project/output \
           rtron/rtron - < /adjust/path/to/convert-opendrive-to-citygml2-simple.kts

Also note that the script must now reference paths in the container file system (/project/input, /project/output).

To cancel the process, run this command in another terminal:

docker rm -f rtron

:recycle: Use r:trån as library (experimental)

r:trån is a collection of software components for spatio-semantic road space models, as described in the architecture. To use its functionality in another Kotlin or Java project, add the dependency to the respective component using Gradle:

dependencies {
  implementation("io.rtron:rtron-main:1.2.2")
  implementation("io.rtron:rtron-readerwriter:1.2.2")
}

To add a dependency using Maven:

<dependency>
    <groupId>io.rtron</groupId>
    <artifactId>rtron-main</artifactId>
    <version>1.2.2</version>
</dependency>

:hammer_and_wrench: Contributing

r:trån was developed so that everyone can benefit from spatio-semantic road space models. Therefore, bug fixes, issue reports and contributions are greatly appreciated.

:mortar_board: Research

If you are interested in the concepts and a first application of r:trån, have a look at our paper. Based on the consistent models now available in OpenDRIVE and CityGML, we generate several target formats for setting up a distributed environment simulation.

@article{SchwabBeilKolbe2020,
  title = {Spatio-Semantic Road Space Modeling for Vehicle{\textendash}Pedestrian Simulation to Test Automated Driving Systems},
  author = {Benedikt Schwab and Christof Beil and Thomas H. Kolbe},
  journal = {Sustainability},
  year = {2020},
  month = may,
  volume = {12},
  number = {9},
  pages = {3799},
  publisher = {MDPI},
  doi = {10.3390/su12093799},
  url = {https://doi.org/10.3390/su12093799}
}

Moreover, these papers may also be of interest:

• Detailed Streetspace Modelling for Multiple Applications: Discussions on the Proposed CityGML 3.0 Transportation Model
• Requirement Analysis of 3D Road Space Models for Automated Driving
• CityGML and the streets of New York - A proposal for detailed street space modelling

:memo: License

r:trån is distributed under the Apache License 2.0. See LICENSE for more information.

:handshake: Thanks

• AUDI AG for providing an awesome work environment within SAVe:
• Prof. Thomas H. Kolbe, Bruno Willenborg and Christof Beil for support and feedback
• Claus Nagel for citygml4j
• JetBrains for Kotlin and their top-notch IDEs