esmini user guide

Specify a window and scenario file. Example:
./bin/esmini --window 60 60 800 400 --osc ./resources/xosc/cut-in.xosc

Visualize trails from moving entities:
./bin/esmini --window 60 60 800 400 --osc ./resources/xosc/cut-in.xosc --trail_mode 3

Show entities as bounding boxes:
./bin/esmini --window 60 60 800 400 --osc ./resources/xosc/cut-in.xosc --bounding_boxes

In addition to several OSG standard camera models esmini adds a set of special purpose camera modes that follows following scenario entities in various ways. Further, the user can add custom cameras via API or launch arguments.

Top level camera mode is selected on keys '1' to '8'. Mode 2-8 are OpenSceneGraph standard cameras. Mode 1 hands over camera control to esmini. In this mode, switch camera model by pressing 'k' which will toggle between all available esmini camera model.

The default camera model is esmini "orbit" which allows for rotating (left-mouse button), zooming (right-mouse button) and panning (scroll wheel / middle mouse button) while following the first entity.

To follow another vehicle press Tab (next vehicle) or Shift TAB (previous vehicle). Also Backspace is mapped to previous vehicle, since shift-TAB do not work on all platforms.

For a complete list of cameras and functions, see Command reference.

esmini camera mode can be selected by launch argument. Here are a few common use cases:

Follow exact behind vehicle:
./bin/esmini --window 60 60 800 400 --osc ./resources/xosc/slow-lead-vehicle.xosc --camera_mode fixed

Orthogonal (no perspective) top view follow vehicle:
./bin/esmini --window 60 60 800 400 --osc ./resources/xosc/slow-lead-vehicle.xosc --camera_mode top

Follow vehicle from inside "driver" point of view:
./bin/esmini --window 60 60 800 400 --osc ./resources/xosc/slow-lead-vehicle.xosc --camera_mode driver

Follow vehicle with some flex and allow rotate, pan and zoom:
./bin/esmini --window 60 60 800 400 --osc ./resources/xosc/slow-lead-vehicle.xosc --camera_mode flex-orbit

In addition to pre-defined camera modes, the user can add custom cameras from API or via launch argument. Custom cameras can be fixed, semi-fixed (fixed position but unconstrained orientation) or relative current vehicle. Here is a few examples:

Custom camera in front of vehicle, e.g. sensor mount position: ./bin/esmini --window 60 60 800 400 --osc ./resources/xosc/slow-lead-vehicle.xosc --custom_camera 3,0,0.6,0,0

Custom camera with fixed position but dynamic orientation, always pointing at current vehicle:
./bin/esmini --window 60 60 800 400 --osc ./resources/xosc/slow-lead-vehicle.xosc --custom_fixed_camera 170,10,5

Custom fixed camera:
./bin/esmini --window 60 60 800 400 --osc ./resources/xosc/slow-lead-vehicle.xosc --custom_fixed_camera 240,15,10,3.5,0.2

Custom fixed top view camera:
./bin/esmini --window 60 60 800 400 --osc ./resources/xosc/slow-lead-vehicle.xosc --custom_fixed_top_camera 180,-1.54,2301,4.71239

See Command reference for a complete list of key shortcut commands.

Visualize OpenDRIVE road features:
./bin/esmini --window 60 60 800 400 --osc ./resources/xosc/cut-in.xosc --road_features on

If a 3D model representation of the road network is missing (i.e. empty or missing SceneGraphFile element of the OpenSCENARIO RoadNetwork class), then esmini will generate a very simple model.

Example:
./bin/esmini --window 60 60 800 400 --osc ./resources/xosc/slow-lead-vehicle.xosc

Add optional flat ground plane:
./bin/esmini --window 60 60 800 400 --osc ./resources/xosc/slow-lead-vehicle.xosc --ground_plane

The generated model can be saved:
./bin/esmini --window 60 60 800 400 --osc ./resources/xosc/slow-lead-vehicle.xosc --save_generated_model
Then look for generated_road.osgb in the current directory.

esmini default background color is skyish, light blue. Change by launch argument --clear-color <r,g,b>, where r, g, b are the red, green, blue components as floating numbers in the range (0:1). Some examples:

Black background:
./bin/esmini --window 60 60 800 400 --osc ./resources/xosc/slow-lead-vehicle.xosc --clear-color 0,0,0

White background:
./bin/esmini --window 60 60 800 400 --osc ./resources/xosc/slow-lead-vehicle.xosc --clear-color 1,1,1

Gray background:
./bin/esmini --window 60 60 800 400 --osc ./resources/xosc/slow-lead-vehicle.xosc --clear-color 0.3,0.3,0.3

esmini make use of OpenSceneGraph sub-sampling method for anti-alias. Default setting is 4 (samples). This can be controlled by the launch argument --aa_mode <samples>. To disable anti-alias:
./bin/esmini --window 60 60 800 400 --osc ./resources/xosc/slow-lead-vehicle.xosc --aa_mode 0

Press 'c' at any time to store a single screenshot.

Press 'C' at any time to start storing screen shot for every frame onward. Press 'C' again to stop.

First, run the scenario and automatically save screenshots for all frames:
./bin/esmini --window 60 60 800 400 --osc ./resources/xosc/cut-in.xosc --fixed_timestep 0.033 --capture_screen

Then, create a video clip using ffmpeg:
ffmpeg -f image2 -framerate 30 -i screen_shot_%5d.tga -c:v libx264 -vf format=yuv420p -crf 20 out.mp4

The above ffmpeg command will create a MPEG4 video with reasonable compression (crf 20). To create a lossless, but still compressed, video e.g. for further post processing:

ffmpeg -f image2 -framerate 30 -i screen_shot_%5d.tga -c:v libx264 -qp 0 out.mp4

