esmini

https://esmini.github.io
Admin
esmini is a software tool that plays OpenSCENARIO XML files, available as both a standalone...
Tokens:115,396
Snippets:1,425
Trust Score:9.7
Update:5 months ago
Show doc for...
Tokens:
Raw
### Run Action Injection Example

Source: https://esmini.github.io/hello-world-tutorial.html

Command to run the action injection example from the esmini/code-examples-bin folder.

```bash
./action_injection ../resources/xosc/cut-in.xosc
```

--------------------------------

### Install OSI for Python

Source: https://esmini.github.io/support-qa.html

Install the Open Simulation Interface (OSI) for Python after setting up Protobuf and the protoc environment variable. This command installs the package from the cloned repository.

```bash
pip install .
```

--------------------------------

### Install Joystick Utilities on Linux

Source: https://esmini.github.io/controllers.html

Install the 'joystick' package using apt to get the 'jstest' utility for testing game controllers.

```bash
sudo apt install joystick
```

--------------------------------

### Simplest esmini Example

Source: https://esmini.github.io/esmini-lib-programming.html

A basic C++ example demonstrating the initialization, stepping, and closing of the esmini library.

```APIDOC
## Simplest esmini Example

### Code

```cpp
#include "./EnvironmentSimulator/Libraries/esminiLib/esminiLib.hpp"

int main()
{
    SE_Init("./resources/xosc/cut-in.xosc", 0, 1, 0, 0);

    while (SE_GetQuitFlag() == 0)
        SE_Step();

    SE_Close();
    return 0;
}
```

### Compile

*   **Linux:**
    `gcc main.cpp ./bin/libesminiLib.so -Wl,-rpath,$ORIGIN -o bin/my_player`
*   **Windows (x64 Native Tools Command Prompt for Visual Studio):**
    `cl main.cpp ./bin/esminiLib.lib /Fe:bin/my_player`

### Run

*   **Linux terminal or Windows PowerShell:**
    `./bin/my_player`
```

--------------------------------

### Install Pre-commit Hooks for esmini

Source: https://esmini.github.io/developers-contributors.html

Install the pre-commit package and then run the install command in the esmini root folder to enable automatic code formatting and static analysis checks on commits.

```bash
pip install pre-commit
pre-commit install
```

--------------------------------

### Build ESMini C# Example

Source: https://esmini.github.io/hello-world-tutorial.html

Commands to build the C# example using CMake. Ensure you are in the 'build' directory created for the project.

```bash
mkdir build
cd build
cmake ..
cmake --build . --config Release
```

--------------------------------

### Command Line Override Example

Source: https://esmini.github.io/monolith.html

Demonstrates launching ESmini with a specific scenario file and a custom configuration file.

```bash
./bin/esmini --osc ./resources/xosc/cut-in.xosc --config_file_path my_settings.yml
```

--------------------------------

### Run ESMini C# Example

Source: https://esmini.github.io/hello-world-tutorial.html

Instructions to run the compiled C# ESMini example. Navigate to the 'esmini/bin' directory to ensure correct relative paths for the scenario file and ESMini library.

```bash
cd ../../../../bin
../EnvironmentSimulator/code-examples/osi-groundtruth-cs/build/Release/osi-groundtruth
```

--------------------------------

### Install pre-commit

Source: https://esmini.github.io/monolith.html

Installs the pre-commit package, which is used for automatic code formatting and static analysis.

```bash
pip install pre-commit
```

--------------------------------

### Install Protobuf for Python on Windows

Source: https://esmini.github.io/support-qa.html

Install the protobuf Python package using pip. Ensure you are using version 3.20.2 as specified.

```bash
pip install protobuf==3.20.2
```

--------------------------------

### esmini Command Line Options Example

Source: https://esmini.github.io/monolith.html

Demonstrates how to specify multiple values for options like 'path' and how the last occurrence wins for single-value options.

```bash
--path /tmp/models /tmp/kalles_models
```

```bash
--logfile_path my_log.txt --logfile_path kalles_log.txt
```

```bash
esmini --osc my_scenario.xosc --disable_stdout
```

--------------------------------

### Install pre-commit hooks

Source: https://esmini.github.io/monolith.html

Installs the pre-commit hooks in the esmini root folder to enable automatic checks when making commits.

```bash
pre-commit install
```

--------------------------------

### Install Asciidoctor and Coderay on Linux

Source: https://esmini.github.io/monolith.html

Installs the necessary tools for generating HTML from AsciiDoc on a Linux system.

```bash
sudo apt install asciidoctor
sudo apt install ruby-coderay
```

--------------------------------

### Install Asciidoctor and Coderay on Windows

Source: https://esmini.github.io/monolith.html

Installs Ruby, Asciidoctor, and Coderay on a Windows system for AsciiDoc to HTML conversion.

```bash
gem install asciidoctor
gem install coderay
gem install asciidoctor-kroki
```

--------------------------------

### Install OpenSceneGraph (Ubuntu)

Source: https://esmini.github.io/openscenegraph-3d-models.html

Install the OpenSceneGraph package on Ubuntu using apt-get.

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

--------------------------------

### Ghost Controller Configuration Example

Source: https://esmini.github.io/controllers.html

