diff --git a/osi_environment.proto b/osi_environment.proto index 5aafe2cac..fb77438fc 100644 --- a/osi_environment.proto +++ b/osi_environment.proto @@ -22,7 +22,10 @@ message EnvironmentalConditions // The time of day at the host vehicles location. // optional TimeOfDay time_of_day = 2; - + + // The unix timestamp describes the time and date at the host vehicle's + // location, referring to UTC. + // // 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]. @@ -31,7 +34,7 @@ message EnvironmentalConditions // 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). + // 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). @@ -90,7 +93,7 @@ message EnvironmentalConditions // Optional external reference to the environmental condition sources. // - // \note For OpenDRIVE and OpenSECNARIO there is no direct counterpart. + // \note For OpenDRIVE and OpenSCENARIO there is no direct counterpart. // // \note For non-ASAM standards, it is implementation-specific how // source_reference is resolved. @@ -101,6 +104,18 @@ message EnvironmentalConditions // repeated ExternalReference source_reference = 9; + // Description of the clouds. + // + optional CloudLayer clouds = 10; + + // Description of the wind. + // + optional Wind wind = 11; + + // Description of the sun. + // + optional Sun sun = 12; + // Definition of discretized precipitation states according to [1]. // (I = Intensity of precipitation in mm per hour mm/h) // @@ -242,55 +257,55 @@ message EnvironmentalConditions // AMBIENT_ILLUMINATION_OTHER = 1; - // Level 1 illumination in ]0.001, 0.01[ lx + // Level 1 illumination in ]0.001, 0.01[ lx. \n // E.g. Night with no artificial light. // // \note Use \c #AMBIENT_ILLUMINATION_LEVEL1 if illumination is less - // than 0.001 lx + // than 0.001 lx. // AMBIENT_ILLUMINATION_LEVEL1 = 2; - // Level 2 illumination in [0.01, 1[ lx + // Level 2 illumination in [0.01, 1[ lx. \n // E.g. Night full moon / Deep twilight. // AMBIENT_ILLUMINATION_LEVEL2 = 3; - // Level 3 illumination in [1, 3[ lx + // Level 3 illumination in [1, 3[ lx. \n // 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 + // Level 4 illumination in [3, 10[ lx. \n // 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 + // Level 5 illumination in [10, 20[ lx. \n // E.g. Minimum lighting on major and expressway roads with high // pedestrian conflict. // AMBIENT_ILLUMINATION_LEVEL5 = 6; - // Level 6 illumination in [20, 400[ lx + // Level 6 illumination in [20, 400[ lx. \n // 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 + // Level 7 illumination in [400, 1000[ lx. \n // E.g. Sunrise or sunset on a clear day / Overcast day. // AMBIENT_ILLUMINATION_LEVEL7 = 8; - // Level 8 illumination in [1000, 10000[ lx + // Level 8 illumination in [1000, 10000[ lx. \n // E.g. Average to full daylight. // AMBIENT_ILLUMINATION_LEVEL8 = 9; - // Level 9 illumination in [10000, 120000[ lx + // Level 9 illumination in [10000, 120000[ lx. \n // E.g. Full daylight to intense sunlight. // // \note Use \c #AMBIENT_ILLUMINATION_LEVEL9 if illumination is more @@ -324,4 +339,154 @@ message EnvironmentalConditions // optional uint32 seconds_since_midnight = 1; } + + // + // \brief Description of a cloud layer. + // + message CloudLayer + { + // Properties of a cloud layer given by fractional cloud cover levels. + // + optional FractionalCloudCover fractional_cloud_cover = 1; + + // Defines the fractional cloud cover [1] given by observation of total cloud amount in eights (oktas) of the sky. + // + // For visual alignment please see reference [2]. + // + // The total degree of coverage indicates how much of the sky is covered with clouds altogether. + // 0 oktas means that there are no traces of clouds in the sky, + // 8 oktas means that the sky is completely covered with clouds and no sky blue can be recognized. + // + // \par References: + // [1] CIE engl. International Commission on Illumination. (2020). CIE S017:2020 ILV: Intl. Lighitng Vocabulary, 2nd edn.. Retrieved March 8, 2022, from https://cie.co.at/eilvterm/17-29-116 \n + // [2] UBC The University of British Columbia. (2018). ATSC 113 Weather for Sailing, Flying & Snow Sports. Retrieved March 8, 2022, from https://www.eoas.ubc.ca/courses/atsc113/flying/met_concepts/01-met_concepts/01c-cloud_coverage/index.html + // + enum FractionalCloudCover + { + // Fractional cloud cover level is unknown (must not be used in ground truth). + // + FRACTIONAL_CLOUD_COVER_UNKNOWN = 0; + + // Other (unspecified but known) fractional cloud cover level. + // + FRACTIONAL_CLOUD_COVER_OTHER = 1; + + // 0/8 of the sky is covered with clouds. + // + FRACTIONAL_CLOUD_COVER_ZERO_OKTAS = 2; + + // 1/8 of the sky is covered with clouds. + // + FRACTIONAL_CLOUD_COVER_ONE_OKTAS = 3; + + // 2/8 of the sky is covered with clouds. + // + FRACTIONAL_CLOUD_COVER_TWO_OKTAS = 4; + + // 3/8 of the sky is covered with clouds. + // + FRACTIONAL_CLOUD_COVER_THREE_OKTAS = 5; + + // 4/8 of the sky is covered with clouds. + // + FRACTIONAL_CLOUD_COVER_FOUR_OKTAS = 6; + + // 5/8 of the sky is covered with clouds. + // + FRACTIONAL_CLOUD_COVER_FIVE_OKTAS = 7; + + // 6/8 of the sky is covered with clouds. + // + FRACTIONAL_CLOUD_COVER_SIX_OKTAS = 8; + + // 7/8 of the sky is covered with clouds. + // + FRACTIONAL_CLOUD_COVER_SEVEN_OKTAS = 9; + + // 8/8 of the sky is covered with clouds. + // + FRACTIONAL_CLOUD_COVER_EIGHT_OKTAS = 10; + + // Sky obscured, describes situations where the sky is not perceivable, e.g. in dense fog. + // + FRACTIONAL_CLOUD_COVER_SKY_OBSCURED = 11; + } + } + + // + // \brief Defines wind properties. + // + message Wind + { + // The origin direction of the wind (not the target direction) in the ground/xy-plane of the + // world coordinate system. Corresponds to the heading/yaw angle, counted counterclockwise. + // 0 pointing north. If north is not explicitly defined via \c #osi3::GroundTruth::proj_string, + // then north is pointing in y-axis direction. The default orientation (x, y, z) is easting, northing, up [1]. + // + // \note 0: north; +pi/2: west; pi: south, 3/2 pi: east. + // + // Unit: rad + // + // The preferred angular range is [0, 2pi]. + // + // \par References: + // [1] PROJ contributors. (2019). PROJ coordinate transformation software library. Open Source Geospatial Foundation. Retrieved January 25, 2019, from https://proj.org/usage/projections.html + // + optional double origin_direction = 1; + + // The wind speed. + // + // Unit: m/s + // + // \rules + // is_greater_than_or_equal_to: 0 + // \endrules + // + optional double speed = 2; + } + + // + // \brief Properties of the sun. + // + message Sun + { + // Azimuth of the sun, counted counterclockwise. + // 0 pointing north. If north is not explicitly defined via \c #osi3::GroundTruth::proj_string, + // then north is pointing in y-axis direction. The default orientation (x, y, z) is easting, northing, up [1]. + // The point of observation is defined to be the global coordinate system's origin. + // + // \note 0: north; +pi/2: west; pi: south, 3/2 pi: east. + // + // Unit: rad + // + // The preferred angular range is [0, 2pi]. + // + // \par References: + // [1] PROJ contributors. (2019). PROJ coordinate transformation software library. Open Source Geospatial Foundation. Retrieved January 25, 2019, from https://proj.org/usage/projections.html + // + optional double azimuth = 1; + + // Solar elevation angle. + // The elevation angle is positive when the sun is above the xy-plane, negative when + // the sun is below the xy-plane. + // The point of observation is defined to be the global coordinate system's origin. + // + // \note 0: xy-plane; +pi/2: zenith; -pi/2: nadir. + // + // Unit: rad + // + // The preferred angular range is [-pi/2, +pi/2]. + // + optional double elevation = 2; + + // Illuminance of the sun, direct sunlight is around 100000 lx. + // + // Unit: lx + // + // \rules + // is_greater_than_or_equal_to: 0 + // \endrules + // + optional double intensity = 3; + } }