Feature/proj offset

.github/spelling_custom_words_en_US.txt

@@ -2,6 +2,7 @@ abc
 absteigen
 adas
 ADR
+affine
 agbl
 al
 Allgemeine
@@ -244,6 +245,7 @@ openscenario
 optischen
 Ordnung
 osi
+OSI's
 osmp
 Ouml
 ouml

doc/architecture/reference_points_coordinate_systems.adoc

@@ -13,6 +13,7 @@ The global coordinate system is an inertial x/y/z-coordinate system.
 The origin is the global reference point that is determined by the environment simulation.
 This reference point may be derived from map data or other considerations.
 Global coordinates can be mapped to a geographic coordinate system via `osi3::GroundTruth::proj_string`.
+Note that before applying any PROJ transformations to global coordinates, the `osi3::GroundTruth::proj_frame_offset` must be applied.
 
 Host vehicle coordinate system::
 The host vehicle coordinate system's origin is defined to be at the center of the rear axle of the host vehicle.

osi_groundtruth.proto

@@ -133,7 +133,8 @@ message GroundTruth
     optional uint32 country_code = 13;
 
     // Projection string that allows to transform all coordinates in GroundTruth
-    // into a different cartographic projection.
+    // into a different cartographic projection after the \c proj_frame_offset
+    // has been applied.
     //
     // The string follows the PROJ rules for projections [1].
     //
@@ -178,4 +179,52 @@ message GroundTruth
     // Logical lanes used e.g. by traffic agents
     //
     repeated LogicalLane logical_lane = 19;
+
+    // Coordinate frame offset to be used for PROJ transformations.
+    //
+    optional ProjFrameOffset proj_frame_offset = 20;
+
+    //
+    // \brief Coordinate frame offset to transform from OSI's global coordinate
+    // system to a coordinate reference system to be used for given PROJ
+    // transformations.
+    //
+    // If an offset is defined, always apply the \c proj_frame_offset on
+    // global OSI coordinates before applying any transformations defined in
+    // \c proj_string.
+    //
+    // To apply the offset, global coordinates are first translated by the given
+    // positional offset (x,y,z). Then, the yaw angle is used to rotate around
+    // the new origin.
+    //
+    // The offset is applied on global OSI coordinates using an affine
+    // transformation with rotation around z-axis:
+    //
+    // xWorld = xOSI * cos(yaw) - yOSI * sin(yaw) + xOffset
+    //
+    // yWorld = xOSI * sin(yaw) + yOSI * cos(yaw) + yOffset
+    //
+    // zWorld = zOSI + zOffset
+    //
+    //
+    // If no yaw is provided (recommended), the formulas simplify to:
+    //
+    // xWorld = xOSI + xOffset
+    //
+    // yWorld = yOSI + yOffset
+    //
+    // zWorld = zOSI + zOffset
+    //
+    message ProjFrameOffset
+    {
+        // Positional offset for relocation of the coordinate frame.
+        //
+        optional Vector3d position = 1;
+
+        // Yaw/heading angle for re-orientation of the coordinate frame around
+        // the z-axis.
+        //
+        optional double yaw = 2;
+    }
+
 }