esmini is a basic OpenSCENARIO player
It contains the following main libraries:
- RoadManager (esminiRMLib). A library providing an interface to road networks described in the OpenDRIVE format.
- ScenarioEngine (esminiLib). The main library providing a viewer and API interface to traffic scenarios described in the OpenSCENARIO format. This library includes RoadManager.
and a few applications that can be used as is or provide ideas for customized solutions:
- esmini. A scenario player application linking esmini modules statically.
- esmini-dyn. A minimalistic example using the esminiLib to play OpenSCENARIO files.
- odrplot. Produces a data file from OpenDRIVE for plotting the road network in Python.
- odrviewer. Visualize OpenDRIVE road network with populated dummy traffic.
- replayer. Re-play previously executed scenarios.
- osireceiver. A simple application receiving OSI messages from esmini over UDP.
Repository: https://github.com/esmini/esmini
Pre-built demo packages are available here. Unzip, navigate to "esmini\run\esmini" and run any of the example scripts. See more info below under "Binaries and demos".
esmini supports OpenSCENARIO v1.1 (from esmini v2.7) and v1.0 (from esmini v1.5). In order to run older versions (i.e. v0.9.1) ASAM provides a transformation scheme (migration0_9_1to1_0.xslt, part of the OpenSCENARIO release bundle) that can be used with tools for automatic migration of XML files.
Please note that the OpenSCENARIO coverage is limited, which means that not all features of OpenSCENARIO are supported. The functionalty grows slow but steady, based on need and contributions.
The code was initially a result from the Swedish collaborative research project Simulation Scenarios, and is now further developed based on users need and OpenSCENARIO development.
For more information about the esmini software parts, please see Inner Workings of esmini.
The purpose of this implementation was to explore and get familiar with the emerging OpenSCENARIO data format. The development aimed at supporting various platforms such as Windows, Mac, Linux, and Android. Tool integration and portability were high priorities, the project outcomes should be capable of incorporation in native C++ applications as well as other frameworks like Unity3D (C#) and MATLAB/Simulink, among many others.
Although allowed by the license this implementation is not primarily intended for production use. The code was developed ad hoc to answer research questions connected with the ongoing project. Therefore, code quality, as expected from standard production applications, is lacking when it comes to clarity, structure, comments, error handling and coding guidelines.
Since the Simulation Scenarios project is closed, no formal support should be expected from the initial contributors.
Nevertheless, regarding the above stated limitations, it was decided to release the code as is, as a public outcome from the project. It can hopefully serve as guidance or just inspiration for those aspiring to build similar tools, or even get accustomed with the OpenSCENARIO format. And of course, all contributions to further development are welcome!
Windows, Linux and Mac supported
Latest release including source, binaries and demo packages is found here: https://github.com/esmini/esmini/releases/latest
3D models used by the example scenarios are included in the demo packages. They are also available here. Unpack into esmini/resources. These assets works on all platforms. Environment models (roads, landscape, buildings...) have been created using VIRES Road Network Editor.
On Mac the zip-package might be put in quarantine, to release it:
xattr -d com.apple.quarantine file.zip
or even better:
xattr -c file.zip
If you get the "damaged file" message, please open a terminal in the folder where the esmini-demo was extracted, and run the following command:
xattr -c -r esmini-demo
If you want to build yourself, please find some instructions here.
Either get the demo or build yourself. To run demo scenarios:
- Navigate to run/esmini
- Run any of the provided batch-script examples (double click on or run from command line)
Or launch esmini from command prompt. There are many options but a few typical examples, assuming current directory is esmini root folder:
-
Just run a scenario:
./bin/esmini --window 60 60 800 400 --osc ./resources/xosc/cut-in.xosc -
Execute and record a scenario with fixed timesteps and no viewer:
./bin/esmini --headless --fixed_timestep 0.01 --record sim.dat --osc ./resources/xosc/cut-in.xosc -
Replay a recorded scenario:
./bin/replayer --window 60 60 800 400 --res_path ./resources --file sim.dat
Further info:
With some limitations (see details here) esmini can play the example scenarios provided with the ASAM OpenSCENARIO v1.1 release bundle.
- If you don't have esmini already, download latest demo package for your platform from here.
- Download the standard from ASAM here (register and download is free of charge).
- Extract to any folder.
- Run the examples from command line in esmini root folder, for example:
./bin/esmini --window 60 60 800 400 --osc ../../openscenario-v1.1.0/Examples/DoubleLaneChanger.xosc
or with absolute path:
./bin/esmini --window 60 60 800 400 --osc c:/stuff/openscenario-v1.1.0/Examples/DoubleLaneChanger.xosc
The easiest way of integrating esmini in your custom application is to link the all inclusive shared library ScenarioEngineDLL. In spite of the name it's available also on Linux and Mac. See this "Hello World" tutorial on how to create a minimalistic application based on it.
In addition to internal API (example) for getting information about the ongoing simulation, e.g. road width and road user position, esmini collects everything into an OSI groundtruth structure. This structure can be 1. stored in an OSI trace-file, 2. retrieved via UDP and/or 3. retrieved directly via API (see esminiLib.hpp).
Note: Only parts of OSI groundthruth is populated.
Hello World tutorial includes an example of how to fetch OSI groundtruth.
Current versions used by esmini:
- OSI version: v3.3.1
- Google Protobuf version: v3.15.2
Script that compiles OSI for Win/Linux/Mac available here. Run in bash, also on Windows, e.g. GIT bash.
esmini shared library works fine also in Unity (Win, Linux, Mac). A simple example can be downloaded from here. The package contains everything needed to get going:
- esmini library C# wrapper
- a generic scenario player script
- a few example scenarios (OpenSCENARIO + OpenDRIVE) including 3D models
- plugins for all platforms (can be updated of course)
- and finally a scene connecting the player script to a game object
Run:
- Import package (Import Package -> Custom Package).
- Load the scene (Assets/Scenes/esmini-scene).
- Then just press play-button.
Select (click on) esmini-player in Hierarchy to show up in Inspector, where you can specify scenario file and a few parameters. Note that scenario file and dependent OpenDRIVE and optional 3D scenegraph file must be present in StreamingAssets folder.
Plugins can be updated, but NOTE that you need to restart Unity to (re)load shared library plugins. And, of course, scenario files and other content can be added or replaced.
see last section in Hello-World_coding-example.
esmini comes with a few controllers (ways of controlling individual entities in the scenario):
- DefaultController. Performs actions exactly as specified in the OpenSCENARIO file. Assigned to entities by default.
- InteractiveController. Hand over control to the user via keyboard arrow keys.
- FollowGhost. A ghost-twin is performing the events a few seconds ahead. The entity will then follow its trajectory.
- ExternalController. State (position, rotation ...) expected to be reported from external simulator via API. Ghost trajectory can be created for an external driver model as reference.
- SumoController. A way of integrating SUMO controlled vehicles in a scenario.
More information here.
esmini make use of OpenSceneGraph (OSG) for visualization of the scenario. The OpenSCENARIO files can optionally refer to existing 3D models of the static environment (scene graph) and dynamic objects (entites). If the scene graph reference is missing, esmini will try to generate a basic model based on the OpenDRIVE road network description.
Currently esmini only supports OSG native .osgb 3D file format. However, there are ways to convert 3D models of some other formats using the OSG tool osgconv. Please see this issue report for some more info.
scenariogeneration is a Python based scenario creation framework. The idea is to write scenarios in a high-level script format and automatically generate and run linked OpenDRIVE and OpenSCENARIO XML counterparts. It supports parameter sweeps to create multiple variants of a parameterized scenario.
OSC-ALKS-scenarios is a collection of scenarios for Automated Lane Keeping System testing. "BMW has taken on the task of implementing the test scenarios from the ALKS regulation using OpenSCENARIO and OpenDRIVE resulting in a bundle of XML files executable with standard compliant simulators."
brifsttar/OpenDRIVE plugin allows you to manipulate OpenDRIVE road networks in Unreal Engine. It's based on esmini RoadManager (esminiRMLib).
esmini-visualizer is a tool to automatically generate video visualizations of scenarios.
Note that it does not seem to work with Anti-Alias filtering. Therefore make sure to run esmini without Anti-Alias by providing argument --aa_mode 0.
OpenScenarioEditor. A simple ASAM OpenSCENARIO editor developed by Infotiv AB under VALU3S project.
RControlStation scenario editor. Another embryo to an OpenSCENARIO editor, part of Self-Driving Model Vehicle Platform (SDVP).
The implementation is very limited at this point, but some things can be edited and the scenario can be executed and observed from above, as well as exported to the other tools. You have to start by importing one of the existing scenarios into the editor, as it cannot make a scenario from scratch.
Instruction:
- Get RControlStation source code
git clone https://github.com/vedderb/rise_sdvp
- Build esmini:
cd rise_sdvp/Linux/RControlStation
git clone https://github.com/esmini/esmini
cd esmini
mkdir build
cd build
cmake ../ -DUSE_OSG=true -DCMAKE_BUILD_TYPE=Release
cmake --build . --config Release --target install
cd ../../
- Edit RControlStation.pro and uncomment the line: #DEFINES += HAS_SIM_SCEN
- Build and run RControlCenter:
./build_lin
export LD_LIBRARY_PATH=esmini/bin
./build/lin/RControlStation
The editor is the last tab in RControlStation.
esmini-pybind11 is an ongoing effort to establish a Python wrapper for internal esmini API (not only shared libraries esminiLib and esminiRMLib).
Carla is an Unreal based open source simulator worth to check out.
OpenDRIVE describes the road network, the static part of a scenario.
OpenSCENARIO describes the dynamic content on top of a road network, e.g. traffic maneuvers and weather conditions.