diff --git a/osi_environment.proto b/osi_environment.proto index 5aafe2cac..3c9d2af1a 100644 --- a/osi_environment.proto +++ b/osi_environment.proto @@ -3,6 +3,7 @@ syntax = "proto2"; option optimize_for = SPEED; import "osi_common.proto"; +import "osi_object.proto"; package osi3; @@ -15,32 +16,35 @@ package osi3; // message EnvironmentalConditions { - // The ambient illumination of the environment. // - optional AmbientIllumination ambient_illumination = 1; - - // The time of day at the host vehicles location. + // \brief 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. // - 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 [1]), not counting leap seconds [2]. - // Historically, the origin of UNIX system time was referred to as - // "00:00:00 GMT, January 1, 1970" [2]. 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 lx ("lux") 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 [1]. + // lm ("lumen") 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 cd ("candela") as 1 lm = 1 cd sr, where sr + // denotes steradian, the unit of solid angle used in 3D geometry analogous + // to the radian [1]. // - // \note You can convert the timestamp using the following [routines - // sorted by languages](https://www.epochconverter.com/#code). + // Categorization is done based on natural day/night time illuminance levels + // [2] and standards for required lighting levels on roads [2, 3, 4, 5]. // // \par References: - // [1] ITU Radiocommunication Assembly. (2002). Recommondation ITU-R TF.460-6 Standard-frequency and time-signal emissions. (Rec. ITU-R TF.460-6). Retrieved January 25, 2020, from http://www.itu.int/dms_pubrec/itu-r/rec/tf/R-REC-TF.460-6-200202-I!!PDF-E.pdf \n - // [2] The Open Group. (2018). POSIX.1-2017 The Open Group Base Specifications Issue 7, 2018 edition. IEEE Std 1003.1-2017 (Revision of IEEE Std 1003.1-2008). Retrieved January 25, 2020, from https://pubs.opengroup.org/onlinepubs/9699919799/xrat/contents.html + // [1] DIN Deutsches Institut fuer Normung e. V. (1982). DIN 5031-3 Strahlungsphysik im optischen Bereich und Lichttechnik - Groessen, Formelzeichen und Einheiten der Lichttechnik. (DIN 5031-3:1982-03). Berlin, Germany. \n + // [2] National Optical Astronomy Observatory. (2015, December 02). Recommended Light Levels. Retrieved January 25, 2020, from https://www.noao.edu/education/QLTkit/ACTIVITY_Documents/Safety/LightLevels_outdoor+indoor.pdf \n + // [3] Wang, Y. & Zou, Y., (2016, March). Study on Illumination for State Highways. Washington State Department of Transportation. Retrieved January 25, 2020, from http://www.wsdot.wa.gov/research/reports/fullreports/847.1.pdf \n + // [4] Laperriere, A. (2011, May). LED street lighting in the municipality of Saint-Gedeon-de-Beauce within the framework of advanced lighting technologies. Retrieved January 25, 2020, from http://sslnet.ca/wp-content/uploads/2011/10/LTE-RT-2011-0076-Anglais.pdf \n + // [5] Crabb, G. I., Beaumont, R. & Webster, D. (2008, October 17). Review of the class and quality of street lighting. Transport Research Laboratory. Retrieved January 25, 2020, from http://courtneystrong.com/wp-content/uploads/2017/07/css-sl1-class-and-quality-of-street-lighting.pdf // - optional int64 unix_timestamp = 8; + optional double ambient_illumination = 1; + + // The time of day at the host vehicles location. + // + optional TimeOfDay time_of_day = 2; // Atmospheric pressure in Pascal at z=0.0 in world frame (about 101325 // Pa). @@ -82,12 +86,41 @@ message EnvironmentalConditions // Description of the precipitation. // - optional Precipitation precipitation = 6; + repeated Precipitation precipitation = 6; + + // Definition of fog. + // (V = Visibility in 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 [1]). + // This is approximately equivalent to visibility measured in terms of the + // contrast of a distant object against its background. + // + // \par References: + // [1] Meteorological Office UK. (2020). Homepage of the Meteorological Office - How we measure visibility. Retrieved January 25, 2020, from http://www.metoffice.gov.uk/guide/weather/observations-guide/how-we-measure-visibility + // + optional double fog = 7; - // Description of the fog. + // 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 [1]), not counting leap seconds [2]. + // Historically, the origin of UNIX system time was referred to as + // "00:00:00 GMT, January 1, 1970" [2]. 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). // - optional Fog fog = 7; - + // \par References: + // [1] ITU Radiocommunication Assembly. (2002). Recommondation ITU-R TF.460-6 Standard-frequency and time-signal emissions. (Rec. ITU-R TF.460-6). Retrieved January 25, 2020, from http://www.itu.int/dms_pubrec/itu-r/rec/tf/R-REC-TF.460-6-200202-I!!PDF-E.pdf \n + // [2] The Open Group. (2018). POSIX.1-2017 The Open Group Base Specifications Issue 7, 2018 edition. IEEE Std 1003.1-2017 (Revision of IEEE Std 1003.1-2008). Retrieved January 25, 2020, from https://pubs.opengroup.org/onlinepubs/9699919799/xrat/contents.html + // + optional int64 unix_timestamp = 8; + // Optional external reference to the environmental condition sources. // // \note For OpenDRIVE and OpenSECNARIO there is no direct counterpart. @@ -101,227 +134,236 @@ message EnvironmentalConditions // repeated ExternalReference source_reference = 9; - // Definition of discretized precipitation states according to [1]. - // (I = Intensity of precipitation in mm per hour mm/h) + // \brief Definition of cloud states. // - // \par Reference: - // [1] Paulat, M., Frei, C., Hagen, M. & Wernli, H. (2008). A gridded dataset of hourly precipitation in Germany: Its construction, climatology and application. Meteorologische Zeitschrift. Vol. 17, No. 6. pp. 719-732. Berlin, Stuttgart, Germany. https://doi.org/10.1127/0941-2948/2008/0332 + // \note Defines the cloud states according to OpenScenario 1.1 // - enum Precipitation - { - // Intensity of precipitation is unknown (must not be used in ground - // truth). - // - PRECIPITATION_UNKNOWN = 0; + optional CloudState cloud_state = 10; - // Other (unspecified but known) intensity of precipitation. - // - PRECIPITATION_OTHER = 1; + // \brief Definition of the wind speed and direction. + // + optional Wind wind = 11; - // No precipitation, when I in [0,0.1[ mm/h - // - PRECIPITATION_NONE = 2; + // \brief Definition of the Sun. + // + // \note within the classification.emitting_structure_attribute \c + // the light intensity and wave length of the sun can be given. + // + optional StationaryObject Sun = 12; - // Very light intensity of precipitation, when I in [0.1,0.5[ mm/h - // - PRECIPITATION_VERY_LIGHT = 3; + // \brief Definition of fog mist with a given location with a bounding box + // + // \note There can be several of fog mist fields + // + repeated FogMist fog_mist = 13; - // Light intensity of precipitation, when I in [0.5,1.9[ mm/h + // + // \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 in s that have passed since midnight local time. + // Used e.g. for determining the current state of the circadian rhythm + // of a driver. // - PRECIPITATION_LIGHT = 4; - - // Moderate intensity of precipitation, when I in [1.9,8.1[ mm/h + // \note No changes of daylight saving time or time zones are + // considered. // - PRECIPITATION_MODERATE = 5; - - // Heavy intensity of precipitation, when I in [8.1,34[ mm/h + // \rules + // is_greater_than_or_equal_to: 0 + // is_less_than: 86400 + // \endrules // - PRECIPITATION_HEAVY = 6; + optional uint32 seconds_since_midnight = 1; + } - // Very heavy intensity of precipitation, when I in [34,149[ mm/h + // + // \brief Defines wind properties. + // + // \note Describes the wind speed and direction from OpenScenario 1.1 + // + message Wind + { + // The target direction of the wind (not the origin direction) in the ground/xy-plane of the \c + // world coordinate system. Corresponds to the heading/yaw angle. \c + // x-axis-direction is 0 rad. Unit [rad]. Range [0...2 pi[ // - PRECIPITATION_VERY_HEAVY = 7; + optional Vector3d direction = 1; - // Extreme intensity of precipitation, when I in [149,infinity[ mm/h + // The wind speed. Unit [m/s]. Range [0...inf[ // - PRECIPITATION_EXTREME = 8; + optional double speed = 2; } - // Definition of discretized fog states according to [1]. - // The bandwidth of thick and dense fog was adjusted to fit the German StVO - // regarding rear fog lights [2, 3]. - // (V = Visibility in 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. + // \brief Mist is defined as 'when there is such obscurity and the associated visibility is equal to or exceeds 1000 m.' + // Like fog, mist is still the result of the suspension of water droplets, but simply at a lower density. [1] + // + // \note Mist typically is quicker to dissipate and can rapidly disappear with even slight winds, + // it's also what you see when you can see your breath on a cold day. Mist is commonly confused with fog, + // which resembles a stratus cloud lying at ground level. These two phenomena differ, but share some commonalities; + // similar processes form both fog and mist. Fog is denser and generally lasts longer, while mist is thinner and more transparent. [2] + // + // The definition of mist as being composed of an aggregate of microscopic and hygroscopic water droplets, + // and that mist is intermediate between haze and fog infers a distinction between haze and fog based + // on the definition of their particle size [3] // // \par References: - // [1] Shepard, F. D. (1996). Reduced visibility due to fog on the highway. Transportation Research Board, National Research Council (Ed.). National Academy Press. Washington, D.C., USA. ISBN 0-309-06006-0. \n - // [2] Strassenverkehrs-Ordnung (StVO) as of dated March 06, 2013 (BGBl. I S. 367), lastly changed by article 4a of the order from June 06, 2019 (BGBl. I S. 756). \n - // [3] stvo.de. (2013, April 01). StVO Par. 17 Beleuchtung. Retrieved January 25, 2020, from https://www.stvo.de/strassenverkehrsordnung/101-17-beleuchtung \n - // [4] Meteorological Office UK. (2020). Homepage of the Meteorological Office - How we measure visibility. Retrieved January 25, 2020, from http://www.metoffice.gov.uk/guide/weather/observations-guide/how-we-measure-visibility + // [1] https://www.metoffice.gov.uk/weather/learn-about/weather/types-of-weather/fog/difference-mist-and-fog + // [2] https://en.wikipedia.org/wiki/Mist + // [3] Ralph G. Eldridge (1969). mist — the transition from haze to fog. The MITRE Corporation, Bedford, Mass. Vol 50, No. 6. pp. 422. https://doi.org/10.1175/1520-0477-50.6.422 // - enum Fog + message FogMist { - // Visibility is unknown (must not be used in ground truth). + // Defines the possible visible range \c Unit: m; Range: [0..inf[. + // + optional double visibility = 1; + + // Dimensions and center of fog in fixed world coordinates. // - FOG_UNKNOWN = 0; + optional BaseStationary bounding_box = 2; - // Other (unspecified but known) fog intensity. + // Reference of an associated 3D model + // It is implementation-specific how model_references are resolved to + // 3d models. + optional string model_reference = 3; + } + + // + // Description of the precipitation with intensity and the type + // (I = Intensity of precipitation in mm per hour mm/h) + // With a given model reference the 3D object of the e.g. rain drop can be given + // + // \par Reference: + // [1] Paulat, M., Frei, C., Hagen, M. & Wernli, H. (2008). A gridded dataset of hourly precipitation in Germany: Its construction, climatology and application. Meteorologische Zeitschrift. Vol. 17, No. 6. pp. 719-732. Berlin, Stuttgart, Germany. https://doi.org/10.1127/0941-2948/2008/0332 + // + message Precipitation + { + // The intensity of the precipitation (valid for all precipitation types). Unit [mm/h]. Range [0...inf[ + // According to OpenScenario 1.1 and according to the context of ISO 2315 // - FOG_OTHER = 1; + optional double intensity = 1; - // Excellent visibility, when V in [40000,infinity[ m + // Type of the precipitation. // - FOG_EXCELLENT_VISIBILITY = 2; + optional PrecipitationType type = 2; + + // Reference of an associated 3D model e.g. Snow flake or rain drop. + // It is implementation-specific how model_references are resolved to + // 3d models. + optional string model_reference = 3; + } - // Good visibility, when V in [10000,40000[ m + // Defines a precipitation by type and value of the weather. + // + enum PrecipitationType + { + // Intensity of precipitation is unknown (must not be used in ground + // truth). // - FOG_GOOD_VISIBILITY = 3; + PRECIPITATION_TYPE_UNKNOWN = 0; - // Moderate visibility, when V in [4000,10000[ m + // Other (unspecified but known) intensity of precipitation. // - FOG_MODERATE_VISIBILITY = 4; + PRECIPITATION_TYPE_OTHER = 1; - // Poor visibility, when V in [2000,4000[ m + // No precipitation. // - FOG_POOR_VISIBILITY = 5; + PRECIPITATION_TYPE_DRY = 2; - // Mist, when V in [1000,2000[ m + // Rain. // - FOG_MIST = 6; + PRECIPITATION_TYPE_RAIN = 3; - // Fog, when V in [200,1000[ m + // Hail. // - FOG_LIGHT = 7; + PRECIPITATION_TYPE_HAIL = 4; - // Thick fog, when V in [50,200[ m + // Snow. // - FOG_THICK = 8; + PRECIPITATION_TYPE_SNOW = 5; - // Dense fog, when V in [0,50[ m - // (allowed to use rear fog light according to [3]) + // Sleet/Graupel. // - FOG_DENSE = 9; + PRECIPITATION_TYPE_SLEET = 6; } - // 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. + // \brief Definition of the cloud state, i.e. cloud state and sky visualization settings. // - // lx ("lux") 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 [1]. - // lm ("lumen") 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 cd ("candela") as 1 lm = 1 cd sr, where sr - // denotes steradian, the unit of solid angle used in 3D geometry analogous - // to the radian [1]. + // \note The total degree of coverage indicates how large the part of the sky vault is which is covered + // with clouds altogether. It is given in eighths, because this division is easier to estimate + // for the observer. 0 eighths means that there are no traces of clouds in the sky, + // 4 eighths means that the sky is covered with clouds up to half, 8 eighths means that the sky is + // completely covered with clouds and no sky blue can be recognized. // - // Categorization is done based on natural day/night time illuminance levels - // [2] and standards for required lighting levels on roads [2, 3, 4, 5]. + // For cloud determination, the observer will choose a location from which he can overlook the entire sky. + // When determining the total cloud cover, all clouds or parts of clouds, regardless of height and genus, + // that are above his location will be added. Aircraft contrails are also counted as cloud cover if they remain + // in the sky for more than 15 minutes. On the other hand, fog is not counted as cloud cover. + // + // With a little practice, the observer can easily determine the total amount of cloud cover. + // Problems occur only with scattered clouds or many single clouds (cumulus). + // Their cloud cover is often overestimated. On the other hand, + // the coverage of thin ice clouds (cirrus) is often underestimated. // // \par References: - // [1] DIN Deutsches Institut fuer Normung e. V. (1982). DIN 5031-3 Strahlungsphysik im optischen Bereich und Lichttechnik - Groessen, Formelzeichen und Einheiten der Lichttechnik. (DIN 5031-3:1982-03). Berlin, Germany. \n - // [2] National Optical Astronomy Observatory. (2015, December 02). Recommended Light Levels. Retrieved January 25, 2020, from https://www.noao.edu/education/QLTkit/ACTIVITY_Documents/Safety/LightLevels_outdoor+indoor.pdf \n - // [3] Wang, Y. & Zou, Y., (2016, March). Study on Illumination for State Highways. Washington State Department of Transportation. Retrieved January 25, 2020, from http://www.wsdot.wa.gov/research/reports/fullreports/847.1.pdf \n - // [4] Laperriere, A. (2011, May). LED street lighting in the municipality of Saint-Gedeon-de-Beauce within the framework of advanced lighting technologies. Retrieved January 25, 2020, from http://sslnet.ca/wp-content/uploads/2011/10/LTE-RT-2011-0076-Anglais.pdf \n - // [5] Crabb, G. I., Beaumont, R. & Webster, D. (2008, October 17). Review of the class and quality of street lighting. Transport Research Laboratory. Retrieved January 25, 2020, from http://courtneystrong.com/wp-content/uploads/2017/07/css-sl1-class-and-quality-of-street-lighting.pdf + // [1] ISO 15469:2004(E) / CIE S 011/E:2003 : Spatial distribution of skylight + // [2] https://de.wikipedia.org/wiki/Bewölkung // - enum AmbientIllumination + enum CloudState { - // Ambient illumination is unknown (must not be used in ground truth). + // Cloud State is unknown (must not be used in ground truth). // - AMBIENT_ILLUMINATION_UNKNOWN = 0; + CLOUD_STATE_UNKNOWN = 0; - // Other (unspecified but known) ambient illumination. + // Other (unspecified but known) CloudState. // - AMBIENT_ILLUMINATION_OTHER = 1; + CLOUD_STATE_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 + // Cloudless (0/8) // - AMBIENT_ILLUMINATION_LEVEL1 = 2; + CLOUD_STATE_CLOUDLESS = 2; - // Level 2 illumination in [0.01, 1[ lx - // E.g. Night full moon / Deep twilight. + // Sunny (1/8) // - AMBIENT_ILLUMINATION_LEVEL2 = 3; + CLOUD_STATE_SUNNY = 3; - // Level 3 illumination in [1, 3[ lx - // E.g. Deep to average twilight / Minimum lighting on local low - // pedestrian conflict roads. + // Serene (2/8)) // - AMBIENT_ILLUMINATION_LEVEL3 = 4; + CLOUD_STATE_SERENE = 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. + // Slightly Cloudy (3/8) // - AMBIENT_ILLUMINATION_LEVEL4 = 5; + CLOUD_STATE_SLIGHTLYCLOUDY = 5; - // Level 5 illumination in [10, 20[ lx - // E.g. Minimum lighting on major and expressway roads with high - // pedestrian conflict. + // Light Cloudy (4/8) // - 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. + CLOUD_STATE_LIGHTCLOUDY = 6; + + // Cloudy (5/8) // - AMBIENT_ILLUMINATION_LEVEL6 = 7; - - // Level 7 illumination in [400, 1000[ lx - // E.g. Sunrise or sunset on a clear day / Overcast day. + CLOUD_STATE_CLOUDY = 7; + + // Heavy Cloudy (6/8) // - AMBIENT_ILLUMINATION_LEVEL7 = 8; - - // Level 8 illumination in [1000, 10000[ lx - // E.g. Average to full daylight. + CLOUD_STATE_HEAVYCLOUDY = 8; + + // Almost Covered (7/8) // - AMBIENT_ILLUMINATION_LEVEL8 = 9; - - // Level 9 illumination in [10000, 120000[ lx - // E.g. Full daylight to intense sunlight. + CLOUD_STATE_ALMOSTCOVERED = 9; + + // Covered (8/8) // - // \note Use \c #AMBIENT_ILLUMINATION_LEVEL9 if illumination is more - // than 120000 lx + CLOUD_STATE_COVERED = 10; + + // No Sky // - 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 in 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. - // - // \rules - // is_greater_than_or_equal_to: 0 - // is_less_than: 86400 - // \endrules - // - optional uint32 seconds_since_midnight = 1; + CLOUD_STATE_NOSKY = 11; } }