To change framerate of the output video, use the fps filter. E.g. from input 30 fps to output 15 fps:

ffmpeg -f image2 -framerate 30 -i screen_shot_%5d.tga -c:v libx264 -vf format=yuv420p,fps=15 -crf 20 out.mp4

Get ffmpeg: http://ffmpeg.org/download.html

Some details regarding H.264 encoding can be found here.

Whenever esmini is launched with the --window <x-pos> <y-pos> <width> <height> argument a viewer will be created with specified window. The --headless flag controls whether any window will be "on screen" or only off-screen. Of course, --headless in combination with no window (no --window argument) will skip rendering altogether, which is a very performance-saving mode to use when possible.

Example:
./bin/esmini.exe --window 60 60 4000 2000 --headless --capture_screen --osc .\resources\xosc\cut-in.xosc
will render images into a virtual frame buffer of size 4k x 2k pixels and then store to file. Note: The size of the virtual frame buffer is not limited by size of any connected display.

To run esmini completely without rendering, just omit the --window argument:
./bin/esmini.exe --osc .\resources\xosc\cut-in.xosc --fixed_timestep 0.01 --record sim.dat
will run the specified scenario quickly and store a .dat file for later analysis or viewing (with replayer).

Note: If --fixed_timestep is omitted esmini will adapt timesteps to actual frametime, so a 30 seconds scenario will take 30 seconds - i.e. no performance gain.

By default any available 3D graphics hardware will be utilized. As fallback esmini (via OSG) will utilize Mesa3D which is a software implementation of the OpenGL graphics stack including parts normally hosted in the graphics hardware system. The Mesa3D approach is useful when running on cloud/cluster machines lacking graphics hardware, perhaps even lacking a window system (like slimmed and headless Ubuntu without X11 support).

Mesa3D on Linux
Mesa3D is normally installed with Linux distributions. Check OpenGL support with the following command:
glxinfo -B

If the command is not available, then Mesa3D utility package is probably missing. Install as:
sudo apt install mesa-utils

To run headless with a virtual frame buffer:

For troubleshooting, the following command might give information about the graphics system:
lspci -vnn | grep VGA -A 12

Mesa3D on Windows

By default esmini is creating a log.txt in the folder from which esmini is launched. In case of esminiLib it will end up in the folder that the application linking esminiLib was launched from.

The log.txt includes the same information normally seen in the terminal window (stdout).

To disable output to terminal:
./bin/esmini --window 60 60 800 400 --osc ./resources/xosc/slow-lead-vehicle.xosc --disable_stdout

To disable creation of the logfile (log.txt):
./bin/esmini --window 60 60 800 400 --osc ./resources/xosc/slow-lead-vehicle.xosc --disable_log

Developer info: Define the symbol DEBUG_TRACE (either as compile flag or by uncomment this code line) to log more details, like what code module and line number is the origin of the log entry.

In addition esmini can save a .dat file which captures the state of all entities. This file can later be used either to replay (see Replay scenario) the scenario or converted to .csv for further analysis, e.g. in Excel.

To create a recording with regular timesteps:
./bin/esmini --window 60 60 800 400 --osc ./resources/xosc/slow-lead-vehicle.xosc --fixed_timestep 0.05 --record sim.dat

To convert the .dat file into .csv, do either of:
./bin/dat2csv sim.dat
or
python ./scripts/dat2csv.py sim.dat

Only a subset of the .dat file information is extracted. To extract some more info, e.g. road coordinates, run: ./scripts/dat2csv --extended sim.dat

You can create .dat files from multiple scenarios in a single command, like this on Linux (bash):

It also works in Git bash on Windows.

To create a more complete csv logfile, compared to the content of the .dat file, activate the CSV_Logger:

./bin/esmini --window 60 60 800 400 --osc ./resources/xosc/cut-in.xosc --fixed_timestep 0.05 --csv_logger full_log.csv

full_log.csv will contain more detailed states for all scenario entities. To also include collision detection:

./bin/esmini --window 60 60 800 400 --osc ./resources/xosc/cut-in.xosc --fixed_timestep 0.05 --csv_logger full_log.csv --collision

All collisions (overlap) between entity bounding boxes will be registered in the collision_ids column of each entity. It will contain the IDs of any entities overlapping at given frame.

Next example, play multiple variants of a scenario in parallel:
./bin/replayer --window 60 60 800 400 --file sim --res_path ./resources --capture_screen --dir tmp

The --dir argument points to a folder containing sim1.dat, sim2.dat and sim3.dat.
The --capture_screen argument will save each frame as an image file on disk.

Merged data from multiple .dat files can be saved into one single .dat file, e.g. for plotting:
./bin/replayer --file sim_ --dir . --save_merged sim_merged.dat

replayer will look in current folder (".") for any .dat file starting with "sim_", i.e. "sim_*.dat". The files will be merged and saved as sim_merged.dat.

By default odrviewer will create a simple 3D model of the OpenDRIVE description and populate it with sparse traffic:
./bin/odrviewer --window 60 60 800 400 --odr ./resources/xodr/fabriksgatan.xodr

Add OpenDRIVE features, like reference line and lanes, on top (toggle on 'o'):
./bin/odrviewer --window 60 60 800 400 --odr ./resources/xodr/fabriksgatan.xodr --road_features

Remove all traffic, just visualize the road geometry:
./bin/odrviewer --window 60 60 800 400 --odr ./resources/xodr/fabriksgatan.xodr --density 0

Increase traffic to exercise all junctions and lanes of the road network:
./bin/odrviewer --window 60 60 800 400 --odr ./resources/xodr/fabriksgatan.xodr --density 7 --road_features

