Documentation and figures 3.0.1 solves #185

.gitignore

@@ -30,3 +30,5 @@ version.py
 __pycache__/
 *.py[cod]
 proto2cpp.log
+.clang-format
+githooks/pre-commit

osi_common.proto

@@ -87,6 +87,8 @@ message Timestamp
 // \brief The dimension of a 3D box, e.g. the size of a 3D bounding box or its
 // uncertainties.
 //
+// \image html OSI_Dimension3d.jpg
+//
 // The dimensions are positive. Uncertainties are negative or positive.
 //
 // Dimension is defined in the specified reference coordinate frame along the
@@ -135,7 +137,9 @@ message Dimension3d
 //
 // <tt>Rotation_yaw_pitch_roll = Rotation_roll*Rotation_pitch*Rotation_yaw</tt>
 //
-// <tt>vector_global_coord_system := Inverse_Rotation_yaw_pitch_roll(</tt><tt>Orientation3d</tt><tt>)*(vector_local_coord_system) + local_origin::position</tt>
+// <tt>vector_global_coord_system :=
+// Inverse_Rotation_yaw_pitch_roll(</tt><tt>Orientation3d</tt><tt>)*(vector_local_coord_system)
+// + local_origin::position</tt>
 //
 // \attention This definition changed in OSI version 3.0.0. Previous OSI
 // versions  (V2.xx) had an other definition.
@@ -198,7 +202,9 @@ message MountingPosition
 
     // Orientation offset relative to the specified reference coordinate system.
     //
-    // <tt>Origin_sensor := Rotation_yaw_pitch_roll(#orientation)*(Origin_reference_coordinate_system - #position)</tt>
+    // <tt>Origin_sensor :=
+    // Rotation_yaw_pitch_roll(#orientation)*(Origin_reference_coordinate_system
+    // - #position)</tt>
     //
     optional Orientation3d orientation = 2;
 }
@@ -210,13 +216,14 @@ message MountingPosition
 //
 // 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 SensorDetectionHeader) 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 Orientation3d. For the
+// \c SensorDetectionHeader) 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 Orientation3d. For the
 // sense of each rotation, the right-hand rule applies.
 //
