Documentation Migration Preview #538

pmai · 2021-06-23T10:32:43Z

This PR is a consolidated rebased preview of all of the documentation migration changes which are also available as separate PRs against the migration branch.

This was created to allow easier at a glance review of the documentation changes in one place. Will be kept up-to-date until merge.

Signed-off-by: Maximilian Rosin <maximilian.rosin@parson-europe.com>

…ocs (#534) Signed-off-by: Maximilian Rosin <maximilian.rosin@parson-europe.com>

Signed-off-by: Maximilian Rosin <maximilian.rosin@parson-europe.com>

max-rosin · 2021-06-24T08:22:20Z

doc/releases/releases.adoc

@@ -0,0 +1,3 @@
+= Releases
+
+ss


Removed in context of PR #533 (4d42c5b).

max-rosin · 2021-06-24T08:42:29Z

doc/releases/v03.02.adoc

+
+https://www.youtube.com/watch?v=SJUhlRoBL8M[Think p(OSI)tive!]
+
+


Fixed whitespace in context of PR #533 (9ac1d74).

max-rosin · 2021-06-24T08:42:46Z

doc/releases/v03.03.adoc

+= https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.3.1[v3.3.1 - OSI "Fabulous Fangio", Update 1]
+
+== https://github.com/OpenSimulationInterface/open-simulation-interface/milestone/18?closed=1[Content/Changes]
+


Fixed whitespace in context of PR #533 (9ac1d74).

max-rosin · 2021-06-24T08:44:02Z

doc/releases/v03.01.adoc

+
+== Purpose
+
+This time of the year Santa comes with presents and has also thought about the sensor modelers of this planet. We introduce the current state of the ISO 23150 discussions including Ultrasonic and Camera Detections. The traffic signs have been reworked and the documentation has been extended for a perfect user experience. Trust me - it's amazing!


Fixed linebreaks in context of PR #533 (9ac1d74).

max-rosin · 2021-06-24T08:44:38Z

doc/releases/v03.00.adoc

+This release is a complete rework including the feedback from many OSI users. Thank you!
+We are aligned with the ongoing discussions for the upcoming ISO 23150 standard for hardware sensor outputs in order to bring simulation and the hardware in the car closer together.
+
+https://github.com/OpenSimulationInterface/open-simulation-interface/pulls?page=1&q=is%3Apr+is%3Aclosed+milestone%3Av3.0.0[Content/Changes]


Added missing header markup in context of PR #533 (9ac1d74).

max-rosin · 2021-06-24T08:44:48Z

doc/releases/v03.00.adoc

+
+This release is a patch reworking parts of the documentation in order to avoid ambiguities and improving the build/installation process of OSI.
+
+https://github.com/OpenSimulationInterface/open-simulation-interface/pulls?page=1&q=is%3Apr+is%3Aclosed+milestone%3Av3.0.1[Content/Changes]


Added missing header markup in context of PR #533 (9ac1d74).

max-rosin · 2021-06-24T09:02:27Z

doc/architecture/trace_file_naming.adoc

@@ -0,0 +1,21 @@
+= OSI trace file naming conventions


Add example in context of PR #528 (5ba5394).

max-rosin · 2021-06-24T09:03:22Z

doc/architecture/trace_file_formats.adoc

@@ -0,0 +1,18 @@
+= OSI trace file formats
+
+There are multiple formats for storing multiple serialized OSI messages into one trace file


Fixed typo in context of PR #528 (5ba5394).

max-rosin · 2021-06-24T09:03:58Z

doc/architecture/formatting_scripts.adoc

@@ -0,0 +1,48 @@
+# Trace-file formatting scripts


Fixed typos in context of PR #528 (5ba5394).

max-rosin · 2021-06-24T11:43:02Z

doc/architecture/reference_points_coordinate_systems.adoc

@@ -0,0 +1,26 @@
+= Reference points and coordinate systems


See PR #516

max-rosin · 2021-06-24T11:46:40Z

doc/misc/osi_vision.adoc

@@ -0,0 +1,11 @@
+= The vision of Open Simulation Interface


See issue #540

max-rosin · 2021-06-24T12:03:24Z

Fixed all the issues I found in the corresponding PRs (see comments).

clemenshabedank · 2021-07-02T09:11:49Z

doc/architecture/architecture_overview.adoc

+
+OSI contains an object-based environment description using the message format of the https://github.com/protocolbuffers/protobuf/wiki[Protocol Buffer] library developed and maintained by Google.
+OSI defines top-level messages that are used to exchange data between separate models.
+Top-level messages define the ``GroundTruth`` interface, the ``SensorData`` interface and, since OSI version 3.0.0, the ``SensorView``, ``SensorViewConfiguration`` and ``FeatureData`` interfaces.


TrafficCommand and TrafficUpdate missing.

Remove comment, gets clear below.

I also fell over that here: https://github.com/OpenSimulationInterface/open-simulation-interface/pull/535/files
let's add an
Top-level messages regarding sensor models define...

clemenshabedank · 2021-07-02T09:35:26Z

doc/architecture/environmental_effect_model.adoc

+Environmental effect models consume sensor-view data and produce sensor-view data.
+Environmental effect models may, for example, include the following:
+
+* Shadows and oclusion


Suggested change

* Shadows and oclusion

* Shadows and occlusion

Maybe Shadows and occlusions (since we used plural for shadows than to stay consistent, also use it for occlusions)

Fixed typo and switched to plural, see 8a14884.

clemenshabedank · 2021-07-02T11:32:55Z

Won't be able to work on reviewing in the next 3 weeks due to vacation. I apologize.

kmeids · 2021-07-06T22:01:04Z

doc/architecture/architecture_overview.adoc

+However, this does not mean that filling the field is optional.
+For the purpose of providing a complete interface, all existing fields should be set, unless not setting a field carries a specific meaning as indicated in the accompanying comment.
+
+All field numbers of 10000 and upward are available for user-specific extensions via custom fields.


Suggested change

All field numbers of 10000 and upward are available for user-specific extensions via custom fields.

All field numbers of 10000 and above are available for user-specific extensions via custom fields.

See 9e24025

kmeids · 2021-07-06T22:03:48Z

doc/architecture/environmental_effect_model.adoc

+Environmental effect models consume sensor-view data and produce sensor-view data.
+Environmental effect models may, for example, include the following:
+
+* Shadows and oclusion


Maybe Shadows and occlusions (since we used plural for shadows than to stay consistent, also use it for occlusions)

kmeids · 2021-07-06T22:04:34Z

doc/architecture/environmental_effect_model.adoc

+
+* Shadows and oclusion
+* Weather effects
+* Physics of a sensor


What is meant by "Physics of a sensor" ?

The actual physics of a sensor, for example, its optics, electronics, and mechanics. We had discussion about this last year (in October if I remember correctly). So I thought, I may just include it here.

kmeids · 2021-07-06T22:08:33Z

doc/architecture/feature_data.adoc

+= Feature data
+
+Feature data contains detected features in the reference frame of a sensor.
+Feature data is generated from ground-truth data.
+It serves, for example, as input for sensor models simulating object detection or feature fusion models.


Feature data needs more description, I feel that it is still vague.

I agree that the topic can be expanded. Do you have any suggestions? What are you missing?

kmeids · 2021-07-06T22:09:27Z

doc/architecture/formatting_scripts.adoc

@@ -0,0 +1,48 @@
+# Trace-file formatting scripts
+
+OSI provides Python scripts for converting trace files from one format to the other.


Suggested change

OSI provides Python scripts for converting trace files from one format to the other.

Python scripts are provided for converting trace files from one format to the other.

Improved wording ("OSI repo contains...") while maintaining active mode (see 3806ef0).

kmeids · 2021-07-06T22:13:17Z

doc/architecture/logical_model.adoc

+Logical models consume sensor-data data and produce sensor-data data.
+
+An example of a logical model is a sensor-fusion model, which fuses the output of multiple sensor models.
+Another use case is the injection of faults after the sensor model.


"injection of faults" does not seem a good choice of words. Let's see how to replace it!

kmeids · 2021-07-06T22:17:38Z

doc/architecture/reference_points_coordinate_systems.adoc

@@ -0,0 +1,26 @@
+= Reference points and coordinate systems
+
+With Open Simulation Interface, an object's position coordinates refer to the center of the object's bounding box.


Suggested change

With Open Simulation Interface, an object's position coordinates refer to the center of the object's bounding box.

In Open Simulation Interface, object's position is defined by the coordinates of it's center of bounding box.

See #516 for current changes.

kmeids · 2021-07-06T22:18:14Z

doc/architecture/reference_points_coordinate_systems.adoc

+= Reference points and coordinate systems
+
+With Open Simulation Interface, an object's position coordinates refer to the center of the object's bounding box.
+This reference point is not necessarily identical to the origin of the respective coordinate systems.


"respective coordinate system" is a bit confusing

Fixed. See #516 for current changes.

max-rosin added 19 commits June 23, 2021 12:26

feat(docs): Create initial document structure (#494)

7464075

Signed-off-by: Maximilian Rosin <maximilian.rosin@parson-europe.com>

feat(docs): Comment out includes irrelevant to v3.4

4f3cf40

Signed-off-by: Maximilian Rosin <maximilian.rosin@parson-europe.com>

feat(docs): Comment out includes irrelevant to v3.4

584f4ed

Signed-off-by: Maximilian Rosin <maximilian.rosin@parson-europe.com>

Describe installation under Linux and Windows (#518)

7803fe7

Signed-off-by: Maximilian Rosin <maximilian.rosin@parson-europe.com>

feat(docs): Add topics to submap (#518)

73cc305

Signed-off-by: Maximilian Rosin <maximilian.rosin@parson-europe.com>

fix(docs): Fix header (#518)

a10fa6c

Signed-off-by: Maximilian Rosin <maximilian.rosin@parson-europe.com>

Describe top-level messages (#506)

a74d9cd

Signed-off-by: Maximilian Rosin <maximilian.rosin@parson-europe.com>

feat(docs): Add traffic command and traffic update (#506)

69668c4

Signed-off-by: Maximilian Rosin <maximilian.rosin@parson-europe.com>

Implement review comments (#506)

8965359

Signed-off-by: Maximilian Rosin <maximilian.rosin@parson-europe.com>

feat(docs): Describe coordinate systems and reference points (#510)

19a69fc

Signed-off-by: Maximilian Rosin <maximilian.rosin@parson-europe.com>

feat(docs): Implement review suggestions (#510)

fde7a88

Signed-off-by: Maximilian Rosin <maximilian.rosin@parson-europe.com>

feat(docs): Implement review suggestions (#510)

cd3c030

Signed-off-by: Maximilian Rosin <maximilian.rosin@parson-europe.com>

feat(docs): Describe model types (#517)

de49020

Signed-off-by: Maximilian Rosin <maximilian.rosin@parson-europe.com>

Describe trace files (#520)

791a280

Signed-off-by: Maximilian Rosin <maximilian.rosin@parson-europe.com>

Fix typos (#520)

a2e59ec

Signed-off-by: Maximilian Rosin <maximilian.rosin@parson-europe.com>

feat(docs): Migrate version info (#532)

e969876

Signed-off-by: Maximilian Rosin <maximilian.rosin@parson-europe.com>

feat(docs): Add architecture overview (#534)

f43b363

Signed-off-by: Maximilian Rosin <maximilian.rosin@parson-europe.com>

feat(docs): Add content about interface fields as found in original d…

5165fbb

…ocs (#534) Signed-off-by: Maximilian Rosin <maximilian.rosin@parson-europe.com>

feat(docs): Add link to reference documentation (#531)

ed32498

Signed-off-by: Maximilian Rosin <maximilian.rosin@parson-europe.com>

pmai added the Documentation Everything which impacts the quality of the documentation and guidelines. label Jun 23, 2021

pmai added this to the V3.4.0 milestone Jun 23, 2021

pmai requested review from ThomasNaderBMW, clemenshabedank, max-rosin and stefancyliax June 23, 2021 10:32

pmai self-assigned this Jun 23, 2021

max-rosin reviewed Jun 24, 2021

View reviewed changes

doc/releases/releases.adoc

@@ -0,0 +1,3 @@

= Releases

ss No newline at end of file

Copy link

Contributor

max-rosin Jun 24, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Removed in context of PR #533 (4d42c5b).

max-rosin reviewed Jun 24, 2021

View reviewed changes

doc/misc/osi_vision.adoc

@@ -0,0 +1,11 @@

= The vision of Open Simulation Interface

Copy link

Contributor

max-rosin Jun 24, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See issue #540

clemenshabedank reviewed Jul 2, 2021

View reviewed changes

kmeids reviewed Jul 6, 2021

View reviewed changes

stefancyliax removed this from the V3.4.0 milestone Aug 4, 2021

stefancyliax closed this Aug 4, 2021


		https://www.youtube.com/watch?v=SJUhlRoBL8M[Think p(OSI)tive!]

		= https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.3.1[v3.3.1 - OSI "Fabulous Fangio", Update 1]

		== https://github.com/OpenSimulationInterface/open-simulation-interface/milestone/18?closed=1[Content/Changes]


		== Purpose

		This time of the year Santa comes with presents and has also thought about the sensor modelers of this planet. We introduce the current state of the ISO 23150 discussions including Ultrasonic and Camera Detections. The traffic signs have been reworked and the documentation has been extended for a perfect user experience. Trust me - it's amazing!


		This release is a patch reworking parts of the documentation in order to avoid ambiguities and improving the build/installation process of OSI.

		https://github.com/OpenSimulationInterface/open-simulation-interface/pulls?page=1&q=is%3Apr+is%3Aclosed+milestone%3Av3.0.1[Content/Changes]

		@@ -0,0 +1,18 @@
		= OSI trace file formats

		There are multiple formats for storing multiple serialized OSI messages into one trace file

	All field numbers of 10000 and upward are available for user-specific extensions via custom fields.
	All field numbers of 10000 and above are available for user-specific extensions via custom fields.

		@@ -0,0 +1,48 @@
		# Trace-file formatting scripts

		OSI provides Python scripts for converting trace files from one format to the other.

	OSI provides Python scripts for converting trace files from one format to the other.
	Python scripts are provided for converting trace files from one format to the other.

		@@ -0,0 +1,26 @@
		= Reference points and coordinate systems

		With Open Simulation Interface, an object's position coordinates refer to the center of the object's bounding box.

	With Open Simulation Interface, an object's position coordinates refer to the center of the object's bounding box.
	In Open Simulation Interface, object's position is defined by the coordinates of it's center of bounding box.

Documentation Migration Preview #538

Documentation Migration Preview #538

Uh oh!

Conversation

pmai commented Jun 23, 2021

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

max-rosin commented Jun 24, 2021

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

clemenshabedank commented Jul 2, 2021

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants