From 93be9e0c0970e08b36b733bda0542c1fb6882164 Mon Sep 17 00:00:00 2001 From: Philip Windecker Date: Tue, 6 Sep 2022 17:47:44 +0200 Subject: [PATCH 01/11] Initial setup for Antora Signed-off-by: Philip Windecker --- .antora/antora.yml | 9 +++ .antora/modules/interface/images | 1 + .antora/modules/interface/nav.adoc | 22 +++++++ .antora/modules/interface/pages | 1 + doc/_config.adoc | 57 +++++++++++++++++++ doc/architecture/architecture_overview.adoc | 5 ++ doc/architecture/data_layer.adoc | 5 ++ .../environmental_effect_model.adoc | 5 ++ doc/architecture/feature_data.adoc | 5 ++ doc/architecture/formatting_scripts.adoc | 5 ++ doc/architecture/ground_truth.adoc | 5 ++ doc/architecture/logical_model.adoc | 5 ++ doc/architecture/packaging_layer.adoc | 5 ++ doc/architecture/proto-files.adoc | 5 ++ .../reference_points_coordinate_systems.adoc | 5 ++ doc/architecture/sensor_data.adoc | 5 ++ doc/architecture/sensor_model.adoc | 5 ++ doc/architecture/sensor_view.adoc | 5 ++ .../sensor_view_configuration.adoc | 5 ++ doc/architecture/test_scripts.adoc | 5 ++ doc/architecture/trace_file_formats.adoc | 5 ++ doc/architecture/trace_file_naming.adoc | 5 ++ doc/architecture/traffic_command.adoc | 6 ++ doc/architecture/traffic_participant.adoc | 5 ++ doc/architecture/traffic_update.adoc | 5 ++ doc/architecture/vehicle_dynamics.adoc | 5 ++ doc/misc/osi_vision.adoc | 5 ++ doc/open-simulation-interface_user_guide.adoc | 24 +++----- doc/setup/including_osi_dev_projects.adoc | 5 ++ doc/setup/installing_linux_cpp.adoc | 5 ++ doc/setup/installing_linux_python.adoc | 5 ++ doc/setup/installing_macos.adoc | 5 ++ doc/setup/installing_windows_cpp.adoc | 5 ++ doc/setup/installing_windows_python.adoc | 5 ++ doc/setup/using_osi_support_tools.adoc | 5 ++ .../benchmark_integration_gpu_radar.adoc | 5 ++ doc/usecases/fusing_sensor_outputs.adoc | 5 ++ doc/usecases/generating_osi_traces.adoc | 5 ++ doc/usecases/injecting_faults.adoc | 5 ++ doc/usecases/modeling_camera_electronics.adoc | 5 ++ doc/usecases/modeling_lidar_sensor.adoc | 5 ++ .../modeling_traffic_participant.adoc | 5 ++ .../transforming_coordinate_systems.adoc | 5 ++ local_build_tools/asciidoctor.bat | 3 + local_build_tools/compose.yml | 8 +++ .../windows_convert_symlinks(ADMIN).bat | 13 +++++ 46 files changed, 307 insertions(+), 17 deletions(-) create mode 100644 .antora/antora.yml create mode 120000 .antora/modules/interface/images create mode 100644 .antora/modules/interface/nav.adoc create mode 120000 .antora/modules/interface/pages create mode 100644 doc/_config.adoc create mode 100644 local_build_tools/asciidoctor.bat create mode 100644 local_build_tools/compose.yml create mode 100644 local_build_tools/windows_convert_symlinks(ADMIN).bat diff --git a/.antora/antora.yml b/.antora/antora.yml new file mode 100644 index 000000000..24a252841 --- /dev/null +++ b/.antora/antora.yml @@ -0,0 +1,9 @@ +# Component name (without spaces!). All content repositories with the same component name are merged in Antora. +name: asamosi +version: + # Update version number accordingly. This is the version for the main branch + main: 'current' + v(*): V$1 + V(*): V$1 + # Update version number accordingly. This is the version for any other activated branch (branch must be added in the generator site.yml!). Schema = 0.0.x- (only works for branches starting with "feature/") + (*): '3.6.0-$1' diff --git a/.antora/modules/interface/images b/.antora/modules/interface/images new file mode 120000 index 000000000..6e64422d3 --- /dev/null +++ b/.antora/modules/interface/images @@ -0,0 +1 @@ +../../../doc/images \ No newline at end of file diff --git a/.antora/modules/interface/nav.adoc b/.antora/modules/interface/nav.adoc new file mode 100644 index 000000000..fe006b5c6 --- /dev/null +++ b/.antora/modules/interface/nav.adoc @@ -0,0 +1,22 @@ +[preface] +* xref:00_preface/00_foreword.adoc[] +[preface] +* xref:00_preface/01_introduction.adoc[] +* xref:01_scope/01_scope.adoc[] +* xref:02_normative_references/01_normative_references.adoc[] +* xref:03_terms_and_definitions/01_terms_and_definitions.adoc[] +* xref:04_abbreviations/01_abbreviations.adoc[] +* xref:05_backward_compatibility/01_backward_compatibility.adoc[] + +[appendix] +* xref:xx_annexes/REPLACE_ME.adoc[] +[bibliography] +* xref:bibliography.adoc[] + +:sectnums!: +* xref:list_of_figures.adoc[] + +:sectnums!: +* xref:list_of_tables.adoc[] + +// TODO Replace with generator \ No newline at end of file diff --git a/.antora/modules/interface/pages b/.antora/modules/interface/pages new file mode 120000 index 000000000..b8f77893d --- /dev/null +++ b/.antora/modules/interface/pages @@ -0,0 +1 @@ +../../../doc \ No newline at end of file diff --git a/doc/_config.adoc b/doc/_config.adoc new file mode 100644 index 000000000..9b86316b4 --- /dev/null +++ b/doc/_config.adoc @@ -0,0 +1,57 @@ + +// This file contains AsciiDoc attributes that shall be used in every AsciiDoc file. +// NOTE: Its content is only applied for Asciidoctor! +// If the same attribute is defined in the antora.yml (without @), the antora.yml definition takes precedence for Antora. + +ifndef::root-path[:root-path: ./] + +:partials-path: {root-path}../_additional_content +:asciidoc-resources: ../asciidoc-resources +:appendix-caption: Annex + +// ifndef::use-antora-rules,include-only-once[] +ifndef::include-only-once[] +:GLO_VAR_STA_ASAM_OpenCRG: ASAM OpenCRG +:glo_var_sta_asam_opencrg: {GLO_VAR_STA_ASAM_OpenCRG} +:GLO_VAR_STA_ASAM_OpenDRIVE: ASAM OpenDRIVE +:GLO_VAR_STA_ASAM_OpenLABEL: ASAM OpenLABEL +:GLO_VAR_STA_ASAM_OpenODD: ASAM OpenODD +:GLO_VAR_STA_ASAM_OSI: ASAM OSI® +:GLO_VAR_STA_ASAM_OpenSCENARIO: ASAM OpenSCENARIO +:GLO_VAR_STA_ASAM_OpenXOntology: ASAM OpenXOntology +:GLO_VAR_STA_BSI_PAS_1883: BSI PAS 1883 +:revnumber: --localbuild-- +:revdate: {docdate} +:bibtex-file: ./content/general_docs/bibliography.bib +// Replace PLACEHOLDER with the name of your standard, e.g. OpenDRIVE +:THIS_STANDARD: {GLO_VAR_STA_ASAM_OSI} +:asam-terminology: https://code.asam.net/common/asam-terminology/-/raw/main/terms_and_definitions_opendrive.adoc +:imagesdir: {root-path}/images +:include-only-once: true +:topicdir: topics +:reusedir: reuse +:toclevels: 3 +:xrefstyle: full +:images_open_simulation_interface: ./open-simulation-interface/doc/images +// :images_osi-sensor-model-packaging: ./osi-sensor-model-packaging/doc/images +:doc_open_simulation_interface: ../../open-simulation-interface/doc/ +:doc_osi-sensor-model-packaging: ../../osi-sensor-model-packaging/doc/ +// Since a document spanning multiple repos is rendered here, the pathing regarding images is a bit involved. +// We create a variable for every repo that is included. It point to the repo in question. +// If the subrepo is rendered seperatly, then the variable is set to just "./images" with ifdef. +// Please note that this variable has to used in all image includes. Includes here have to use "image::./images..." +// :images_osi_sensor_model_packaging: ./osi-sensor-model-packaging/doc/images // example +:imagesoutdir: ./images/generated_images + +endif::[] + +ifndef::use-antora-rules[] +include::{asciidoc-resources}/preamble.adoc[] +endif::[] + +ifdef::env-gitlab[] +:relfilesuffix: .adoc +endif::[] + + +:asciidoc-resources: ../0_resources \ No newline at end of file diff --git a/doc/architecture/architecture_overview.adoc b/doc/architecture/architecture_overview.adoc index f0d8b4f9b..2ff070951 100644 --- a/doc/architecture/architecture_overview.adoc +++ b/doc/architecture/architecture_overview.adoc @@ -1,5 +1,10 @@ = Overview of OSI architecture +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] + OSI contains an object-based environment description that uses the message format of the https://github.com/protocolbuffers/protobuf/wiki[Protocol Buffer] library. Google developed and maintains the Protocol Buffer library. OSI defines top-level messages that are used to exchange data between separate models. diff --git a/doc/architecture/data_layer.adoc b/doc/architecture/data_layer.adoc index a0d4c6770..c23067af3 100644 --- a/doc/architecture/data_layer.adoc +++ b/doc/architecture/data_layer.adoc @@ -1,5 +1,10 @@ = Data layer +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] + The OSI data layer is defined in the message specifications using the ProtoBuf IDL cite:[protobuf]. This defines the data that can be transmitted using OSI, including the structure and the semantics of the data. diff --git a/doc/architecture/environmental_effect_model.adoc b/doc/architecture/environmental_effect_model.adoc index 89bc02b7e..1c5050eff 100644 --- a/doc/architecture/environmental_effect_model.adoc +++ b/doc/architecture/environmental_effect_model.adoc @@ -1,5 +1,10 @@ = Environmental effect model +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] + Environmental effect models consume `SensorView` messages and produce `SensorView` messages. Environmental effect models may, for example, alter `SensorView` messages to include effects and phenomena caused by: diff --git a/doc/architecture/feature_data.adoc b/doc/architecture/feature_data.adoc index 79527d6f9..70743ba08 100644 --- a/doc/architecture/feature_data.adoc +++ b/doc/architecture/feature_data.adoc @@ -1,5 +1,10 @@ = Feature data +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] + `FeatureData` messages contain detected features in the reference frame of a sensor. `FeatureData` messages are generated from `GroundTruth` messages. They serve, for example, as an input to sensor models simulating object detection or feature fusion models. diff --git a/doc/architecture/formatting_scripts.adoc b/doc/architecture/formatting_scripts.adoc index 2ff767ce4..fd1d23e65 100644 --- a/doc/architecture/formatting_scripts.adoc +++ b/doc/architecture/formatting_scripts.adoc @@ -1,5 +1,10 @@ = Trace-file formatting scripts +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] + The OSI repository contains Python scripts for converting trace files from one format to another. The formatting scripts are stored in `open-simulation-interface/format/` diff --git a/doc/architecture/ground_truth.adoc b/doc/architecture/ground_truth.adoc index 2a03bc137..d54d2d843 100644 --- a/doc/architecture/ground_truth.adoc +++ b/doc/architecture/ground_truth.adoc @@ -1,5 +1,10 @@ = Ground truth +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] + `GroundTruth` messages describe the simulated environment containing all simulated objects in the global coordinate system at consecutive time instances. They are based on data available to the simulation environment. `GroundTruth` messages are typically contained in `Sensorview` messages. \ No newline at end of file diff --git a/doc/architecture/logical_model.adoc b/doc/architecture/logical_model.adoc index 3fec5de78..c694f2214 100644 --- a/doc/architecture/logical_model.adoc +++ b/doc/architecture/logical_model.adoc @@ -1,5 +1,10 @@ = Logical model +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] + Logical models consume `SensorData` messages and produce `SensorData` messages. An example of a logical model is a sensor-fusion model, which combines the output of multiple sensor models to produce data with less uncertainty. diff --git a/doc/architecture/packaging_layer.adoc b/doc/architecture/packaging_layer.adoc index c8f62b2bd..ba29622f2 100644 --- a/doc/architecture/packaging_layer.adoc +++ b/doc/architecture/packaging_layer.adoc @@ -1,5 +1,10 @@ = Packaging layer +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] + The OSI packaging layer specifies how components that use the OSI data layer, for example, sensor models, are packaged for exchange. This specifies model types and their mandatory and optional OSI inputs, OSI outputs, and parameter interfaces. diff --git a/doc/architecture/proto-files.adoc b/doc/architecture/proto-files.adoc index a5ee64802..2c638a259 100644 --- a/doc/architecture/proto-files.adoc +++ b/doc/architecture/proto-files.adoc @@ -1,5 +1,10 @@ = Protobuffer files +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] + TODO: Add general description. osi_common.proto:: diff --git a/doc/architecture/reference_points_coordinate_systems.adoc b/doc/architecture/reference_points_coordinate_systems.adoc index 3b7a08153..d66b9208c 100644 --- a/doc/architecture/reference_points_coordinate_systems.adoc +++ b/doc/architecture/reference_points_coordinate_systems.adoc @@ -1,5 +1,10 @@ = Coordinate systems, reference points and coordinate transformation +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] + OSI uses DIN ISO 8855:2013-11 cite:[iso8855] for coordinate systems and transformations between coordinate systems. OSI uses three coordinate systems: diff --git a/doc/architecture/sensor_data.adoc b/doc/architecture/sensor_data.adoc index 6096fbb76..161e9fd2a 100644 --- a/doc/architecture/sensor_data.adoc +++ b/doc/architecture/sensor_data.adoc @@ -1,5 +1,10 @@ = Sensor data +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] +sw `SensorData` messages imitate the output of real sensors. They can be generated from `GroundTruth` messages, `SensorView` messages, `FeatureData` messages, or `SensorData` messages. With the exception of feature data, all information regarding the environment is given with respect to the virtual sensor coordinate system. diff --git a/doc/architecture/sensor_model.adoc b/doc/architecture/sensor_model.adoc index 423ea0668..27cbb49df 100644 --- a/doc/architecture/sensor_model.adoc +++ b/doc/architecture/sensor_model.adoc @@ -1,4 +1,9 @@ = Sensor model +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] + Sensor models consume `SensorView` messages and produce `SensorData` messages. Sensor-model output does not represent raw data but detected features or classified objects. \ No newline at end of file diff --git a/doc/architecture/sensor_view.adoc b/doc/architecture/sensor_view.adoc index 394d26ab4..673a3bbaf 100644 --- a/doc/architecture/sensor_view.adoc +++ b/doc/architecture/sensor_view.adoc @@ -1,5 +1,10 @@ = Sensor view +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] + The sensor view provides the input to OSI sensor models. `SensorView` messages are derived from `GroundTruth` messages. All information regarding the environment is given with respect to the virtual sensor coordinate system, with two exceptions: diff --git a/doc/architecture/sensor_view_configuration.adoc b/doc/architecture/sensor_view_configuration.adoc index 9bba9d973..113927d4b 100644 --- a/doc/architecture/sensor_view_configuration.adoc +++ b/doc/architecture/sensor_view_configuration.adoc @@ -1,5 +1,10 @@ = Sensor-view configuration +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] + The sensor view is flexibly defined to provide different kinds of sensor models with an appropriate input. The sensor-view configuration defines the configuration of a particular sensor view. diff --git a/doc/architecture/test_scripts.adoc b/doc/architecture/test_scripts.adoc index 72a061235..0ad665c37 100644 --- a/doc/architecture/test_scripts.adoc +++ b/doc/architecture/test_scripts.adoc @@ -1,5 +1,10 @@ = Test scripts +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] + TODO: Add general description. __init__.py:: diff --git a/doc/architecture/trace_file_formats.adoc b/doc/architecture/trace_file_formats.adoc index 510797dff..236b57d2d 100644 --- a/doc/architecture/trace_file_formats.adoc +++ b/doc/architecture/trace_file_formats.adoc @@ -1,5 +1,10 @@ = OSI trace file formats +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] + There are multiple formats for storing multiple serialized OSI messages in one trace file. *.osi:: diff --git a/doc/architecture/trace_file_naming.adoc b/doc/architecture/trace_file_naming.adoc index 6899b8ce9..61bc74638 100644 --- a/doc/architecture/trace_file_naming.adoc +++ b/doc/architecture/trace_file_naming.adoc @@ -1,5 +1,10 @@ = OSI trace file naming conventions +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] + **Name format** The names of OSI trace files should have the following format: diff --git a/doc/architecture/traffic_command.adoc b/doc/architecture/traffic_command.adoc index b8fd41657..b69b635ac 100644 --- a/doc/architecture/traffic_command.adoc +++ b/doc/architecture/traffic_command.adoc @@ -1,3 +1,9 @@ = Traffic command +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] + + `TrafficCommand` messages contain control commands from the scenario engine to traffic participant models. \ No newline at end of file diff --git a/doc/architecture/traffic_participant.adoc b/doc/architecture/traffic_participant.adoc index 5e6ccd993..f8340f0e2 100644 --- a/doc/architecture/traffic_participant.adoc +++ b/doc/architecture/traffic_participant.adoc @@ -1,5 +1,10 @@ = Traffic participant +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] + A traffic participant is an element of the simulated world and can change its state during simulation time, for example, its position and orientation. A traffic participant represents one of the following: diff --git a/doc/architecture/traffic_update.adoc b/doc/architecture/traffic_update.adoc index e788df8be..ffdd34a54 100644 --- a/doc/architecture/traffic_update.adoc +++ b/doc/architecture/traffic_update.adoc @@ -1,4 +1,9 @@ = Traffic update +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] + `TrafficUpdate` messages are provided by traffic participants. They provide updates on the position, state, and future trajectory of a traffic participant back to the simulation environment. \ No newline at end of file diff --git a/doc/architecture/vehicle_dynamics.adoc b/doc/architecture/vehicle_dynamics.adoc index bb2faea14..97bf507b6 100644 --- a/doc/architecture/vehicle_dynamics.adoc +++ b/doc/architecture/vehicle_dynamics.adoc @@ -1,3 +1,8 @@ = Vehicle dynamics +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] + TODO: Content to be added in future release. diff --git a/doc/misc/osi_vision.adoc b/doc/misc/osi_vision.adoc index f0bc4ec3a..018043d00 100644 --- a/doc/misc/osi_vision.adoc +++ b/doc/misc/osi_vision.adoc @@ -1,5 +1,10 @@ = Idea behind Open Simulation Interface +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] + {THIS_STANDARD} Open Simulation Interface is a specification for interfaces between models and components of a distributed simulation. OSI is strongly focused on the environmental perception of automated driving functions. However, OSI also specifies interfaces for modeling traffic participants. \ No newline at end of file diff --git a/doc/open-simulation-interface_user_guide.adoc b/doc/open-simulation-interface_user_guide.adoc index 6c8e619fb..8a6673db0 100644 --- a/doc/open-simulation-interface_user_guide.adoc +++ b/doc/open-simulation-interface_user_guide.adoc @@ -1,22 +1,9 @@ -ifndef::THIS_STANDARD[] - -:asciidoc-resources: ../asciidoc-resources -include::{asciidoc-resources}/preamble.adoc[] - -:revnumber: --localbuild-- -:revdate: {docdate} - -:topicdir: topics -:reusedir: reuse - -:imagesdir: . -:images_open_simulation_interface: ./images - - -endif::[] - +:root-path: ./ +include::{root-path}_config.adoc[] = Open Simulation Interface +:antora_mapping: title;numbered +ifndef::use-antora-rules[] include::./misc/osi_vision.adoc[leveloffset=+1] @@ -115,3 +102,6 @@ include::./setup/installing_windows_python.adoc[leveloffset=+2] //== Improving performance //TODO: Define topics and issues regarding performance. + +endif::[] +:!antora-mapping: diff --git a/doc/setup/including_osi_dev_projects.adoc b/doc/setup/including_osi_dev_projects.adoc index 15c3d3153..cbfcc846d 100644 --- a/doc/setup/including_osi_dev_projects.adoc +++ b/doc/setup/including_osi_dev_projects.adoc @@ -1,5 +1,10 @@ = Including OSI in development projects +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] + TODO: Content to be added in future release. // TODO: Add description of this task. diff --git a/doc/setup/installing_linux_cpp.adoc b/doc/setup/installing_linux_cpp.adoc index 540eb1de4..b7d86891f 100644 --- a/doc/setup/installing_linux_cpp.adoc +++ b/doc/setup/installing_linux_cpp.adoc @@ -1,5 +1,10 @@ = Installing OSI for C++ on Linux +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] + **Prerequisites** * You have installed _cmake_. diff --git a/doc/setup/installing_linux_python.adoc b/doc/setup/installing_linux_python.adoc index 84f507461..4f10b2b79 100644 --- a/doc/setup/installing_linux_python.adoc +++ b/doc/setup/installing_linux_python.adoc @@ -1,5 +1,10 @@ = Installing OSI for Python on Linux +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] + **Prerequisites** * You have installed _pip3_. diff --git a/doc/setup/installing_macos.adoc b/doc/setup/installing_macos.adoc index 4fffb36c3..09890545b 100644 --- a/doc/setup/installing_macos.adoc +++ b/doc/setup/installing_macos.adoc @@ -1,5 +1,10 @@ = Installing OSI on MacOS +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] + TODO: Content to be added in future release. // TODO: Add description of this task. diff --git a/doc/setup/installing_windows_cpp.adoc b/doc/setup/installing_windows_cpp.adoc index d365803f1..728113eda 100644 --- a/doc/setup/installing_windows_cpp.adoc +++ b/doc/setup/installing_windows_cpp.adoc @@ -1,5 +1,10 @@ = Installing OSI for C++ on Windows +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] + **Prerequisites** * You have installed _cmake_ as an administrator. diff --git a/doc/setup/installing_windows_python.adoc b/doc/setup/installing_windows_python.adoc index 660428d53..ee5f1771e 100644 --- a/doc/setup/installing_windows_python.adoc +++ b/doc/setup/installing_windows_python.adoc @@ -1,5 +1,10 @@ = Installing OSI for Python on Windows +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] + **Prerequisites** * You have installed _Python_ with administrator rights. diff --git a/doc/setup/using_osi_support_tools.adoc b/doc/setup/using_osi_support_tools.adoc index 952260da1..062240c8f 100644 --- a/doc/setup/using_osi_support_tools.adoc +++ b/doc/setup/using_osi_support_tools.adoc @@ -1,5 +1,10 @@ = Using OSI supporting tools +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] + TODO: Content to be added in future release. // TODO: Add description of this task. diff --git a/doc/usecases/benchmark_integration_gpu_radar.adoc b/doc/usecases/benchmark_integration_gpu_radar.adoc index 83d2098ef..2c6fead55 100644 --- a/doc/usecases/benchmark_integration_gpu_radar.adoc +++ b/doc/usecases/benchmark_integration_gpu_radar.adoc @@ -1,5 +1,10 @@ = Benchmarking and integration: OSI-GPU-radar +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] + TODO: Content to be added in future release. TODO: Clarify content of this use case and make title more clear diff --git a/doc/usecases/fusing_sensor_outputs.adoc b/doc/usecases/fusing_sensor_outputs.adoc index 0d20baf54..67e2f7bd1 100644 --- a/doc/usecases/fusing_sensor_outputs.adoc +++ b/doc/usecases/fusing_sensor_outputs.adoc @@ -1,5 +1,10 @@ = Fusing sensor outputs +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] + TODO: Content to be added in future release. // TODO: Add extensive description of this use case. diff --git a/doc/usecases/generating_osi_traces.adoc b/doc/usecases/generating_osi_traces.adoc index 2dd888a7e..a725047e5 100644 --- a/doc/usecases/generating_osi_traces.adoc +++ b/doc/usecases/generating_osi_traces.adoc @@ -1,5 +1,10 @@ = Generating OSI traces +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] + TODO: Content to be added in future release. // TODO: Add extensive description of this use case. diff --git a/doc/usecases/injecting_faults.adoc b/doc/usecases/injecting_faults.adoc index 047d55c9a..3a7b97d6c 100644 --- a/doc/usecases/injecting_faults.adoc +++ b/doc/usecases/injecting_faults.adoc @@ -1,5 +1,10 @@ = Injecting faults +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] + TODO: Content to be added in future release. // TODO: Add extensive description of this use case. diff --git a/doc/usecases/modeling_camera_electronics.adoc b/doc/usecases/modeling_camera_electronics.adoc index a9cd48a70..05bb6ed37 100644 --- a/doc/usecases/modeling_camera_electronics.adoc +++ b/doc/usecases/modeling_camera_electronics.adoc @@ -1,5 +1,10 @@ = Modeling camera electronics +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] + TODO: Content to be added in future release. // TODO: Add extensive description of this use case. diff --git a/doc/usecases/modeling_lidar_sensor.adoc b/doc/usecases/modeling_lidar_sensor.adoc index 45552354b..78dfe6f7b 100644 --- a/doc/usecases/modeling_lidar_sensor.adoc +++ b/doc/usecases/modeling_lidar_sensor.adoc @@ -1,5 +1,10 @@ = Modeling a LIDAR sensor +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] + // TODO: Add extensive description of this use case. **Prerequisites** diff --git a/doc/usecases/modeling_traffic_participant.adoc b/doc/usecases/modeling_traffic_participant.adoc index e3d10e7c2..cf880d34a 100644 --- a/doc/usecases/modeling_traffic_participant.adoc +++ b/doc/usecases/modeling_traffic_participant.adoc @@ -1,5 +1,10 @@ = Modeling a traffic participant +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] + Different models may be involved in modeling a traffic participant. In all the use cases, a simulator loads and interprets a scenario and a map prior to execution. The scenario is, for example, provided by OpenSCENARIO. diff --git a/doc/usecases/transforming_coordinate_systems.adoc b/doc/usecases/transforming_coordinate_systems.adoc index ccbeb090f..92ac3d5e7 100644 --- a/doc/usecases/transforming_coordinate_systems.adoc +++ b/doc/usecases/transforming_coordinate_systems.adoc @@ -1,5 +1,10 @@ = Coordinate transformations +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] + == Vehicle and sensor coordinate systems When running simulations, it is frequently necessary to transform coordinates from the global coordinate system for a specific vehicle and its sensors. diff --git a/local_build_tools/asciidoctor.bat b/local_build_tools/asciidoctor.bat new file mode 100644 index 000000000..a5dd7d2ae --- /dev/null +++ b/local_build_tools/asciidoctor.bat @@ -0,0 +1,3 @@ +@ECHO OFF +docker-compose up -d +PAUSE \ No newline at end of file diff --git a/local_build_tools/compose.yml b/local_build_tools/compose.yml new file mode 100644 index 000000000..a37849c18 --- /dev/null +++ b/local_build_tools/compose.yml @@ -0,0 +1,8 @@ +version: "2" + +services: + asciidoctor: + image: asciidoctor/docker-asciidoctor + volumes: + - ../:/documents + entrypoint: asciidoctor --failure-level WARN -r asciidoctor-kroki -a mathjax -r asciidoctor-bibtex --trace content/index.adoc -o local_build_tools/HTML_content_local_build.html \ No newline at end of file diff --git a/local_build_tools/windows_convert_symlinks(ADMIN).bat b/local_build_tools/windows_convert_symlinks(ADMIN).bat new file mode 100644 index 000000000..3ddf5dc6f --- /dev/null +++ b/local_build_tools/windows_convert_symlinks(ADMIN).bat @@ -0,0 +1,13 @@ +@ECHO OFF +SET Targetpath=..\.antora\modules\interface +SET Symlinkroot=..\..\.. + +mklink /D %Targetpath%\images %Symlinkroot%\doc\images + +mklink /D %Targetpath%\pages %Symlinkroot%\doc + +@REM mklink /D %Targetpath%\partials %Symlinkroot%\_additional_content + +@REM mklink /D %Targetpath%\attachments %Symlinkroot%\_attachments + +PAUSE \ No newline at end of file From 6659d6857138be8f5f41cc7c6f8080141a9e854e Mon Sep 17 00:00:00 2001 From: Philip Windecker Date: Tue, 6 Sep 2022 18:10:18 +0200 Subject: [PATCH 02/11] Fixed config and updated links Signed-off-by: Philip Windecker --- doc/_config.adoc | 2 -- doc/architecture/formatting_scripts.adoc | 2 +- doc/architecture/trace_file_formats.adoc | 1 + 3 files changed, 2 insertions(+), 3 deletions(-) diff --git a/doc/_config.adoc b/doc/_config.adoc index 9b86316b4..c64098bf2 100644 --- a/doc/_config.adoc +++ b/doc/_config.adoc @@ -53,5 +53,3 @@ ifdef::env-gitlab[] :relfilesuffix: .adoc endif::[] - -:asciidoc-resources: ../0_resources \ No newline at end of file diff --git a/doc/architecture/formatting_scripts.adoc b/doc/architecture/formatting_scripts.adoc index fd1d23e65..e226bd577 100644 --- a/doc/architecture/formatting_scripts.adoc +++ b/doc/architecture/formatting_scripts.adoc @@ -54,4 +54,4 @@ The default value is `None`. **Related topics** -* <<_osi_trace_file_formats>> \ No newline at end of file +* <> \ No newline at end of file diff --git a/doc/architecture/trace_file_formats.adoc b/doc/architecture/trace_file_formats.adoc index 236b57d2d..2f2d742a2 100644 --- a/doc/architecture/trace_file_formats.adoc +++ b/doc/architecture/trace_file_formats.adoc @@ -1,3 +1,4 @@ +[#top-osi_trace_file_formats] = OSI trace file formats ifndef::include-only-once[] From 50a57ad9d2c00cd73ec6a01a51ad73b8205c8b0a Mon Sep 17 00:00:00 2001 From: Philip Windecker Date: Wed, 7 Sep 2022 17:22:12 +0200 Subject: [PATCH 03/11] Added figure anchors Signed-off-by: Philip Windecker --- .antora/modules/gen/doxynav.adoc | 0 doc/architecture/architecture_overview.adoc | 3 +++ doc/architecture/traffic_participant.adoc | 2 ++ doc/usecases/modeling_traffic_participant.adoc | 4 ++++ doc/usecases/transforming_coordinate_systems.adoc | 2 ++ 5 files changed, 11 insertions(+) create mode 100644 .antora/modules/gen/doxynav.adoc diff --git a/.antora/modules/gen/doxynav.adoc b/.antora/modules/gen/doxynav.adoc new file mode 100644 index 000000000..e69de29bb diff --git a/doc/architecture/architecture_overview.adoc b/doc/architecture/architecture_overview.adoc index 2ff070951..a3f7855f6 100644 --- a/doc/architecture/architecture_overview.adoc +++ b/doc/architecture/architecture_overview.adoc @@ -12,6 +12,7 @@ Top-level messages define the `GroundTruth` interface, the `SensorData` interfac The following figure shows the interfaces and models involved in modeling a sensor. +[#fig-open-simulation-interface-overview] .Open Simulation Interface overview image::{images_open_simulation_interface}/osi-context.png[1100] @@ -21,12 +22,14 @@ The `TrafficCommand` interface makes it possible to send commands to traffic par The `TrafficUpdate` interface makes it possible to receive the updated state from traffic participant models. The following figure shows the interfaces of a generic traffic participant. +[#fig-interface-traffic-participant] .Interface of a traffic participant image::{images_open_simulation_interface}/osi-traffic-participant-principle.png[1100] Traffic participant models may use other OSI interfaces internally, for example, to model autonomous vehicles. The following figure shows a more advanced use case for traffic participants. +[#fig-traffic-participant-sensor-models] .Traffic participant with sensor models, AD function, and dynamic model image::{images_open_simulation_interface}/osi-traffic-participant-advanced.png[1100] diff --git a/doc/architecture/traffic_participant.adoc b/doc/architecture/traffic_participant.adoc index f8340f0e2..9318ed632 100644 --- a/doc/architecture/traffic_participant.adoc +++ b/doc/architecture/traffic_participant.adoc @@ -19,12 +19,14 @@ The ego vehicle is therefore also a traffic participant. The following figure shows the interface of a traffic participant. +[#fig-interface-traffic-participant-2] .Interface of a traffic participant image::{images_open_simulation_interface}/osi-traffic-participant-principle.png[1100] Traffic participant models may use other OSI interfaces internally, for example, to model autonomous vehicles. The following figure shows a more advanced use case for traffic participants. +[#fig-traffic-participant-other-osi-interfaces] .Traffic participant using other OSI interfaces internally image::{images_open_simulation_interface}/osi-traffic-participant-advanced.png[1100] diff --git a/doc/usecases/modeling_traffic_participant.adoc b/doc/usecases/modeling_traffic_participant.adoc index cf880d34a..53352cec8 100644 --- a/doc/usecases/modeling_traffic_participant.adoc +++ b/doc/usecases/modeling_traffic_participant.adoc @@ -15,6 +15,7 @@ The traffic participants are co-simulated. The following figure shows a very simple use case. +[#fig-simple-traffic-participant] .Simple traffic participant image::{images_open_simulation_interface}/osi-traffic-participant-use-case-1.png[1100] @@ -23,6 +24,7 @@ The traffic participant's dynamics are included in the model if they exist. The following figure shows a traffic participant with separately modeled behavior and dynamics. +[#fig-traffic-participants-separate-dynamics] .Traffic participants with separate dynamics image::{images_open_simulation_interface}/osi-traffic-participant-use-case-2.png[1100] @@ -32,6 +34,7 @@ These must be handled with a different data description format. The following figure shows a more complex traffic participant. +[#fig-traffic-participant-sensor-models-2] .Traffic participant with sensor models, AD function, and dynamics model image::{images_open_simulation_interface}/osi-traffic-participant-use-case-3.png[1100] @@ -44,6 +47,7 @@ The loop to the environment simulation is closed via traffic update. The following figure shows a cooperative use case with both an AD function and a human driver. +[#fig-traffic-participant-ad-function-human-driver] .Traffic participant with an AD function and human driver image::{images_open_simulation_interface}/osi-traffic-participant-use-case-4.png[1100] diff --git a/doc/usecases/transforming_coordinate_systems.adoc b/doc/usecases/transforming_coordinate_systems.adoc index 92ac3d5e7..bee0c8aeb 100644 --- a/doc/usecases/transforming_coordinate_systems.adoc +++ b/doc/usecases/transforming_coordinate_systems.adoc @@ -105,4 +105,6 @@ The reference point of the vehicle is given by a vector in the global coordinate A vector pointing from the reference position of the vehicle to the center of the rear axle then yields the origin of the vehicle coordinate system. The mounting positions of the sensors and therefore the origins of the corresponding sensor coordinate systems are given with respect to the vehicle coordinate system. +[#fig-coordinate-systems-example] +.TODO title image::{images_open_simulation_interface}/osi_example_coordinate_systems.png[] \ No newline at end of file From d5f41f186a079add159bda1f539be3bd4b4a1c43 Mon Sep 17 00:00:00 2001 From: Philip Windecker Date: Wed, 7 Sep 2022 17:28:48 +0200 Subject: [PATCH 04/11] Added tab anchors Signed-off-by: Philip Windecker --- doc/architecture/trace_file_naming.adoc | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/architecture/trace_file_naming.adoc b/doc/architecture/trace_file_naming.adoc index 61bc74638..8b49fa776 100644 --- a/doc/architecture/trace_file_naming.adoc +++ b/doc/architecture/trace_file_naming.adoc @@ -35,6 +35,8 @@ Trace file contains `TrafficCommand` messages. Given an OSI trace file with the following information: +[#tab-example-osi-trace-file-information] +.Example OSI trace file information [cols="1,1"] |=== |Timestamp (ISO 8601) cite:[iso8601] From fdf6674b7388993276ec7628072ab20a6fa08f91 Mon Sep 17 00:00:00 2001 From: Philip Windecker Date: Thu, 8 Sep 2022 13:58:47 +0200 Subject: [PATCH 05/11] Fixed minor bugs and updated links to interface spec Signed-off-by: Philip Windecker --- doc/architecture/sensor_data.adoc | 2 +- doc/architecture/sensor_view.adoc | 2 +- doc/architecture/traffic_participant.adoc | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/architecture/sensor_data.adoc b/doc/architecture/sensor_data.adoc index 161e9fd2a..d25844619 100644 --- a/doc/architecture/sensor_data.adoc +++ b/doc/architecture/sensor_data.adoc @@ -4,7 +4,7 @@ ifndef::include-only-once[] :root-path: ../ include::{root-path}_config.adoc[] endif::[] -sw + `SensorData` messages imitate the output of real sensors. They can be generated from `GroundTruth` messages, `SensorView` messages, `FeatureData` messages, or `SensorData` messages. With the exception of feature data, all information regarding the environment is given with respect to the virtual sensor coordinate system. diff --git a/doc/architecture/sensor_view.adoc b/doc/architecture/sensor_view.adoc index 673a3bbaf..b20797ff9 100644 --- a/doc/architecture/sensor_view.adoc +++ b/doc/architecture/sensor_view.adoc @@ -10,5 +10,5 @@ The sensor view provides the input to OSI sensor models. All information regarding the environment is given with respect to the virtual sensor coordinate system, with two exceptions: * Physical technology-specific data, given with respect to the physical sensor coordinate system specified in the corresponding physical sensor's mounting position. - One example of technology-specific data is: https://opensimulationinterface.github.io/open-simulation-interface/structosi3_1_1CameraSensorView.html#ac58456a34babf78792ea2608eb963f36[`image_data` of `osi3::CameraSensorView`] + One example of technology-specific data is: xref:gen:structosi3_1_1CameraSensorView.adoc#ac58456a34babf78792ea2608eb963f36[`image_data` of `osi3::CameraSensorView`] * Ground truth given in the global coordinate system. \ No newline at end of file diff --git a/doc/architecture/traffic_participant.adoc b/doc/architecture/traffic_participant.adoc index 9318ed632..aee5524e3 100644 --- a/doc/architecture/traffic_participant.adoc +++ b/doc/architecture/traffic_participant.adoc @@ -8,7 +8,7 @@ endif::[] A traffic participant is an element of the simulated world and can change its state during simulation time, for example, its position and orientation. A traffic participant represents one of the following: -- Living being. +- Living being - Means of transportation for living beings - Means of transportation for goods - Any other movable object that may travel on the road network From 86b2b1eee4a3dac6275436985946fbc03018f3f4 Mon Sep 17 00:00:00 2001 From: Philip Windecker Date: Thu, 8 Sep 2022 14:41:44 +0200 Subject: [PATCH 06/11] Updated feedback button behavior Signed-off-by: Philip Windecker --- doc/_config.adoc | 1 + doc/architecture/architecture_overview.adoc | 3 +-- doc/architecture/data_layer.adoc | 3 +-- doc/architecture/environmental_effect_model.adoc | 3 +-- doc/architecture/feature_data.adoc | 3 +-- doc/architecture/formatting_scripts.adoc | 3 +-- doc/architecture/ground_truth.adoc | 3 +-- doc/architecture/logical_model.adoc | 3 +-- doc/architecture/packaging_layer.adoc | 3 +-- doc/architecture/proto-files.adoc | 3 +-- doc/architecture/reference_points_coordinate_systems.adoc | 3 +-- doc/architecture/sensor_data.adoc | 3 +-- doc/architecture/sensor_model.adoc | 3 +-- doc/architecture/sensor_view.adoc | 3 +-- doc/architecture/sensor_view_configuration.adoc | 3 +-- doc/architecture/test_scripts.adoc | 3 +-- doc/architecture/trace_file_formats.adoc | 5 ++--- doc/architecture/trace_file_naming.adoc | 3 +-- doc/architecture/traffic_command.adoc | 4 +--- doc/architecture/traffic_participant.adoc | 3 +-- doc/architecture/traffic_update.adoc | 3 +-- doc/architecture/vehicle_dynamics.adoc | 3 +-- doc/misc/osi_vision.adoc | 3 +-- doc/setup/including_osi_dev_projects.adoc | 3 +-- doc/setup/installing_linux_cpp.adoc | 3 +-- doc/setup/installing_linux_python.adoc | 3 +-- doc/setup/installing_macos.adoc | 3 +-- doc/setup/installing_windows_cpp.adoc | 3 +-- doc/setup/installing_windows_python.adoc | 3 +-- doc/setup/using_osi_support_tools.adoc | 3 +-- doc/usecases/benchmark_integration_gpu_radar.adoc | 3 +-- doc/usecases/fusing_sensor_outputs.adoc | 3 +-- doc/usecases/generating_osi_traces.adoc | 3 +-- doc/usecases/injecting_faults.adoc | 3 +-- doc/usecases/modeling_camera_electronics.adoc | 3 +-- doc/usecases/modeling_lidar_sensor.adoc | 3 +-- doc/usecases/modeling_traffic_participant.adoc | 3 +-- doc/usecases/transforming_coordinate_systems.adoc | 3 +-- 38 files changed, 39 insertions(+), 76 deletions(-) diff --git a/doc/_config.adoc b/doc/_config.adoc index c64098bf2..e046f24ad 100644 --- a/doc/_config.adoc +++ b/doc/_config.adoc @@ -8,6 +8,7 @@ ifndef::root-path[:root-path: ./] :partials-path: {root-path}../_additional_content :asciidoc-resources: ../asciidoc-resources :appendix-caption: Annex +:page-feedbackurl: https://github.com/OpenSimulationInterface/open-simulation-interface/issues/new // ifndef::use-antora-rules,include-only-once[] ifndef::include-only-once[] diff --git a/doc/architecture/architecture_overview.adoc b/doc/architecture/architecture_overview.adoc index a3f7855f6..498427b40 100644 --- a/doc/architecture/architecture_overview.adoc +++ b/doc/architecture/architecture_overview.adoc @@ -1,9 +1,8 @@ -= Overview of OSI architecture - ifndef::include-only-once[] :root-path: ../ include::{root-path}_config.adoc[] endif::[] += Overview of OSI architecture OSI contains an object-based environment description that uses the message format of the https://github.com/protocolbuffers/protobuf/wiki[Protocol Buffer] library. Google developed and maintains the Protocol Buffer library. diff --git a/doc/architecture/data_layer.adoc b/doc/architecture/data_layer.adoc index c23067af3..e624015a1 100644 --- a/doc/architecture/data_layer.adoc +++ b/doc/architecture/data_layer.adoc @@ -1,9 +1,8 @@ -= Data layer - ifndef::include-only-once[] :root-path: ../ include::{root-path}_config.adoc[] endif::[] += Data layer The OSI data layer is defined in the message specifications using the ProtoBuf IDL cite:[protobuf]. This defines the data that can be transmitted using OSI, including the structure and the semantics of the data. diff --git a/doc/architecture/environmental_effect_model.adoc b/doc/architecture/environmental_effect_model.adoc index 1c5050eff..03c341455 100644 --- a/doc/architecture/environmental_effect_model.adoc +++ b/doc/architecture/environmental_effect_model.adoc @@ -1,9 +1,8 @@ -= Environmental effect model - ifndef::include-only-once[] :root-path: ../ include::{root-path}_config.adoc[] endif::[] += Environmental effect model Environmental effect models consume `SensorView` messages and produce `SensorView` messages. Environmental effect models may, for example, alter `SensorView` messages to include effects and phenomena caused by: diff --git a/doc/architecture/feature_data.adoc b/doc/architecture/feature_data.adoc index 70743ba08..f6ebf271f 100644 --- a/doc/architecture/feature_data.adoc +++ b/doc/architecture/feature_data.adoc @@ -1,9 +1,8 @@ -= Feature data - ifndef::include-only-once[] :root-path: ../ include::{root-path}_config.adoc[] endif::[] += Feature data `FeatureData` messages contain detected features in the reference frame of a sensor. `FeatureData` messages are generated from `GroundTruth` messages. diff --git a/doc/architecture/formatting_scripts.adoc b/doc/architecture/formatting_scripts.adoc index e226bd577..9b1a26857 100644 --- a/doc/architecture/formatting_scripts.adoc +++ b/doc/architecture/formatting_scripts.adoc @@ -1,9 +1,8 @@ -= Trace-file formatting scripts - ifndef::include-only-once[] :root-path: ../ include::{root-path}_config.adoc[] endif::[] += Trace-file formatting scripts The OSI repository contains Python scripts for converting trace files from one format to another. The formatting scripts are stored in `open-simulation-interface/format/` diff --git a/doc/architecture/ground_truth.adoc b/doc/architecture/ground_truth.adoc index d54d2d843..512387778 100644 --- a/doc/architecture/ground_truth.adoc +++ b/doc/architecture/ground_truth.adoc @@ -1,9 +1,8 @@ -= Ground truth - ifndef::include-only-once[] :root-path: ../ include::{root-path}_config.adoc[] endif::[] += Ground truth `GroundTruth` messages describe the simulated environment containing all simulated objects in the global coordinate system at consecutive time instances. They are based on data available to the simulation environment. diff --git a/doc/architecture/logical_model.adoc b/doc/architecture/logical_model.adoc index c694f2214..902403684 100644 --- a/doc/architecture/logical_model.adoc +++ b/doc/architecture/logical_model.adoc @@ -1,9 +1,8 @@ -= Logical model - ifndef::include-only-once[] :root-path: ../ include::{root-path}_config.adoc[] endif::[] += Logical model Logical models consume `SensorData` messages and produce `SensorData` messages. diff --git a/doc/architecture/packaging_layer.adoc b/doc/architecture/packaging_layer.adoc index ba29622f2..ef0687859 100644 --- a/doc/architecture/packaging_layer.adoc +++ b/doc/architecture/packaging_layer.adoc @@ -1,9 +1,8 @@ -= Packaging layer - ifndef::include-only-once[] :root-path: ../ include::{root-path}_config.adoc[] endif::[] += Packaging layer The OSI packaging layer specifies how components that use the OSI data layer, for example, sensor models, are packaged for exchange. diff --git a/doc/architecture/proto-files.adoc b/doc/architecture/proto-files.adoc index 2c638a259..9bb8ab133 100644 --- a/doc/architecture/proto-files.adoc +++ b/doc/architecture/proto-files.adoc @@ -1,9 +1,8 @@ -= Protobuffer files - ifndef::include-only-once[] :root-path: ../ include::{root-path}_config.adoc[] endif::[] += Protobuffer files TODO: Add general description. diff --git a/doc/architecture/reference_points_coordinate_systems.adoc b/doc/architecture/reference_points_coordinate_systems.adoc index d66b9208c..4e845281a 100644 --- a/doc/architecture/reference_points_coordinate_systems.adoc +++ b/doc/architecture/reference_points_coordinate_systems.adoc @@ -1,9 +1,8 @@ -= Coordinate systems, reference points and coordinate transformation - ifndef::include-only-once[] :root-path: ../ include::{root-path}_config.adoc[] endif::[] += Coordinate systems, reference points and coordinate transformation OSI uses DIN ISO 8855:2013-11 cite:[iso8855] for coordinate systems and transformations between coordinate systems. OSI uses three coordinate systems: diff --git a/doc/architecture/sensor_data.adoc b/doc/architecture/sensor_data.adoc index d25844619..f06383960 100644 --- a/doc/architecture/sensor_data.adoc +++ b/doc/architecture/sensor_data.adoc @@ -1,9 +1,8 @@ -= Sensor data - ifndef::include-only-once[] :root-path: ../ include::{root-path}_config.adoc[] endif::[] += Sensor data `SensorData` messages imitate the output of real sensors. They can be generated from `GroundTruth` messages, `SensorView` messages, `FeatureData` messages, or `SensorData` messages. diff --git a/doc/architecture/sensor_model.adoc b/doc/architecture/sensor_model.adoc index 27cbb49df..bf55655e1 100644 --- a/doc/architecture/sensor_model.adoc +++ b/doc/architecture/sensor_model.adoc @@ -1,9 +1,8 @@ -= Sensor model - ifndef::include-only-once[] :root-path: ../ include::{root-path}_config.adoc[] endif::[] += Sensor model Sensor models consume `SensorView` messages and produce `SensorData` messages. Sensor-model output does not represent raw data but detected features or classified objects. \ No newline at end of file diff --git a/doc/architecture/sensor_view.adoc b/doc/architecture/sensor_view.adoc index b20797ff9..adeb6254e 100644 --- a/doc/architecture/sensor_view.adoc +++ b/doc/architecture/sensor_view.adoc @@ -1,9 +1,8 @@ -= Sensor view - ifndef::include-only-once[] :root-path: ../ include::{root-path}_config.adoc[] endif::[] += Sensor view The sensor view provides the input to OSI sensor models. `SensorView` messages are derived from `GroundTruth` messages. diff --git a/doc/architecture/sensor_view_configuration.adoc b/doc/architecture/sensor_view_configuration.adoc index 113927d4b..09d0d5fb7 100644 --- a/doc/architecture/sensor_view_configuration.adoc +++ b/doc/architecture/sensor_view_configuration.adoc @@ -1,9 +1,8 @@ -= Sensor-view configuration - ifndef::include-only-once[] :root-path: ../ include::{root-path}_config.adoc[] endif::[] += Sensor-view configuration The sensor view is flexibly defined to provide different kinds of sensor models with an appropriate input. The sensor-view configuration defines the configuration of a particular sensor view. diff --git a/doc/architecture/test_scripts.adoc b/doc/architecture/test_scripts.adoc index 0ad665c37..354bea07a 100644 --- a/doc/architecture/test_scripts.adoc +++ b/doc/architecture/test_scripts.adoc @@ -1,9 +1,8 @@ -= Test scripts - ifndef::include-only-once[] :root-path: ../ include::{root-path}_config.adoc[] endif::[] += Test scripts TODO: Add general description. diff --git a/doc/architecture/trace_file_formats.adoc b/doc/architecture/trace_file_formats.adoc index 2f2d742a2..0ed0a4515 100644 --- a/doc/architecture/trace_file_formats.adoc +++ b/doc/architecture/trace_file_formats.adoc @@ -1,10 +1,9 @@ -[#top-osi_trace_file_formats] -= OSI trace file formats - ifndef::include-only-once[] :root-path: ../ include::{root-path}_config.adoc[] endif::[] +[#top-osi_trace_file_formats] += OSI trace file formats There are multiple formats for storing multiple serialized OSI messages in one trace file. diff --git a/doc/architecture/trace_file_naming.adoc b/doc/architecture/trace_file_naming.adoc index 8b49fa776..bbc892422 100644 --- a/doc/architecture/trace_file_naming.adoc +++ b/doc/architecture/trace_file_naming.adoc @@ -1,9 +1,8 @@ -= OSI trace file naming conventions - ifndef::include-only-once[] :root-path: ../ include::{root-path}_config.adoc[] endif::[] += OSI trace file naming conventions **Name format** diff --git a/doc/architecture/traffic_command.adoc b/doc/architecture/traffic_command.adoc index b69b635ac..f8cd90d24 100644 --- a/doc/architecture/traffic_command.adoc +++ b/doc/architecture/traffic_command.adoc @@ -1,9 +1,7 @@ -= Traffic command - ifndef::include-only-once[] :root-path: ../ include::{root-path}_config.adoc[] endif::[] - += Traffic command `TrafficCommand` messages contain control commands from the scenario engine to traffic participant models. \ No newline at end of file diff --git a/doc/architecture/traffic_participant.adoc b/doc/architecture/traffic_participant.adoc index aee5524e3..3418cc11f 100644 --- a/doc/architecture/traffic_participant.adoc +++ b/doc/architecture/traffic_participant.adoc @@ -1,9 +1,8 @@ -= Traffic participant - ifndef::include-only-once[] :root-path: ../ include::{root-path}_config.adoc[] endif::[] += Traffic participant A traffic participant is an element of the simulated world and can change its state during simulation time, for example, its position and orientation. A traffic participant represents one of the following: diff --git a/doc/architecture/traffic_update.adoc b/doc/architecture/traffic_update.adoc index ffdd34a54..33461d23d 100644 --- a/doc/architecture/traffic_update.adoc +++ b/doc/architecture/traffic_update.adoc @@ -1,9 +1,8 @@ -= Traffic update - ifndef::include-only-once[] :root-path: ../ include::{root-path}_config.adoc[] endif::[] += Traffic update `TrafficUpdate` messages are provided by traffic participants. They provide updates on the position, state, and future trajectory of a traffic participant back to the simulation environment. \ No newline at end of file diff --git a/doc/architecture/vehicle_dynamics.adoc b/doc/architecture/vehicle_dynamics.adoc index 97bf507b6..ee8a950a0 100644 --- a/doc/architecture/vehicle_dynamics.adoc +++ b/doc/architecture/vehicle_dynamics.adoc @@ -1,8 +1,7 @@ -= Vehicle dynamics - ifndef::include-only-once[] :root-path: ../ include::{root-path}_config.adoc[] endif::[] += Vehicle dynamics TODO: Content to be added in future release. diff --git a/doc/misc/osi_vision.adoc b/doc/misc/osi_vision.adoc index 018043d00..1bb239154 100644 --- a/doc/misc/osi_vision.adoc +++ b/doc/misc/osi_vision.adoc @@ -1,9 +1,8 @@ -= Idea behind Open Simulation Interface - ifndef::include-only-once[] :root-path: ../ include::{root-path}_config.adoc[] endif::[] += Idea behind Open Simulation Interface {THIS_STANDARD} Open Simulation Interface is a specification for interfaces between models and components of a distributed simulation. OSI is strongly focused on the environmental perception of automated driving functions. diff --git a/doc/setup/including_osi_dev_projects.adoc b/doc/setup/including_osi_dev_projects.adoc index cbfcc846d..7138417c8 100644 --- a/doc/setup/including_osi_dev_projects.adoc +++ b/doc/setup/including_osi_dev_projects.adoc @@ -1,9 +1,8 @@ -= Including OSI in development projects - ifndef::include-only-once[] :root-path: ../ include::{root-path}_config.adoc[] endif::[] += Including OSI in development projects TODO: Content to be added in future release. diff --git a/doc/setup/installing_linux_cpp.adoc b/doc/setup/installing_linux_cpp.adoc index b7d86891f..97050578d 100644 --- a/doc/setup/installing_linux_cpp.adoc +++ b/doc/setup/installing_linux_cpp.adoc @@ -1,9 +1,8 @@ -= Installing OSI for C++ on Linux - ifndef::include-only-once[] :root-path: ../ include::{root-path}_config.adoc[] endif::[] += Installing OSI for C++ on Linux **Prerequisites** diff --git a/doc/setup/installing_linux_python.adoc b/doc/setup/installing_linux_python.adoc index 4f10b2b79..771de0b20 100644 --- a/doc/setup/installing_linux_python.adoc +++ b/doc/setup/installing_linux_python.adoc @@ -1,9 +1,8 @@ -= Installing OSI for Python on Linux - ifndef::include-only-once[] :root-path: ../ include::{root-path}_config.adoc[] endif::[] += Installing OSI for Python on Linux **Prerequisites** diff --git a/doc/setup/installing_macos.adoc b/doc/setup/installing_macos.adoc index 09890545b..83d64609c 100644 --- a/doc/setup/installing_macos.adoc +++ b/doc/setup/installing_macos.adoc @@ -1,9 +1,8 @@ -= Installing OSI on MacOS - ifndef::include-only-once[] :root-path: ../ include::{root-path}_config.adoc[] endif::[] += Installing OSI on MacOS TODO: Content to be added in future release. diff --git a/doc/setup/installing_windows_cpp.adoc b/doc/setup/installing_windows_cpp.adoc index 728113eda..d14208544 100644 --- a/doc/setup/installing_windows_cpp.adoc +++ b/doc/setup/installing_windows_cpp.adoc @@ -1,9 +1,8 @@ -= Installing OSI for C++ on Windows - ifndef::include-only-once[] :root-path: ../ include::{root-path}_config.adoc[] endif::[] += Installing OSI for C++ on Windows **Prerequisites** diff --git a/doc/setup/installing_windows_python.adoc b/doc/setup/installing_windows_python.adoc index ee5f1771e..e48ccd1f8 100644 --- a/doc/setup/installing_windows_python.adoc +++ b/doc/setup/installing_windows_python.adoc @@ -1,9 +1,8 @@ -= Installing OSI for Python on Windows - ifndef::include-only-once[] :root-path: ../ include::{root-path}_config.adoc[] endif::[] += Installing OSI for Python on Windows **Prerequisites** diff --git a/doc/setup/using_osi_support_tools.adoc b/doc/setup/using_osi_support_tools.adoc index 062240c8f..829bf3d04 100644 --- a/doc/setup/using_osi_support_tools.adoc +++ b/doc/setup/using_osi_support_tools.adoc @@ -1,9 +1,8 @@ -= Using OSI supporting tools - ifndef::include-only-once[] :root-path: ../ include::{root-path}_config.adoc[] endif::[] += Using OSI supporting tools TODO: Content to be added in future release. diff --git a/doc/usecases/benchmark_integration_gpu_radar.adoc b/doc/usecases/benchmark_integration_gpu_radar.adoc index 2c6fead55..a60951458 100644 --- a/doc/usecases/benchmark_integration_gpu_radar.adoc +++ b/doc/usecases/benchmark_integration_gpu_radar.adoc @@ -1,9 +1,8 @@ -= Benchmarking and integration: OSI-GPU-radar - ifndef::include-only-once[] :root-path: ../ include::{root-path}_config.adoc[] endif::[] += Benchmarking and integration: OSI-GPU-radar TODO: Content to be added in future release. TODO: Clarify content of this use case and make title more clear diff --git a/doc/usecases/fusing_sensor_outputs.adoc b/doc/usecases/fusing_sensor_outputs.adoc index 67e2f7bd1..5c8636323 100644 --- a/doc/usecases/fusing_sensor_outputs.adoc +++ b/doc/usecases/fusing_sensor_outputs.adoc @@ -1,9 +1,8 @@ -= Fusing sensor outputs - ifndef::include-only-once[] :root-path: ../ include::{root-path}_config.adoc[] endif::[] += Fusing sensor outputs TODO: Content to be added in future release. diff --git a/doc/usecases/generating_osi_traces.adoc b/doc/usecases/generating_osi_traces.adoc index a725047e5..2e0037ace 100644 --- a/doc/usecases/generating_osi_traces.adoc +++ b/doc/usecases/generating_osi_traces.adoc @@ -1,9 +1,8 @@ -= Generating OSI traces - ifndef::include-only-once[] :root-path: ../ include::{root-path}_config.adoc[] endif::[] += Generating OSI traces TODO: Content to be added in future release. diff --git a/doc/usecases/injecting_faults.adoc b/doc/usecases/injecting_faults.adoc index 3a7b97d6c..dce6ca97a 100644 --- a/doc/usecases/injecting_faults.adoc +++ b/doc/usecases/injecting_faults.adoc @@ -1,9 +1,8 @@ -= Injecting faults - ifndef::include-only-once[] :root-path: ../ include::{root-path}_config.adoc[] endif::[] += Injecting faults TODO: Content to be added in future release. diff --git a/doc/usecases/modeling_camera_electronics.adoc b/doc/usecases/modeling_camera_electronics.adoc index 05bb6ed37..ab7d8d4f3 100644 --- a/doc/usecases/modeling_camera_electronics.adoc +++ b/doc/usecases/modeling_camera_electronics.adoc @@ -1,9 +1,8 @@ -= Modeling camera electronics - ifndef::include-only-once[] :root-path: ../ include::{root-path}_config.adoc[] endif::[] += Modeling camera electronics TODO: Content to be added in future release. diff --git a/doc/usecases/modeling_lidar_sensor.adoc b/doc/usecases/modeling_lidar_sensor.adoc index 78dfe6f7b..fadba71d6 100644 --- a/doc/usecases/modeling_lidar_sensor.adoc +++ b/doc/usecases/modeling_lidar_sensor.adoc @@ -1,9 +1,8 @@ -= Modeling a LIDAR sensor - ifndef::include-only-once[] :root-path: ../ include::{root-path}_config.adoc[] endif::[] += Modeling a LIDAR sensor // TODO: Add extensive description of this use case. diff --git a/doc/usecases/modeling_traffic_participant.adoc b/doc/usecases/modeling_traffic_participant.adoc index 53352cec8..4754a85d3 100644 --- a/doc/usecases/modeling_traffic_participant.adoc +++ b/doc/usecases/modeling_traffic_participant.adoc @@ -1,9 +1,8 @@ -= Modeling a traffic participant - ifndef::include-only-once[] :root-path: ../ include::{root-path}_config.adoc[] endif::[] += Modeling a traffic participant Different models may be involved in modeling a traffic participant. In all the use cases, a simulator loads and interprets a scenario and a map prior to execution. diff --git a/doc/usecases/transforming_coordinate_systems.adoc b/doc/usecases/transforming_coordinate_systems.adoc index bee0c8aeb..98f2afc0b 100644 --- a/doc/usecases/transforming_coordinate_systems.adoc +++ b/doc/usecases/transforming_coordinate_systems.adoc @@ -1,9 +1,8 @@ -= Coordinate transformations - ifndef::include-only-once[] :root-path: ../ include::{root-path}_config.adoc[] endif::[] += Coordinate transformations == Vehicle and sensor coordinate systems From d2c72439f02f7c0bff832681f89ca70b02c5dc04 Mon Sep 17 00:00:00 2001 From: Philip Windecker Date: Fri, 9 Sep 2022 15:27:27 +0200 Subject: [PATCH 07/11] Updated README Signed-off-by: Philip Windecker --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 61746b18e..3cf3b7b48 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,8 @@ As the complexity of automated driving functions rapidly increases, the requirem For more information on OSI see the [official documentation](https://opensimulationinterface.github.io/osi-documentation/) or the [official reference documentation](https://opensimulationinterface.github.io/open-simulation-interface/) for defined protobuf messages. + + [1] Hanke, T., Hirsenkorn, N., van-Driesten, C., Garcia-Ramos, P., Schiementz, M., Schneider, S. & Biebl, E. (2017, February 03). *A generic interface for the environment perception of automated driving functions in virtual scenarios.* Retrieved January 25, 2020, from https://www.hot.ei.tum.de/forschung/automotive-veroeffentlichungen/ ## Usage From 08f0f24040991a4c421fe103b1b009ade3b53f5e Mon Sep 17 00:00:00 2001 From: Philip Windecker Date: Fri, 9 Sep 2022 15:42:11 +0200 Subject: [PATCH 08/11] Antora tagging Signed-off-by: Philip Windecker --- .antora/antora.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.antora/antora.yml b/.antora/antora.yml index 24a252841..1ee0a3eaa 100644 --- a/.antora/antora.yml +++ b/.antora/antora.yml @@ -3,6 +3,7 @@ name: asamosi version: # Update version number accordingly. This is the version for the main branch main: 'current' + v(*)-antora: V$1 v(*): V$1 V(*): V$1 # Update version number accordingly. This is the version for any other activated branch (branch must be added in the generator site.yml!). Schema = 0.0.x- (only works for branches starting with "feature/") From dd58dc840cf5ed893959ec1f5f574b880a788ef8 Mon Sep 17 00:00:00 2001 From: Philip Windecker Date: Fri, 9 Sep 2022 15:53:01 +0200 Subject: [PATCH 09/11] Unified versioning for repos Signed-off-by: Philip Windecker --- .antora/antora.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.antora/antora.yml b/.antora/antora.yml index 1ee0a3eaa..e091a6471 100644 --- a/.antora/antora.yml +++ b/.antora/antora.yml @@ -7,4 +7,4 @@ version: v(*): V$1 V(*): V$1 # Update version number accordingly. This is the version for any other activated branch (branch must be added in the generator site.yml!). Schema = 0.0.x- (only works for branches starting with "feature/") - (*): '3.6.0-$1' + (*): 'V3.6.0-$1' From 7019b45a2f9a9f16e0e9d3daacb126498ab274c9 Mon Sep 17 00:00:00 2001 From: Philip Windecker Date: Fri, 9 Sep 2022 16:39:09 +0200 Subject: [PATCH 10/11] Updated image link for asciidoc Signed-off-by: Philip Windecker --- doc/_config.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/_config.adoc b/doc/_config.adoc index e046f24ad..d022648fc 100644 --- a/doc/_config.adoc +++ b/doc/_config.adoc @@ -33,7 +33,7 @@ ifndef::include-only-once[] :reusedir: reuse :toclevels: 3 :xrefstyle: full -:images_open_simulation_interface: ./open-simulation-interface/doc/images +:images_open_simulation_interface: {imagesdir} // :images_osi-sensor-model-packaging: ./osi-sensor-model-packaging/doc/images :doc_open_simulation_interface: ../../open-simulation-interface/doc/ :doc_osi-sensor-model-packaging: ../../osi-sensor-model-packaging/doc/ From c3ca3c9d187ce198e64ff14ea83a30cd1da846a2 Mon Sep 17 00:00:00 2001 From: Philip Windecker Date: Thu, 15 Sep 2022 13:45:45 +0200 Subject: [PATCH 11/11] Updated pull request template Signed-off-by: Philip Windecker --- .github/pull_request_template.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 09f7c8370..b18379317 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -11,8 +11,8 @@ Is this a bug fix or a feature? Does it break any existing functionality or forc How has it been tested? #### Take this checklist as orientation for yourself, if this PR is ready for the Change Control Board: -- [ ] My suggestion follows the [style and contributors guidelines](https://opensimulationinterface.github.io/osi-documentation/open-simulation-interface/doc/howtocontribute.html). -- [ ] I have taken care about the [documentation](https://opensimulationinterface.github.io/osi-documentation/open-simulation-interface/doc/commenting.html). +- [ ] My suggestion follows the [style and contributors guidelines](https://opensimulationinterface.github.io/osi-antora-generator/asamosi/latest/specification/contributing/start_contributing.html). +- [ ] I have taken care about the [message documentation](https://opensimulationinterface.github.io/osi-antora-generator/asamosi/latest/specification/contributing/commenting_messages.html) and the [fields and enums documentation](https://opensimulationinterface.github.io/osi-antora-generator/asamosi/latest/specification/contributing/commenting_fields_enums.html). - [ ] I have done the [DCO signoff](https://opensimulationinterface.github.io/osi-documentation/open-simulation-interface/doc/howtocontribute.html#developer-certification-of-origin-dco). - [ ] My changes generate no errors when passing CI tests. - [ ] I have successfully implemented and tested my fix/feature locally.