.. | |
******************************************************************************* | |
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:: /../../../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 | |
======== ============== ============ ============ =========== ============== ============ ============ =========== |