Use custom 3D model:
./bin/odrviewer --window 60 60 800 400 --odr ./resources/xodr/fabriksgatan.xodr --model ./resources/models/fabriksgatan.osgb --density 5

Slow down traffic:
./bin/odrviewer --window 60 60 800 400 --odr ./resources/xodr/fabriksgatan.xodr --model ./resources/models/fabriksgatan.osgb --density 3 --speed_factor 0.6

esmini odrplot is a small application that creates a track.csv file that can be plotted with another small Python script xodr.py:
./bin/odrplot ./resources/xodr/fabriksgatan.xodr
./EnvironmentSimulator/Applications/odrplot/xodr.py track.csv

Combine in a one-liner:
./bin/odrplot ./resources/xodr/fabriksgatan.xodr;./EnvironmentSimulator/Applications/odrplot/xodr.py track.csv

To navigate in the plot, click the four-arrow icon (see image below) and then use mouse according to:

esmini provides a Python based script, plot_dat.py, to plot information in .dat files.

First, create a .dat file. For that we don’t need a window. Run esmini headless:
./bin/esmini --headless --fixed_timestep 0.05 --osc ./resources/xosc/acc-test.xosc --record sim.dat

The scenario looks like this:

Next, plot speed over time:
./scripts/plot_dat.py sim.dat --param speed

To see what parameters are available for plot:
./scripts/plot_dat.py sim.dat --list_params

will output a list similar to:
Plottable parameters:
id, model_id, obj_type, obj_category, ctrl_type, time, speed, wheel_angle, wheel_rot, centerOffsetX, centerOffsetY, centerOffsetZ, width, length, height, scaleMode, visibilityMask, x, y, z, h, p, r, roadId, laneId, offset, t, s

Most parameters does normally not make sense to plot, but it depends on the test case. Maybe it’s interesting to see when a car makes a lane change. Plot laneId over time:
./scripts/plot_dat.py sim.dat --param laneId

A plot can show multiple parameters:
./scripts/plot_dat.py sim.dat --param laneId --param speed

To plot trajectories, change X-axis parameter from time to x and plot y parameter (over x):
./scripts/plot_dat.py sim.dat --x_axis x --param y

Lock axis aspect ratio, i.e. make axis scale equal:
./scripts/plot_dat.py sim.dat --x_axis x --param y --equal_axis_aspect

Plot merged .dat files (created as described in Save merged .dat files)

./scripts/plot_dat.py --param speed sim_merged.dat

Entity IDs will get an offset multiplier of 100, corresponding to the order of which the dat files were read by replayer. The mapping between ID range and dat file is printed to the console by replayer when the merged dat file is created, as the following example of four input files:

From version 2.32.0 esmini can plot some pre-configured data values during simulation. Simply add launch flag --plot.

Features so far:

By default the plotting is executing in a separate thread, having minimal impact on esmini performance. It is also possible to execute in synchronous mode, where plotting is part of esmini main thread and stepping is done in synch. The mode can be specified explicitly. Examples:

Simply enable plotting, default mode:

./bin/esmini --window 60 60 800 400 --osc ./resources/xosc/cut-in.xosc --fixed_timestep 0.05 --plot

Enforce synchronous mode:

./bin/esmini --window 60 60 800 400 --osc ./resources/xosc/cut-in.xosc --fixed_timestep 0.05 --plot synchronous

Asynchronous mode can be specified as well, although it’s default hence not needed:

./bin/esmini --window 60 60 800 400 --osc ./resources/xosc/cut-in.xosc --fixed_timestep 0.05 --plot asynchronous

Note: On macos OpenGL window must be part of main thread. Hence synchronous mode is enforced on macos.

(Special case implementation introduced in esmini v2.23.1)

Compared to SpeedAction, the SpeedProfileAction offers more tools in terms of dynamic constraints. Hence it can be actually be useful also for single entry, i.e. reach a single target speed.

The implementation differs for the single entry case. Target speed will be reached if constraints allows for it. If not, the speed will still be reached, but later than specified.

There are three sub cases:

1. Speed can be reached within time

The speed profile will contain three phases: Jerk, constant acceleration, jerk.

Example:
Replace the four entries in speed-profile.xosc with the following ones:

Initial positive jerk will be applied until necessary acceleration is reached. Keep constant acceleration (linear segment in the speed profile) until negative jerk needs to be applied in order to reach target speed on time and at zero acceleration.

2. Speed can’t be reached in time due to acceleration constraints

This speed profile will also contain three phases: Jerk, constant acceleration, jerk.

Example:
Replace the four entries in speed-profile.xosc with the following ones:

Initial positive jerk will be applied until maximum acceleration is reached (or maximum deceleration). Keep constant acceleration (linear segment in the speed profile) until negative jerk needs to be applied in order to reach target speed at zero acceleration. Due to the acceleration limitation there will be a delay as well. The log file will include something like:

3. Speed can’t be reached in time due to jerk constraints

This speed profile will contain only two jerk phases.

Example:
Keep entries from last case, but change jerk settings as follows:

In this case the jerk settings are too weak to reach target speed in time. Not enough acceleration can be achieved in the given time window.

Positive jerk will be applied until negative jerk has to be applied in order to reach target speed at zero acceleration. Hence there is no room for a phase of constant acceleration. Due to the jerk limitation there will be a delay. The log file will include something like:

Replace the four entries with the following ones:

What we see here is that for linear mode (FollowingMode="position") the speed of the first entry will apply immediately regardless of the current speed at the time of the action being triggered. For constrained mode (FollowingMode="follow") we see that the initial speed value (3.0) is overridden by the current speed (0.0). From there it will strive for the second entry, obeying the constraints.

The overall idea with the "follow" mode is to maintain continuity in the speed profile, up to jerk degree.

