From 4d9cc821ec672b4db21e5552a473efb44f0f02fa Mon Sep 17 00:00:00 2001 From: Thomas Sedlmayer Date: Mon, 22 Jun 2026 12:39:27 +0200 Subject: [PATCH] Extend OSC subset coverage Signed-off-by: Thomas Sedlmayer --- specification/osc_subset_definition.md | 152 +----------------- .../osc_subset_definition_iteration_1.md | 151 +++++++++++++++++ .../osc_subset_definition_iteration_2.md | 101 ++++++++++++ 3 files changed, 258 insertions(+), 146 deletions(-) create mode 100644 specification/osc_subset_definition_iteration_1.md create mode 100644 specification/osc_subset_definition_iteration_2.md diff --git a/specification/osc_subset_definition.md b/specification/osc_subset_definition.md index 263883a..85e69e8 100644 --- a/specification/osc_subset_definition.md +++ b/specification/osc_subset_definition.md @@ -1,159 +1,19 @@ # ASAM OpenSCENARIO XML Subset Definition -This document specifies a succeeding set of subsets of ASAM OpenSCENARIO XML 1.3.0 that form the basis of a validation suite approach for validating ASAM OpenSCENARIO implementations. +This document is the entry point for a succeeding set of subsets of ASAM OpenSCENARIO XML 1.3.0 that form the basis of a validation suite approach for validating ASAM OpenSCENARIO implementations. The subsets are defined in order to avoid ambiguous or hard to validate aspects of OpenSCENARIO, while remaining useful for the exchange of recorded or otherwise generated scenarios in actual practice. With increasing functionality of the validation suite, increased subsets of OpenSCENARIO can be defined and validated. -## Subset Definition: Most Minimal Subset (Iteration 1) +## Subset Iterations -The most minimal subset aims to minimally represent the content of a basic OSI SensorView trace. -Only basic vehicles with two axles and a corresponding polyline-based trajectory are allowed. -The OpenSCENARIO storyboard elements overhead is reduced to a minimum and a major part of optional OpenSCENARIO features like parameters, triggers or complex coordinate systems are excluded. - -### General Constraints - -This subset specification only allows OpenSCENARIO XML 1.3.0 scenario definitions. -All optional elements and attributes not explicitly included in this specification are excluded. -Only explicitly included action types are allowed; all others are excluded. -Only explicitly included position types are allowed; all others are excluded. - -### Included Features - -#### Storyboard - -The storyboard must consist of a single story. -Each scenario object's behavior must be defined by a single action. -Maximum execution count of maneuver groups and events must be set to '1'. -The priority of events must be set to 'override'; parallel events for the same scenario object are not allowed. -The storyboard stop trigger must terminate the execution after the last story ends. - -#### Scenario Objects - -Only scenario objects of type 'vehicle' are allowed. -Only vehicles of category 'car' are allowed. -For each car a front axle and a rear axle must be defined. - -#### Actions, Trajectories and Coordinate Systems - -This subset allows only trajectory-based behaviours using FollowTrajectoryAction with Polyline shape in the storyboard. -Coordinates for polyline trajectories must be defined using WorldPosition elements. -If global coordinates (e.g. UTM coordinates) are used, large values must be offset to be near the origin of the coordinate system. -The time reference domain of FollowTrajectoryAction must be set to 'absolute'. -The time reference scale must be set to '1.0'. -The time reference offset must be set to '0.0'. -The trajectory following mode must be set to 'position'. -Each vertex point of a trajectory must contain a corresponding timestamp. - -### Excluded Features - -This section lists certain OpenSCENARIO features that are explicitly excluded from the subset. - -- InitActions (Note: Action initialization is not required for the defined set of actions in this subset.) -- Triggers with the exception of the storyboard stop trigger -- Catalogs, CatalogReference -- Parameters, ParameterDeclaration -- Variables, VariableDeclaration -- Monitors, MonitorDeclaration -- EntitySelection -- ObjectController - -### Exceptions - -For the successful interpretation of a scenario with specific OpenSCENARIO implementations, exceptions to the above minimal subset definition must be made. - -#### esmini -Esmini requires 'InitActions' to ensure successful spawning of scenario objects. -In that case, the definition of one 'TeleportAction' with position type 'WorldPosition' per contained scenario object in 'InitActions' is allowed. - -#### gt-gen-simulator -- Requires an empty \ in vehicle definition even though not required by OpenSCENARIO. -> Fixed in gt-gen-simulator 9.0.0 -- Requires one vehicle to be named 'Ego' or 'Host'. -- Requires a specification of a road network (e.g. OpenDRIVE map) in the scenario definition. -- The scenario objects must not be placed outside the defined road (network). The simulator stops with an unhandled exception when a vehicle leaves the road. - ``` - [2024-12-13 11:05:25.915] [gtgen::core] [error] [18.500s] Terminating due to an unhandled exception: - gtgen::core::environment::EnvironmentException - what(): Cannot keep lane offset for entity "osi_moving_object_2" (id: 1001): Position -65.365737171, 16.113888127, 0.709500000 not on a lane - ``` -- Does not support StoryboardElementStateCondition to end the storyboard when the story ends. - -### OSC Generation - -To generate a scenario from an OSI SensorView trace file, the following OSI attributes are required or the corresponding information has to be added in other ways to the scenario file: -- timestamp -- global_ground_truth / timestamp -- global_ground_truth / moving_object / id / value -- global_ground_truth / moving_object / base / dimension -- global_ground_truth / moving_object / base / position -- global_ground_truth / moving_object / base / orientation -- global_ground_truth / moving_object / vehicle_attributes / bbcenter_to_rear -- global_ground_truth / moving_object / vehicle_attributes / bbcenter_to_front -- global_ground_truth / moving_object / wheel_data / wheel_radius - -The information for certain required OpenSCENARIO attributes is not covered by OSI. -This is the case for vehicle performance parameters (maximum acceleration, maximum deceleration, maximum speed) and axle information (track width). -For the above-specified minimal subset definition these attributes should not influence the scenario execution. -Nevertheless, realistic parameters are chosen and set in the scenario file. - -For each scenario object's trajectory, the vertex point timestamps must match the timestamps of the OSI trace file. - -## Example Scenarios - -- [Shortened minimal subset scenario example](./../example/20240603T143803.535904Z_osc_pmsf_dronetracker_119_cutout_shortened.xosc). - -## Validation with OSC Quality Checker - -The validation of adherence to this subset specification can be checked with the corresponding extension of the OSC Quality Checker: - - +- [Subset Definition: Most Minimal Subset (Iteration 1)](./osc_subset_definition_iteration_1.md) +- [Subset Definition: Release Subset (Iteration 2)](./osc_subset_definition_iteration_2.md) ## Future Extensions - Expand on time requirements (Trajectory/Vertex timestamps), e.g. check monotonic increasing of timestamps in Quality Checker -- Include basic start and stop triggers -- Add relative timing and/or scaling for trajectories +- Expand trigger coverage beyond the currently validated start and stop trigger cases +- Add trajectory time reference scaling and additional relative timing variants - Add relative positioning for trajectories and other more complex position types (e.g. TrajectoryPosition to test s-/t-coordinates) - Add trajectory follow mode 'follow' - Add clothoid, spline, nurbs trajectories -- Add more complex actions (e.g. SpeedAction) - -### Outcome for OpenSCENARIO - -The following section presents issues, especially regarding the clarity of the documentation, that arose during the development of the minimal subset of OpenSCENARIO XML 1.3.0. - -#### Init Actions - -The OpenSCENARIO documentation does not clearly state which actions require prior initialization using InitActions. -Note: 10.3: "ASAM OpenSCENARIO does not enforce specifying the initial position and speed of entities, but it is considered best practice to do so. Most actions and conditions require those values to be set." -What does "most actions/conditions" mean? -For some actions it may not even make sense to be initialized with some position because it is not known (e.g. polyline trajectory with fixed timestamps). -Therefore, the best practice of always defining InitActions is not adequate. - -#### Coordinate System Documentation - -The information with which reference point a scenario object is placed in the superordinated coordinate system (e.g. a vehicle is placed at the ground projection of its rear axle) is not stated clearly in the documentation. - -There should be a note that the attribute 'positionX' should always be set to 0 for a vehicle's rear axle. - -#### Documentation of Storyboard Stop Trigger - -8.4.7 Execution of a storyboard: "Simulation tools can use this behavior to explicitly stop the simulation." Unclear meaning. - -#### Maximum Execution Count of Events - -The attribute 'maximumExecutionCount' in the class Event is optional (cardinality 0..1). -A default value of '1' is defined. -It is not clearly stated that the default value of 1 applies if the attribute is not set. -There is also a default value defined for 'maximumExecutionCount' in the class ManeuverGroup which is not optional. -The general meaning of a 'default value' is unclear. - -#### Inconsistent Naming - -- TODO: List found issues - -### Outcome for OSC Quality Checker - -There should be a rule checking that all vehicles except trailers contain a front axle. -This restriction is documented in the model reference (Vehicle / Axles). - -There should be a rule to check if the attribute 'positionX' is set to 0 for a vehicle's rear axle. diff --git a/specification/osc_subset_definition_iteration_1.md b/specification/osc_subset_definition_iteration_1.md new file mode 100644 index 0000000..0ba6ef0 --- /dev/null +++ b/specification/osc_subset_definition_iteration_1.md @@ -0,0 +1,151 @@ +# Subset Definition: Most Minimal Subset (Iteration 1) + +[Back to ASAM OpenSCENARIO XML Subset Definition](./osc_subset_definition.md) + +The most minimal subset aims to minimally represent the content of a basic OSI SensorView trace. +Only basic vehicles with two axles and a corresponding polyline-based trajectory are allowed. +The OpenSCENARIO storyboard elements overhead is reduced to a minimum and a major part of optional OpenSCENARIO features like parameters, triggers or complex coordinate systems are excluded. + +## General Constraints + +This subset specification only allows OpenSCENARIO XML 1.3.0 scenario definitions. +All optional elements and attributes not explicitly included in this specification are excluded. +Only explicitly included action types are allowed; all others are excluded. +Only explicitly included position types are allowed; all others are excluded. + +## Included Features + +### Storyboard + +The storyboard must consist of a single story. +Each scenario object's behavior must be defined by a single action. +Maximum execution count of maneuver groups and events must be set to '1'. +The priority of events must be set to 'override'; parallel events for the same scenario object are not allowed. +The storyboard stop trigger must terminate the execution after the last story ends. + +### Scenario Objects + +Only scenario objects of type 'vehicle' are allowed. +Only vehicles of category 'car' are allowed. +For each car a front axle and a rear axle must be defined. + +### Actions, Trajectories and Coordinate Systems + +This subset allows only trajectory-based behaviours using FollowTrajectoryAction with Polyline shape in the storyboard. +Coordinates for polyline trajectories must be defined using WorldPosition elements. +If global coordinates (e.g. UTM coordinates) are used, large values must be offset to be near the origin of the coordinate system. +The time reference domain of FollowTrajectoryAction must be set to 'absolute'. +The time reference scale must be set to '1.0'. +The time reference offset must be set to '0.0'. +The trajectory following mode must be set to 'position'. +Each vertex point of a trajectory must contain a corresponding timestamp. + +## Excluded Features + +This section lists certain OpenSCENARIO features that are explicitly excluded from the subset. + +- InitActions (Note: Action initialization is not required for the defined set of actions in this subset.) +- Triggers with the exception of the storyboard stop trigger +- Catalogs, CatalogReference +- Parameters, ParameterDeclaration +- Variables, VariableDeclaration +- Monitors, MonitorDeclaration +- EntitySelection +- ObjectController + +## Exceptions + +For the successful interpretation of a scenario with specific OpenSCENARIO implementations, exceptions to the above minimal subset definition must be made. + +### esmini +Esmini requires 'InitActions' to ensure successful spawning of scenario objects. +In that case, the definition of one 'TeleportAction' with position type 'WorldPosition' per contained scenario object in 'InitActions' is allowed. + +### gt-gen-simulator +- Requires an empty \ in vehicle definition even though not required by OpenSCENARIO. -> Fixed in gt-gen-simulator 9.0.0 +- Requires one vehicle to be named 'Ego' or 'Host'. +- Requires a specification of a road network (e.g. OpenDRIVE map) in the scenario definition. +- The scenario objects must not be placed outside the defined road (network). The simulator stops with an unhandled exception when a vehicle leaves the road. + ``` + [2024-12-13 11:05:25.915] [gtgen::core] [error] [18.500s] Terminating due to an unhandled exception: + gtgen::core::environment::EnvironmentException + what(): Cannot keep lane offset for entity "osi_moving_object_2" (id: 1001): Position -65.365737171, 16.113888127, 0.709500000 not on a lane + ``` +- Does not support StoryboardElementStateCondition to end the storyboard when the story ends. + +## OSC Generation + +To generate a scenario from an OSI SensorView trace file, the following OSI attributes are required or the corresponding information has to be added in other ways to the scenario file: +- timestamp +- global_ground_truth / timestamp +- global_ground_truth / moving_object / id / value +- global_ground_truth / moving_object / base / dimension +- global_ground_truth / moving_object / base / position +- global_ground_truth / moving_object / base / orientation +- global_ground_truth / moving_object / vehicle_attributes / bbcenter_to_rear +- global_ground_truth / moving_object / vehicle_attributes / bbcenter_to_front +- global_ground_truth / moving_object / wheel_data / wheel_radius + +The information for certain required OpenSCENARIO attributes is not covered by OSI. +This is the case for vehicle performance parameters (maximum acceleration, maximum deceleration, maximum speed) and axle information (track width). +For the above-specified minimal subset definition these attributes should not influence the scenario execution. +Nevertheless, realistic parameters are chosen and set in the scenario file. + +For each scenario object's trajectory, the vertex point timestamps must match the timestamps of the OSI trace file. + +## Validation Coverage + +This subset was covered by the original simple trajectory replay validation: + +- `osc_validation/validation/scenario/trajectories/val_simple_trajectories.py` + +## Example Scenarios + +- [Shortened minimal subset scenario example](./../example/20240603T143803.535904Z_osc_pmsf_dronetracker_119_cutout_shortened.xosc). + +## Validation with OSC Quality Checker + +The validation of adherence to the most minimal subset specification (Iteration 1) can be checked with the corresponding extension of the OSC Quality Checker: + + + +### Outcome for OpenSCENARIO + +The following section presents issues, especially regarding the clarity of the documentation, that arose during the development of the minimal subset of OpenSCENARIO XML 1.3.0. + +#### Init Actions + +The OpenSCENARIO documentation does not clearly state which actions require prior initialization using InitActions. +Note: 10.3: "ASAM OpenSCENARIO does not enforce specifying the initial position and speed of entities, but it is considered best practice to do so. Most actions and conditions require those values to be set." +What does "most actions/conditions" mean? +For some actions it may not even make sense to be initialized with some position because it is not known (e.g. polyline trajectory with fixed timestamps). +Therefore, the best practice of always defining InitActions is not adequate. + +#### Coordinate System Documentation + +The information with which reference point a scenario object is placed in the superordinated coordinate system (e.g. a vehicle is placed at the ground projection of its rear axle) is not stated clearly in the documentation. + +There should be a note that the attribute 'positionX' should always be set to 0 for a vehicle's rear axle. + +#### Documentation of Storyboard Stop Trigger + +8.4.7 Execution of a storyboard: "Simulation tools can use this behavior to explicitly stop the simulation." Unclear meaning. + +#### Maximum Execution Count of Events + +The attribute 'maximumExecutionCount' in the class Event is optional (cardinality 0..1). +A default value of '1' is defined. +It is not clearly stated that the default value of 1 applies if the attribute is not set. +There is also a default value defined for 'maximumExecutionCount' in the class ManeuverGroup which is not optional. +The general meaning of a 'default value' is unclear. + +#### Inconsistent Naming + +- TODO: List found issues + +### Outcome for OSC Quality Checker + +There should be a rule checking that all vehicles except trailers contain a front axle. +This restriction is documented in the model reference (Vehicle / Axles). + +There should be a rule to check if the attribute 'positionX' is set to 0 for a vehicle's rear axle. diff --git a/specification/osc_subset_definition_iteration_2.md b/specification/osc_subset_definition_iteration_2.md new file mode 100644 index 0000000..40abfcc --- /dev/null +++ b/specification/osc_subset_definition_iteration_2.md @@ -0,0 +1,101 @@ +# Subset Definition: Release Subset (Iteration 2) + +[Back to ASAM OpenSCENARIO XML Subset Definition](./osc_subset_definition.md) + +The release subset extends Iteration 1 with the OpenSCENARIO XML features that are currently covered by the validation suite. +Iteration 1 remains the historical minimal subset for basic OSI SensorView trace replay. +This subset still targets OpenSCENARIO XML 1.3.0 scenario definitions. +Where validation cases reference clarified behavior from OpenSCENARIO XML 1.4.0, that clarification is documented as a validation expectation for the covered behavior and not as a general expansion to all OpenSCENARIO XML 1.4.0 features. + +## General Constraints + +All optional elements and attributes not explicitly included in this specification remain excluded. +Only explicitly included action types, trigger and condition types, position types, timing behavior, and storyboard structures are included. +The vehicle-focused constraints from Iteration 1 remain unless explicitly expanded in this section. + +## Included Features + +### Storyboard and Sequencing + +The storyboard may use multiple sequential storyboard elements where covered by the split trajectory validation cases. +Sequential trajectory fragments are validated at the following storyboard levels: + +- `Event` +- `Maneuver` +- `ManeuverGroup` +- `Act` +- `Story` + +Sequencing between split trajectory fragments may use `StoryboardElementStateCondition` with `state="completeState"`. +The storyboard stop trigger may use `SimulationTimeCondition` to terminate the scenario at a defined simulation time. + +### Scenario Objects + +Only scenario objects of type `vehicle` are included. +Only vehicles of category `car` are included. +Vehicle dimensions and bounding box dimensions are validated against OSI reference traces for the covered vehicle objects. +The remaining vehicle constraints from Iteration 1, including front and rear axle requirements, continue to apply. + +### Init Actions + +The release subset includes the following `Init` actions: + +- Private `TeleportAction` with `WorldPosition` +- `AddEntityAction` with `WorldPosition` +- Private `SpeedAction` with an absolute speed target + +### Trajectory Actions, Timing, and Coordinate Systems + +The release subset includes `FollowTrajectoryAction` with: + +- `Polyline` trajectory shape +- Timed `Vertex` elements +- `WorldPosition` positions +- `followingMode="position"` +- Absolute time reference cases for the current trajectory time and future trajectory time validation cases +- Relative time reference cases generated by the OSI trace replay and split trajectory validation cases + +Trajectory interpolation is validated for timed polyline trajectories in position mode. +The validation suite includes the OpenSCENARIO XML 1.4.0 constant-acceleration interpolation expectation and also permits the linear position interpolation behavior used for older-version compatibility checks. +Versions before OpenSCENARIO XML 1.4.0 did not require a specific interpolation method. + +### Triggers and Conditions + +The release subset includes event `StartTrigger` conditions for activating validated trajectory behavior. +The following condition types and attributes are included: + +- `SimulationTimeCondition` +- `TraveledDistanceCondition` +- `SpeedCondition` with `conditionEdge` values `rising`, `falling`, and `none` +- `DistanceCondition` to `WorldPosition` with `relativeDistanceType="euclidianDistance"` +- `DistanceCondition` to `WorldPosition` with `relativeDistanceType="longitudinal"` +- `TimeToCollisionCondition` to target `WorldPosition` +- `Condition` `delay` for speed and longitudinal distance trigger cases + +Unless stated above, trigger behavior remains outside the release subset. + +## Validation Coverage + +This subset includes the Iteration 1 simple trajectory replay coverage and is additionally covered by the following validation scenarios: + +- Trajectory behavior: `osc_validation/validation/scenario/trajectories/val_follow_trajectory_future_time_reference.py` +- Trajectory behavior: `osc_validation/validation/scenario/trajectories/val_follow_trajectory_teleport.py` +- Trajectory behavior: `osc_validation/validation/scenario/trajectories/val_interpolation.py` +- Init actions: `osc_validation/validation/scenario/init_actions/val_init_actions.py` +- Trigger conditions: `osc_validation/validation/scenario/triggers/val_condition_delay.py` +- Trigger conditions: `osc_validation/validation/scenario/triggers/val_distance_euclidian_start_trigger.py` +- Trigger conditions: `osc_validation/validation/scenario/triggers/val_distance_longitudinal_start_trigger.py` +- Trigger conditions: `osc_validation/validation/scenario/triggers/val_simulation_time_start_trigger.py` +- Trigger conditions: `osc_validation/validation/scenario/triggers/val_speed_start_trigger.py` +- Trigger conditions: `osc_validation/validation/scenario/triggers/val_time_to_collision_start_trigger.py` +- Trigger conditions: `osc_validation/validation/scenario/triggers/val_traveled_distance_start_trigger.py` +- Sequencing: `osc_validation/validation/scenario/sequencing/val_split_trajectory.py` +- Object state: `osc_validation/validation/scenario/object_state/val_vehicle_dimensions.py` + +### Outcome for OpenSCENARIO + +The following GitLab issues were opened for OpenSCENARIO standard questions and documentation gaps identified while defining this subset: + +- [OSC 1.4 default polyline interpolation changes behavior vs 1.3.x](https://code.asam.net/simulation/openscenario/openscenario-xml/-/issues/721) +- [Expected engine behavior for unsupported features?](https://code.asam.net/simulation/openscenario/openscenario-xml/-/issues/722) +- [Documentation issues for (Relative)DistanceCondition](https://code.asam.net/simulation/openscenario/openscenario-xml/-/issues/723)