Update comments and reformat documentation

Update comments
Reformat comments (max 80 chars).

Author: Carsten Kuebler

osi_common.proto

@@ -6,8 +6,9 @@ package osi;
 
 
 //
-// \brief A cartesian 3D vector for positions, velocities or accelerations or its uncertainties.
-// 
+// \brief A cartesian 3D vector for positions, velocities or accelerations or
+// its uncertainties.
+//
 // Units are [m] for positions, [m/s] for velocities and [m/s^2] for accelerations.
 //
 // The coordinate system is defined as right-handed. 
@@ -16,55 +17,64 @@ message Vector3d
 {
     // The x coordinate.
     //
+    // Unit [m] [m/s] or [m/s^2]
     optional double x = 1;
 
     // The y coordinate.
     //
+    // Unit [m] [m/s] or [m/s^2]
     optional double y = 2;
 
     // The z coordinate.
     //
+    // Unit [m] [m/s] or [m/s^2]
     optional double z = 3;
 }
 
 //
-// \brief A cartesian 2D vector for positions, velocities or accelerations or its uncertainties.
-// 
+// \brief A cartesian 2D vector for positions, velocities or accelerations or
+// its uncertainties.
+//
 // Units are [m] for positions, [m/s] for velocities and [m/s^2] for accelerations.
 //
 message Vector2d
 {
     // The x coordinate.
     //
+    // Unit [m] [m/s] or [m/s^2]
     optional double x = 1;
 
     // The y coordinate.
     //
+    // Unit [m] [m/s] or [m/s^2]
     optional double y = 2;
 }
 
 //
 // \brief A timestamp.
 // 
-// Names and types of fields are chosen in accordance to google/protobuf/timestamp.proto to allow a possible switch in the future. 
-// There is no definition of the zero point in time neither it is the Unix epoch. 
-// A simulation may start at the zero point in time but it is not mandatory.
-//
+// Names and types of fields are chosen in accordance to 
+// google/protobuf/timestamp.proto to allow a possible switch in the future. 
+// There is no definition of the zero point in time neither it is the Unix
+// epoch. A simulation may start at the zero point in time but it is not
+// mandatory.
 message Timestamp
 {
-    // The number of seconds since the start of e.g. the simulation / system / vehicle. 
+    // The number of seconds since the start of e.g. the simulation / system / 
+    // vehicle. 
+    //
     // Unit: [s]
     optional int64 seconds = 1;
 
     // The number of nanoseconds since the start of the last second. 
+    //
     // Unit: [ns]
     optional int32 nanos = 2;
 }
 
 //
-// \brief The dimension of a 3D box, e.g. the size of a 3D bounding box or its uncertainties.
-// 
-// Units are all [m].
+// \brief The dimension of a 3D box, e.g. the size of a 3D bounding box or its
+// uncertainties.
 //
 // The dimensions are positive. Uncertainties are negative or positive.
 //
@@ -75,25 +85,26 @@ message Dimension3d
 {
     // The length of the box.
     //
+    // Unit [m]
     optional double length = 1;
 
     // The width of the box.
     //
+    // Unit [m]
     optional double width = 2;
 
     // The height of the box.
     //
+    // Unit [m]
     optional double height = 3;
 }
 
 //
 // \brief A 3D orientation, orientation rate or orientation acceleration (i.e. 
 // derivatives) or its uncertainties denoted in euler angles.
 // 
-// Units are 
-// \arg [rad] for orientation
-// \arg [rad/s] for rates
-// \arg [rad/s^2] for accelerations
+// Units are [rad] for orientation [rad/s] for rates and [rad/s^2] for 
+// accelerations
 // 
 // The preferred angular range is (-pi, pi]. The coordinate system is defined as 
 // right-handed. 
@@ -122,14 +133,17 @@ message Orientation3d
 {
     // The roll angle/rate/acceleration.
     //
+    // Unit: [rad] [rad/s] or [rad/s^2]
     optional double roll = 1;
 
     // The pitch angle/rate/acceleration.
     //
+    // Unit: [rad] [rad/s] or [rad/s^2]
     optional double pitch = 2;
 
     // The yaw angle/rate/acceleration.
     //
+    // Unit: [rad] [rad/s] or [rad/s^2]
     optional double yaw = 3;
 }
 
@@ -175,33 +189,30 @@ message MountingPosition
 //
 // Used e.g., for low level representations of radar detections.
 // 
