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 coordinate system::
+Coordinate system for all quantities which are part of ground truth.
+The world coordinate system is an inertial x/y/z-coordinate system.
+
+Sensor coordinate system::
+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 coordinate system::
+Coordinate system for local object coordinates, for example, vehicle coordinates.
+For vehicles, the origin is the middle of the rear axle projected onto the ground.
+Other objects may use different origins.
+
+The following image 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 the middle of rear axle projected onto the ground.
+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 given in the vehicle coordinate system.