Enhance description for bounding_box_section

Add information regarding the handling of side mirrors and the
definition of the bounding box.

Signed-off-by: Pierre R. Mai <pmai@pmsf.de>

Author: thempen

osi_common.proto

@@ -387,14 +387,17 @@ message LogicalLaneAssignment
     optional double angle_to_lane = 4;
 }
 
-// \brief A bounding box containing a sub-section of a object. 
+// \brief A bounding box description. 
 //
 // A bounding box representing a sub-section of it's parents overall dimension, 
-// either that of a \c MovingObject or \c StationaryObject .
+// either that of a \c BaseMoving or \c BaseStationary .
 //
 // The parent frame of the \c BoundingBox is not relative to the parent object
 // it is associated to, but in the same parent frame as the parent object.
 //
+// \note The actual bounding box of the object is defined in dimension, position
+// and orientation of the \c BaseMoving and \c BaseStationary .
+//
 message BoundingBox
 {
     // The 3D dimensions of the bounding box.
@@ -448,31 +451,25 @@ message BoundingBox
         TYPE_CHASSIS = 2;
 
         // The door of a vehicle.
-        //
-        // \note A door may extend beyond the dimension of the parent when in
-        // an open state. A closed door must be within the original dimension.
         // 
         TYPE_DOOR = 3;
 
         // The side mirror of a vehicle.
         //
-        // \note A side mirror may extend beyond the dimension of the parent.
+        // \note The side mirror is not included in the actual bounding box of 
+        // the parent object.
         // 
         TYPE_SIDE_MIRROR = 4;
 
         // Additional cargo attached to the a vehicle which is temporarily
         // attached.
-        //
-        // \note Cargo may extend beyond the dimension of the parent.
         // 
         TYPE_CARGO = 5;
 
         // The wheel of a vehicle.
         //
-        // \note A wheel may extend beyond the dimension of the parent.
-        //
         // \note For more detailed information about the wheels of an object,
-        // please refer to \c MovingObject/VehicleAttributes/WheelData .
+        // please refer to \c MovingObject/VehicleAttributes/WheelData.
         // 
         TYPE_WHEEL = 6;
 
@@ -484,6 +481,7 @@ message BoundingBox
         // 
         // \note Limbs can be sub-divided to increase accuracy, i.e. for upper 
         // and lower arm/leg sections.
+        //
         TYPE_LIMB = 8;
 
         // The head of a person or animal.
@@ -526,6 +524,9 @@ message BaseStationary
     // The 3D dimensions of the stationary object (bounding box), e.g. a
     // landmark.
     //
+    // \note The \c #dimension must completely enclose the geometry of the 
+    // \c BaseStationary .
+    //
     optional Dimension3d dimension = 1;
 
     // The reference point for position and orientation, i.e. the center (x,y,z)
@@ -572,13 +573,9 @@ message BaseStationary
     // Sub-divisions of the overall bounding box of the \c BaseStationary object.
     //
     // The bounding box sections can include separate parts on partially-opaque
-    // objects such are trees with a distinction between trunk and crown.
-    //
-    // \note When one or more \c BoundingBox s are associated to a 
-    // \c BaseStationary , the expectation is that all sections are contained
-    // within the bounds of the \c #dimension .
+    // objects such as trees with a distinction between trunk and crown.
     // 
-    // \note It is also expcted that when using \c #bounding_box_section ,
+    // \note It is expected that when using \c #bounding_box_section ,
     // anyone consuming this data has the guarantee that all others parts of 
     // the \c BaseStationary are covered by a sub-section, such that the 
     // guarentee is that the remaining area of the objects dimension is
@@ -607,13 +604,17 @@ message BaseMoving
 {
     // The 3D dimension of the moving object (its bounding box).
     //
+    // \note The \c #dimension must completely enclose the geometry of the 
+    // \c BaseMoving .
+    //
     // \note The bounding box does NOT include side mirrors for vehicles.
     //
     optional Dimension3d dimension = 1;
 
     // The reference point for position and orientation: the center (x,y,z) of
     // the bounding box.
     //
+    //
     optional Vector3d position = 2;
 
     // The relative orientation of the moving object w.r.t. its parent frame,
@@ -712,16 +713,13 @@ message BaseMoving
     //
     // The bounding box sections can include side mirrors, cargo, etc. for 
     // vehicles, as well as body-part sections for pedestrians.
-    //
-    // \note When one or more \c BoundingBox s are associated to a 
-    // \c BaseMoving , the expectation is that all sections are contained
-    // within the bounds of the \c #dimension .
     // 
-    // \note It is also expcted that when using \c #bounding_box_section ,
+    // \note It is also expected that when using \c #bounding_box_section ,
     // anyone consuming this data has the guarantee that all others parts of 
     // the \c BaseMoving are covered by a sub-section, such that the 
     // guarentee is that the remaining area of the objects dimension is
     // represented by space where no physical collisions could be detected.
+    // This does not include the side mirrors.
     //
     repeated BoundingBox bounding_box_section = 9;
 }