This example demonstrates how to configure a scenario where the ghost entity utilizes the 'followRoute' controller. Ensure the ghost controller is listed first if multiple controllers are assigned, as it will be associated with the 'Ego' entity.

```xml
follow_route_ghost_starting_on_route.xosc
```

--------------------------------

### Install Linux Dependencies for esmini Build

Source: https://esmini.github.io/getting-started.html

Installs necessary system tools and libraries on Ubuntu for building esmini from source. Ensure these are present before proceeding with the build.

```bash
sudo apt install build-essential gdb ninja-build git pkg-config libgl1-mesa-dev libpthread-stubs0-dev libjpeg-dev libxml2-dev libpng-dev libtiff5-dev libgdal-dev libpoppler-dev libdcmtk-dev libgstreamer1.0-dev libgtk2.0-dev libcairo2-dev libpoppler-glib-dev libxrandr-dev libxinerama-dev curl cmake black
```

--------------------------------

### Install Graphical Joystick Tester on Linux

Source: https://esmini.github.io/controllers.html

Install the 'jstest-gtk' package using apt to obtain a graphical interface for testing game controllers.

```bash
sudo apt install jstest-gtk
```

--------------------------------

### Install OpenSceneGraph Dependencies (Ubuntu)

Source: https://esmini.github.io/openscenegraph-3d-models.html

Install necessary dependencies for building OpenSceneGraph on Ubuntu using apt-get.

```bash
sudo apt-get build-dep openscenegraph
```

--------------------------------

### Run esmini Example from Command Line

Source: https://esmini.github.io/getting-started.html

Execute an esmini scenario directly from the command line. Specify the window dimensions and the OpenSCENARIO file to load.

```bash
./bin/esmini --window 60 60 800 400 --osc ./resources/xosc/cut-in.xosc
```

--------------------------------

### Log Use Case Example

Source: https://esmini.github.io/monolith.html

Example of running a scenario with metadata enabled, followed by a filtered run focusing on storyboard events. This demonstrates a practical workflow for debugging specific functionalities.

```bash
./bin/esmini --window 60 60 800 400 --osc ./resources/xosc/cut-in.xosc --log_meta_data
```

```bash
./bin/esmini --window 60 60 800 400 --osc ./resources/xosc/cut-in.xosc --log_only_modules Storyboard,StoryboardElement,OSCCondition
```

--------------------------------

### String Concatenation Example

Source: https://esmini.github.io/scenario-features.html

Demonstrates string concatenation using parameters. Ensure parameters are correctly evaluated before concatenation.

```string
${Event_overtake_ + $ActorName}
```

```string
${Event_change_speed_to_ + $Speed}
```

--------------------------------

### Generate Visual Studio Solution on Windows

Source: https://esmini.github.io/monolith.html

Command to generate a Visual Studio solution file for the esmini 'Hello World' example using CMake.

```batch
mkdir build
cd build
cmake .. (will generate solution for multiple variants, including Release and Debug)
```

--------------------------------

### Run ALKS_R157SM Example

Source: https://esmini.github.io/controllers.html

Executes the alks_r157_cut_in_quick_brake.xosc scenario with default settings. Use this to quickly test the controller's behavior.

```bash
./bin/esmini --window 60 60 800 400 --osc ./resources/xosc/alks_r157_cut_in_quick_brake.xosc
```

--------------------------------

### Install Dependencies on CentOS 7

Source: https://esmini.github.io/build-guide.html

Commands to install essential development tools and libraries on CentOS 7 required for building esmini. This includes git, cmake, C++ compiler, and graphical libraries.

```bash
sudo yum install git
sudo yum install cmake
sudo yum install gcc-c++

sudo yum install freeglut-devel
sudo yum install fontconfig-devel
sudo yum install libXrandr-devel
sudo yum install libXinerama-devel

sudo yum install epel-release
sudo yum install p7zip
```

--------------------------------

### Example Log Excerpt

Source: https://esmini.github.io/monolith.html

A sample of log output showing info-level messages related to storyboard events, actions, and conditions, including timestamps and module names.

```text
...
[0.001] [info] OverTakerStartSpeedEvent standbyState -> startTransition -> runningState
[0.001] [info] OverTakerStartSpeedAction initState -> startTransition -> runningState
[6.179] [info] Trigger /------------------------------------------------
[6.179] [info] CutInStartCondition == true, HWT: 0.40 > 0.40, edge rising
[6.179] [info] Triggering entity 0: Ego
[6.179] [info] Trigger  ------------------------------------------------/
[6.179] [info] OverTakerStartSpeedAction runningState -> endTransition -> completeState
[6.179] [info] OverTakerStartSpeedEvent complete after 1 execution
[6.179] [info] OverTakerStartSpeedEvent runningState -> endTransition -> completeState
[6.179] [info] Event OverTakerStartSpeedEvent ended, overwritten by event CutInEvent
[6.179] [info] CutInEvent standbyState -> startTransition -> runningState
[6.179] [info] CutInAction initState -> startTransition -> runningState
[7.696] [info] Trigger /------------------------------------------------
[7.696] [info] BrakeCondition_HWT_0.7 == true, HWT: 0.70 > 0.70, edge rising
[7.696] [info] Triggering entity 0: Ego
[7.696] [info] Trigger  ------------------------------------------------/
[7.696] [info] Other events ongoing, OvertakerBrakeEvent will run in parallel
[7.696] [info] OvertakerBrakeEvent standbyState -> startTransition -> runningState
...
```

