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

doc/architecture/reference_points_coordinate_systems.adoc

@@ -0,0 +1,26 @@
+= Reference points and coordinate systems
+
+With Open Simulation Interface, an object's position coordinates refer to the center of the object's bounding box.
+This reference point is not necessarily identical to the origin of the respective coordinate systems.
+OSI uses DIN ISO 8855:2013-11 for coordinate systems and transformations between coordinate systems.
+
+OSI uses three coordinate systems:
+
+World coordinates::
+Coordinate system for all quantities which are part of ground truth.
+The world coordinate system is an inertial x/y/z-coordinate system.
+
+Sensor coordinates::
+Coordinate system for all quantities which are part of sensor data.
+The origin is the mounting position of the physical sensor or a virtual mounting position, depending on the technology.
+
+Object coordinates::
+Coordinate system for local object coordinates, for example, vehicle coordinates.
+For vehicles, the origin is the middle of the rear axle.
+Other objects may use different origins.
+
+The following images shows an example of the differents coordinate systems.
+It also shows that the reference point of the vehicle is located in the center of its bounding box whereas the origin of the vehicle coordinate system is located on the rear axle.
+In this example, the virtual mounting position coincides with the origin of the vehicle coordinate system.
+
+image::{imagedir}/osi_coordinate_systems.png[]

doc/open-simulation-interface_user_guide.adoc

@@ -7,6 +7,7 @@
 
 :topicdir: topics
 :reusedir: reuse
+:imagedir: images
 
 // header & footer for html
 // html themes
@@ -52,11 +53,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 +105,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/usecases/transforming_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.