Merge pull request #159 from OpenSimulationInterface/documentation/review_1

Reformatting and review

Author: jdsika

osi_environment.proto

@@ -18,12 +18,15 @@ message EnvironmentalConditions
     //
     optional TimeOfDay time_of_day = 2;  
 
-    // Atmospheric pressure in Pascal [Pa] at z=0.0 in world frame (about 101325 [Pa]).
+    // Atmospheric pressure in Pascal at z=0.0 in world frame (about 101325
+    // [Pa]).
     //
+    // Unit: [Pa]
     optional double atmospheric_pressure = 3;
 
-    // Temperature in Kelvin [K] at z=0.0 in world frame.
+    // Temperature in Kelvin at z=0.0 in world frame.
     //
+    // Unit: [K]
     optional double temperature = 4;
 
     // Description of the precipitation.
@@ -38,8 +41,7 @@ message EnvironmentalConditions
     // (I = Intensity of precipitation in mm per hour [mm/h])
     //
     // \par References: 
-    // [1] PAULAT, Marcus, et al. A gridded dataset of hourly precipitation in Germany: Its construction, climatology and application.
-    // Meteorologische Zeitschrift, 2008, 17. Jg. Nr. 6, S. 719-732.
+    // [1] PAULAT, Marcus, et al. A gridded dataset of hourly precipitation in Germany: Its construction, climatology and application. Meteorologische Zeitschrift, 2008, 17. Jg. Nr. 6, S. 719-732.
     enum Precipitation
     {
         // Intensity of precipitation is unknown (must not be used in ground truth).
@@ -80,11 +82,15 @@ message EnvironmentalConditions
     }
 
     // Definition of discretized fog states according to [2].
-    // The bandwidth of thick and dense fog was adjusted to fit the German StVO regarding rear fog lights [3].
+    // The bandwidth of thick and dense fog was adjusted to fit the German StVO 
+    // regarding rear fog lights [3].
     // (V = Visibility in meters [m]) 
     //
-    // Visibility is defined as the length of the atmosphere over which a beam of light travels before its luminous flux is reduced to 5% of its original value (definition used by the Meteorological Office [4]). 
-    // This is approximately equivalent to visibility measured in terms of the contrast of a distant object against its background.
+    // Visibility is defined as the length of the atmosphere over which a beam 
+    // of light travels before its luminous flux is reduced to 5% of its 
+    // original value (definition used by the Meteorological Office [4]). 
+    // This is approximately equivalent to visibility measured in terms of the 
+    // contrast of a distant object against its background.
     //
     // \par References: 
     // [2] SHEPARD, Frank D. Reduced visibility due to fog on the highway. Transportation Research Board, 1996.
@@ -134,15 +140,21 @@ message EnvironmentalConditions
     }
 
     // Definition of discretized ambient illumination states:
-    // Ambient light is any light in the vehicle's environment that is not emitted by the vehicle 
-    // itself. It can include sun/moon light, light from other cars, street lights, etc.
+    // Ambient light is any light in the vehicle's environment that is not
+    // emitted by the vehicle itself. It can include sun/moon light, light from
+    // other cars, street  lights, etc.
     // 
-    // Lux [lx] is the SI unit of luminance or illumination of an area of exact one square metre, which is 
-    // equal to one lumen per square meter 1 [lx] = 1 [lm/m^2] [5].
-    // The lumen [lm] is the SI derived unit of luminous flux and a measure of the total
-    // quantity of visible light emitted by a source. The lumen is defined in relation to the candela [cd] as 1 [lm] =1 [cd sr] where [sr] denotes steradian, the unit of solid angle used in 3D geometry analogous to the radian. 
+    // Lux [lx] is the SI unit of luminance or illumination of an area of exact
+    // one square metre, which is equal to one lumen per square meter 1 [lx] = 
+    // 1 [lm/m^2] [5].
+    // The lumen [lm] is the SI derived unit of luminous flux and a measure of
+    // the total quantity of visible light emitted by a source. The lumen is 
+    // defined in relation to the candela [cd] as 1 [lm] =1 [cd sr] where [sr] 
+    // denotes steradian, the unit of solid angle used in 3D geometry analogous 
+    // to the radian. 
     //
-    //Categorization is done based on natural day/night time illuminance levels [6] and standards for required lighting levels on roads [6, 7, 8, 9]. 
+    // Categorization is done based on natural day/night time illuminance levels 
+    // [6] and standards for required lighting levels on roads [6, 7, 8, 9]. 
     //
     // \par References:
     // [5] [The NIST Reference on Constants, Units, and Uncertainty](https://physics.nist.gov/cuu/Units/units.html)