--------------------------------

### Generate Makefile on Linux

Source: https://esmini.github.io/monolith.html

Commands to generate a Makefile for the esmini 'Hello World' example on Linux using CMake, specifying the build type.

```bash
mkdir build
cd build
cmake .. -DCMAKE_BUILD_TYPE=Release for Release variant, or
cmake .. -DCMAKE_BUILD_TYPE=Debug for Debug variant
```

--------------------------------

### Run OpenSCENARIO Example with Absolute Path

Source: https://esmini.github.io/run-asam-examples.html

Execute an OpenSCENARIO file using esmini from the command line with an absolute path. This is useful when the relative path is not straightforward.

```bash
./bin/esmini --window 60 60 800 400 --osc c:/stuff/openscenario-v1.1.0/Examples/DoubleLaneChanger.xosc
```

--------------------------------

### Build esmini with Make (Linux)

Source: https://esmini.github.io/build-guide.html

On Linux, after configuring with CMake, you can use the 'make' utility directly to build the project. This command builds all projects in parallel and installs them.

```bash
cd build
make -j4 install
```

--------------------------------

### Get Option Value by Name

Source: https://esmini.github.io/developers-contributors.html

Retrieve the value of a configuration option using its string name. Suitable for infrequent access or initial setup.

```c++
std::string GetOptionValue(std::string option_name);
```

--------------------------------

### Basic ESMini Simulation Setup

Source: https://esmini.github.io/esmini-lib-programming.html

Initialize the ESMini environment with a given scenario file, then run the simulation step by step until the quit flag is set. Finally, close the simulation environment.

```cpp
#include "./EnvironmentSimulator/Libraries/esminiLib/esminiLib.hpp"

int main()
{
    SE_Init("./resources/xosc/cut-in.xosc", 0, 1, 0, 0);

    while (SE_GetQuitFlag() == 0)
        SE_Step();

    SE_Close();
    return 0;
}
```

--------------------------------

### Define OpenDRIVE Tunnel

Source: https://esmini.github.io/scenario-features.html

Define a tunnel using the OpenDRIVE tunnel element. This example shows basic tunnel properties like start position, length, name, and ID.

```xml
<tunnel s="30.0" length="250.0" name="MyTunnel" id="1" type="standard"/>
```

--------------------------------

### Option Precedence Example

Source: https://esmini.github.io/command-reference.html

When multiple '--path' options are provided, esmini searches in the last specified directory first. This demonstrates precedence for multi-value options.

```bash
--path /tmp/my_car_models --path /tmp/kalles_car_models
```

--------------------------------

### Initialize esmini with Flexible Arguments

Source: https://esmini.github.io/hello-world-tutorial.html

Demonstrates initializing esmini using `SE_InitWithArgs` by passing a list of arguments, offering more flexibility than the basic `SE_Init` function. Ensure the esmini shared library is accessible.

```python
'''
   demonstrate how to initialize esmini with arguments instead of a few limited arguments
   using ideas from: https://comp.lang.python.narkive.com/RUdYlz64/trying-to-pass-sys-argv-as-int-argc-char-argv-using-ctypes

   Instruction:
     - make sure the esmini shared library (esminiLib.dll or esminiLib.so) is present in esmini/bin folder
     - if not, either compile esmini (see User guide) or fetch bin package release
     - from this folder (where this code module is), run: python ./init_by_args.py
'''

import ctypes as ct
import sys

if sys.platform == "linux" or sys.platform == "linux2":
    se = ct.CDLL("../../../bin/libesminiLib.so")
elif sys.platform == "darwin":
    se = ct.CDLL("../../../bin/libesminiLib.dylib")
elif sys.platform == "win32":
    se = ct.CDLL("../../../bin/esminiLib.dll")
else:
    print("Unsupported platform: {}".format(platform))
    quit()

# specify arguments types of esmini function
se.SE_InitWithArgs.argtypes = [ct.c_int, ct.POINTER(ct.POINTER(ct.c_char))]

# create the list of arguments
args = [
    "--window", "60", "60", "800", "400",
    "--osc", "../resources/xosc/cut-in.xosc",
    ]

# prepare argument list for ctypes use
argv = (ct.POINTER(ct.c_char) * len(args))()
argc = len(argv)
for i, arg in enumerate(args):
    argv[i] = ct.create_string_buffer(arg.encode())

# init esmini
if se.SE_InitWithArgs(argc, argv) != 0:
    exit(-1)

# execute esmini until end of scenario or user requested quit by ESC key
while se.SE_GetQuitFlag() == 0:
    se.SE_Step()
```

--------------------------------

### Action Injection Python Example

Source: https://esmini.github.io/hello-world-tutorial.html

Location of the Python version of the action injection example.

```python
EnvironmentSimulator/code-examples/hello_world/action_injection.py
```

--------------------------------

### Create Build Directory and Configure CMake (Windows)

Source: https://esmini.github.io/hello-world-tutorial.html

Generates Visual Studio solution files for the esmini player application. Run from the 'Hello-World_coding-example' root folder.

```bash
mkdir build
cd build
cmake ..
```

--------------------------------

### Initialize and Run esmini Simulator