-// Units are [m] for radial distance and [rad] for azimuth and elevation angles.
-// With the x-axis of the sensor frame pointing in the central viewing direction 
-// of the sensor, the z-axis pointing upwards and the senor frame being 
-// right-handed, azimuth and elevation are defined as the rotations that would 
-// have to be applied to the sensor frame to make its x-axis point towards the 
-// referenced point or to align it with the referenced vector. The rotations are 
-// to be performed \b azimuth \b first (around the z-axis) and \b elevation 
-// \b second (around the new y-axis) to follow the definition of 
-// OSI:Orientation3D. For the sense of each rotation, the right-hand rule 
-// applies. 
-// 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.
+// Azimuth and elevation are defined as the rotations that would have to be 
+// applied to the local frame (e.g sensor frame definition in 
+// \c OSI:DetectionHeader) to make its x-axis point towards the referenced point
+// or to align it with the referenced vector. The rotations are to be performed
+// \b azimuth \b first (around the z-axis) and \b elevation \b second (around 
+// the new y-axis) to follow the definition of \c OSI:Orientation3D. For the
+// sense of each rotation, the right-hand rule applies.
 //
 // vector_cartesian := Rotation(elevation)*Rotation(azimuth)*Unit_vector_x*distance
 message Spherical3d
 {
     // The radial distance.
     //
+    // Unit: [m]
     optional double distance = 1;
 
     // The azimuth (horizontal) angle.
     //
+    // Unit: [rad]
     optional double azimuth = 2;
 
     // The elevation (vertical) angle.
     //
+    // Unit: [rad]
     optional double elevation = 3;
 }
 

osi_featuredata.proto

@@ -45,35 +45,40 @@ message DetectionHeader
     // for detailed discussions on the semantics of time-related fields.
     optional Timestamp measurement_time = 2;
 
-    // Monotonous counter to identify the exact cycle.
-    //
-    optional uint32 cycle_counter = 3;
-
-    // Mounting position of the sensor (origin and orientation of the cartesian
-    // sensor coordinate system); given relative from the middle of the rear
-    // axle of the host vehicle coordinate system (see: \c OSI::Vehicle vehicle
-    // reference point) to the sensor detection coordinate system's origin. The
-    // sensor detection coordinate system is a spherical polar coordinate system
-    // (same origin and orientation as cartesian sensor coordinate system).
-    //
-    // The sensor detection coordinate system's x-axis must be the angle
-    // bisector of the sensor's horizontal and vertical field of view in a
-    // right-handed coordinate system. The xy-plane represents the horizontal
-    // field of view and the xz-plane the vertical field of view.
+    // Monotonous counter to identify the exact cycle. 
+    // Generally the detecion function is called periodic and 
+    // \c DetectionHeader::cycle_counter corresponds to the number of periods.
+    optional uint64 cycle_counter = 3;
+
+
+    // Mounting position of the sensor (origin and orientation of the sensor 
+    // frame). Both origin and orientation are given in and with respect to the 
+    // host vehicle coordinate system (see: \c OSI::Vehicle vehicle reference
+    // point).
     //
-    // The origin represents the current mounting pose to the best knowledge of
-    // the sensor. The estimation of the 6D pose 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. 
+    // The sensor frame's x-axis is pointing in the central viewing direction of 
+    // the sensor. It is the angle bisector of the sensor's horizontal and 
+    // vertical field of view. The terms horizontal and vertical must be 
+    // understood as names for the two principal planes of the sensor's field of 
+    // view (relative to the sensor frame's orientation), which do not have to
+    // be horizontal or vertical in the strict sense of being parallel or 
+    // perpendicular to the local gravitational vector. The horizontal field
+    // of view defines the sensor frame's xy-plane and the vertical field
+    // of view defines the xz-plane. The sensor frame is right-handed and the 
+    // z-axis is pointing in an upward direction.
     //
+    // The sensor frame uses cartesian coordinates. The sensor frame's origin is
+    // identical to sensor detection frame's origin. Detections are defined in 
+    // the sensor detection frame which uses e.g. spherical coordinates.
     optional MountingPosition mounting_position = 4;
 
-    // Uncertainty of the mounting pose calibration should be included in the
-    // interface (x, y, z, yaw, pitch, roll).
-    //
+    // The origin/orientation of the sensor frame represents the current
+    // mounting pose to the best knowledge of the sensor. The estimation of the
+    // 6D pose 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_rmse = 5;
 
     // Data Qualifier expresses to what extent the content of this event can be 
@@ -172,7 +177,7 @@ enum DetectionClassification
 
 
 //
-// \brief A list of lidar detection.
+// \brief A list of lidar detection from one sensor.
 //
 message LidarDetectionList
 {
@@ -235,7 +240,7 @@ message LidarDetection
 }
 
 //
-// \brief A list of radar detections.
+// \brief A list of radar detections from one sensor.
 //
 message RadarDetectionList
 {