osi_environment.proto

syntax = "proto2";

option optimize_for = SPEED;

package osi3;

//
// \brief The conditions of the environment.
//
// Definition of light, weather conditions and other environmental conditions.
//
// \note These conditions apply locally around the host vehicle.
//
message EnvironmentalConditions
{
    // The ambient illumination of the environment.
    //
    optional AmbientIllumination ambient_illumination = 1;

    // The time of day at the host vehicles location.
    //
    optional TimeOfDay time_of_day = 2;
    
    // The Unix epoch (or Unix time or POSIX time or Unix timestamp) is
    // the number of seconds that have elapsed since January 1, 1970
    // (midnight UTC/GMT), not counting leap seconds
    // (in ISO 8601: 1970-01-01T00:00:00Z). Literally speaking the epoch
    // is Unix time 0 (midnight 1/1/1970), but 'epoch' is often used as
    // a synonym for 'Unix time'. Many Unix systems store epoch dates as
    // a signed 32-bit integer, which might cause problems on January 19,
    // 2038 (known as the Year 2038 problem or Y2038). 
    //
    // \note You can convert the timestamp using the following [routines
    // sorted by languages](https://www.epochconverter.com/#code)
    //
    // \par References:
    // - [1] [Epoch & Unix Timestamp Conversion Tools](https://www.epochconverter.com/)
    // - [2] [Wikipedia: Coordinated Universal Time] (https://en.wikipedia.org/wiki/Coordinated_Universal_Time)
    //
    optional int64 unix_timestamp = 8;

    // Atmospheric pressure in Pascal at z=0.0 in world frame (about 101325
    // [Pa]).
    //
    // Unit: [Pa]
    //
    optional double atmospheric_pressure = 3;

    // Temperature in Kelvin at z=0.0 in world frame.
    //
    // Unit: [K]
    //
    optional double temperature = 4;

    // Relative humidity in at z=0.0 in world frame.
    //
    // Note that physically more relevant measures, like absolute or specific
    // humidity can be easily derived from relative_humidity, given that the
    // temperature and atmospheric_pressure are known.
    //
    // Unit: [%]
    optional double relative_humidity = 5;

    // Description of the precipitation.
    //
    optional Precipitation precipitation = 6;

    // Description of the fog.
    //
    optional Fog fog = 7;

    // Definition of discretized precipitation states according to [1].
    // (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.
    //
    enum Precipitation
    {
        // Intensity of precipitation is unknown (must not be used in ground
        // truth).
        //
        PRECIPITATION_UNKNOWN = 0;

        // Other (unspecified but known) intensity of precipitation.
        //
        PRECIPITATION_OTHER = 1;

        // No precipitation, when I in [0,0.1[ [mm/h]
        //
        PRECIPITATION_NONE = 2;

        // Very light intensity of precipitation, when I in [0.1,0.5[ [mm/h]
        //
        PRECIPITATION_VERY_LIGHT = 3;

        // Light intensity of precipitation, when I in [0.5,1.9[ [mm/h]
        //
        PRECIPITATION_LIGHT = 4;

        // Moderate intensity of precipitation, when I in [1.9,8.1[ [mm/h]
        //
        PRECIPITATION_MODERATE = 5;

        // Heavy intensity of precipitation, when I in [8.1,34[ [mm/h]
        //
        PRECIPITATION_HEAVY = 6;

        // Very heavy intensity of precipitation, when I in [34,149[ [mm/h]
        //
        PRECIPITATION_VERY_HEAVY = 7;

        // Extreme intensity of precipitation, when I in [149,infinity[ [mm/h]
        //
        PRECIPITATION_EXTREME = 8;
    }

    // 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].
    // (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.
    //
    // \par References:
    // - [2] SHEPARD, Frank D. Reduced visibility due to fog on the highway.
    // Transportation Research Board, 1996.
    // - [3] [StVO 17 chapter
    // 3](https://www.stvo.de/strassenverkehrsordnung/101-17-beleuchtung)
    // - [4] [Homepage of the Meteorological
    // Office](http://www.metoffice.gov.uk/guide/weather/observations-guide/how-we-measure-visibility)
    //
    enum Fog
    {
        // Visibility is unknown (must not be used in ground truth).
        //
        FOG_UNKNOWN = 0;

        // Other (unspecified but known) fog intensity.
        //
        FOG_OTHER = 1;

        // Excellent visibility, when V in [40000,infinity[ [m]
        //
        FOG_EXCELLENT_VISIBILITY = 2;

        // Good visibility, when V in [10000,40000[ [m]
        //
        FOG_GOOD_VISIBILITY = 3;

        // Moderate visibility, when V in [4000,10000[ [m]
        //
        FOG_MODERATE_VISIBILITY = 4;

        // Poor visibility, when V in [2000,4000[ [m]
        //
        FOG_POOR_VISIBILITY = 5;

        // Mist, when V in [1000,2000[ [m]
        //
        FOG_MIST = 6;

        // Fog, when V in [200,1000[ [m]
        //
        FOG_LIGHT = 7;

        // Thick fog, when V in [50,200[ [m]
        //
        FOG_THICK = 8;

        // Dense fog, when V in [0,50[ [m]
        // (allowed to use rear fog light according to [3])
        //
        FOG_DENSE = 9;
    }

    // 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.
    //
    // Lux [lx] is the SI unit of luminance or illumination of an area of exact
    // one square meter, 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].
    //
    // \par References:
    // - [5] [The NIST Reference on Constants, Units, and
    // Uncertainty](https://physics.nist.gov/cuu/Units/units.html)
    // - [6] [National Optical Astronomy
    // Observatory](https://www.noao.edu/education/QLTkit/ACTIVITY_Documents/Safety/LightLevels_outdoor+indoor.pdf)
    // - [7] [Standards for required street lighting in the
    // USA](http://www.wsdot.wa.gov/research/reports/fullreports/847.1.pdf)
    // - [8] [Canadian IES-RP-8 standards for road lighting - municipality of
    // Saint-Gedeon-de-.
    // Beauce](http://sslnet.ca/wp-content/uploads/2011/10/LTE-RT-2011-0076-Anglais.pdf)
    // - [9] [European standards for road
    // lighting](http://courtneystrong.com/wp-content/uploads/2017/07/css-sl1-class-and-quality-of-street-lighting.pdf)
    //
    enum AmbientIllumination
    {
        // Ambient illumination is unknown (must not be used in ground truth).
        //
        AMBIENT_ILLUMINATION_UNKNOWN = 0;

        // Other (unspecified but known) ambient illumination.
        //
        AMBIENT_ILLUMINATION_OTHER = 1;

        // 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.
        //
        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.
        //
        AMBIENT_ILLUMINATION_LEVEL4 = 5;

        // Level 5 illumination in [10, 20[ [lx]
        // 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.
        //
        AMBIENT_ILLUMINATION_LEVEL6 = 7;

        // Level 7 illumination in [400, 1000[ [lx]
        // E.g. Sunrise or sunset on a clear day / Overcast day.
        //
        AMBIENT_ILLUMINATION_LEVEL7 = 8;

        // Level 8 illumination in [1000, 10000[ [lx]
        // E.g. Average to full daylight.
        //
        AMBIENT_ILLUMINATION_LEVEL8 = 9;

        // 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;
    }

    //
    // \brief The time of day at a specified location.
    //
    // \note In general the global position of the parent frame should be
    // obtainable in order to derive the local time.
    // This information can be calculated from the \c #unix_timestamp in
    // combination with \c #osi3::GroundTruth::proj_string and the position of
    // the corresponding \c #osi3::BaseStationary or \c #osi3::BaseMoving .
    //
    message TimeOfDay
    {
        // The number of seconds [s] that have passed since midnight local time.
        // Used e.g. 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_since_midnight = 1;
    }
}