| .. | |
| ******************************************************************************* | |
| Copyright (c) 2021 in-tech GmbH | |
| This program and the accompanying materials are made available under the | |
| terms of the Eclipse Public License 2.0 which is available at | |
| http://www.eclipse.org/legal/epl-2.0. | |
| SPDX-License-Identifier: EPL-2.0 | |
| ******************************************************************************* | |
| .. _observation_log: | |
| Observation_Log | |
| ############### | |
| This section describes the parameters and outputs of the ``Observation_Log`` observer. | |
| .. _observationlog_paramerization: | |
| Paramerization | |
| ============== | |
| Following parameters are supported: | |
| .. table:: | |
| :class: tight-table | |
| =================== ============= ========================================================================== | |
| Parameter Type Description | |
| =================== ============= ========================================================================== | |
| OutputFilename String Name of the output file (normally ``simulationOutput.xml``) | |
| LoggingCyclicsToCsv Bool If ``true``, cyclics are written an additional file (one CSV file per run) | |
| LoggingGroup_<NAME> StringVector Defines which columns belong to the logging group named NAME | |
| LoggingGroups StringVector Defines active logging groups | |
| =================== ============= ========================================================================== | |
| The columns, defined by the ``LoggingGroup_<NAME>`` correspond to cyclic data entries written by the core and other components. | |
| At time or writing, the core publishes the following cyclics (see source of ``AgentNetwork.cpp``): | |
| - XPosition | |
| - YPosition | |
| - VelocityEgo | |
| - AccelerationEgo | |
| - YawAngle | |
| - YawRate | |
| - SteeringAngle | |
| - TotalDistanceTraveled | |
| - PositionRoute | |
| - TCoordinate | |
| - Lane | |
| - Road | |
| - SecondaryLanes | |
| - AgentInFront | |
| Please refer to the individual components, for information about their published cyclics. | |
| .. todo:: | |
| The concept Cyclics and the DataBuffer needs further explanation. | |
| We also need a way to better communicate, who is publishing what. | |
| This should directly come out of the source code, to keep the documentation up to date. | |
| .. admonition:: **Wildcards in LoggingGroup definitions** | |
| | It is possible to use the wildcard character ``*`` in a ``LoggingGroup_<NAME>`` entry. | |
| | The wildcard can be used only once per column reference. | |
| **Example** | |
| .. literalinclude:: /../../../repo/sim/contrib/examples/Common/simulationConfig.xml | |
| :language: xml | |
| :start-at: <Library>Observation_Log</Library> | |
| :end-at: </Parameters> | |
| Output Files | |
| ============ | |
| .. _observationlog_simout: | |
| SimulationOutput | |
| ~~~~~~~~~~~~~~~~ | |
| Every successful run (single experiment) generates a single file, normally called ``simulationOutput.xml`` (see :ref:'observationlog_paramerization'). | |
| The output can contain multiple invocations of the same configuration with different random seeds. | |
| For each invocation a RunResult is stored, which contains information about the agents and their parameters. | |
| As well as run specific events and parameters. | |
| .. code-block:: xml | |
| <SimulationOutput> | |
| <RunResults> | |
| <RunResult RunId="0"> | |
| ... | |
| </RunResult> | |
| <RunResult RunId="1"> | |
| ... | |
| </RunResult> | |
| </RunResults> | |
| </SimulationOutput> | |
| The RunResult consist out of the following parts: | |
| - :ref:`observationlog_runstatistics` | |
| - :ref:`observationlog_events` | |
| - :ref:`observationlog_agents` | |
| - :ref:`observationlog_cyclics` | |
| .. _observationlog_runstatistics: | |
| RunStatistics | |
| ------------- | |
| This section contains the RandomSeed and general statistics of the invocation. | |
| .. table:: | |
| :class: tight-table | |
| ======================= ================================================================== | |
| Tag Description | |
| ======================= ================================================================== | |
| RandomSeed Random seed used for this invocation | |
| VisibilityDistance Visibility distance of the world | |
| StopReason Displays the reason why the simulation stopped. | |
| Currently only due to time out. | |
| StopTime Currently not used and set to -1 | |
| EgoAccident Flag which shows whether the ego agent was involved in an accident | |
| TotalDistanceTraveled Total traveled distance of all agents | |
| EgoDistanceTraveled Total traveled distance of ego vehicle only | |
| ======================= ================================================================== | |
| .. _observationlog_events: | |
| Events | |
| ------ | |
| This section contains all events that occurred during the invocation. | |
| Event can either be triggered by an EventDetector, Manipulator or by certain vehicle components. | |
| They are used to track special behavior in the simulation. | |
| .. table:: | |
| :class: tight-table | |
| ====================== ===================================================================================== | |
| Attribute Description | |
| ====================== ===================================================================================== | |
| Time Time in ms when the event occurred. | |
| Source Name of the component which created the event. | |
| ``OpenSCENARIO``, if triggered by an OpenSCENARIO condition. | |
| Name In case of an OpenSCENARIO event, a path expression Story/Act/Sequence/Maneuver/Event | |
| using the names of the corresponding tags as described in the OpenSCENARIO file. | |
| Otherwise determined by the triggering component. | |
| TriggeringEntities List of entity IDs triggering this event. | |
| AffectedEntities List of entity IDs affected by this event. | |
| Parameters List of generic key/value string pairs. | |
| ====================== ===================================================================================== | |
| .. _observationlog_agents: | |
| Agents | |
| ------ | |
| This section contains some information on how each agent is configured. | |
| .. table:: | |
| :class: tight-table | |
| ====================== ============================================================== | |
| Attribute Description | |
| ====================== ============================================================== | |
| Id Identification number | |
| AgentTypeGroupName The agent category. This can either be Ego, Scenario or Common | |
| AgentTypeName Name of the agent profile | |
| VehicleModelType Name of the vehicle model | |
| DriverProfileName Name of the driver profile | |
| ====================== ============================================================== | |
| .. code-block:: xml | |
| <Agent Id="0" | |
| AgentTypeGroupName="Ego" | |
| AgentTypeName="MiddleClassCarAgent" | |
| VehicleModelType="car_bmw_7" | |
| DriverProfileName="Regular"> | |
| The VehicleAttributes tag lists basic information of the vehicle parameters. | |
| .. table:: | |
| :class: tight-table | |
| ======================= ============================================================================= | |
| Attribute Description | |
| ======================= ============================================================================= | |
| Width Width of the vehicles bounding box | |
| Length Length of the vehicles bounding box | |
| Height Height of the vehicles bounding box | |
| LongitudinalPivotOffset Distance between center of the bounding box and reference point of the agent. | |
| Positive distances are closer to the front of the vehicle. | |
| Negative distances are closer to the rear of the vehicle. | |
| ======================= ============================================================================= | |
| The Sensors tag lists all sensors of the agent and their parameters. | |
| .. table:: | |
| :class: tight-table | |
| ======================= ===================================================================== | |
| Attribute Description | |
| ======================= ===================================================================== | |
| Name Name of the component | |
| Model Type of the sensor | |
| MountingPosLongitudinal Relative longitudinal position of the sensor in relation to the agent | |
| MountingPosLateral Relative lateral position of the sensor in relation to the agent | |
| MountingPosHeight Relative height of the sensor in relation to the agent | |
| OrientationPitch Pitch rotation of the sensor in relation to the agent | |
| OrientationYaw Yaw rotation of the sensor in relation to the agent | |
| OpeningAngleH Horizontal opening angle of the sensor | |
| OpeningAngleV Vertical opening angle of the sensor | |
| DetectionRange Range how far the sensor reaches in m | |
| ======================= ===================================================================== | |
| .. note:: | |
| Calculation of visual obstruction is currently supported only by the Geometric2D sensor. | |
| See :ref:`systemconfigblueprint` for configuration. | |
| .. code-block:: xml | |
| <Sensor Name="Geometric2DFront" | |
| Model="Geometric2D" | |
| MountingPosLongitudinal="0" | |
| MountingPosLateral="0" | |
| MountingPosHeight="0.5" | |
| OrientationPitch="0" | |
| OrientationYaw="0" | |
| OpeningAngleH="20" | |
| OpeningAngleV="-999" | |
| DetectionRange="300" /> | |
| .. _observationlog_cyclics: | |
| Cyclics | |
| ------- | |
| If the parameter ``LoggingCyclicsToCsv`` is set to ``false``, this section contains all logged parameters of the agents per time step. | |
| The tag ``header`` defines the layout of all samples. | |
| Each entry of the header consists of the agent id and the name of the logged value, in the form ``ID:SAMPLE_NAME``. | |
| A sample contains all information for one specific time step. | |
| If an agent does not exist at the current time step, the value is ' '. | |
| **Example** | |
| In this example exist two agents with the ids 0 and 1. | |
| Two time steps were being tracked, one at 0 seconds and one at 100 ms. | |
| Agent 0 has a constant velocity of 30 m/s and starts at the position X: 100 and Y: 50. | |
| Agent 1 has a initial velocity of 40 m/s and starts at the position X: 200 and Y: 50. | |
| .. code-block:: xml | |
| <Cyclics> | |
| <Header>00:VelocityEgo, 00:XPosition, 00:YPosition, 00:YawAngle, 01:VelocityEgo, 01:XPosition, 01:YPosition, 01:YawAngle</Header> | |
| <Samples> | |
| <Sample Time="0">30, 100, 50, 0, 40, 200, 50, 0</Sample> | |
| <Sample Time="100">30, 103, 50, 0, 40, 204, 50, 0</Sample> | |
| </Samples> | |
| </Cyclics> | |
| If the parameter ``LoggingCyclicsToCsv`` is set to ``true``, this section only contains a reference to the corresponding CSV file, e.g. | |
| .. code-block:: xml | |
| <Cyclics> | |
| <CyclicsFile>Cyclics_Run_000.csv</CyclicsFile> | |
| </Cyclics> | |
| For each invocation, the file number of the filename is incremented, starting with ``Cyclics_Run_000.csv``. | |
| Cyclics_Run_### | |
| ~~~~~~~~~~~~~~~ | |
| This file contains the samples as described in :ref:'observationlog_cyclics', but with the time step as leading column. | |
| **Example** | |
| ======== ============== ============ ============ =========== ============== ============ ============ =========== | |
| Timestep 00:VelocityEgo 00:XPosition 00:YPosition 00:YawAngle 01:VelocityEgo 01:XPosition 01:YPosition 01:YawAngle | |
| ======== ============== ============ ============ =========== ============== ============ ============ =========== | |
| 0 30 100 50 0 40 200 50 0 | |
| 100 30 103 50 0 40 204 50 0 | |
| ======== ============== ============ ============ =========== ============== ============ ============ =========== |