Source: https://esmini.github.io/hello-world-tutorial.html

Initializes the esmini simulator with command line arguments and executes the scenario step by step until the quit flag is set.

```python
import ctypes as ct
import sys

# fetch command line arguments
argc = len(sys.argv)
argv = (ct.POINTER(ct.c_char) * (argc + 1))()
for i, arg in enumerate(sys.argv):
    argv[i] = ct.create_string_buffer(arg.encode('utf-8'))

# init esmini
if ct.SE_InitWithArgs(argc, argv) != 0:
    exit(-1)

# execute esmini until end of scenario or user requested quit by ESC key
while ct.SE_GetQuitFlag() == 0:
    ct.SE_Step()
```

--------------------------------

### Basic esmini Build with CMake

Source: https://esmini.github.io/build-guide.html

Standard commands to clone, configure, and build esmini. Ensure you are in the esmini root folder before executing.

```bash
git clone https://github.com/esmini/esmini
cd esmini
mkdir build
cd build
cmake ..
cmake --build . --config Release --target install
```

--------------------------------

### Fetch and Process OSI Groundtruth Data in C++

Source: https://esmini.github.io/monolith.html

This C++ example demonstrates initializing the simulator, fetching OSI groundtruth data, and iterating through frames to print object information. Ensure OSI headers are included and the simulator is initialized with a valid scenario file.

```cpp
#include "esminiLib.hpp"

#include "osi_common.pb.h"
#include "osi_object.pb.h"
#include "osi_groundtruth.pb.h"
#include "osi_version.pb.h"

int main(int argc, char* argv[])
{
    (void)argc;
    (void)argv;
    const osi3::GroundTruth* gt;

    SE_EnableOSIFile(0);  // 0 or "" will result in default filename, ground_truth.osi
    SE_SetOSIStaticReportMode(SE_OSIStaticReportMode::DEFAULT);

    SE_Init("../resources/xosc/cut-in_simple.xosc", 0, 1, 0, 0);

    // Fetch initial OSI struct, this will also update the OSI data
    gt = reinterpret_cast<const osi3::GroundTruth*>(SE_GetOSIGroundTruthRaw());

    // Lane boundaries (static road info only available in first OSI frame)
    printf("lane boundaries: %d\n", gt->lane_boundary_size());
    for (int j = 0; j < gt->lane_boundary_size(); j++)
    {
        printf("  lane boundary %d, nr of boundary points: %d\n", j, gt->lane_boundary(j).boundary_line_size());

#if 0  // change to 1 in order to print all boundary points
                        for (int k = 0; k < gt->lane_boundary(j).boundary_line_size(); k++)
                        {
                                printf("    (%.2f, %.2f)\n",
                                        gt->lane_boundary(j).boundary_line(k).position().x(),
                                        gt->lane_boundary(j).boundary_line(k).position().y());
                        }
#endif
    }

    for (int i = 0; i < 4; i++)
    {
        SE_StepDT(0.01);  // ground truth will be automatically updated each step if we have either an OSIFile or fetched a pointer to the
                          // osi3::GroundTruth struct

        // Print timestamp
        printf("Frame %d timestamp: %.2f\n",
               i + 1,
               static_cast<double>(gt->timestamp().seconds()) + 1E-9 * static_cast<double>(gt->timestamp().nanos()));

        // Static content such as lane boundaries should be 0 at this point (we have SE_OSIStaticReportMode::DEFAULT, change to API or API_AND_LOG to
        // get static data)
        printf("lane boundaries: %d\n", gt->lane_boundary_size());

        // Road markings, e.g. zebra lines
        printf("road markings: %d\n", gt->road_marking_size());

        // Moving objects
        printf("moving objects: %d\n", gt->moving_object_size());

#if 1  // change to 1 in order to print some moving object state info
       // Print object id, position, orientation and velocity
        for (int j = 0; j < gt->moving_object().size(); j++)
        {
            printf("  obj id %u pos (%.2f, %.2f, %.2f) orientation (%.2f, %.2f, %.2f) vel (%.2f, %.2f, %.2f) acc (%.2f, %.2f, %.2f)\n",
                   static_cast<unsigned int>(gt->moving_object(j).id().value()),
                   gt->moving_object(j).base().position().x(),
                   gt->moving_object(j).base().position().y(),
                   gt->moving_object(j).base().position().z(),
                   gt->moving_object(j).base().orientation().yaw(),
                   gt->moving_object(j).base().orientation().pitch(),
                   gt->moving_object(j).base().orientation().roll(),
                   gt->moving_object(j).base().velocity().x(),
                   gt->moving_object(j).base().velocity().y(),
                   gt->moving_object(j).base().velocity().z(),
                   gt->moving_object(j).base().acceleration().x(),
                   gt->moving_object(j).base().acceleration().y(),
                   gt->moving_object(j).base().acceleration().z());
        }
#endif

        // Moving objects
        printf("stationary objects: %d\n", gt->stationary_object_size());
    }

    SE_Close();

    return 0;
}
```

--------------------------------

### Install Mesa3D Utilities on Linux

Source: https://esmini.github.io/use-cases.html

Installs the necessary utilities for Mesa3D software rendering on Debian-based Linux distributions.

```bash
sudo apt install mesa-utils
```

--------------------------------

