Skip to content

Commit 5218133

Browse files
ainarjdsika
ainar
authored and
jdsika
committed
First release of the validator (#9)
* First release candidate, release notes separately
1 parent d500279 commit 5218133

File tree

80 files changed

+7194
-375
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

80 files changed

+7194
-375
lines changed

‎.gitignore‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -102,3 +102,11 @@ venv.bak/
102102

103103
# mypy
104104
.mypy_cache/
105+
106+
# Visual Studio Code
107+
.vscode
108+
109+
# Madeup extension for OSI byteencoded string
110+
*.osibytes
111+
*.sosibytes
112+
.DS_Store

‎KPIs/Doxyfile‎

Lines changed: 2494 additions & 0 deletions
Large diffs are not rendered by default.

‎KPIs/Makefile‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
KPISDOCDIR=${KPIDOCDIR}
2+
3+
.PHONY: clean
4+
5+
doxy: clean
6+
doxygen >> /dev/null > /dev/null 2>&1
7+
mv html $${KPIDOCDIR:-here}
8+
9+
clean:
10+
rm -rf $${KPIDOCDIR:-here}/*

‎KPIs/README.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# KPIs of OSI
2+
3+
## Presentation
4+
5+
As a scrum team, we would like to create a data validity KPI (requirements) for each message of OSI.
6+
7+
The KPI should be followed to create a OSI 3 message to be considered as *valid*.
8+
9+
These KPI requirements are available here on a Doxygen documentation: http://opensimulationinterface.github.io/osi-validation/KPIs/
10+
11+
## How to deploy the Doxygen documentation
12+
13+
### Requirements (Linux only)
14+
15+
- Doxygen (on Debian/Ubuntu: `sudo apt install doxygen`)
16+
- make
17+
18+
### Deploy
19+
20+
Run in the KPIs folder: `make`
21+
22+
To clean the folder: `make clean`

‎KPIs/all_other.dox‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
\namespace osi3
2+
3+
The OSI classes live in namespace osi3 to access this namespace in CPP use

‎KPIs/osi_BaseMoving.dox‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
/*!
2+
\class BaseMoving
3+
\brief The base attributes of an object that is moving.
4+
5+
This includes the \c MovingObject , \c DetectedMovingObject , \c HostVehicleData ,
6+
\c SensorData .
7+
8+
\par Requirements
9+
10+
General requirements:
11+
- All fields must be set and initialized
12+
- Meaningful data must be set for all the data fields
13+
14+
15+
16+
Attribute | Type | Repeated | Unit | Requirements
17+
:----------------|---------------|----------|---------------------|------------------------------------------------------
18+
dimension | Dimension3d | No | [m] | Must be set, all components must be positive
19+
position | Vector3d | No | [m] | Must be set
20+
orientation | Orientation3d | No | [rad] | Must be set, all values must me inside range (-pi,pi]
21+
velocity | Vector3d | No | [m/s] | Must be set
22+
acceleration | Vector3d | No | [m/s<sup>2</sup>] | Must be set
23+
orientation_rate | Orientation3d | No | [rad/s<sup>2</sup>] | Must be set
24+
base_polygon | Vector2d | Yes | [m] | See the notes in \c BaseStationary
25+
26+
27+
\par Difference between GroundTruth and SensorData
28+
29+
All coordinates and orientations from \c GroundTruth objects are relative to the
30+
global ground truth frame. All coordinates and orientations from detected
31+
objects (\c SensorData) are relative to the \c HostVehicle frame.
32+
33+
\par base_polygon data field
34+
See the dicsussion in \c BaseStationay/
35+
*/

‎KPIs/osi_BaseStationary.dox‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
/*!
2+
\class BaseStationary
3+
\brief The base attributes of a stationary object or entity.
4+
5+
This includes the \c StationaryObject , \c TrafficSign , \c TrafficLight , \c RoadMarking messages.
6+
7+
\par Requirements
8+
9+
General requirements:
10+
- All fields must be set and initialized
11+
- Meaningful data must be set for all the data fields
12+
13+
14+
Field | Type | Repeated | Unit | Requirements
15+
:------------|---------------|----------|-------|---------------------------------------------
16+
dimension | Dimension3d | No | [m] | Must be set, all components must be positive
17+
position | Vector3d | No | [m] | Must be set
18+
orientation | Orientation3d | No | [rad] | All values must me inside range (-pi,pi]
19+
base_polygon | Vector2d | Yes | [m] | See the note below
20+
21+
22+
\par Difference between GroundTruth and SensorData
23+
All coordinates and orientations from \c GroundTruth objects are relative to the
24+
global ground truth frame. All coordinates and orientations from detected
25+
objects (\c SensorData) are relative to the \c HostVehicle frame.
26+
27+
\par base_polygon data field
28+
29+
Usage as ground truth:
30+
31+
The two dimensional (flat) contour of the object. This is an extension of the concept of a bounding box as defined by Dimension3d. The contour is the projection of the object's outline onto the z-plane in the object frame (independent of its current position and orientation). The height is the same as the height of the bounding box.
32+
33+
Usage as sensor data:
34+
The polygon describes the visible part of the object's contour.
35+
36+
General definitions:
37+
- The polygon is defined in the local object frame: x pointing forward and y to the left.
38+
- The origin is the center of the bounding box.
39+
- As ground truth, the polygon is closed by connecting the last with the first point. Therefore these two points must be different. The polygon must consist of at least three points.
40+
- As sensor data, however, the polygon is open.
41+
- The polygon is defined counter-clockwise.
42+
- The validity of base_polygon depend on context it is used
43+
44+
If the base_polygon field is used in GroundTruth context it is always a function of object's bounding box dimension,orientation and position. And is always four distinct elements.
45+
If the base_polygon is used in SensorData context it can be polygon of more then four elements but also less the four elements 0 element array if the object is not visible to the sensor at all.
46+
The situation when visible part of the objects consists of two separate contours is not handled
47+
*/

‎KPIs/osi_Dimension3d.dox‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
/*!
2+
\class Dimension3d
3+
\brief The dimension of a 3D box, e.g. the size of a 3D bounding box or its uncertainties.
4+
5+
Dimension is defined in the specified reference coordinate frame along the x-axis (=length), y-axis (=width) and z-axis (=height).
6+
7+
\par Requirements
8+
9+
All fields must be initialized.
10+
11+
All fields must be positive.
12+
13+
Field | Type | Unit | Requirements
14+
:---------|--------|------|----------------:
15+
length | double | [m] | Must be positive
16+
width | double | [m] | Must be positive
17+
height | double | [m] | Must be positive
18+
*/

‎KPIs/osi_EnvironmentalConditions.dox‎

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
/*!
2+
\class EnvironmentalConditions
3+
\brief The conditions of the environment.
4+
5+
Definition of light, weather conditions and other environmental conditions.
6+
7+
8+
\par Requirements
9+
10+
field | type | repeated | Requirements
11+
-------------------- | --------------------- | -------- | -----------
12+
ambient_illumination | EnvironmentalConditions::AmbientIllumination | no | Must be set and valid
13+
time_of_day | EnvironmentalConditions::TimeOfDay | no | Must be set and valid
14+
atmospheric_pressure | double | no | Must be in Pascal [Pa]; must be set
15+
temperature | double | no | Mun be in Kelvin [K]; must be set
16+
relative_humidity | double | no | Must be in range [0 - 100] [%]; must be set
17+
precipitation | EnvironmentalConditions::Precipitation | no | Must be set and valid
18+
fog | EnvironmentalConditions::Fog | no | Must be set and valid
19+
20+
\note temperature, atmospheric_pressure and relative_humidity refer to these values at z = 0.0 height 0m see level
21+
22+
\note atmospheric_pressure is essensialy [QNH](https://en.wikipedia.org/wiki/QNH). Accepted extreme values are 800 hPa and 1200 hPa.
23+
24+
\note temperature has accepted extreme values of 170\ K and 340\ K.
25+
26+
\note Should we use more common units like. Celcius, hPa to avoid errors.
27+
28+
###############################################################################
29+
30+
\class EnvironmentalConditions::Precipitation
31+
\brief Definition of discretized precipitation states
32+
33+
Definition of discretized precipitation states according to [1].
34+
(I = Intensity of precipitation in mm per hour [mm/h])
35+
36+
\par Requirements
37+
38+
Number | Type name | Requirements
39+
:----- | :------------------ | :---------
40+
0 | PRECIPITATION_UNKNOWN | Intensity of precipitation is unknown (must not be used in ground truth).
41+
1 | PRECIPITATION_OTHER | Other (unspecified but known) intensity of precipitation.
42+
2 | PRECIPITATION_NONE | No precipitation, when I in [0,0.1[ [mm/h]
43+
3 | PRECIPITATION_VERY_LIGHT | Very light intensity of precipitation, when I in [0.1,0.5[ [mm/h]
44+
4 | PRECIPITATION_LIGHT | Light intensity of precipitation, when I in [0.5,1.9[ [mm/h]
45+
5 | PRECIPITATION_MODERATE | Moderate intensity of precipitation, when I in [1.9,8.1[ [mm/h]
46+
6 | PRECIPITATION_HEAVY | Heavy intensity of precipitation, when I in [8.1,34[ [mm/h]
47+
7 | PRECIPITATION_VERY_HEAVY | Very heavy intensity of precipitation, when I in [34,149[ [mm/h]
48+
49+
\par References:
50+
51+
[1] PAULAT, Marcus, et al. A gridded dataset of hourly precipitation
52+
in Germany: Its construction, climatology and application.
53+
Meteorologische Zeitschrift, 2008, 17. Jg. Nr. 6, S. 719-732.
54+
55+
###############################################################################
56+
57+
\class EnvironmentalConditions::Fog
58+
\brief Definition of discretized fog states
59+
60+
Definition of discretized fog states according to [2]. The bandwidth of thick and dense fog was adjusted to fit the German StVO
61+
regarding rear fog lights [3]. (V = Visibility in meters [m])
62+
63+
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]).
64+
This is approximately equivalent to visibility measured in terms of the contrast of a distant object against its background.
65+
66+
\par Requirements
67+
68+
Number | Type name | Requirements
69+
:----- | :------------------ | :---------
70+
0 | FOG_UNKOWN | Visibility is unknown (must not be used in ground truth).
71+
1 | FOG_OTHER | Other (unspecified but known) fog intensity.
72+
2 | FOG_EXCELLENT_VISIBILITY | Excellent visibility, when V in [40000,infinity[ [m]
73+
3 | FOG_GOOD_VISIBILITY | Good visibility, when V in [10000,40000[ [m]
74+
4 | FOG_MODERATE_VISIBILITY | Moderate visibility, when V in [4000,10000[ [m]
75+
5 | FOG_POOR_VISIBILITY | Poor visibility, when V in [2000,4000[ [m]
76+
6 | FOG_MIST | Mist, when V in [1000,2000[ [m]
77+
7 | FOG_LIGHT | Fog, when V in [200,1000[ [m]
78+
8 | FOG_THICK | Thick fog, when V in [50,200[ [m]
79+
80+
\par References:
81+
- [2] SHEPARD, Frank D. Reduced visibility due to fog on the highway. Transportation Research Board, 1996.
82+
- [3] [StVO 17 chapter 3](https://www.stvo.de/strassenverkehrsordnung/101-17-beleuchtung)
83+
- [4] [Homepage of the Meteorological Office](http://www.metoffice.gov.uk/guide/weather/observations-guide/how-we-measure-visibility)
84+
85+
###############################################################################
86+
87+
\class EnvironmentalConditions::TimeOfDay
88+
\brief The time of day at the location of the vehicle.
89+
90+
\par Requirements
91+
92+
field | type | repeated | Requirements
93+
-------------------- | ------- | -------- | -----------
94+
seconds_since_midnight |uint32 | no | Must be in range [0 , 86400[
95+
96+
The number of seconds [s] that have passed since midnight local time.
97+
Used for determining the current state of the circadian rhythm of a driver.
98+
99+
\note Rename "local time" to local time zone.
100+
101+
\note No changes of daylight saving time or time zones are considered. So we should specify which time are we using.
102+
103+
\note This field intent is to describe fitness of the driver to operate a vehicle. Maybe we should move this field to Occupant. Or have another field hours awake.
104+
105+
###############################################################################
106+
107+
\class EnvironmentalConditions::AmbientIllumination
108+
\brief Definition of discretized ambient illumination states
109+
110+
Definition of discretized ambient illumination states:
111+
Ambient light is any light in the vehicle's environment that is not
112+
emitted by the vehicle itself. It can include sun/moon light, light from
113+
other cars, street lights etc.
114+
115+
Categorization is done based on natural day/night time illuminance levels
116+
[6] and standards for required lighting levels on roads [6, 7, 8, 9].
117+
118+
\par Requirements
119+
120+
Number | Type name | Requirements
121+
:----- | :------------------ | :---------
122+
0 | AMBIENT_ILLUMINATION_UNKNOWN | Ambient illumination is unknown (must not be used in ground truth).
123+
1 | AMBIENT_ILLUMINATION_OTHER | Other (unspecified but known) ambient illumination.
124+
2 | AMBIENT_ILLUMINATION_LEVEL1 | 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]
125+
3 | AMBIENT_ILLUMINATION_LEVEL2 | Level 2 illumination in [0.01, 1[ [lx] E.g. Night full moon / Deep twilight.
126+
4 | AMBIENT_ILLUMINATION_LEVEL3 | Level 3 illumination in [1, 3[ [lx] E.g. Deep to average twilight / Minimum lighting on local low pedestrian conflict roads.
127+
5 | AMBIENT_ILLUMINATION_LEVEL4 | 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.
128+
6 | AMBIENT_ILLUMINATION_LEVEL5 | Level 5 illumination in [10, 20[ [lx] E.g. Minimum lighting on major and expressway roads with high pedestrian conflict.
129+
7 | AMBIENT_ILLUMINATION_LEVEL6 | 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.
130+
8 | AMBIENT_ILLUMINATION_LEVEL7 | Level 7 illumination in [400, 1000[ [lx] E.g. Sunrise or sunset on a clear day / Overcast day.
131+
9 | AMBIENT_ILLUMINATION_LEVEL8 | Level 8 illumination in [1000, 10000[ [lx] E.g. Average to full daylight.
132+
133+
\note Flickering is not considered. It might be very important for camera sensors. Flickering in tunels.
134+
135+
\note Ambient ilumination color temperature is not considered. It might be important for determination of colors e.g. Road markings white or yellow.
136+
137+
\note Position of the Sun relative to ego might influence the sensor output quality, as well as driver situational awarness.
138+
139+
\par References:
140+
- [5] [The NIST Reference on Constants, Units, and Uncertainty](https://physics.nist.gov/cuu/Units/units.html)
141+
- [6] [National Optical Astronomy Observatory](https://www.noao.edu/education/QLTkit/ACTIVITY_Documents/Safety/LightLevels_outdoor+indoor.pdf)
142+
- [7] [Standards for required street lighting in the USA](http://www.wsdot.wa.gov/research/reports/fullreports/847.1.pdf)
143+
- [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)
144+
- [9] [European standards for road lighting](http://courtneystrong.com/wp-content/uploads/2017/07/css-sl1-class-and-quality-of-street-lighting.pdf)
145+
*/

‎KPIs/osi_GroundTruth.dox‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
/*!
2+
\class SensorView
3+
4+
\brief The ground truth information from the simulation environment.
5+
6+
This ground truth information is supposed to describe the whole simulated
7+
environment around any simulated vehicle. For each simulated host vehicle
8+
(there may be one or multiple), define an area around the vehicle which
9+
is greater than the combined field of views (FOV) of all obstructed sensors
10+
in the vehicle. The ground truth data is supposed to describe the convex
11+
hull of all such areas w.r.t. a global simulation coordinate system.
12+
13+
The simulation coordinate system may change during the simulation if and
14+
only if all coordinates w.r.t. this coordinate system are also changed.
15+
16+
The data has to be sent at a rate defined by the receiving partner. When
17+
sending, values with default values might be left default in order to improve
18+
performance.
19+
20+
To provide a complete interface, all fields of all contained messages must be
21+
properly set unless specifically stated in the field's definition that the
22+
field may remain unset.
23+
24+
In enums (e.g. types) the unknown (first / default) value is not allowed to
25+
be used in the ground truth interface.
26+
27+
Field | Type | Repeated | Requirements
28+
-------------------------|----------------------------|----------|---------------------------------------
29+
version | \c InterfaceVersion | No | Must be set and valid
30+
timestamp | \c Timestamp | No | Must be set and valid
31+
host_vehicle_id | \c Identifier | No | Must correspond to the host_vehicle_id
32+
stationary_object | \c StationaryObject | Yes | If set must be valid
33+
moving_object | \c MovingObject | Yes | If set must be valid
34+
traffic_sign | \c TrafficSign | Yes | If set must be valid
35+
traffic_light | \c TrafficLight | Yes | If set must be valid
36+
road_marking | \c RoadMarking | Yes | If set must be valid
37+
lane_boundary | \c LaneBoundary | Yes | If set must be valid
38+
lane | \c Lane | Yes | If set must be valid
39+
occupant | \c Occupant | Yes | If set must be valid
40+
environmental_conditions | \c EnvironmentalConditions | No | Must be set and valid
41+
country_code | \c uint32 | No | Must be set and correspond to a ISO-3166 country code
42+
proj_string | \c string | No | If set must be valid
43+
map_reference | \c string | No |
44+
45+
46+
\par Details on timestamp
47+
48+
The data timestamp of the simulation environment. The zero time point is
49+
arbitrary but must be identical for all messages.
50+
Recommendation: Zero time point for start point of the simulation.
51+
52+
\note Zero time point does not need to coincide with the UNIX epoch.
53+
54+
\note For ground truth data this timestamp coincides both with the
55+
notional simulation time the data applies to and the time it was sent
56+
(there is no inherent latency for ground truth data, as opposed to
57+
sensor data).
58+
59+
\par proj_string
60+
The string follows the PROJ.4 project rules for projections [1].
61+
62+
\par References:
63+
- [1] [Proj.4 Projections] (https://proj4.org/usage/projections.html)
64+
65+
\par Details on map_reference
66+
Opaque reference of a map.
67+
68+
\note Origin and orientation of the map have to coincide with the
69+
inertial coordinate frame of the ground truth.
70+
71+
\note It is implementation-specific how map_reference is resolved.
72+
73+
\note OSI uses singular instead of plural for repeated field names.
74+
*/

0 commit comments

Comments
 (0)