Replace any entries with the following ones:

Specified max acceleration will be applied until target speed is reached. Note: In the non-linear case and with multiple entries, the function will fail if the specified acceleration can’t be reached with given jerk constraints (maxAcceleration and maxDeceleration). Try to lower the maxAcceleration/deceleration in this case.

You can also combine entries with and without time constraint, like in following example:

Car will accelerate until speed 10 m/s is reached, then spend 3 seconds to reach 15 m/s.

(from release v2.23.2)

What if the acceleration is not zero when the SpeedProfileAction is started, for example interrupting an ongoing SpeedAction in Follow mode?

To maintain a continuous acceleration profile the action will use current acceleration as initial value. The standard states that the acceleration is expected to be zero at start and end of the action. The esmini interpretation is that the CHANGE is zero at start while the ACTUAL value is zero at end (since the action can only control acceleration while being active, not before).

Example: Once again starting from speed-profile.xosc, instead of setting an instant initial speed make it ramp up from 0 to 5 m/s over a duration of 4 seconds by tweaking the initial speed actions, for both entities, as below:

The initial speed action will apply constant acceleration until time = 2.0 seconds, when the SpeedProfileAction is triggered. While the linear profile will jump to 0 m/s (as specified in first entry) the follow mode profile will just apply necessary jerk to reach target acceleration with respect to following entries.

Initial acceleration is also respected for the special case of a single entry, for example:

the result becomes:

To skip jerk phase, e.g. as in emergency brake with an abrupt stop, just set AccelerationRate to a large number.

Example: Once again starting from speed-profile.xosc, change speed in the Init speed actions to 10.0 and replace the speed profile actions as below:

Note: A drawback is that the setting will affect any acceleration phase in the complete profile. In other words, a limitation is that entries can’t have individual settings. In the example above it’s not problem since the first jerk phase is a deceleration while the second is an acceleration. If different rate values of same type are needed, it can be achieved by defining multiple SpeedProfile actions in a sequence, with individual performance settings.

To get more understanding of the implementation, see a few slides here.

Road signs are specified in the OpenDRIVE road network description file. A road sign is identified by up to four parameters:

Country code is a two letter word according to the ISO 3166-1 alpha-2 system. Examples: Sweden = se, Germany = de.

Type and subtype defines the semantic meaning of the sign. The value is used when applicable to further specify information, e.g. speed or weight. Data type and meaning of the parameters may differ between countries. However a mapping to each country’s system is often feasible.

Examples: In Sweden a speed sign belongs to the category prohibition signs named "c". Within that category speed signs is a sub group with index 31. Within that group each sign has a value of speed/10, e.g. 5=50km/h, 10=100km/h. So the parameters for a Swedish speed limit 90 km/h sign becomes: se, c, 31, 9.

In Germany there are no similar categories. Instead all signs have a unique group or type number, e.g. speed signs make up group 274. Then the value defines the speed. No need for subtype. So the parameters for a German speed limit 90 km/h sign becomes: de, 274, -, 90.

Instead of hard-coding road sign support esmini will lookup the OSI code from a separate sign definition file, which is unique for each country. Name convention for the file is: country code + "_traffic_signals.txt". Example: Swedish catalog is named "se_traffic_signals.txt".

The file is a simple text format each line defining a sign ID and corresponding OSI type.

Swedish example: c.31-7=TYPE_SPEED_LIMIT_BEGIN
German example: 274=TYPE_SPEED_LIMIT_BEGIN

Type is mandatory. For esmini to distinguish between subtype and value different separators are used: "." before subtype and "-" before value. For some signs the value is optional, e.g. for speed signs it simply specify the speed limit. But for some signs it is used as a subtype to identify a variant of a sign, as in the German 101 type category.

Example files can be found in esmini/resources/traffic_signals.

Currently (v2.25.0) the esmini sign support is very limited. However, it should be fairly straight forward to add signs into existing catalogs and even catalogs (for more countries).

esmini road signs are created as follows:

A script is available as a starting point for automating the two last steps in the process above.

The OpenDRIVE file straight_500m_signs.xodr includes a bunch of speed signs, some Swedish and some German ones. It shows how the signs are specified in terms of the country code, type, subtype and value attributes.

It also shows how to specify the 3D model using the name attribute: If filename composed by country, type, subtype and value is not found, the name attribute + ".osgb" will be used for a second and final attempt.

Making use of Python threading pool framework we can utilize any multiple CPU kernels and run scenario variants in parallel. This is handled by the script scripts/run_distribution.py.

Usage: run_distribution.py <esmini args>

Make sure to add at least the following esmini arguments:
--osc <scenario file>
--param_dist <parameter distribution file>
--fixed_timestep <timestep>
--headless

Example:

python ./scripts/run_distribution.py --osc ./resources/xosc/cut-in.xosc --param_dist ./resources/xosc/cut-in_parameter_set.xosc --fixed_timestep 0.05 --headless

Of course, the --headless (and --fixed_timestep) is not required. It is possible to run with viewer as well:

python ./scripts/run_distribution.py --osc ./resources/xosc/cut-in.xosc --param_dist ./resources/xosc/cut-in_parameter_set.xosc --window 60 60 800 400

but the windows will open on top of each other at the same location on the screen, so you need to manually move them apart to see the parallel runs. Anyway, this use case is probably not relevant so the recommendation is to run headless with fixed time step.

Putting it all together, execute the scenario permutations in parallel and then view the result in replayer:

python ./scripts/run_distribution.py --osc ./resources/xosc/cut-in.xosc --param_dist ./resources/xosc/cut-in_parameter_set.xosc --fixed_timestep 0.05 --headless --record sim.dat ; ./bin/replayer --window 60 60 800 400 --res_path ./resources/ --file sim_ --dir .