### esmini Execution with Recording and Logging Options

Source: https://esmini.github.io/monolith.html

Illustrates executing esmini with options for recording simulation data (.dat), Open Simulation Interface (.osi) files, and CSV logging. Output files are named with permutation information.

```bash
./bin/esmini --window 60 60 800 400 --osc ./resources/xosc/cut-in_parameter_set.xosc --record sim.dat --osi_file gt.osi --csv_logger data_log.csv
```

--------------------------------

### Run OpenSCENARIO Example with Relative Path

Source: https://esmini.github.io/run-asam-examples.html

Execute an OpenSCENARIO file using esmini from the command line with a relative path. Ensure esmini is in the root folder and the scenario file is accessible.

```bash
./bin/esmini --window 60 60 800 400 --osc ../../openscenario-v1.1.0/Examples/DoubleLaneChanger.xosc
```

--------------------------------

### Install XML Schema Validation Dependencies

Source: https://esmini.github.io/developers-contributors.html

Install the required Python packages (xmlschema and lxml) for XML schema validation.

```bash
pip install -r support/python/requirements.txt
```

--------------------------------

### Install esmini Python Dependencies

Source: https://esmini.github.io/developers-contributors.html

Install the required Python packages for esmini development using the provided requirements file.

```bash
pip install -r ./support/python/requirements.txt
```

--------------------------------

### Load and Play a Scenario in C++

Source: https://esmini.github.io/hello-world-tutorial.html

Initializes the esmini environment with a specified scenario file and steps through simulation frames. Use this for basic scenario playback.

```cpp
#include "esminiLib.hpp"

int main(int argc, char* argv[])
{
        SE_Init("../../resources/xosc/cut-in.xosc", 0, 1, 0, 0);

        for (int i = 0; i < 500; i++)
        {
                SE_Step();
        }

        SE_Close();

        return 0;
}

```

--------------------------------

### Install MSYS2 Packages

Source: https://esmini.github.io/monolith.html

Installs essential development tools and libraries for esmini on MSYS2. Ensure MSYS2 is updated before running these commands.

```bash
pacman -Syu --disable-download-timeout --noconfirm
pacman -Su --disable-download-timeout --noconfirm
pacman -S --needed base-devel mingw-w64-x86_64-toolchain --disable-download-timeout --noconfirm
pacman -S mingw-w64-x86_64-cmake --disable-download-timeout --noconfirm
```

--------------------------------

### Build Slim esmini with Custom Dependencies

Source: https://esmini.github.io/build-guide.html

Configure the build by disabling optional external dependencies like OSG, OSI, SUMO, and googletest. All options are true by default.

```bash
cmake .. -D USE_OSG=False -D USE_SUMO=False
```

```bash
cmake .. -D USE_OSG=False -D USE_SUMO=False -D USE_OSI=False -D USE_GTEST=False -D USE_IMPLOT=False
```

--------------------------------

### Initialize esmini with Command Line Arguments

Source: https://esmini.github.io/monolith.html

Initializes the esmini simulator using command-line arguments passed to the script. Ensure the esmini shared library is accessible.

```python
import ctypes as ct
import sys

# fetch command line arguments
argc = len(sys.argv)
argv = (ct.POINTER(ct.c_char) * (argc + 1))()
for i, arg in enumerate(sys.argv):
    argv[i] = ct.create_string_buffer(arg.encode('utf-8'))

# init esmini
if ct.CDLL("../bin/libesminiLib.so").SE_InitWithArgs(argc, argv) != 0:
    exit(-1)

# execute esmini until end of scenario or user requested quit by ESC key
while ct.CDLL("../bin/libesminiLib.so").SE_GetQuitFlag() == 0:
    ct.CDLL("../bin/libesminiLib.so").SE_Step()
```

--------------------------------

### Junction ID String Functions

Source: https://esmini.github.io/support-qa.html

API functions to get the string representation of a junction ID or to get the internal ID from a string.

```APIDOC
## Junction ID String Functions

### Description
Provides functions to interact with junction IDs, allowing conversion between string representations and internal integer IDs.

### Functions

- **SE_GetJunctionIdString**
  - **Description**: Retrieves the string representation of a given junction ID.
  - **Parameters**:
    - `junction_id` (id_t) - The internal junction ID.
  - **Returns**:
    - `const char *` - The string representation of the junction ID.

- **SE_GetJunctionIdFromString**
  - **Description**: Retrieves the internal ID corresponding to a given junction ID string.
  - **Parameters**:
    - `junction_id_str` (const char *) - The string representation of the junction ID.
  - **Returns**:
    - `id_t` - The internal junction ID.

```

--------------------------------

### Build esmini from Source

Source: https://esmini.github.io/getting-started.html

Steps to configure, build, and install esmini using CMake from the project's root directory. This process downloads necessary third-party binaries and assets.

```bash
mkdir build
cd build
cmake ..
cmake --build . --config Release --target install
```

--------------------------------

### Road ID String Functions

Source: https://esmini.github.io/support-qa.html

API functions to get the string representation of a road ID or to get the internal ID from a string.

