blender-driving-scenario-creator

Blender Driving Scenario Creator add-on

This Blender add-on lets you create OpenDRIVE and OpenSCENARIO based scenarios for development and testing of advanced driver assistance systems and autonomous driving functions.

How to install

Prior to installing the add-on inside of Blender some requirements must be installed. The process slightly differs for Linux, Windows, and macOS.

Requirements Linux

For the sake of simplifying the following instructions let’s assume that we work with a Debian based Linux distribution (such as Ubuntu or Mint) and Blender has been downloaded and installed to

/opt/blender/

Then we first need to install the scenarigeneration library into the Blender Python environment since the add-on uses the library as a backend to write OpenDRIVE and OpenSCENARIO files. Additionally, pyclothoids is needed which is used by the add-on and the scenarigeneration lib as well. Navigate to your Blender included Python installation

cd /opt/blender/<blender_version>/python/bin

now install the lib(s)

./python<python_version> -m pip install scenariogeneration

Use sudo -E if the Blender install directory is owned by root. Note that sudo is not required in case Blender is installed to the user home directory or the user has write access to the directory. Also make sure not to not forget the ./ at the beginning such that the Python executable from within the directory is used and not another instance on your system.

For exporting .osgb files we also need to install OpenSceneGraph to have the osgconv tool available. This is necessary because Blender is unable to directly export to the .osgb scenegraph format, while esmini can only process this particular format. On a Debian/Ubuntu/Mint system this can be achieved with

sudo apt install openscenegraph

If you manually install OpenSceneGraph make sure that osgconv can be found through your PATH environment variable, otherwise the export with .osgb 3D model files will fail.

Requirements Windows

Assuming Blender has been downloaded and installed using the .msi installer, open PowerShell in admin mode by pressing Windows+X and then then A.

In PowerShell navigate to the Blender install folder with (don’t forget to insert the version number)

cd "C:\Program Files\Blender Foundation\Blender <blender_version>\<blender_version>\python\bin"

Run the following command to install the scenariogeneration library

.\python -m pip install scenariogeneration --target ..\lib\site-packages

Note that you might be able to do this without admin rights in case you are using the “Portable” version of Blender. Also if you are having trouble with this part of the installation, consider starting over with a clean installation of Blender and/or removing any leftovers of Python in your %appdata% folder.

Download and extract (for example to C:\Tools\OpenSceneGraph) openscenegraph.

Add the OpenSceneGraph bin folder to the PATH environment variable using the “Edit environment variables for your account” tool (look for it in the Windows start menu). Note that otherwise the export with .osgb 3D model files will fail because osgconv can not be found by the add-on.

Requirements macOS

Assuming Blender has been downloaded and installed in /Applications, open Terminal and navigate to Blender’s bundled Python installation. Replace <blender_version> and <python_version> with the values used by your Blender installation.

cd "/Applications/Blender.app/Contents/Resources/<blender_version>/python/bin"

Then install the scenariogeneration library into Blender’s Python environment:

./python<python_version> -m pip install scenariogeneration

Install Homebrew if it is not already installed, then use it to install OpenSceneGraph, which provides the osgconv tool required for exporting .osgb files:

brew install open-scene-graph

Make sure that the directory containing osgconv is available through your PATH environment variable.

Add-on (Linux, Windows, and macOS)

Finally download the driving scenario generator release .zip archive. Open Blender and go to Edit -> Preferences -> Add-ons. Click “Install…”. Select the .zip archive and confirm. Activate the add-on by ticking the little box next to it, in the add-on list.

Scenario preview (Linux, Windows, and macOS)

Install esmini to any location and set the esmini library file path in Blender at Edit -> Preferences -> Add-ons -> Driving Scenario Creator -> esmini_library_path.

For macOS, the first time the esmini preview or export uses the library, macOS may block the dylib. Run it once to show the Gatekeeper warning, allow it in macOS security settings, and then run it again in Blender, allowing it in the popup when prompted.

How to use

Before using the add-on some preliminary settings are recommended.

Recommended Blender settings

When you are in the Blender Layout workspace (see the tabs at the top), press N or click the little left arrow next to the navigation gizmo to toggle the sidebar. Click View, set Clip Start to 1 m and Clip End to 10000 m to avoid some 3D viewport clipping issues since the Blender default setting is targeted more towards smaller models. Click the Shading dropdown button (the little down arrow in the top right corner of the 3D viewport) and select Texture to be able to directly see the road sign textures.

It is also very useful to make yourself familiar with the most important shortcuts to navigate with the camera in the 3D viewport. The most important ones are Shift + Middlemouse to pan and Alt + Middlemouse to move the pivot point. The pivot point will automatically be placed on the surface of an object when it is under the mouse pointer which is extremely useful. The view can be rotated by holding Middlemouse. Additionally, the View Pie Menu is very useful to see the scene from different fixed angles. It can be opened with the ` (backtick) button on the US keyboard layout, alternatively use the Numpad shortcuts or go to Edit -> Preferences -> Input -> Emulate Numpad and use the 1-9 keys. Hint for German keyboard layouts: go to Edit -> Preferences -> Keymap -> 3D View -> 3D View (Global) -> View and add the Ctrl modifier key to the shortcut. Then it will work with the ^ key which is in the same location as the ` key in the US keyboard layout (above the Tab key).