@@ -162,27 +174,33 @@ message EnvironmentalConditions
 
         // Level 1 illumination in ]0.001, 0.01[ [lx]
         // E.g. Night with no artificial light.
+        //
+        // \note Use \c AMBIENT_ILLUMINATION_LEVEL1 if illumination is less than 0.001 [lx]
         AMBIENT_ILLUMINATION_LEVEL1 = 2;
 
         // Level 2 illumination in [0.01, 1[ [lx]
         // E.g. Night full moon / Deep twilight.
         AMBIENT_ILLUMINATION_LEVEL2 = 3;
 
         // Level 3 illumination in [1, 3[ [lx]
-        // E.g. Deep to average twilight / Minimum lighting on local low pedestrian conflict roads.
+        // E.g. Deep to average twilight / Minimum lighting on local low 
+        // pedestrian conflict roads.
         AMBIENT_ILLUMINATION_LEVEL3 = 4;
 
         // Level 4 illumination in [3, 10[ [lx]
         // E.g. Average to full twilight / Minimum lighting on collector roads /
-        // Minimum lighting on major and expressway roads with low to average pedestrian conflict.
+        // Minimum lighting on major and expressway roads with low to average 
+        // pedestrian conflict.
         AMBIENT_ILLUMINATION_LEVEL4 = 5;
 
         // Level 5 illumination in [10, 20[ [lx]
-        // E.g. Minimum lighting on major and expressway roads with high pedestrian conflict.
+        // E.g. Minimum lighting on major and expressway roads with high 
+        // pedestrian conflict.
         AMBIENT_ILLUMINATION_LEVEL5 = 6;
 
         // Level 6 illumination in [20, 400[ [lx]
-        // E.g. Roads with more lighting / Very dark overcast day to sunrise or sunset on a clear day.
+        // E.g. Roads with more lighting / Very dark overcast day to sunrise or 
+        // sunset on a clear day.
         AMBIENT_ILLUMINATION_LEVEL6 = 7;
 
         // Level 7 illumination in [400, 1000[ [lx]
@@ -195,6 +213,9 @@ message EnvironmentalConditions
 
         // Level 9 illumination in [10000, 120000[ [lx]
         // E.g. Full daylight to intense sunlight.
+        //
+        // \note Use \c AMBIENT_ILLUMINATION_LEVEL9 if illumination is more than
+        // 120000 [lx]
         AMBIENT_ILLUMINATION_LEVEL9 = 10;
     }
 
@@ -204,9 +225,11 @@ message EnvironmentalConditions
     message TimeOfDay
     {
         // The number of seconds [s] that have passed since midnight local time.
-        // Used for determining the current state of the circadian rhythm of a driver.
+        // Used for determining the current state of the circadian rhythm of a 
+        // driver.
         //
-        // \note No changes of daylight saving time or time zones are considered.
-        optional uint32 seconds_from_midnight = 1;
+        // \note No changes of daylight saving time or time zones are 
+        // considered.
+        optional uint32 seconds_since_midnight = 1;
     }
 }

osi_groundtruth.proto

@@ -16,89 +16,93 @@ package osi;
 // \brief The ground truth information from the simulation environment.
 //
 // This ground truth information is supposed to describe the whole simulated
-// environment around any simulated vehicle.  For each simulated host vehicle
-// (might only be one, but could also be multiple) define an area around the
-// vehicle which is greater than the combined field of views (FOV) of all
-// sensors obstructed in the vehicle. The ground truth data is supposed to
-// describe the convex hull of all such areas w.r.t. a global simulation
-// coordinate system.
+// environment around any simulated vehicle. For each simulated host vehicle
+// (there may be one or multiple), define an area around the vehicle which
+// is greater than the combined field of views (FOV) of all obstructed sensors 
+// in the vehicle. The ground truth data is supposed to describe the convex
+// hull of all such areas w.r.t. a global simulation coordinate system.
 //
-// The simulation coordinate system might change during the simulation if and
-// only if, all coordinates w.r.t. this coordinate system are also changed.
+// The simulation coordinate system may change during the simulation if and
+// only if all coordinates w.r.t. this coordinate system are also changed.
 //
 // The data has to be sent at a rate defined by the receiving partner. When
 // sending, values with default values might be left default in order to improve
 // performance.
 //