```APIDOC
## Road ID String Functions

### Description
Provides functions to interact with road IDs, allowing conversion between string representations and internal integer IDs.

### Functions

- **SE_GetRoadIdString**
  - **Description**: Retrieves the string representation of a given road ID.
  - **Parameters**:
    - `road_id` (id_t) - The internal road ID.
  - **Returns**:
    - `const char *` - The string representation of the road ID.

- **SE_GetRoadIdFromString**
  - **Description**: Retrieves the internal ID corresponding to a given road ID string.
  - **Parameters**:
    - `road_id_str` (const char *) - The string representation of the road ID.
  - **Returns**:
    - `id_t` - The internal road ID.

```

--------------------------------

### C++ esmini Driver Model Example

Source: https://esmini.github.io/monolith.html

This C++ code demonstrates initializing and running an esmini scenario with an ExternalController. It registers a callback for parameter declarations and sets up the vehicle's initial state and control parameters.

```cpp
#include "stdio.h"
#include "math.h"
#include <string>
#include "esminiLib.hpp"

void paramDeclCB(void* user_arg)
{
    bool ghostMode = *(static_cast<bool*>(user_arg));

    SE_LogMessage((std::string("Running with ghostMode = ").append(ghostMode == true ? "true" : "false")).c_str());
    SE_SetParameterBool("GhostMode", ghostMode);
}

int main(int argc, char* argv[])
{
    (void)argc;
    (void)argv;

    const double defaultTargetSpeed = 50.0;
    const double curveWeight        = 30.0;
    const double throttleWeight     = 0.1;
    const double duration           = 35.0;
    bool         ghostMode[3]       = {false, true, true};

    SE_SimpleVehicleState  vehicleState = {0, 0, 0, 0, 0, 0, 0, 0};
    SE_ScenarioObjectState objectState;
    SE_RoadInfo            roadInfo;

    for (int i = 0 < 3; i++)
    {
        SE_RegisterParameterDeclarationCallback(paramDeclCB, &ghostMode[i]);

        if (SE_Init("../EnvironmentSimulator/code-examples/test-driver/test-driver.xosc", 0, 1, 0, 0) != 0)
        {
            SE_LogMessage("Failed to initialize the scenario, quit\n");
            return -1;
        }

        // Lock object to the original lane
        // If setting to false, the object road position will snap to closest lane
        SE_SetLockOnLane(0, true);

        // Initialize the vehicle model, fetch initial state from the scenario
        SE_GetObjectState(0, &objectState);
        void* vehicleHandle = SE_SimpleVehicleCreate(objectState.x, objectState.y, objectState.h, 4.0, 0.0);
        SE_SimpleVehicleSteeringRate(vehicleHandle, 6.0);

```

--------------------------------

### Install MSYS2 Packages

Source: https://esmini.github.io/build-guide.html

Commands to update MSYS2 packages and install the necessary toolchain and CMake for compiling esmini within the MSYS2 environment.

```bash
pacman -Syu --disable-download-timeout --noconfirm
```

```bash
pacman -Su --disable-download-timeout --noconfirm
pacman -S --needed base-devel mingw-w64-x86_64-toolchain --disable-download-timeout --noconfirm
pacman -S mingw-w64-x86_64-cmake --disable-download-timeout --noconfirm
```

```bash
pacman -S git --disable-download-timeout --noconfirm
```

--------------------------------

### Condition Delay Example

Source: https://esmini.github.io/scenario-features.html

Demonstrates delaying conditions within trigger groups. This example uses simulation time and speed thresholds with varying delays.

```xml
C1: SimulationTime ≥ 6.0 | 0.0 | none
C2: Speed ≥ 25.0 | 0.0 | none
C3: SimulationTime ≥ 6.0 | 0.0 | none
C4: Speed ≥ 25.0 | 2.0 | rising
C5: SimulationTime ≥ 6.0 | 0.0 | none
C6: Speed ≥ 25.0 | 4.0 | none
```

--------------------------------

### Install CentOS 7 Packages for esmini

Source: https://esmini.github.io/monolith.html

Installs necessary development packages on CentOS 7, including git, cmake, C++ compiler, and various graphical/font libraries.

```bash
sudo yum install git
sudo yum install cmake
sudo yum install gcc-c++
sudo yum install freeglut-devel
sudo yum install fontconfig-devel
sudo yum install libXrandr-devel
sudo yum install libXinerama-devel
sudo yum install epel-release
sudo yum install p7zip
```

--------------------------------

### OpenSCENARIO NURBS Trajectory Example

Source: https://esmini.github.io/scenario-construction-tips.html

This example demonstrates the use of NURBS for defining smooth trajectories in OpenSCENARIO. NURBS are recommended for smooth movements like lane changes.

