feat(docs): Describe coordinate systems and reference points (#510)

Signed-off-by: Maximilian Rosin <maximilian.rosin@parson-europe.com>

Author: max-rosin

doc/architecture/coordinate_systems.adoc

@@ -0,0 +1,16 @@
+= Reference points and coordinate systems
+
+With Open Simulation Interface, an object's position coordinates refer to the center of the object's bounding box, independent of the coordinate system. This reference point is not identical to the origin of any coordinate systems.
+
+OSI uses three coordinate systems:
+
+World coordinates::
+Coordinate system for all quantities which are part of ground truth.
+
+Sensor coordinates::
+Coordinate system for all quantities which are part of sensor data.
+
+Object coordinates::
+Coordinate system for local object coordinates, for example, vehicle coordinates.
+
+OSI uses DIN ISO 8855:2013-11 for coordinate systems and transformations between coordinate systems.

doc/architecture/reference_points.adoc

@@ -52,11 +52,9 @@ include::./architecture/traffic_participant.adoc[leveloffset=+3]
 
 include::./architecture/vehicle_dynamics.adoc[leveloffset=+3]
 
-=== Coordinate systems and reference points
+// Coordinate systems and reference points (level 3)
 
-include::./architecture/coordinate_systems.adoc[leveloffset=+3]
-
-include::./architecture/reference_points.adoc[leveloffset=+3]
+include::./architecture/reference_points_coordinate_systems.adoc[leveloffset=+2]
 
 === Layering
 
@@ -106,6 +104,8 @@ include::./usecases/benchmark_integration_gpu_radar.adoc[leveloffset=+2]
 
 include::./usecases/generating_osi_traces.adoc[leveloffset=+2]
 
+include::./usecases/transforming_coordinate_systems.adoc[leveloffset=+2]
+
 == Improving performance
 
 TODO: Define topics and issues regarding performance.

doc/architecture/reference_points_coordinate_systems.adoc

@@ -0,0 +1,22 @@
+= Transforming coordinate systems
+
+Transforming coordinates for a specific vehicle or sensor is a common task when running simulations.
+OSI uses DIN ISO 8855:2013-11 for coordinate systems and transformations between coordinate systems.
+
+//TODO: Should we add one or more sentences about the mathematical operations involved?
+
+**Corresponding messages**
+
+``GroundTruth::moving_object::base::position``::
+Defines the position of the vehicle’s reference point.
+
+``GroundTruth::moving_object::base::orientation``::
+Defines the orientation of the vehicle’s reference point.
+
+``GroundTruth::moving_object::vehicle_attributes::bbcenter_to_rear``::
+The vector pointing from the vehicle’s reference point to the middle of the rear axle under neutral load conditions in vehicle coordinates.
+The middle of the rear axle is 
+
+``SensorData::mounting_position``::
+Defines the sensor’s position and orientation and thereby the origin of the sensor coordinate system.
+The mounting position is defined in sensor coordinates and relative to the origin of the vehicle coordinate system.