Use vehicle axis system definition of DIN ISO 8855

Change OSI transformation between axis systems to ISO definition.
World frame -> vehicle frame -> sensor frame ...

Orientation is defined (world -> vehicle) rotate yaw -> rotate pitch -> rotate roll.

Note this is the international standard and differs from national american standard.
(OSI V2.xxx used national american standard)

Author: Carsten Kuebler

osi_common.proto

@@ -97,18 +97,24 @@ message Dimension3d
 // 
 // The preferred angular range is (-pi, pi]. The coordinate system is defined as right-handed. 
 //  
-// The rotations are to be performed \b roll \b first, \b pitch \b second and \b yaw \b third to follow the definition according to [1]. 
+// The rotations are to be performed \b yaw \b first, \b pitch \b second and \b roll \b third to follow the definition according to [1]. 
 // 
 // Rotations are defined in the reference coordinate frame around z-axis (=yaw), y-axis (=pitch) and x-axis (=roll), 
 // not in the body frame of the object. 
-// A positive angle corresponds to a counter-clockwise rotation around the respective axis.
+// A positive angle corresponds to a clockwise rotation around the respective axis.
 //
 // Roll/Pitch are 0 if the objects xy-plane is parallel to its parent's xy-plane.
 // Yaw is 0 if the object's local x-axis is parallel to its parent's x-axis.
 //
+// Rotation_yaw_pitch_roll = Rotation_roll*Rotation_pitch*Rotation_yaw
+//
+// vector_global_coord_system := Inverse_Rotation_yaw_pitch_roll(orientation)*(vector_local_coord_system) + local_origin.position
+
+//
+// \note This definition changed in OSI version 3.0.0. Previous OSI versions (V2.xx) had an other definition.
+//
 // \par References: 
-// [1] LAVALLE, Steven M. Planning algorithms. Cambridge university press, 2006. Chapter 3.2.3.
-// See http://planning.cs.uiuc.edu/node102.html for online version of this chapter.
+// [1] DIN ISO 8855:2013-11
 //
 message Orientation3d
 {
@@ -155,7 +161,7 @@ message MountingPosition
     optional Vector3d position = 1;
 
     // Orientation offset relative to the specified reference coordinate system.
-    //
+    // Origin_sensor := Rotation_yaw_pitch_roll(MountingPosition.orientation)*(Origin_reference_coordinate_system - MountingPosition.position)
     optional Orientation3d orientation = 2;
 }
 
@@ -167,7 +173,10 @@ message MountingPosition
 // Units are [m] for radial distance and [rad] for azimuth and elevation angles. 
 // If azimuth and elevation are zero, the referenced point lies directly ahead
 // in the central viewing direction of the sensor, and the respective vector points directly in the latter.
+// A positive angle corresponds to a clockwise rotation around the respective axis, i.e. 
+// z-axis (azimuth = yaw), y-axis (elevation = pitch).
 //