-// To provide a complete interface, all fields of all messages have to be set,
-// unless specifically stated in the field's definition that the field may
-// remain unset.
+// To provide a complete interface, all fields of all contained messages must be
+// properly set unless specifically stated in the field's definition that the
+// field may remain unset.
 //
 // In enums (e.g. types) the unknown (first / default) value is not allowed to
 // be used in the ground truth interface.
 //
 message GroundTruth
 {
-    // The interface version used by the sender (simulation environment).
-    //
+    // The interface version used by the sender (i.e. the simulation
+    // environment).
     optional InterfaceVersion version = 1;
 
-    // The data timestamp of the simulation environment. Zero time is arbitrary
-    // but must be identical for all messages. Zero time does not need to
-    // coincide with the unix epoch. Recommended is the starting time point of
-    // the simulation.
+    // The data timestamp of the simulation environment. The zero time point is
+    // arbitrary but must be identical for all messages. 
+    // Recommendation: Zero time point for start point of the simulation.
+    //
+    // \note Zero time point does not need to coincide with the unix epoch. 
     //
     // \note For ground truth data this timestamp coincides both with the
     // notional simulation time the data applies to and the time it was sent
     // (there is no inherent latency for ground truth data, as opposed to
     // sensor data).
     optional Timestamp timestamp = 2;
 
-    // A list of vehicles.
+    // The list of (host) vehicles.
     //
     repeated Vehicle vehicle = 3;
 
-    // A list of moving objects (excluding vehicles).
+    // The list of all other moving objects (i.e. excluding vehicles).
     //
     repeated MovingObject moving_object = 4;
 
-    // A list of stationary objects (excluding traffic signs and traffic lights).
-    //
+    // The list of stationary objects (excluding traffic signs and traffic
+    // lights).
     repeated StationaryObject stationary_object = 5;
 
-    // A list of traffic signs.
+    // The list of traffic signs.
     //
     repeated TrafficSign traffic_sign = 6;
 
-    // A list of traffic lights.
+    // The list of traffic lights.
     //
     repeated TrafficLight traffic_light = 7;
 
-    // A list of road surface markings (LaneMarkings are excluded and defined as LaneBoundaries as part of the Lanes).
+    // The list of road surface markings (lane markings are excluded and
+    // defined as \c LaneBoundary).
     //
     repeated RoadMarking road_marking = 8;
 
-    // A list of lanes forming a road network.
+    // The list of lanes forming a road network.
     //
     repeated Lane lane = 9;
 
-    // A list of lane boundaries from lanes.
+    // The list of lane boundaries from lanes.
     //
     repeated LaneBoundary lane_boundary = 10;
 
-    // A list of passengers in the (host) vehicle(s).
+    // The list of passengers in the (host) vehicle(s).
     //
     repeated Occupant occupant = 11;
 
     // Conditions of the environment.
     //
     optional EnvironmentalConditions environmental_conditions = 12;
 
-    // The country code in 3 digit numeric format: ISO Code 3166/1 [1,2]. 
-    // e.g. Germany = 276, USA = 840
+    // The ISO country code in 3 digit numeric format according to:
+    // ISO Code 3166/1 [1,2]. 
+    // E.g. Germany = 276, USA = 840.
+    //
+    // Unit: []
     //
     // \par References: 
-    // [1] [ISO 3166/1 Country codes] (https://www.iso.org/obp/ui/) 
-    // [2] [ISO 3166/1 Wikipedia] (https://en.wikipedia.org/wiki/ISO_3166-1) 
+    // [1] [International Standard ISO 3166-1: Codes for the representation of names of countries and their subdivisions – Part 1: Country codes, third ed., 2013] (https://www.iso.org/obp/ui/) 
+    // [2] [Wikipedia ISO 3166/1] (https://en.wikipedia.org/wiki/ISO_3166-1) 
     optional uint32 country_code = 13;
 }

osi_hostvehicledata.proto

@@ -15,16 +15,16 @@ package osi;
 //
 message HostVehicleData
 {
-    // Current estimated location based on GPS- and related navigation sensors
+    // Current estimated location based on GPS- and related navigation sensors.
     //
     // \note Note that dimension and base_polygon need not be set.
     //
     optional BaseMoving location = 1;
 
-    // Current estimated location error based on GPS- and related navigation sensors
+    // Current estimated location error based on GPS- and related navigation 
+    // sensors.
     //
     // \note Note that dimension and base_polygon need not be set.
     //
     optional BaseMoving location_rmse = 2;
-
 }