Using the actual add-on

Click Driving Scenario Creator in the sidebar. From here you can create roads and vehicles using the mouse by clicking the buttons in the “Driving Scenario Creator” menu. Roads, signs, vehicles and trajectories can be placed with the mouse. Junction connecting roads can be build using the mouse similar to normal roads after first building a junction area. The cursor will snap to the lanes of the incoming roads in this case. Besides driving lanes this also works for walking and biking lanes so that pedestrians and cyclists can cross a junction. A connecting road can only link lanes of the same kind, hence after starting on a walking lane the cursor only snaps to the walking lanes of the other incoming roads. Note, that in Blender it is possible to quickly left click multiple times in order to select objects which are located on top of each other. This helps with selecting and deleting junction connecting roads. Grid snapping can be activated by holding Ctrl. Additional geometry sections can be added by holding Shift and clicking. Start heading of a road can be adjusted by holding Alt and moving the mouse pointer. For the clothoid geometry using the Hermite solver the end heading can be adjusted by holding Shift and moving the mouse wheel. Road elevation can be changed by holding E(3D view) or S(sideview) keys and moving the mouse. After placing roads, road signs can be attached to them and placed at the side. Finally, vehicles can be placed and a trajectory can be assigned to them.

Tool / operation	Shortcut or control	Function
Add-on menu	N (vanilla Blender)	Toggle the sidebar with the add-on menu
Road drawing	Mouseleft	Place the start/end point; after placing the end point, start another road
Road drawing	Hold Shift + Mouseleft	Add another geometry section instead of finishing
Road drawing	Hold Ctrl	Snap to the 3D grid instead of an existing road
Road drawing	Hold Alt	Adjust the start heading while placing the end point
Road drawing	Hold E	Adjust elevation from the current view
Road drawing	Hold S	Switch to side view while adjusting elevation
Road drawing	Hold Shift + Mousewheel Up/Down	Adjust the end heading
4-way junction	Mouseleft	Place the two points
4-way junction	Hold Ctrl	Snap to the 3D grid
4-way junction	Hold E	Adjust elevation from the current view
4-way junction	Hold S	Switch to side view while adjusting elevation
Junction connecting road	Mouseleft	Place the start/end point on incoming road joints
Junction connecting road	Hold Shift + Mouseleft	Add another geometry section instead of finishing
Junction connecting road	Hold Ctrl	Snap to the 3D grid
Junction connecting road	Hold Alt	Adjust the start heading while placing the end point
Junction connecting road	Hold E	Adjust elevation from the current view
Junction connecting road	Hold S	Switch to side view while adjusting elevation
Junction connecting road	Hold Shift + Mousewheel Up/Down	Adjust the end heading
Road objects: signs, traffic lights, stop lines, and stencils	Mouseleft	Select the reference road/object and place the object
Road objects: signs and traffic lights	Hold Ctrl	Snap to the 3D grid while placing the object
Road objects: signs and traffic lights	Hold Alt	Adjust the object heading
Road objects: stop lines and stencils	Hold Shift	Disable lane-surface snapping
Parking spots	Mouseleft	Place parking spots on the selected road
Parking spots	Hold Shift + Mousewheel Up/Down	Increase/decrease the number of parking spots
Entity placement: cars and pedestrians	Mouseleft	Place an entity; placement remains active for more entities
Entity placement: cars and pedestrians	Hold Shift	Disable lane-center and orientation snapping
Entity placement: cars and pedestrians	Hold Alt	Keep the entity position fixed and adjust its heading
Move entity	Mouseleft	Select an OpenSCENARIO entity or trajectory, then confirm its new position
Move entity	Hold Shift	Disable lane-center and orientation snapping
Move entity	Hold Alt	Keep the entity position fixed and adjust its heading
Edit entity	Mouseleft	Select an OpenSCENARIO entity, then edit its properties in the popup
Trajectories: polyline, NURBS, and clothoid spline	Mouseleft	Select an entity, then place trajectory points
Trajectories	Hold Alt while placing a point	Reverse the trajectory segment from that point
Trajectories	Hold Ctrl	Snap to the 3D grid when placing a point on a surface
Trajectories	Hold E	Adjust elevation from the current view
Trajectories	Hold S	Switch to side view while adjusting elevation
Clothoid spline trajectory	Hold Shift + Mousewheel Up/Down	Adjust the end heading
Generic junction (area)	Mouseleft	Select incoming road ends
All modal tools	Mouseleft	Confirm the current point or selection
All modal tools	Mouse right	Cancel the current step or go back one step; exit when at the first step
All modal tools	Esc	Cancel and exit the active tool
All modal tools	Return or Space	Finish the current operation, where supported
All modal tools	Mousewheel Up/Down	Zoom out/in
All modal tools	Hold Alt + Middlemouse	Center the view on the cursor