+// vector_cartesian := Rotation(elevation)*Rotation(azimuth)*Unit_vector_x*distance
 message Spherical3d
 {
     // The radial distance.
@@ -188,6 +197,9 @@ message Spherical3d
 // 
 // This includes the StationaryObject, TrafficSign, TrafficLight, RoadMarking messages.
 //
+// All coordinates and orientations are relative to the global ground truth
+// coordinate system.
+//
 message BaseStationary
 {
     // The 3D dimensions of the stationary object (bounding box), e.g. a landmark:
@@ -199,7 +211,9 @@ message BaseStationary
     optional Vector3d position = 2;
 
     // The relative orientation of the stationary object w.r.t. its parent frame.
-    // There may be some constraints how to use orientation w.r.t. to some stationary object's or entity's definition.
+    //
+    // Origin_base_stationary_entity := Rotation_yaw_pitch_roll(BaseStationary.orientation)*(Origin_parent_coordinate_system - BaseStationary.position)
+    // \note There may be some constraints how to align the orientation w.r.t. to some stationary object's or entity's definition.
     optional Orientation3d orientation = 3;
 
     // Usage as ground truth:
@@ -225,6 +239,9 @@ message BaseStationary
 // 
 // This includes the MovingObject messages.
 //
+// All coordinates and orientations are relative to the global ground truth
+// coordinate system.
+//
 message BaseMoving
 {
     // The 3D dimension of the moving object (its bounding box).
@@ -237,18 +254,27 @@ message BaseMoving
 
     // The relative orientation of the moving object w.r.t. its parent frame.
     //
+    // Origin_base_moving_entity := Rotation_yaw_pitch_roll(BaseMoving.orientation)*(Origin_parent_coordinate_system - BaseMoving.position)
+    // \note There may be some constraints how to align the orientation w.r.t. to some stationary object's or entity's definition.
     optional Orientation3d orientation = 3;
 
     // The relative velocity of the moving object w.r.t. its parent frame and parent velocity.
     // The velocity becomes global/absolute if the parent frame does not move.
+    //
+    // BaseMoving.position(t) := BaseMoving.position(t-dt)+velocity*dt 
     optional Vector3d velocity = 4;
 
     // The relative acceleration of the moving object w.r.t. its parent frame and parent acceleration.
     // The acceleration becomes global/absolute if the parent frame is not accelerating.
+    //
+    // BaseMoving.position(t) := BaseMoving.position(t-dt)+velocity*dt+acceleration/2*dt^2
+    // BaseMoving.velocity(t) := BaseMoving.velocity(t-dt)+acceleration*dt 
     optional Vector3d acceleration = 5;
 
-    // The relative orientation rate of the moving object w.r.t. its parent frame and parent orientation rate in the center point of the bounding box.
-    // The orientation rate becomes global/absolute if the parent frame is not rotating.
+    // The relative orientation rate of the moving object w.r.t. its parent frame and parent orientation rate in the center point of the bounding box (origin of the bounding box frame).
+    //
+    // Rotation_yaw_pitch_roll(BaseMoving.orientation(t)) := Rotation_yaw_pitch_roll(BaseMoving.orientation_rate*dt)*Rotation_yaw_pitch_roll(BaseMoving.orientation(t-dt))
+    // \note BaseMoving.orientation(t) is \b not equal BaseMoving.orientation(t-dt)+BaseMoving.orientation_rate*dt
     optional Orientation3d orientation_rate = 6;
 
     // Usage as ground truth:

osi_detectedobject.proto

@@ -93,16 +93,20 @@ message DetectedObject
     // The estimated probabilities for the object to belong to a specific class.
     //
     optional ClassProbability class_probability = 17;
-
-    // The estimated pedestrian head pose.
+    
+    // Pedestrian head pose for behaviour prediction. Describes the head
+    // orientation w.r.t. the host vehicle orientation.
+    // x-axis of head_pose is pedestrian's straight ahead viewing direction.
     //
-    // \note Pedestrian specific value.
-    optional Orientation3d pedestrian_head_pose = 18;
+    // View_normal_base_coord_system = Inverse_Rotation(head_pose)*Unit_vector_x 
+    optional Orientation3d head_pose = 18;
 
-    // The estimated pedestrian upper body pose.
+    // Pedestrian upper body pose for behaviour prediction. Describes the
+    // upper body orientation w.r.t. the host vehicle orientation.
+    // x-axis of upper_body_pose is pedestrian's upper body intended moving direction.
     //
-    // \note Pedestrian specific value.
-    optional Orientation3d pedestrian_upper_body_pose = 19;
+    // View_normal_base_coord_system = Inverse_Rotation(upper_body_pose)*Unit_vector_x 
+    optional Orientation3d upper_body_pose = 19;
 
     // Percentage side lane left.
     //

osi_featuredata.proto

@@ -54,17 +54,18 @@ message DetectionHeader
     //
     // The origin of the detection coordinate system (= spherical polar
     // coordinates) is the sensor mounting pose in the host vehicle coordinate
-    // system.
+    // system w.r.t. orientation of the sensor mounting position.
     //
     // The host vehicle coordinate system is at the center of the rear axle
     // (from the top view as well as from the side view) in the static case.
     // The origin represents the current mounting pose to the best knowledge of
-    // the sensor. It includes the estimated 6D pose estimation given by  the
+    // the sensor. It includes the estimated 6D pose estimation given by the
     // calibration. The uncertainty of this estimation is given with the
     // corresponding 6D root mean squared error. The estimation of the current
     // origin does not include effects due to short-time dynamics, such as pitch
     // angles from braking, but includes long-time calibration values, such as
     // pitch angles from luggage in the trunk.
+    // 
     optional MountingPosition mounting_position = 4;
 
     // Uncertainty of the mounting pose calibration should be included in the

osi_landmark.proto

@@ -9,6 +9,9 @@ package osi;
 //
 // \brief A traffic sign.
 //
+// All coordinates and orientations are relative to the global ground truth
+// coordinate system.
+//
 message TrafficSign
 {
     // The ID of the traffic sign.
@@ -935,6 +938,9 @@ message TrafficLight
 // 
 // Lane Markings are excluded and defined as LaneBoundaries as part of the Lanes.
 //
+// All coordinates and orientations are relative to the global ground truth
+// coordinate system.
+//
 message RoadMarking
 {
     // The ID of the road marking.
@@ -988,11 +994,6 @@ message RoadMarking
     // Might be multiple if the road marking goes across multiple lanes.
     repeated Identifier assigned_lane = 9;
 
-    // Intersection orientation of the road marking.
-    //
-    // \note Defined for \c Lane::type = TYPE_INTERSECTION, otherwise zero vector
-    optional Vector3d roadmarking_orientation = 10;
-
     // Definition of road marking types.
     //
     enum Type

osi_object.proto

@@ -15,10 +15,10 @@ package osi;
 // for the host vehicle (R rotates from vehicle to world frame, i.e. inverse
 // orientation of base.orientation).
 // 
-// For all vehicles, including host vehicles, the position given  in
+// For all vehicles, including host vehicles, the position given in
 // base.position points to the center of the vehicle's bounding box.
 //
-// The object coordinates are defined as x-axis is the direction from rear to
+// The vehicle object coordinates are defined as x-axis is the direction from rear to
 // front of the vehicle, y-axis corresponds to rear axle and z-axis points to
 // vehicle ceiling.
 //

osi_sensordata.proto

@@ -76,16 +76,21 @@ message SensorData
     optional Identifier host_vehicle_id = 5;
 
     // The mounting position of the sensor (origin and orientation of the sensor coordinate system)
+    // given in vehicle coordinates [1].
     //
-    // given in vehicle coordinates: origin is ( \c Vehicle::base.position + INV(\c Vehicle::base.orientation) * \c Vehicle::bbcenter_to_rear) the orientation is equal to the orientation of the vehicle \c Vehicle::base.orientation.
+    // \arg \b x-direction of sensor coordinate system: sensor viewing direction
+    // \arg \b z-direction of sensor coordinate system: sensor (up)
+    // \arg \b y-direction of sensor coordinate system: perpendicular to x and z right hand system
     //
-    // \arg \b x-direction: longitudinal direction & positive in driving direction
-    // \arg \b y-direction: lateral direction & positive to the left when looking orientated as a driver
-    // \arg \b z-direction: perpendicular to x and z right hand system (up)
-    //
-    // See https://en.wikipedia.org/wiki/Axes_conventions#/media/File:RPY_angles_of_cars.png 
+    // \par References: 
+    // [1] DIN ISO 8855:2013-11
     //
     // \note This field is usually static during the simulation.
+    // \note The origin of vehicle's coordinate system in world frame is 
+    // ( \c Vehicle::base.position + Inverse_Rotation_yaw_pitch_roll(\c Vehicle::base.orientation) * \c Vehicle::bbcenter_to_rear) .
+    // The orientation of the vehicle's coordinate system is equal to the orientation 
+    // of the vehicle's bounding box \c Vehicle::base.orientation.
+    //
     optional MountingPosition mounting_position = 6;
 
     // The root mean squared error of the mounting position.

osi_sensorinputconfiguration.proto

@@ -64,23 +64,31 @@ package osi;
 message SensorInputConfiguration
 {
     // The mounting position of the sensor (origin and orientation of the sensor coordinate system)
+    // given in vehicle coordinates [1].
     //
-    // given in vehicle coordinates: origin is \c Vehicle::reference_point; the orientation is equal to the orientation of the vehicle.
+    // \arg \b x-direction of sensor coordinate system: sensor viewing direction
+    // \arg \b z-direction of sensor coordinate system: sensor (up)
+    // \arg \b y-direction of sensor coordinate system: perpendicular to x and z right hand system
     //
-    // \arg \b x-direction: longitudinal direction & positive in driving direction
-    // \arg \b y-direction: lateral direction & positive to the left when looking orientated as a driver
-    // \arg \b z-direction: perpendicular to x and z right hand system (up)
+    // \par References: 
+    // [1] DIN ISO 8855:2013-11
     //
-    // See https://en.wikipedia.org/wiki/Axes_conventions#/media/File:RPY_angles_of_cars.png
+    // \note The origin of vehicle's coordinate system in world frame is 
+    // ( \c Vehicle::base.position + Inverse_Rotation_yaw_pitch_roll(\c Vehicle::base.orientation) * \c Vehicle::bbcenter_to_rear) .
+    // The orientation of the vehicle's coordinate system is equal to the orientation 
+    // of the vehicle's bounding box \c Vehicle::base.orientation.
     // \note A default position can be provided by the sensor model (e.g. to indicate the position the model was validated for),
     // but this is optional; the environment simulation must provide a valid mounting position (based on the vehicle configuration)
     // when setting the input configuration.
+    //
     optional MountingPosition mounting_position = 1;
 
     // Field of View in horizontal orientation of the sensor
     //
     // This determines the limit of the cone of interest of ground truth
     // that the simulation environment has to provide.
+    // Viewing range: [-field_of_view_horizontal/2, field_of_view_horizontal]
+    // in sensor coordinate system.
     //
     // Unit: [rad]
     optional double field_of_view_horizontal = 2;
@@ -89,6 +97,8 @@ message SensorInputConfiguration
     //
     // This determines the limit of the cone of interest of ground truth
     // that the simulation environment has to provide.
+    // Viewing range: [-field_of_view_vertical/2, field_of_view_vertical]
+    // in sensor coordinate system.
     //
     // Unit: [rad]
     optional double field_of_view_vertical = 3;
@@ -199,6 +209,7 @@ message RadarSensorInputConfiguration
     //
     // \brief The radar antenna diagram.
     //
+    // \note Rotation is defined analog OSI:Spherical3d
     message AntennaDiagramEntry {
         // Horizontal deflection (azimuth) of entry in sensor/antenna
         // coordinates

osi_sensorspecific.proto

@@ -29,15 +29,7 @@ message LidarSpecificObjectData
 //
 message CameraSpecificObjectData
 {
-    // Pedestrian head pose for behaviour prediction. Describes the head
-    // orientation w.r.t. the host vehicle orientation.
-    //
-    optional Orientation3d head_pose = 1;
-
-    // Pedestrian upper body pose for behaviour prediction. Describes the
-    // upper body orientation w.r.t. the host vehicle orientation.
-    //
-    optional Orientation3d upper_body_pose = 2;
+    // currently no fields.
 }
 
 //