Skip to content

Commit 84cfaf2

Browse files
vkreschjdsika
vkresch
authored and
jdsika
committed
Added local documentation (#351)
1 parent b90159b commit 84cfaf2

17 files changed

Lines changed: 1244 additions & 32 deletions

‎doc/README.md‎

Lines changed: 0 additions & 32 deletions
This file was deleted.

‎doc/commenting.rst‎

Lines changed: 325 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,325 @@
1+
.. _commenting:
2+
3+
Commenting
4+
===========
5+
6+
During the building process of open simulation interface (using the `proto2cpp <https://github.com/OpenSimulationInterface/proto2cpp>`_ filter), doxygen is creating a `reference documentation <https://opensimulationinterface.github.io/open-simulation-interface/>`_ processing all comments written in the code of the interface. In order to do that doxygen needs the comments to be written in a certain way. Please follow these rules to achieve that the reference documentation is created correctly. You will find further information on doxygen `here <http://www.doxygen.nl/manual/docblocks.html>`_.
7+
8+
For any additional comment styles see `list <http://www.doxygen.nl/manual/commands.html>`_ of doxygen commands.
9+
10+
11+
Commenting with block syntax
12+
-----------------------------
13+
Start every comment with ``//`` and do not use ``///``.
14+
15+
16+
Commenting on messages
17+
------------------------
18+
When writing comments specifying messages please use the following template:
19+
20+
.. code-block:: protobuf
21+
22+
// <Add your single line comment like this>
23+
//
24+
message ExampleMessage
25+
{
26+
}
27+
28+
Doxygen will interpret a comment consisting just of one single line as a brief description.
29+
However to keep the style of the documentation coherent there should not be any brief description when commenting on fields and enums. That is why adding one more empty line when commenting becomes necessary. There is no need for an extra empty line if you are commenting more than one line anyways.
30+
31+
.. code-block:: proto
32+
33+
// <If you write two or more lines of comments...>
34+
// <... you do not need to add an empty line>
35+
message ExampleMessage
36+
{
37+
}
38+
39+
The commenting for messages follows the following order:
40+
41+
1. Brief description
42+
2. Image
43+
3. Detailed description
44+
4. Note
45+
46+
First you define the message.
47+
48+
.. code-block:: protobuf
49+
50+
message EnvironmentalConditions
51+
{
52+
}
53+
54+
Next provide a brief description of the message with ``\brief``.
55+
56+
.. code-block:: protobuf
57+
58+
// \brief The conditions of the environment.
59+
//
60+
message EnvironmentalConditions
61+
{
62+
}
63+
64+
Then you can optionally provide an image to explain the message better. A picture is worth a thousand words.
65+
66+
.. code-block:: protobuf
67+
68+
// \brief The conditions of the environment.
69+
//
70+
// \image html EnvironmentalConditions.svg
71+
//
72+
message EnvironmentalConditions
73+
{
74+
}
75+
76+
You can optionally add a detailed description which can have multiple lines.
77+
78+
.. code-block:: protobuf
79+
80+
// \brief The conditions of the environment.
81+
//
82+
// \image html EnvironmentalConditions.svg
83+
//
84+
// Definition of light, weather conditions and other environmental conditions.
85+
//
86+
message EnvironmentalConditions
87+
{
88+
}
89+
90+
Lastly you can add a small note about the message and have a completely commented message.
91+
92+
.. code-block:: protobuf
93+
94+
// \brief The conditions of the environment.
95+
//
96+
// \image html EnvironmentalConditions.svg
97+
//
98+
// Definition of light, weather conditions and other environmental conditions.
99+
//
100+
// \note These conditions apply locally around the host vehicle.
101+
//
102+
message EnvironmentalConditions
103+
{
104+
}
105+
106+
Commenting on fields and enums
107+
--------------------------------
108+
The commenting for fields and enums follows the following order:
109+
110+
1. Explanation
111+
2. Unit
112+
3. Note
113+
4. Reference
114+
5. Rule
115+
116+
First you add a field into a message with an appropriate index number.
117+
118+
.. code-block:: protobuf
119+
120+
// \brief The conditions of the environment.
121+
//
122+
// \image html EnvironmentalConditions.svg
123+
//
124+
// Definition of light, weather conditions and other environmental conditions.
125+
//
126+
// \note These conditions apply locally around the host vehicle.
127+
//
128+
message EnvironmentalConditions
129+
{
130+
optional double atmospheric_pressure = 1;
131+
}
132+
133+
134+
135+
Then you describe the field by adding an explanation.
136+
137+
.. code-block:: protobuf
138+
139+
// \brief The conditions of the environment.
140+
//
141+
// \image html EnvironmentalConditions.svg
142+
//
143+
// Definition of light, weather conditions and other environmental conditions.
144+
//
145+
// \note These conditions apply locally around the host vehicle.
146+
//
147+
message EnvironmentalConditions
148+
{
149+
// Atmospheric pressure in Pascal at z=0.0 in world frame (about 101325 [Pa]).
150+
//
151+
optional double atmospheric_pressure = 1;
152+
}
153+
154+
Next you decide the unit of the field.
155+
156+
.. code-block:: protobuf
157+
158+
// \brief The conditions of the environment.
159+
//
160+
// \image html EnvironmentalConditions.svg
161+
//
162+
// Definition of light, weather conditions and other environmental conditions.
163+
//
164+
// \note These conditions apply locally around the host vehicle.
165+
//
166+
message EnvironmentalConditions
167+
{
168+
// Atmospheric pressure in Pascal at z=0.0 in world frame (about 101325 [Pa]).
169+
//
170+
// Unit: [Pa]
171+
//
172+
optional double atmospheric_pressure = 1;
173+
}
174+
175+
You can optionally add a note to the field to describe the field better.
176+
177+
.. code-block:: protobuf
178+
179+
// \brief The conditions of the environment.
180+
//
181+
// \image html EnvironmentalConditions.svg
182+
//
183+
// Definition of light, weather conditions and other environmental conditions.
184+
//
185+
// \note These conditions apply locally around the host vehicle.
186+
//
187+
message EnvironmentalConditions
188+
{
189+
// Atmospheric pressure in Pascal at z=0.0 in world frame (about 101325 [Pa]).
190+
//
191+
// Unit: [Pa]
192+
//
193+
// \note 100000 Pa = 1 bar
194+
//
195+
optional double atmospheric_pressure = 1;
196+
}
197+
198+
If you want to provide a reference to a DIN or to web page which helps in understanding the field you can add a reference.
199+
200+
.. code-block:: protobuf
201+
202+
// \brief The conditions of the environment.
203+
//
204+
// \image html EnvironmentalConditions.svg
205+
//
206+
// Definition of light, weather conditions and other environmental conditions.
207+
//
208+
// \note These conditions apply locally around the host vehicle.
209+
//
210+
message EnvironmentalConditions
211+
{
212+
// Atmospheric pressure in Pascal at z=0.0 in world frame (about 101325 [Pa]).
213+
//
214+
// Unit: [Pa]
215+
//
216+
// \note 100000 Pa = 1 bar
217+
//
218+
// \par Reference:
219+
// - [1] [Definition atmospheric pressure](https://en.wikipedia.org/wiki/Atmospheric_pressure)
220+
//
221+
optional double atmospheric_pressure = 1;
222+
}
223+
224+
Finally you can provide a set of rules which this field needs to be followed. The available rules can be found below. When adding rules to \*.proto files make sure that the rules are encapsulated between the ``\rules`` and ``\endrules`` tags. Now you have a fully commented message with a fully commented field.
225+
226+
.. code-block:: protobuf
227+
228+
// \brief The conditions of the environment.
229+
//
230+
// \image html EnvironmentalConditions.svg
231+
//
232+
// Definition of light, weather conditions and other environmental conditions.
233+
//
234+
// \note These conditions apply locally around the host vehicle.
235+
//
236+
message EnvironmentalConditions
237+
{
238+
// Atmospheric pressure in Pascal at z=0.0 in world frame (about 101325 [Pa]).
239+
//
240+
// Unit: [Pa]
241+
//
242+
// \note 100000 Pa = 1 bar
243+
//
244+
// \par Reference:
245+
// - [1] [Definition atmospheric pressure](https://en.wikipedia.org/wiki/Atmospheric_pressure)
246+
//
247+
// \rules
248+
// is_optional
249+
// is_greater_than_or_equal_to: 90000
250+
// is_less_than_or_equal_to: 200000
251+
// \endrules
252+
//
253+
optional double atmospheric_pressure = 1;
254+
}
255+
256+
257+
The rule definition must follow the syntax which is defined by a regex search which you can see below:
258+
259+
.. code-block:: python
260+
261+
'is_greater_than': r'\b(is_greater_than)\b: \d+(\.\d+)?' # is_greater_than: 1
262+
'is_greater_than_or_equal_to': r'\b(is_greater_than_or_equal_to)\b: \d+(\.\d+)?' # is_greater_than_or_equal_to: 1
263+
'is_less_than_or_equal_to': r'\b(is_less_than_or_equal_to)\b: \d+(\.\d+)?' # is_less_than_or_equal_to: 10
264+
'is_less_than': r'\b(is_less_than)\b: \d+(\.\d+)?' # is_less_than: 2
265+
'is_equal': r'\b(is_equal)\b: \d+(\.\d+)?' # is_equal: 1
266+
'is_different': r'\b(is_different)\b: \d+(\.\d+)?' # is_different: 2
267+
'is_global_unique': r'\b(is_global_unique)\b' # is_global_unique
268+
'refers': r'\b(refers)\b' # refers
269+
'is_iso_country_code': r'\b(is_iso_country_code)\b' # is_iso_country_code
270+
'first_element': r'\b(first_element)\b: \{.*: \d+\.\d+\}' # first_element: {is_equal: 0.13, is_greater_than: 0.13}
271+
'last_element': r'\b(last_element)\b: \{.*: \d+\.\d+\}' # last_element: {is_equal: 0.13, is_greater_than: 0.13}
272+
'is_optional': r'\b(is_optional)\b' # is_optional
273+
'check_if': r'\b(check_if)\b: \[\{.*: \d+(\.\d+)?, target: .*}, \{do_check: \{.*: \d+(\.\d+)?}}]' # check_if: [{is_equal: 2, is_greater_than: 3, target: this.y}, {do_check: {is_equal: 1, is_less_than: 3}}]
274+
275+
You can check the correctness of these regular expression on `regex101 <https://regex101.com/r/6tomm6/16>`_.
276+
277+
278+
.. is_greater_than: 2
279+
.. is_greater_than: 2.23
280+
.. is_greater_than_or_equal_to: 1
281+
.. is_greater_than_or_equal_to: 1.12
282+
.. is_less_than_or_equal_to: 10
283+
.. is_less_than_or_equal_to: 10.123
284+
.. is_less_than: 2
285+
.. is_less_than: 2.321
286+
.. is_equal: 1
287+
.. is_equal: 1.312
288+
.. is_different: 2
289+
.. is_different: 2.2122
290+
.. is_global_unique
291+
.. refers
292+
.. is_iso_country_code
293+
.. first_element: {is_equal: 3, is_greater: 2}
294+
.. first_element: {is_equal: 0.13, is_greater: 0.13}
295+
.. last_element: {is_equal: 3, is_greater: 2}
296+
.. last_element: {is_equal: 0.13, is_greater: 0.13}
297+
.. check_if: [{is_equal: 2, is_greater_than: 3, target: this.y}, {do_check: {is_equal: 1, is_less_than: 3}}]
298+
.. is_set
299+
300+
301+
Commenting with doxygen references
302+
------------------------------------
303+
If you need to reference to another message etc., you can achieve that by just using the exact same name of this message (upper and lower case sensitive) in your comment and put '\c' in front of the message name.
304+
305+
.. code-block:: proto
306+
307+
// A reference to \c GroundTruth message.
308+
309+
If you want to reference a nested message, use '::' instead of '.' as separators in comments.
310+
311+
If you want to reference message fields and enums add '#' to the enum/field name.
312+
313+
.. code-block:: proto
314+
315+
// A reference to a enum e.g. \c #COLOR_GREEN.
316+
317+
Commenting with links
318+
----------------------
319+
With ``[<add name of your link>](<add url of your link>)`` you can integrate a link to a certain homepage while commenting.
320+
321+
Commenting with images
322+
----------------------
323+
To include images write your comment similar to this ``// \image html <Add name of your image> "<Add optional caption here>"``
324+
Please place all your included images in ``./open-simulation-interface/docs/images``.
325+

‎doc/coordinatesystem.rst‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
Coordinate systems and reference points
2+
============================================
3+
4+
Coordinate systems
5+
-------------------
6+
7+
Currently three coordinate systems exist.
8+
9+
- world frame (for all quantities which are part of groundtruth)
10+
- sensor frame (for all quantities which are part of sensordata)
11+
- object frame (for local object coordinates like axle offset vectors)
12+
13+
The transformation between frames for a specific vehicle/sensor is performed using the information in
14+
15+
- ``GroundTruth::moving_object::base::position and ::orientation``: These define the position and orientation of the vehicle's reference point, i.e. center of bounding box.
16+
- ``GroundTruth::moving_object::vehicle_attributes::bbcenter_to_rear``: This defines the vehicle frame origin resp. the relative frame of the vehicle, i.e. it defines the offset of the rear axis center relative to the vehicle's reference point (center of bounding box). This offset is static and given in vehicle coordinates.
17+
- ``SensorData::mounting_position``: This defines the sensor's position and orientation relative to the vehicle frame's origin, i.e. rear axis center, and therefore defines sensor frame origin resp. the relative frame of the sensor.
18+
19+
20+
Reference points
21+
------------------
22+
23+
All position coordinates refer to the center of the bounding box of the object (vehicle or otherwise). This does not depend on the reference frame and is identical for all objects without exceptions.
24+
25+
26+
Example: Position vectors of vehicles
27+
---------------------------------------
28+
29+
A position vector consists of two points + orientation / coordinate system:
30+
31+
**start point**: This is the origin of the coordinate system. (i.e. sensor frame or world frame).
32+
33+
**end point**: often referred to as reference point. It is always the middle of the bounding box.
34+
35+
**orientation**: captured by the coordinate system. (i.e. sensor frame or world frame).
36+
37+
Open Simulation Interface uses DIN ISO 8855:2013-11 for coordinate systems and transformations between coordinate systems.

0 commit comments

Comments
 (0)