```xml
<OpenSCENARIO>
  <FileHeader revMajor="1" revMinor="0" date="2023-10-27T10:00:00" description="NURBS Trajectory Example" author="Example Author"/>
  <ParameterDeclarations/>
  <CatalogLocations/>
  <RoadNetwork>
    <LogicRoadNetwork authority="esmini">
      <CenterRoadNetwork>
        <Properties>
          <Property name="file" value="example_road.xodr"/>
        </Properties>
      </CenterRoadNetwork>
    </LogicRoadNetwork>
  </RoadNetwork>
  <Entities>
    <ScenarioObject name="Ego">
      <Vehicle name="vehicle.tesla.model_3" vehicleCategory="car">
        <ParameterDeclarations/>
      </Vehicle>
    </ScenarioObject>
    <ScenarioObject name="Target">
      <Vehicle name="vehicle.audi.rs7" vehicleCategory="car">
        <ParameterDeclarations/>
      </Vehicle>
    </ScenarioObject>
  </Entities>
  <Storyboard>
    <Init>
      <Actions>
        <GlobalAction>
          <EnvironmentAction>
            <Environment name="Environment1">
              <TimeOfDay dynamic="false" வேளாண்="10:00:00"/>
              <Weather cloudiness="0.2" precipitation="0.0" temperature="20.0" dynamic="false"/>
              <RoadCondition frictionScaleFactor="1.0"ヤー="false"/>
            </Environment>
          </EnvironmentAction>
        </GlobalAction>
        <UserDefinedAction>
          <PrivateAction entityRef="Ego">
            <TeleportAction>
              <Position>
                <WorldPosition x="0.0" y="0.0" z="0.0" h="0.0"/>
              </Position>
            </TeleportAction>
          </PrivateAction>
        </UserDefinedAction>
        <UserDefinedAction>
          <PrivateAction entityRef="Target">
            <TeleportAction>
              <Position>
                <WorldPosition x="-50.0" y="0.0" z="0.0" h="0.0"/>
              </Position>
            </TeleportAction>
          </PrivateAction>
        </UserDefinedAction>
      </Actions>
    </Init>
    <Story name="MyStory">
      <Act name="MyAct">
        <ManeuverGroup maximumExecutionCount="1" name="TargetManeuver">
          <Actors>
            <EntityRef entityRef="Target"/>
          </Actors>
          <Maneuver name="CutInManeuver">
            <Event name="CutInEvent" priority="overwrite">
              <ActionSequence>
                <PrivateAction entityRef="Target">
                  <FollowTrajectoryAction>
                    <Trajectory name="CutInTrajectory">
                      <RateChange target="0.5" name="speed"/>
                      < NURBS name="nurbs_curve">
                        <controlPoint>
                          <x>0.0</x>
                          <y>0.0</y>
                          <z>0.0</z>
                        </controlPoint>
                        <controlPoint>
                          <x>10.0</x>
                          <y>2.0</y>
                          <z>0.0</z>
                        </controlPoint>
                        <controlPoint>
                          <x>20.0</x>
                          <y>0.0</y>
                          <z>0.0</z>
                        </controlPoint>
                        <degree>2</degree>
                      </NURBS>
                    </Trajectory>
                  </FollowTrajectoryAction>
                </PrivateAction>
              </ActionSequence>
              <StartTrigger>
                <ConditionGroup>
                  <Condition name="StartCondition" delay="0" conditionEdge="rising">
                    <ByValue>
                      <SimulationTimeCondition value="2.0" rule="greaterThan"/>
                    </ByValue>
                  </Condition>
                </ConditionGroup>
              </StartTrigger>
            </Event>
          </Maneuver>
        </ManeuverGroup>
        <StartTrigger/>
      </Act>
    </Story>
    <StopTrigger/>
  </Storyboard>
</OpenSCENARIO>
```

--------------------------------

### Build All 3rd Party Libraries (OSI, SUMO, OSG)

Source: https://esmini.github.io/build-guide.html

A combined script to generate or rebuild all three main 3rd party libraries: OSI, SUMO, and OSG.

```bash
scripts/generate_osi_sumo_osg_libs.sh
```

--------------------------------

### Set and Get String Parameter with esminiLib

Source: https://esmini.github.io/inner-workings.html

Shows how to set and get a string parameter using esminiLib. Note the use of .c_str() for printing and the necessary casting when retrieving the value.

```c++
std::string myString = "Hello";
SE_Parameter param;
param.name = "MyStringParameter";
param.value = &myString;
SE_SetParameter(param);
SE_GetParameter(&param);
printf("param value: %s\n", myString.c_str());
// or by casting the value
printf("param value: %s\n", (*((std::string*)param.value)).c_str());
```

--------------------------------

### Enable OSI Tracefile

Source: https://esmini.github.io/esmini-lib-programming.html

Enable the creation of an OSI tracefile. Specify a custom filename or use the default 'ground_truth.osi'.

```c
SE_EnableOSIFile(filename);
```

--------------------------------

### Handling Spaces in Path Values (Bad Example)

Source: https://esmini.github.io/command-reference.html

Without quotes, spaces in path values are treated as argument separators, leading to incorrect path parsing. This example shows an unintended outcome.

```yaml
esmini:
  path: ./resources/my scenarios /tmp
```

--------------------------------

### XML Schema Validation: Single File

Source: https://esmini.github.io/monolith.html

Example of validating a single OpenSCENARIO file against its schema.

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

--------------------------------

### Run esmini Player (Linux)

Source: https://esmini.github.io/hello-world-tutorial.html

Launches the esmini player application from the command line. This command should be executed from the 'build' directory.

```bash
./esmini-player
```

--------------------------------

### Build esmini App from Command Line (Linux)

Source: https://esmini.github.io/monolith.html

Commands to build the esmini application on Linux using CMake or Make.

```bash
cmake --build . or just
make
```

--------------------------------

### Program Options API

Source: https://esmini.github.io/monolith.html

Functions to set and get program options, with options for persistent settings across runs.

