Skip to content
Snippets Groups Projects
Ziqi Zhou's avatar
Ziqi Zhou authored
Feat: support road coordinate in time headway condition

See merge request eclipse/openpass/openscenario1_engine!247
0d0543d6
History

OpenScenarioEngine

User Guide

The OpenScenarioEngine is an implementation of the component OpenSCENARIO Director, as proposed by ASAM OpenSCENARIO XML:

An OpenSCENARIO Director (OSC Director) is a component that interprets the OSC Model Instance and governs the progress of a scenario in a simulation. The OSC Director is the component responsible for running the scenario.

Usage

The engine has several dependencies, which are managed by submodules which are checked out into engine/deps. For a detailed overview of the dependencies please refer to the Architecture Documentation.

Prerequisites

The engine internally uses the OpenScenarioLib, which need to be built manually (please refer to the build instructions) before configuring using CMake.

For CMake to find the library, you need to tell it where the pre-built libraries are via the CMAKE_PREFIX_PATH, which can be done e.g. by adding the following lines to the .bashrc (if you use bash):

CMAKE_PREFIX_PATH=<path_to_engine>/engine/deps/openscenario_api/cpp/build/cgReleaseMakeShared/expressionsLib:<path_to_engine>/engine/deps/openscenario_api/cpp/build/cgReleaseMakeShared/openScenarioLib:<path_to_engine>/engine/deps/openscenario_api/cpp/build/cgReleaseMakeShared/antlr4_runtime/src/antlr4_runtime/runtime/Cpp/dist:$CMAKE_PREFIX_PATH

Building the Engine

Linux

# STARTING FROM ROOT OF REPOSITORY

# get dependencies
git submodule init
git submodule update

# building the openscenario_api
# this might differ on your machine → see official build instructions
cd engine/deps/openscenario_api/cpp/buildArtifact
chmod +x generateLinux.sh
./generateLinux.sh shared release make parallel

cd ../../../.. # back to engine
cmake -S . -B build
cd build
make OpenScenarioEngine

Windows (MINGW64 - experimental)

# STARTING FROM ROOT OF REPOSITORY

# get dependencies
git submodule init
git submodule update

# patching openscenario_api for MinGW64
cd engine/deps/openscenario_api
git apply ../patches/openscenario_api/mingw64/v1.3.1.patch

# building the openscenario_api (path to JAVA executable might differ!)
cd cpp
cmake -Wno-dev --preset="MSYS-shared-release" -DJava_JAVA_EXECUTABLE=/C/Program\ Files/Zulu/zulu-11/bin/java.exe
cmake --build --preset="Build-MSYS-shared-release"

# building the engine
cd ../../.. # back to engine
cmake -G "MSYS Makefiles" -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=bin -S . -B build
cd build
make install

⚠️ Note that the demo is not part the all target.

Running the Demo (Using the Engine)

The demo uses googletest/googlemock and the fakes supplied by the MantleAPI to show how the OpenScenarioEngine can be used in an executable.

Linux

# STARTING FROM ROOT OF REPOSITORY
cd engine
mkdir build && cd build
cmake ..
make OpenScenarioEngineDemo # would also build OpenScenarioEngine
./OpenScenarioEngineDemo ../demo/example/scenario.xosc

Windows (MINGW64 - experimental)

# STARTING FROM ROOT OF REPOSITORY
cd engine
cmake -G "MSYS Makefiles" -S . -B build
cd build
make OpenScenarioEngineDemo # would also build OpenScenarioEngine
./OpenScenarioEngineDemo ../demo/example/scenario.xosc

⚠️ If you start the demo, Windows might tell you that some dlls are missing. Locate and copy all of them into build.

Features

Covered Actions and Conditions

The following Actions and Conditions of ASAM OpenSCENARIO XML (currently v1.3.0) are under development:

Conditions

Type Subtype Status
ByEntityCondition DistanceCondition Supports only RelativeDistanceType::kLongitudinal && CoordinateSystem::kEntity && freespace=false
ByEntityCondition ReachPositionCondition ✔️ Restricted by conversion: see Conversions::Position below
ByEntityCondition RelativeDistanceCondition Supports only RelativeDistanceType::kLongitudinal && CoordinateSystem::kEntity
ByEntityCondition RelativeSpeedCondition ✔️ Complete
ByEntityCondition SpeedCondition ✔️ Without direction
ByEntityCondition TimeHeadwayCondition Supports only DistanceType::kEuclidean and CoordinateSystem::kEntity or CoordinateSystem::kLane or CoordinateSystem::kRoad(freespace=false)
ByEntityCondition TimeToCollisionCondition In clarification: Issue #7
ByEntityCondition TraveledDistanceCondition ✔️ Complete
ByValueCondition SimulationTimeCondition ✔️ Complete
ByValueCondition UserDefinedValueCondition ✔️ Complete

Actions