-// <tt>vector_cartesian := Rotation(#elevation)*Rotation(#azimuth)*Unit_vector_x*#distance</tt>
+// <tt>vector_cartesian :=
+// Rotation(#elevation)*Rotation(#azimuth)*Unit_vector_x*#distance</tt>
 //
 message Spherical3d
 {
@@ -245,8 +252,10 @@ message Spherical3d
 // This includes the \c StationaryObject , \c TrafficSign ,
 // \c TrafficLight , \c RoadMarking messages.
 //
+// \image html OSI_BaseStationary.jpg
+//
 // All coordinates and orientations from ground truth objects are relative to
-// the global ground truth frame. All coordinates and orientations
+// the global ground truth frame (see image). All coordinates and orientations
 // from detected objects are relative to the host vehicle frame (see:
 // \c MovingObject::Vehicle vehicle reference point).
 //
@@ -265,7 +274,9 @@ message BaseStationary
     // The relative orientation of the stationary object w.r.t. its parent
     // frame.
     //
-    // <tt>Origin_base_stationary_entity := Rotation_yaw_pitch_roll(#orientation)*(Origin_parent_coordinate_system - #position)</tt>
+    // <tt>Origin_base_stationary_entity :=
+    // Rotation_yaw_pitch_roll(#orientation)*(Origin_parent_coordinate_system -
+    // #position)</tt>
     //
     // \note There may be some constraints how to align the orientation w.r.t.
     // to some stationary object's or entity's definition.
@@ -274,8 +285,8 @@ message BaseStationary
 
     // Usage as ground truth:
     // The two dimensional (flat) contour of the object. This is an extension of
-    // the concept of a bounding box as defined by \c Dimension3d. The contour is
-    // the projection of the object's outline onto the z-plane in the object
+    // the concept of a bounding box as defined by \c Dimension3d. The contour
+    // is the projection of the object's outline onto the z-plane in the object
     // frame (independent of its current position and orientation). The height
     // is the same as the height of the bounding box.
     //
@@ -318,7 +329,9 @@ message BaseMoving
 
     // The relative orientation of the moving object w.r.t. its parent frame.
     //
-    // <tt>Origin_base_moving_entity := Rotation_yaw_pitch_roll(#orientation)*(Origin_parent_coordinate_system - #position)</tt>
+    // <tt>Origin_base_moving_entity :=
+    // Rotation_yaw_pitch_roll(#orientation)*(Origin_parent_coordinate_system -
+    // #position)</tt>
     //
     // \note There may be some constraints how to align the orientation w.r.t.
     // to some stationary object's or entity's definition.
@@ -338,7 +351,8 @@ message BaseMoving
     // The acceleration becomes global/absolute if the parent frame is not
     // accelerating.
     //
-    // <tt> #position (t) := #position (t-dt)+ #velocity *dt+ #acceleration /2*dt^2</tt>
+    // <tt> #position (t) := #position (t-dt)+ #velocity *dt+ #acceleration
+    // /2*dt^2</tt>
     //
     // <tt> #velocity (t) := #velocity (t-dt)+ #acceleration *dt</tt>
     //
@@ -348,16 +362,19 @@ message BaseMoving
     // frame and parent orientation rate in the center point of the bounding box
     // (origin of the bounding box frame).
     //
-    // <tt>Rotation_yaw_pitch_roll(#orientation (t)) := Rotation_yaw_pitch_roll(#orientation_rate *dt)*Rotation_yaw_pitch_roll(#orientation (t-dt))</tt>
+    // <tt>Rotation_yaw_pitch_roll(#orientation (t)) :=
+    // Rotation_yaw_pitch_roll(#orientation_rate
+    // *dt)*Rotation_yaw_pitch_roll(#orientation (t-dt))</tt>
     //
-    // \note <tt>#orientation (t)</tt> is \b not equal <tt>#orientation (t-dt)+#orientation_rate *dt</tt>
+    // \note <tt>#orientation (t)</tt> is \b not equal <tt>#orientation
+    // (t-dt)+#orientation_rate *dt</tt>
     //
     optional Orientation3d orientation_rate = 6;
 
     // Usage as ground truth:
     // The two dimensional (flat) contour of the object. This is an extension of
-    // the concept of a bounding box as defined by \c Dimension3d. The contour is
-    // the projection of the object's outline onto the z-plane in the object
+    // the concept of a bounding box as defined by \c Dimension3d. The contour
+    // is the projection of the object's outline onto the z-plane in the object
     // frame (independent of its current position and orientation). The height
     // is the same as the height of the bounding box.
     //

osi_detectedlane.proto

@@ -70,12 +70,13 @@ message DetectedLaneBoundary
     // attribute has to be set for each instance. All other values will be
     // reused from the previous \c BoundaryPoint in the sequence or set to
     // default values if there is none or it was never set. For dashed lines,
-    // one \c LaneBoundary::BoundaryPoint has to be at the start and another at the end
-    // of each dashed line segment. For Botts' dots lines, one
-    // \c LaneBoundary::BoundaryPoint position has to define each Botts' dot.
+    // one \c LaneBoundary::BoundaryPoint has to be at the start and another at
+    // the end of each dashed line segment. For Botts' dots lines, one \c
+    // LaneBoundary::BoundaryPoint position has to define each Botts' dot.
     //
-    // \attention For \c LaneBoundary::BoundaryPoint the same rules regarding maximum
-    // distance and approximation error apply as for \c Lane::Classification::centerline.
+    // \attention For \c LaneBoundary::BoundaryPoint the same rules regarding
+    // maximum distance and approximation error apply as for \c
+    // Lane::Classification::centerline.
     //
     repeated LaneBoundary.BoundaryPoint boundary_line = 3;
 

osi_detectedobject.proto

@@ -71,8 +71,8 @@ message DetectedItemHeader
         //
         MEASUREMENT_STATE_UNKNOWN = 0;
 
-        // Measurement state is unspecified (but known, i.e. value is not part of
-        // this enum list).
+        // Measurement state is unspecified (but known, i.e. value is not part
+        // of this enum list).
         //
         MEASUREMENT_STATE_OTHER = 1;
 
@@ -91,6 +91,8 @@ message DetectedItemHeader
 // \brief A stationary object (e.g. landmark) in the environment as detected by
 // the sensor.
 //
+// \image html OSI_DetectedStatObject.jpg
+//
 message DetectedStationaryObject
 {
     // Common information of one detected item.
@@ -242,18 +244,20 @@ message DetectedMovingObject
         // Specific information about the classification of the vehicle.
         //
         //
-        // \note This field is mandatory if the \c CandidateMovingObject::type is
-        // \c MovingObject::TYPE_VEHICLE .
+        // \note This field is mandatory if the \c CandidateMovingObject::type
+        // is \c MovingObject::TYPE_VEHICLE .
         //
         optional MovingObject.VehicleClassification vehicle_classification = 3;
 
         // Pedestrian head pose for behavior prediction. Describes the head
         // orientation w.r.t. the host vehicle orientation.
         // The x-axis of the right-handed head frame is pointing along the
-        // pedestrian's straight ahead viewing direction and the z-axis is pointing
-        // upwards (cranial direction [1] i.e. to pedestrian's skull cap).
+        // pedestrian's straight ahead viewing direction and the z-axis is
+        // pointing upwards (cranial direction [1] i.e. to pedestrian's skull
+        // cap).
         //
-        // <tt>View_normal_base_coord_system = Inverse_Rotation(#head_pose)*Unit_vector_x</tt>
+        // <tt>View_normal_base_coord_system =
+        // Inverse_Rotation(#head_pose)*Unit_vector_x</tt>
         //
         // \note This field is mandatory if the \c CandidateMovingObject.type is
         // \c MovingObject::TYPE_PEDESTRIAN
@@ -266,14 +270,15 @@ message DetectedMovingObject
         // Pedestrian upper body pose for behavior prediction. Describes the
         // upper body orientation w.r.t. the host vehicle orientation.
         // The x-axis of the right-handed upper body frame is pointing along the
-        // pedestrian's upper body ventral direction [2] (i.e. usually pedestrian's
-        // intended moving direction) and the z-axis is pointing upwards (to
-        // pedestrian's head).
+        // pedestrian's upper body ventral direction [2] (i.e. usually
+        // pedestrian's intended moving direction) and the z-axis is pointing
+        // upwards (to pedestrian's head).
         //
-        // <tt>View_normal_base_coord_system = Inverse_Rotation(#upper_body_pose)*Unit_vector_x</tt>
+        // <tt>View_normal_base_coord_system =
+        // Inverse_Rotation(#upper_body_pose)*Unit_vector_x</tt>
         //
-        // \note This field is mandatory if the \c CandidateMovingObject::type is
-        // \c MovingObject::TYPE_PEDESTRIAN
+        // \note This field is mandatory if the \c CandidateMovingObject::type
+        // is \c MovingObject::TYPE_PEDESTRIAN
         //
         // \par References:
         // - [2] https://en.wikipedia.org/wiki/Anatomical_terms_of_location

osi_detectedroadmarking.proto

@@ -11,6 +11,8 @@ package osi3;
 //
 // \brief A road marking in the environment as detected by the sensor.
 //
+// \image html OSI_DetectedRoadMarking.jpg
+//
 message DetectedRoadMarking
 {
     // Common information of one detected item.

osi_detectedtrafficlight.proto

@@ -11,6 +11,8 @@ package osi3;
 //
 // \brief A traffic light in the environment as detected by the sensor.
 //
+// \image html OSI_DetectedTrafficLight.jpg
+//
 message DetectedTrafficLight
 {
     // Common information of one detected item.

osi_detectedtrafficsign.proto

@@ -11,6 +11,8 @@ package osi3;
 //
 // \brief A traffic sign in the environment as detected by the sensor.
 //
+// \image html OSI_DetectedTrafficSigns.jpg
+//
 message DetectedTrafficSign
 {
     // Common information of one detected item.
@@ -30,6 +32,8 @@ message DetectedTrafficSign
     //
     // \brief Candidates for a detected main sign as estimated by the sensor.
     //
+    // \image html OSI_DetectedMainTrafficSign.jpg
+    //
     message DetectedMainSign
     {
         // A list of candidates for this traffic sign as estimated by the
@@ -48,8 +52,8 @@ message DetectedTrafficSign
         // (Normally it is equal to the ground truth z-axis.)
         // The x-axis of the given \c BaseStationary::orientation is view
         // normal of the traffic sign's image.
-        // This x-axis points from the traffic sign's image in the direction from
-        // where a 'viewer' could see the traffic sign image.
+        // This x-axis points from the traffic sign's image in the direction
+        // from where a 'viewer' could see the traffic sign image.
         //
         optional BaseStationary base = 2;
 
@@ -71,9 +75,9 @@ message DetectedTrafficSign
         {
             // The estimated probability that this candidate is the true value.
             //
-            // \note The sum of all \c #probability must be one. This probability is
-            // given under the condition of
-            // \c DetectedItemHeader::existence_probability.
+            // \note The sum of all \c #probability must be one. This
+            // probability is given under the condition of \c
+            // DetectedItemHeader::existence_probability.
             //
             // Range: [0,1]
             //
@@ -104,11 +108,12 @@ message DetectedTrafficSign
             //
             GEOMETRY_CIRCLE = 2;
 
-            // Traffic sign has a triangular geometry pointing to the top. (3 corners)
+            // Traffic sign has a triangular geometry pointing to the top. (3
+            // corners)
             //
             GEOMETRY_TRIANGLE_TOP = 3;
 
-            //Traffic sign has a triangular geometry pointing down. (3 corners)
+            // Traffic sign has a triangular geometry pointing down. (3 corners)
             //
             GEOMETRY_TRIANGLE_DOWN = 4;
 
@@ -135,11 +140,13 @@ message DetectedTrafficSign
             //
             GEOMETRY_DIAMOND = 9;
 
-            // Traffic sign has a geometry of an arrow pointing to the left. (5 corners)
+            // Traffic sign has a geometry of an arrow pointing to the left. (5
+            // corners)
             //
             GEOMETRY_ARROW_LEFT = 10;
 
-            // Traffic sign has a geometry of an arrow pointing to the right. (5 corners)
+            // Traffic sign has a geometry of an arrow pointing to the right. (5
+            // corners)
             //
             GEOMETRY_ARROW_RIGHT = 11;
 
@@ -153,6 +160,8 @@ message DetectedTrafficSign
     // \brief Candidates for all detected supplementary signs of one traffic
     // sign as estimated by the sensor.
     //
+    // \image html OSI_DetectedSuppSign.jpg
+    //
     message DetectedSupplementarySign
     {
         // The definition of one of more supplementary signs that together
@@ -167,12 +176,12 @@ message DetectedTrafficSign
         // The orientation of the bounding box \c SupplementarySign::base
         // ( \c BaseStationary::orientation ) is defined as follows:
         // The z-axis of the given \c BaseStationary::orientation is the vector
-        // from the bottom to the top of the supplementary traffic sign's 2D image
-        // plate. (Normally it is equal to the ground truth z-axis.)
-        // The x-axis of the given \c BaseStationary::orientation is view
-        // normal of the supplementary traffic sign's image.
-        // This x-axis points from the supplementary traffic sign's image in the
-        // direction from where a 'viewer' could see the supplementary traffic sign image.
+        // from the bottom to the top of the supplementary traffic sign's 2D
+        // image plate. (Normally it is equal to the ground truth z-axis.) The
+        // x-axis of the given \c BaseStationary::orientation is view normal of
+        // the supplementary traffic sign's image. This x-axis points from the
+        // supplementary traffic sign's image in the direction from where a
+        // 'viewer' could see the supplementary traffic sign image.
         //
         optional BaseStationary base = 2;
 
@@ -191,21 +200,22 @@ message DetectedTrafficSign
         {
             // The estimated probability that this candidate is the true value.
             //
-            // \note The sum of all \c #probability must be one. This probability is
-            // given under the condition of
-            // \c DetectedItemHeader::existence_probability.
+            // \note The sum of all \c #probability must be one. This
+            // probability is given under the condition of \c
+            // DetectedItemHeader::existence_probability.
             //
             // Range: [0,1]
             //
             optional double probability = 1;
 
-            // The classification of one of more supplementary signs that together
-            // define this candidate.
+            // The classification of one of more supplementary signs that
+            // together define this candidate.
             //
             // \note IDs, which are referenced in this message, usually
             // reference to \c DetectedXXX::tracking_id IDs.
             //
-            optional TrafficSign.SupplementarySign.Classification classification = 2;
+            optional TrafficSign.SupplementarySign.Classification
+                classification = 2;
         }
     }
 }