Before or after adding roads add additional Blender objects as desired. When done modelling, export everything together by clicking Export driving scenario. Choose a directory and a 3D file format (.fbx, .gltf, .osgb) for the export and confirm.

OpenSCENARIO XML action node editor

The add-on includes a custom Blender node editor for building the dynamic OpenSCENARIO XML action graph. To use it click Toggle node editor in the Actions section of the OpenSCENARIO panel. Click Add to add nodes and then drag them around, configure and connect them together with the mouse. The graph is exported together with the rest of the scenario every time you export the scenario or start the esmini preview.

Available action nodes include:

• Speed, with absolute and relative speed targets.
• Lane Change, with absolute and relative lane targets.
• Lane Offset, with a calculated transition duration.
• Longitudinal Distance, with distance or time-gap targets, coordinate-system and displacement options, and dynamic acceleration/deceleration constraints.
• User Defined Action, for custom commands.

Action nodes have an Entity selector populated from the entities in the scene. Longitudinal-distance actions also have a separate Target entity selector. Action nodes expose a Trigger input and a Complete output. Unconnected action triggers start at simulation time 0.0 and run in parallel. Connecting Complete to another action’s Trigger makes the second action wait for the first action’s completion.

Use Simulation Time Trigger for time-based starts. Trigger OR and Trigger AND combine multiple inputs and provide a True output that can trigger a subsequent action. Set their input count to the number of conditions you need and connect every configured input before exporting. Trigger OR starts its output when any input condition is true. Trigger AND waits until all input conditions are true. For action outputs, these conditions refer to the source action’s completion state.

Use Scenario Stop Trigger to stop the overall storyboard. It can use a time limit, a connected action or logic trigger, or both. When both are enabled, the first condition to become true stops the scenario. Disable Use time limit when the stop should be controlled only by its connected trigger.

esmini preview mode (inside Blender)

The addon includes a preview-only esmini integration in the sidebar panel. Use this when you want to preview entity motion in the Blender viewport. Note that this does not bake any keyframes in Blender. To use the preview

1. Point esmini library path in the addon preferences to your local esmini shared library file (esminiLib / libesminiLib).
2. In the Driving Scenario Creator panel find the esmini Preview section control with the player buttons.
3. When clicking Play, the add-on exports a temporary scenario and starts esmini in headless mode.
4. Play the timeline forward to update OpenSCENARIO entity transforms from esmini state.
5. Click Stop to stop the preview and restore original authored transforms.

How to run exported scenarios

With esmini available the exported scenario can be run with

cd <export_directory>
esmini --osc xosc/bdsc_export.xosc --window 50 50 800 400

How to develop

For development of the add-on the Blender VS Code extension is very recommendable. It allows hot reloading and rapid iterations.

To regenerate sign, stencil, or entity preview images, install librsvg and ImageMagick. Use brew install librsvg imagemagick on macOS or sudo apt install librsvg2-bin imagemagick on Ubuntu/Debian. All conversion scripts use rsvg-convert to render SVGs before ImageMagick performs any PNG resizing or cropping.

How to run the tests

There is a handful of tests for the geometries in the tests/ directory. They can be run by executing pytest from the Blender python distribution in the project root directory

/opt/blender/<blender_version>/python/bin/pytest

If pytest is not installed use pip to install it into the Blender directory as described with the scenariogeneration library above.

The tests can also be run and debugged from within VS Code by adding the following line to the .vscode/settings.json which is generated by VS Code when configuring/scanning for the tests

{
    ...
    "python.defaultInterpreterPath": "/opt/blender/<blender_version>/python/bin/python3.<python_version>",
    ...
}

License

The source code of this tool is distributed under the GPL version 3.0 license as required for all Blender add-ons. Note, that this does not imply that the tool can not be used in a commercial context. In fact, there is probably no issue using it in the same way as you would use Blender itself, Linux or GCC since you will probably not be modifying the source code and/or linking against it.

Furthermore, if your enterprise has already reached a state where open source software contribution is possible or your business has embraced open source software long ago, your contributions and pull requests are welcome if they are maintainable.

Credits

Credits for the current version go to

• pyoscx/scenarigeneration developers for the .xodr/.xosc generating/writing lib used as backend
• Archipack add-on developer(s) for general Blender add-on tool inspiration
• Blender VS Code extension for quick iterative development and hot reloading
• pyclothoids which is a Python wrapper for Enrico Bertolazzi’s Clothoids library
• Wikipedia and its contributors for the public domain (“gemeinfrei”) German road sign textures and road stencil designs

Main author/maintainer contact

Please open issues and pull requests on GitHub to discuss openly. For private support inquiries contact the repository owner via email, Twitter or create an issue to initiate the communication. If you consider contributing large new features please consider to have a discussion before beginning with the clean implementation.