To find out the number of permutations of a specific scenario and parameter distribution, use the --return_nr_permutations launch argument. Example:

./bin/esmini --osc ./resources/xosc/cut-in.xosc --param_dist ./resources/xosc/cut-in_parameter_set.xosc --return_nr_permutations

Output: Nr permutations: 6

For scripters: esmini will also return the number of permutations as exit code, for simple use in scripts. After executing the above the exit code can be inspected/verified from shell as well:

PowerShell:
echo $LastExitCode
6

bash:
echo $?
6

First, there is a great complete guide at https://sumo.dlr.de/docs/

The main flow of our example is:

Step-by-step:

Currently, as of esmini v2.37.1, SUMO is integrated in terms of a controller. To add a SUMO simulation, define an entity as usual, assign the SumoController and set its "filepath" property to the sumocfg file.

Now when we have a complete SUMO configuration, do the following steps in order to use it in esmini:

In most cases the same mode setting will be used throughout the simulation for each object. For this reason, as conveience, the mode can be set once per object. Example:

pos.SetMode(Position::PosModeType::SET, PosMode::Z_REL | PosMode::H_ABS | PosMode::P_REL | PosMode::R_REL);

Then, when calling set functions, mode can be set to zero. Example:

pos.SetInertiaPosMode(x, y, z, h, p, r, 0);

or use the simple variants skipping the mode argument. Example:

pos.SetInertiaPos(x, y, z, h, p, r);

These cases will utilize the current setting.

Note the type=SET argument of the SetMode() example above. It specifies as to which type of operations the settings applies to. There are two types of modes: SET and UPDATE. SET applies to API calls setting Cartesian coordinates. UPDATE applies to position updates by default controller and API calls setting Lane and Road coordinates.

This way a position object can, for example, maintain relative heading follow the curvature of the road when updated by the default controller, while heading can be set explicitly in terms of absolute value by API calls.

pos.SetMode(Position::PosModeType::UPDATE, PosMode::Z_REL | PosMode::H_REL | PosMode::P_REL | PosMode::R_REL);

pos.SetMode(Position::PosModeType::SET, PosMode::Z_REL | PosMode::H_ABS | PosMode::P_REL | PosMode::R_REL);

There will be a default setting for both SET and UPDATE which will be applied until changed by SetMode() function:

Further examples

Specify only mode for Z, reuse whatever setting for the remaining components:

pos.SetInertiaPosMode(x, y, z, h, p, r, PosMode::Z_ABS);

Set/reset default value for pitch, reuse whatever setting for the other components:

pos.SetInertiaPosMode(x, y, z, h, p, r, PosMode::Z_MASK & PosMode::Z_DEF);

Performs actions exactly as specified in the OpenSCENARIO file. Assigned to entities by default. Can be assigned at any point to "unassign" any currently assigned controller.

A simple vehicle model controlled by the user via keyboard (arrow keys).

A simple driver model. A ghost-twin performing the events a few seconds ahead. The entity will then do its best to mimic the motion and speed of the ghost by follow the trajectory. The primary purpose of this controller is to provide an example, but it can be useful to smoothen out the sometimes synthetic feel of pure default controller.

The entity will not be moved by the scenario. Instead its state (position, rotation …​) is expected to be reported from external simulator via API, e.g. SE_ReportObjectPos. Ghost trajectory can optionally be created for an external driver model to use as reference.

A way of integrating SUMO controlled vehicles in a scenario. OpenSCENARIO vehicles are reported to SUMO, and SUMO vehicles are reported back to esmini. A reference to a SUMO config file is provided as input to the controller. See cut-in_sumo.xosc for an example.