Interface Type Status
none AcquirePositionAction ✔️ Complete
none AssignControllerAction 🚧 Sets without consideration of motion domain
none AssignRouteAction ✔️ Restricted by conversion: see Conversions::Position
none CustomCommandAction ✔️ Complete
none EnvironmentAction ✔️ Does not interpret RoadCondition in Environment. In Weather does not interpret FractionalCloudCover, Wind, DomeImage. In Fog does not interpret BoundingBox. In Precipitation does not interpret PrecipitationType.
none LightStateAction 🚧 Supports LightType and LightState [only the LightMode], transitionTime is ignored at the moment.
none TeleportAction ✔️ Restricted by conversion: see Conversions::Position below
none TrafficSignalAction ✔️ Complete
none TrafficSignalStateAction ✔️ Complete
none TrafficSinkAction ✔️ Does not interpret rate and TrafficDefinition, and restricted by conversion: see Conversions::Position below
none VisibilityAction ✔️ Complete
MotionControlAction FollowTrajectoryAction 🚧 Supports trajectory shapes polyline and clothoid spline + (Possibility for optimization in the base class)
MotionControlAction LaneChangeAction ✔️ Complete
MotionControlAction LaneOffsetAction ✔️ Complete
MotionControlAction LateralDistanceAction ✔️ Does not interpret DynamicConstraints and restricted by conversion: see Conversions::Coordinate System and Conversions::Continuous
MotionControlAction LongitudinalDistanceAction ❌ Not yet implemented
MotionControlAction SpeedAction 🚧 Supports shapes linear and cubic, latter using linear shape coefficients (see MR74)
TrafficAction TrafficSwarmAction ✔️ Does not interprete directionOfTravelDistribution

TrafficSignalController

If defined in the road network, the engine manages TrafficSignalControllers on its own. The corresponding traffic light states of the traffic light phases are automatically emitted for the respective time steps, using the interface mantle_api::IEnvironment::SetTrafficSignalState.

Restrictions:

  • Phases must define at least a single TrafficSignalState
  • Delays and references between controllers not implemented yet
  • TrafficSignalGroupStates (openSCENARIO 1.2) currently not supported

Conversions

Absolute Target Lane

Converts number (ID) of the target lane entity from string to mantle_api::LaneId

Coordinate System

Converts NET_ASAM_OPENSCENARIO::v1_3::CoordinateSystem enum to OpenScenario::CoordinateSystem enum.

Subtype Status
entity
lane ✔️
road
trajectory

Lane Change Target

Converts to mantle_api::UniqueId

Subtype Status
RelativeTargetLane ✔️
AbsoluteTargetLane ✔️

Position

Converts to mantle_api::Pose

Subtype Status
WorldPosition ✔️
RelativeWorldPosition
RelativeObjectPosition
RoadPosition ✔️
RelativeRoadPosition
LanePosition ✔️
RelativeLanePosition ✔️
RoutePosition
GeoPosition ✔️
TrajectoryPosition

Relative Distance Type

Converts NET_ASAM_OPENSCENARIO::v1_3::IRelativeDistanceType enum type to OpenScenario::RelativeDistanceType enum.

Relative Target Lane

Converts NET_ASAM_OPENSCENARIO::v1_3::IRelativeTargetLane type object to mantle_api::UniqueId from its relative pose and the signed number of lanes that is offset from the reference entity's current lane.

Route

Converts to OPENSCENARIO::Route

Subtype Status
Route ✔️
CatalogReference ✔️

Rule

Compares the quantitative variables or signals with the given condition and returns True or False. Note: Conversion rule for DateTime object type is not yet implemented.

Type of the variable Status
Double ✔️
String ✔️
DateTime

Speed Action Target

Converts to OPENSCENARIO::SpeedActionTarget which is of type units::velocity::meters_per_second_t.

Subtype Status
AbsoluteTargetSpeed ✔️
RelativeTargetSpeed ✔️

Continuous

Subtype Status
True
False ✔️

Time Reference

Converts NET_ASAM_OPENSCENARIO::v1_3::ITimeReference object type to mantle_api::FollowTrajectoryControlStrategy::TrajectoryTimeReference when the timing information is taken into account. Note: For now only absolute time value is considered but not relative time value.

Time to Collision Condition Target

Converts NET_ASAM_OPENSCENARIO::v1_3::ITimeToCollisionConditionTarget object type either of mantle_api::Pose or Entity depending on its property. Note: If the object has the property Position, then it is restricted by conversion Conversions::Position

Traffic Signal Controller

Takes in the NET_ASAM_OPENSCENARIO::v1_3::ITrafficSignalController object type and returns the name of the target object in the form of a string.

Trajectory Reference

Converts NET_ASAM_OPENSCENARIO::v1_3::ITrajectoryRef object type to mantle_api::Trajectory

Subtype Status
TrajectoryRef ✔️
CatalogReference ✔️

Transition Dynamics

Converts NET_ASAM_OPENSCENARIO::v1_3::ITransitionDynamics object type to mantle_api::TransitionDynamics Note: Right now the property followingMode is not considered.

Customizations w.r.t ASAM OpenSCENARIO Standard

Property Parsing

The OpenSCENARIO standard does not impose strict requirements on the format of custom properties, allowing for flexibility in their definition. To facilitate this, the OpenScenarioEngine uses JSON to parse string-type properties into an internal object format. This approach enables the definition of complex properties, such as distributions, which can be used within actions. For example, a velocity distribution might be defined and used in a TrafficAreaAction.

For more information on how to define these properties, refer to the documentation an provided schemas in doc/json_properties.

Dependencies

Dependency Commit Version License
CPM 03705fc 0.36.0 MIT License
googletest f8d7d77 1.14.0 BSD-3-Clause License
JSON for Modern C++ db78ac1 3.9.1 MIT License
MantleAPI 7d2ed281 18.0.0 EPL 2.0
openpass/stochastics-library 6c9dde71 0.11.0 EPL 2.0
OpenSCENARIO API 5980e88 1.4.0 Apache 2.0
Units e27eed9 2.3.4 MIT License
YASE d0c0e58d EPL 2.0

Issues

Please report (and see) here.

License

Eclipse Public License 2.0