```APIDOC
## Program Options API

### Description
Provides functions to manage program options, including setting and unsetting them, with variants for persistent storage across multiple scenario runs.

### Functions

- `SE_SetOption(const char *name)`: Sets an option without persistence.
- `SE_SetOptionPersistent(const char *name)`: Sets an option persistently.
- `SE_SetOptionValue(const char *name, const char *value)`: Sets an option with a specific value without persistence.
- `SE_SetOptionValuePersistent(const char *name, const char *value)`: Sets an option with a specific value persistently.
- `SE_UnsetOption(const char *name)`: Unsets an option.
- `SE_GetOptionValue(const char *name)`: Retrieves the current value of an option.
- `SE_GetOptionValueByEnum(unsigned int)`: Retrieves an option value using an enum (refer to 'Using options (in code)' for details).
```

--------------------------------

### Build 3rd Party Libraries (SUMO)

Source: https://esmini.github.io/build-guide.html

Shell script to generate or rebuild the SUMO (Simulation of Urban MObility) libraries.

```bash
scripts/generate_sumo_libs.sh
```

--------------------------------

### Set Protoc Environment Variable

Source: https://esmini.github.io/support-qa.html

Set the PROTOC environment variable to the location of your protoc.exe. This is required for the OSI installation process.

```powershell
$env:PROTOC="C:/tmp/protoc-3.20.2-win64/bin/protoc.exe"
```

--------------------------------

### Initialize and Process OSI Ground Truth in C#

Source: https://esmini.github.io/hello-world-tutorial.html

This C# code demonstrates how to initialize the ESMini simulator, step through the simulation, retrieve OSI ground truth messages, and parse them to extract information about moving objects. It requires the ESMiniWrapper.cs and is targeted for Windows, but may work on Linux if the wrapper is adapted.

```csharp
using System;
using System.Runtime.InteropServices;
using ESMini;

using Google.Protobuf;

using static Osi3.GroundTruth;

namespace esmini_csharp
{
    class Program
    {
        static void Main(string[] args)
        {
            // initialize esmini
            if (ESMiniLib.SE_Init("../resources/xosc/cut-in.xosc", 0, 1, 0, 0) != 0)
            {
                Console.WriteLine("failed to load scenario");
                return;
            }

            int size = 0;
            while (ESMiniLib.SE_GetQuitFlag() != 1)
            {
                // Step esmini
                ESMiniLib.SE_Step();

                // Get OSI message
                IntPtr int_ptr = ESMiniLib.SE_GetOSIGroundTruth(ref size);
                Byte[] byte_array = new Byte[size];
                Marshal.Copy(int_ptr, byte_array, 0, size);
                Osi3.GroundTruth gt_msg = Osi3.GroundTruth.Parser.ParseFrom(byte_array);

                // Write some info from OSI message
                Console.WriteLine("Time: {0:N3}", gt_msg.Timestamp.Seconds + 1e-9 * gt_msg.Timestamp.Nanos);
                foreach (Osi3.MovingObject o in gt_msg.MovingObject)
                {
                    Console.WriteLine("  Object[{0}], Pos: {1:N2}, {2:N2}, {3:N2}",
                        o.Id.Value, o.Base.Position.X, o.Base.Position.Y, o.Base.Position.Z);
                }
            }
        }
    }
}
```

--------------------------------

### XML Schema Validation: File and Directory

Source: https://esmini.github.io/monolith.html

Example of validating a single scenario file and all files within a directory against their schemas.

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

--------------------------------

### Configure and Build esmini on CentOS 7

Source: https://esmini.github.io/build-guide.html

Configure esmini with specific CMake options for CentOS 7 (disabling SUMO and OSI, enabling OSG) and then build and install the project. This also includes cloning the repository and setting up the build directory.

```bash
git clone https://github.com/esmini/esmini

cd esmini

cd externals
mkdir OpenSceneGraph
cd OpenSceneGraph
curl -L "https://www.dropbox.com/s/mxztf6zbgojyntp/osg_centos.7z?dl=1" -o osg_centos.7z
7za x osg_centos.7z
rm osg_centos.7z

cd ../..
mkdir build
cd build
cmake -D USE_OSG=True -D USE_SUMO=False -D USE_OSI=False -D USE_GTEST=False ..
cmake --build . --target install --config Release
cd ..
./bin/esmini.exe --headless --fixed_timestep 0.01 --record sim.dat --osc ./resources/xosc/cut-in.xosc
```

--------------------------------

### XML Schema Validation: Two Directories

Source: https://esmini.github.io/monolith.html

Example of validating all scenario files within two specified directories against their schemas.

```bash
python3 scripts/run_schema_comply.py resources EnvironmentSimulator
```

--------------------------------

### Traffic Light Specification in OpenDRIVE

Source: https://esmini.github.io/scenario-features.html

Example of how a traffic light is specified in OpenDRIVE, indicating it is dynamic and using the 'OpenDRIVE' country.

```xml
<trafficLight dynamic="yes" country="OpenDRIVE" type="1" subtype="1"/>
```

--------------------------------

### Launching esmini with Scenario File

Source: https://esmini.github.io/command-reference.html

This command launches esmini and specifies the scenario file to be used. It applies basic settings only.

```bash
./bin/esmini --osc ./resources/xosc/cut-in.xosc
```
Tokens:
Raw