Based and inspired by Regulation 157 Safety Models. Includes four safety models relating to the (UNECE ALKS regulation #157). The controller includes preliminary and experimental implementation of four models:

Implementation of the Lane Independent Routing Model (LIRM) developed as part of the master thesis project Olsson, Daniel; Rylander, Eric: "A Framework for Verification and Validation of Simulation Models in esmini".

From the report: "LIRM has solved the issue with lane dependent routing that esmini had, by implementing a new controller that extends the behavior of the pathfinding and route following to incorporate lane changes."

This controller enhance the capabilities for an entity to find a path through the road network according to a specified route (basically a set of waypoints). The main advantage, compared to the route handler of the default controller, is that lane changes will be injected by the path finding algorithm in search for optimal path. The model will also take route strategy (Shortest, Fastest or Least Intersections) into consideration, which the default controller does not yet support.

A good example is found in follow_route_with_lane_change.xosc. The vehicle start out in left-most lane and needs to make three lane changes in order to exit the highway.

./bin/esmini --window 60 60 800 400 --osc ./EnvironmentSimulator/Unittest/xosc/follow_route_with_lane_change.xosc --trail_mode 1

An UDP interface for external driver models or vehicle simulators. The idea is to allow external devices to control entities in an ongoing esmini simulation, over network.

Concept:

There are a few input mode options:

For more info see: UDPDriverController.pdf

Demo (running a somewhat outdated testUDPDriver.py):

A simple "follow-the-leader" controller which aims to keep a specified distance to a specified leading vehicle. The controller utilizes a simple 2D "bicycle" vehicle model. Each time-step the controller finds out the direction and distance to the lead vehicle. Based on this, the acceleration and steering input is calculated and provided to the vehicle model.

The term off-road indicates that the controller does not consider any road network features. Note that it still can run on roads, parking lots, just that it’s ignoring it in terms of lanes and road-marks.

Below is a video clip showing the controller in action on an open paved area. The white lead vehicle is controlled interactively by the user via arrow keys. The controller is assigned to the red car which then strives to follow the lead car at the distance of 20 meters.

Windows
Binaries including FBX but not DAE support, see here:
https://objexx.com/OpenSceneGraph.html

Linux

sudo apt-get update
sudo apt-get -y install openscenegraph

Reference: https://installati.one/install-openscenegraph-ubuntu-20-04/?expand_article=1

There are no fixed structure where scenario resources, e.g. vehicle 3D model or controller catalog, needs to be stored. Instead, additional search paths can be added by launch argument --path <path>. For example:

./bin/esmini --window 60 60 800 400 --osc ./resources/xosc/slow-lead-vehicle.xosc --path ../../ --path c:/tmp/my_models

will add the relative path ../../ and absolute path c:/tmp/my_models to the list of places where to look for resources referred to by the scenario.

When esmini is downloaded as a zip file from Internet it might be blocked, i.e. prevented from being started, by Windows to protect your system. This is indicated by the following, or similar, message popping up when attempt to start:

"Microsoft Defender SmartScreen prevented an unrecognized app from starting. Running this app might put your PC at risk."

As long as the zip was downloaded from esmini official GitHub repository (https://github.com/esmini/esmini) it is perfectly safe to use.

The simplest solution is to unblock the zip file before unpacking it:

Note: This method also works for individual files after unzipping. But it can only be applied for one file at a time, why it’s simpler to unblock the complete zip before unpacking.

It is also possible to unblock from Powershell command line:

From esmini version 2.26.6 mac executables are universal binaries which means they work on both Intel and Apple Silicon based Macs. Following are some known issues and work arounds:

SUMO comes with a great tool, netconvert, that can convert road networks from and to various formats.

Prerequisite: Download and install SUMO from here.

Example: Convert an OSM map to OpenDRIVE for use in esmini:

netconvert --osm-files city.osm --opendrive-output city.xodr --no-turnarounds

Preview in odrviewer:

./bin/odrviewer --window 60 60 800 400 --odr city.xodr

Do either:

or

There are a few external dependencies that takes long time to build from scratch. Instead they are provided in compressed packages including needed headerfiles and prebuilt libraries. The packages are available for Win, Mac and Linux. For Windows and Linux they include Debug mode binaries, in addition to the Release variant.

The cmake script will check for the availability of these libraries, by simply checking for existence of corresponding folders, e.g. osg, osi, sumo, under esmini/externals. If missing, compressed packages will be downloaded and extracted.

Not often, but at some points the prebuilt libraries needs to be updated. In most cases it affects the esmini build configuration and/or code. Hence, sometimes an update of esmini comes with a need to update the external libraries as well. Lack of automatic handling, such update needs to be done manually. One way is to delete the specific folder(s) and run ordinary cmake command again. But the simplest way is to enforce redownload of all packages:

cmake .. -D FORCE_DOWNLOAD_BINARIES=TRUE

The FORCE_DOWNLOAD_BINARIES flag will be checked by the cmake script for enforced download of all packages. Upon successful download, the libraries will be replaced, one by one.

Library updates are not detected by the esmini build dependencies, why a clean rebuild of esmini should be performed manually afterwards.

In order to appear in the scenario, without need for AddEntity action, an entity must be represented in the Init section of the Storyboard. Common is to add actions to establish inital position and speed.

Example:

In esmini, the behavior of the two position types RoadPosition and LanePosition differ in terms of heading.

In the image below, the white cars are positioned by RoadPosition with t=-1.5 and t=1.5 respectively while the red cars are positioned by LanePosition with laneId="-1" and laneId="1" respectively.

Explicitly specified heading (in Orientation sub-element):

In next image, an Orientation element was added with absolute heading = 0.4 for all four cars.

In next image, an Orientation element was added with relative heading = 0.4 for all four cars.

Corresponding behavior applies also to RelativeRoadPosition and RelativeLanePosition.

In OpenDRIVE definition of laneOffset: A lane offset may be used to shift the center lane away from the road reference line.

In esmini lane offset affects the reference line as well as center lane, which is a deviation from the OpenDRIVE standard. As consequence, t values are also shifted with the lane offset.

2+1 roads can be defined utilizing lane offset. Consider image below:

esmini

OpenDRIVE

A 2+1 example example scenario is found here: resources/xosc/two_plus_one_road.xosc

Follow the following steps to install OSI (and dependent Google Protobuf) for use by some esmini scripts, e.g. osi2csv.py.

Protobuf for Python (skip if already installed)

protoc (Protobuf compiler)

OSI for Python

This should be it.

How to remove old versions (if needed)

esmini can run in two different time modes: 1. Real-time and 2. Fixed-time. Default is real-time.

The following command, from esmini root, will run real-time:
./bin/esmini --window 60 60 800 400 --osc ./resources/xosc/cut-in.xosc

This one fixed-time:
./bin/esmini --window 60 60 800 400 --fixed_timestep 0.05 --osc ./resources/xosc/cut-in.xosc

The difference is basically that real-time will run with as small time-steps as possible (actually limit at 1 ms to avoid unnecessary CPU load), maxim zing precision but constrained by system clock. In other words, the scenario will play out in "natural" speed, good for previewing or demonstrating sc narios. Each timestep is calculated by esmini based on passed system-time since last frame.

The fixed-time is simpler, esmini will simply execute the scenario as fast as possible applying the specified delta-time for each step. Good for runni g tests for later post processing of resulting logs, data or OSI files.

A common use-case is to run esmini quick/headless and then utilize the replayer for viewing the result. See more info here: Replay scenario

OpenDRIVE allows for non integer string IDs. Although commonly unsigned integer is used. The standard OpenDRIVE 1.8 states that IF the ID represents an integer number, it should comply to uint32_t and stay within the given range.

esmini partly supports* string IDs, by mapping to internal integer IDs. The way it works:

If the ID is a number in the range of 0..0xfffffffe (4 294 967 294), then:
map it to the same internal ID
Else, if the number is a string or a number out of range:
map it to a unique internal ID

Note: 0xffffffff (4 294 967 295) is reserved for ID_UNDEFINED which is the default value and also used for error indication

Example: Assume an OpenDRIVE includes the following road (or junction) IDs:

The IDs will be mapped as follows:

Now, why not make use of available numbers between 1 and 124? It’s because esmini is lazy, not spending effort (performance) to book-keep sorted list of IDs. Instead, only the largest number in use will be monitored.

In addition, there are esmini lib API functions to lookup string and internal IDs:

That way, a custom application can find out what internal IDs esmini has assigned to any non-number string IDs.

Corresponding functions exist in esmini roadmanager lib.

* String ID support was introduced in v2.37.15. By v2.39.0 internal representation changed from 32 bit signed int to unsigned int. At that point also undefined ID changed from -1 to 0xffffffff.

Note: Make sure cmake.preset set to auto to recognize the presets (defined in the CMakePresets.json file). Open setting (Ctrl + ,) type cmake.preset, set auto in drop down box. This is a global setting.

To run:

For Debug, Repeat step 1 and select ubuntu_debug. Repeat step 2 to build debug binaries and then step 4. Breakpoints can be added to the program specified in the launch.json file (do step 3 if not already done).

Build target can also be changed in the status bar, click Set the default build target. If not cmake commands are visible in status bar, check global settings: Ctrl + , then write "cmake status bar" to find Status Bar Visibility setting. Set to visible.

Another way to set build target is via Ctrl+Shift+P, then write "set build target" to find CMake: Set Build Target setting. Select it and choose build target in the drop down list that should appear.

Make sure cmake.preset set to never to ignore the preset file (CMakePresets.json):

Note: This is a global setting, i.e. will affect other VSCode instances. Reset to auto if needed. Another way to ignore the presets is simply to remove the CMakePresets.json file and restart VSCode.

To run:

For debug:

Repeat step 2 and select Debug. Repeat step 3 to 6. Breakpoints can be added to the program specified in the launch.json.

For more info see: https://code.visualstudio.com/docs/cpp/CMake-linux

dev and master branches should be in perfect sync, i.e. based on common history. Unfortunately, to keep this true and to avoid messy history and lost tags, branch history might be changed in rare cases. That can lead to local branch clones out of synch. If that is the case, follow these steps to restore sync of your local branch:

<branch name> might be master or dev, or whatever branch to be restored.

or specifics:

There are two sets of tests on different frameworks:

The unit tests suites are basically C++ code modules of test cases based on the Google Test framework. They range from true unit tests (testing individual classes or functions) to system level tests reading a scenario and inspecting output, e.g. log files or visualization pixel data. The key feature of the unit tests is the possibility to inspect internal objects and variables.

Example: Unittest/RoadManager_test.cpp

The smoke test suite is basically execution of a selection of scenarios with some strategic inspections of the result. Scenario elements and timing can be checked against log file while object info such as position, rotation and speed can be checked against dat file entries. A Python framework handles the execution and gathering of result for convenient checking.

The smoke test script is found here: test/smoke_test.py

For easy execution of all tests, both unit tests and smoke tests, run this main test script: scripts/run_tests.sh, from esmini root folder:

./scripts/run_tests.sh

Tip: On Windows, run it from GIT bash.

XML schema validation ensures scenario files (xosc and xodr) complies with the OpenSCENARIO and OpenDrive XSD schemas. The checks are done by the Python script run_schema_comply.py located in the scripts directory. The schema files are located in the resources/schema directory. From release v2.40, all esmini scenario files are validated against the schemas as part of CI.

The script depends on the xmlschema and lxml Python packages. To install required packages, run:

pip install -r support/python/requirements.txt

Run the XML validation tests:

python3 ./scripts/run_schema_comply.py <path1> [path2] [path3] …​

where path can be an XML file or a directory. Any directory subfolders will be included recursively.

Example 1, check single file:

python3 scripts/run_schema_comply.py resources/xosc/cut-in.xosc

Example 2, check two files:

python3 scripts/run_schema_comply.py resources/xosc/cut-in.xosc resources/xodr/two_plus_one.xodr

Example 3, check two directories:

python3 scripts/run_schema_comply.py resources EnvironmentSimulator

Example 4, check one file and one directory:

python3 scripts/run_schema_comply.py EnvironmentSimulator/Unittest/xosc/conflicting-domains.xosc resources

Tip: Use bash find command to apply finer filtering. Example:

python3 scripts/run_schema_comply.py $(find ./resources ./EnvironmentSimulator -name "follow_route*.xosc" -or -name "*500*.xodr" -or -name "*signs.xodr")

validates all OpenSCENARIO files starting with "follow_route" and all OpenDRIVE files containing "500" or ending basename with "signs" or containing "500", in and under the resource and EnvironmentSimulator folders.

On Ubuntu some combination of gcc and sanitizer randomly cause sanitizer run failure with error message: AddressSanitizer:DEADLYSIGNAL.

If this happens, try the following:

setarch will affect reported architecture from system to sanitizer. bash is to restore shell environment, it can of course be replaced by any shell program, e.g. tcsh.

To revert settings, simply run:

First exit will escape the latter bash environment, the second reverts effect of the setarch command.

Source of setarch tip: https://stackoverflow.com/questions/77894856/possible-bug-in-gcc-sanitizers

Screenshots can be controlled via the API:

nrOfFrames: -1 ⇒ continuously, 0 ⇒ stop, > 0 ⇒ number of frames, e.g. 1=next frame only, 2=next two frames

Images will be stored in current folder with name screen_shot_*.tga (* = counter) for post processing.

Images can also be saved to memory for instant processing. Control the feature with:

state: true ⇒ capture images, false ⇒ don’t capture (default, might improve performance on some systems)

Grab image with:

image is a reference to a SE_Image struct which will contain the image meta and image data

See image-capture code example.

Finally, to disable esmini image handling altogether and revert to OSG default handling, make the following call before SE_Init():

SE_SetOffScreenRendering(false);

Note that disabling the this will permanently disable the callback mechanism for the complete esmini session (overriding any SE_SaveImagesToRAM() call).

Similarly as with camera related launch arguments, camera positioning can be controlled via esmini lib API.

More info, see headerfile.

Any number of cameras can be defined. These cameras can then be activated via function: SE_SetCameraMode().

Applications can even loop through the camera modes to produce images from several cameras. See code example multiple-cameras.cpp.

OSI data can be retrieved in three ways:

OSI provides information needed for sensor models at bounding box level for both moving and stationary objects, including ones defined in OpenDRIVE. Sensor models can then detect overlap, occlusion and collisions between those bounding boxes. Although sensor models are not within scope of esmini, there is a code example on how to retrieve and extract OSI data. It can perhaps be a starting point: osi-groundtruth.cpp

For even simpler use cases esmini provides a sensor mechanism, basically collecting scenario objects which reference point is within a sensor view frustum. This is too rough for collision detection, but can be useful for low-pass features like adaptive cruse control (ACC) or just optimizing CPU load by filtering objects for some processing.

The view frustum is defined by a horizontal field of view combined with near and far limits. Basically an object is detected by a ideal sensor if the object reference point is within the view frustum, i.e:

The sensors are added from the code, see the esmini-dyn code example. API is found here.

Limitations:

Now that you can build and run Hello World, it’s time to explore some functionality of esmini. Next section presents a few code examples to try out, e.g. by modifying main.cpp.

Exercise: Change scenario to pedestrian.xosc, then compile and run the program again.

You can now specify esmini arguments according to esmini launch commands.

Example:

This example shows how to retrieve the state of scenario objects.

We also check the return code from the initialization and react on any error.

A silly example showing how you can just take control over vehicle state via the API. The Ego car will move one meter along the Y-axis for each frame while rotating…​

Now we will also introduce the quit_flag, which lets you quit by pressing 'Esc' key.

In addition we’ll try out the alignment feature. By default objects will be aligned to road surface. This behavior can be controlled with alignment settings. In below example, the Ego vehicle will be aligned to road surface except during iterations 100-200 where it will obey the reported Z coordinate and move accordingly to elevation/Z = 10 meter.

Exercise: Change heading with i, e.g:

SE_ReportObjectPos(0, 0.0f, 8.0f, (float)i, 0.0f, 1.57f + 0.01f*i, 0.0f, 0.0f);

Yes, it looks crazy! But it demonstrates how an application totally can take control of a vehicle.

Try to run cut-in_interactive.xosc, as below.

Control the Ego vehicle with arrow keys.

To disable controllers and hand over to default scenario behavior set first argument flag (see headerfile esminiLib.hpp):

Note: If you want M_PI, add on top (before includes): #define _USE_MATH_DEFINES

There are two approaches to collision detection that fit different use cases:

As an alternative to the external control examples above, you can control the speed of an object directly. Just note that any triggered scenario actions involving the object might conflict with speed settings via lib API. Recommendation is control an object either via API or scenario file. That said, the combination can be useful for some use cases.

The code will modulate speed of Ego (first vehicle) between 2 and 20 mps.

Example run command, from esmini/code-examples-bin folder:
./speed_controller ../resources/xosc/cut-in.xosc

There is also a Python version of this example:
EnvironmentSimulator/code-examples/hello_world/speed_controller.py

This example demonstrates how you can control longitudinal and lateral motion by applying the following actions:

Currently (v2.37.0) the action injection feature is limited to these three actions, but it’s rather easy to extend if needed.

The code will apply three actions according as follows:

Example run command, from esmini/code-examples-bin folder:
./action_injection ../resources/xosc/cut-in.xosc

There is also a Python version of this example:
EnvironmentSimulator/code-examples/hello_world/action_injection.py

Using a simple vehicle model this example demonstrates how a driver model can interact with the scenario in terms of pedal and steering input. This time we use the ExternalController again to ensure any scenario actions is not conflicting with the driver model.

To show different variants we also show how to set scenario parameters during intialization, via callbacks. In effect this is a way to achieve runtime variants of the same basic scenario.

Before heading into the application code we will look into the scenario file EnvironmentSimulator/code-examples/test-driver/test-driver.xosc.

Now, let’s have a look inside it to see how to activate the ExternalController, which will prevent the DefaultController to interfere with the Ego vehicle and instead hand over exclusive control to our application. You can skip this and go to the C++ code example below if you’re not interested in the controller setup.

Note: The GhostMode parameter is set to true or false in the ParameterDeclarations section in the top of the scenario file.

The reason for putting it AFTER the positioning is that oterwise the position action would have no effect, since once the controller is activated all scenario actions will be ignored. The controller then having exclusive control.

Now let’s head into the code example. It will run the scenario three times:

Now, study the code and perhaps play around mainpulating some values.

Don’t worry about the stationary red car on the road, you’ll just drive through it.

Try experimenting with the driver settings, e.g. increase lookahead distance factor from 0.75 to 1.75.

When running the application, press key 'j' to toggle ghost trail dots and lines visualization.

Challenge: Attach a front looking sensor to detect it and have the driver to brake to avoid collision…​