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

To concatenate multiple files, first create a text file listing the input files. Example:

video_list.txt:

Then run the ffmpeg command, like: ffmpeg -f concat -i video_list.txt -c copy merged.mkv

Note: The input files must be same timebase and resolution to work well.

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 filename can be customized.

The log file 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

esmini has enhanced logger from release v2.41.0 supporting log verbosity levels, log file appending, enabling/disabling meta data and filtering on module level logging.

From version 2.54.0 esmini implements a package-based .dat file format. The new format comes with increased flexibility without unnecessary file size growth. It supports gradually adding/removing content in the .dat files without breaking compatibility. Packages consists of header (packet ID and packet size) and the data. This file can later be used either to replay (see Replay scenario) the scenario or convert it to .csv for further analysis, e.g. in Excel.

A list of available packet IDs and packet structure etc. can be found in:
EnvironmentSimulator/Modules/ScenarioEngine/SourceFiles/PacketHandler.hpp

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:
./bin/dat2csv sim.dat

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

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.

The new .dat file format starts at version 3.0, succeeding version 2. The version is written to the file header. The versioning follows semantic versioning principles, where:

Replaying a .dat file created with a different minor version, both previous and future, is supported. For example, replay a .dat file created with esmini version 3.7 using replayer version 3.5, and vice versa. However, due to the nature of the changes, the replay behavior can’t be guaranteed to be identical between minor versions. For example, content added via a new package in a newer minor version will not be present when replaying with an older minor version. In summary, replayer will gracefully skip unknown packages while showing all recognized ones.

If the major version of the .dat file differs from the replayer version, replay is not supported. For example, a .dat file created with version 4.1 cannot be replayed using version 3.8, and vice versa. Either the .dat file has to be recreated using the same major version as the replayer, or the replayer has to be updated/downgraded to match the major version of the .dat file.

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, 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.