├── .antora ├── antora.yml └── modules │ └── specification │ ├── images │ ├── nav_contribution.adoc │ ├── nav_introduction.adoc │ ├── nav_loft.adoc │ └── pages ├── .github ├── ISSUE_TEMPLATE │ ├── bug_report.md │ ├── feature_request.md │ └── question.md ├── pull_request_template.md └── workflows │ ├── antora-build.yml │ ├── asciidoc-build.yml │ └── remote_release.yml ├── .gitignore ├── .gitmodules ├── LICENSE ├── README.adoc ├── content ├── _config.adoc ├── _static │ └── images │ │ ├── osi-context.png │ │ ├── osi-traffic-participant-advanced.png │ │ ├── osi-traffic-participant-principle.png │ │ ├── osi-traffic-participant-use-case-1.png │ │ ├── osi-traffic-participant-use-case-2.png │ │ ├── osi-traffic-participant-use-case-3.png │ │ ├── osi-traffic-participant-use-case-4.png │ │ └── osilogo.png ├── appendix │ └── releases │ │ ├── compatibility.adoc │ │ ├── v02.00.adoc │ │ ├── v02.01.adoc │ │ ├── v02.02.00.adoc │ │ ├── v02.02.01.adoc │ │ ├── v03.00.00.adoc │ │ ├── v03.00.01.adoc │ │ ├── v03.01.00.adoc │ │ ├── v03.01.01.adoc │ │ ├── v03.01.02.adoc │ │ ├── v03.02.adoc │ │ ├── v03.03.00.adoc │ │ ├── v03.03.01.adoc │ │ ├── v03.04.adoc │ │ ├── v03.05.adoc │ │ ├── v03.06.adoc │ │ └── v03.07.adoc ├── contributing │ ├── branching_member.adoc │ ├── commenting_fields_enums.adoc │ ├── commenting_messages.adoc │ ├── contributing_docs.adoc │ ├── contribution_rules.adoc │ ├── creating_images.adoc │ ├── creating_references.adoc │ ├── dco.adoc │ ├── forking_no_member.adoc │ ├── licensing.adoc │ ├── naming_conventions.adoc │ ├── reporting_issues.adoc │ ├── review_author.adoc │ ├── review_reviewer.adoc │ ├── signing_off_commits.adoc │ ├── start_contributing.adoc │ ├── test_scripts.adoc │ └── writing_commit_messages.adoc ├── general_docs │ ├── bibliography.adoc │ ├── bibliography.bib │ ├── changes.adoc │ ├── conventions.adoc │ ├── deliverables.adoc │ ├── foreword.adoc │ ├── glossary.adoc │ ├── osi_repos.adoc │ ├── statements.adoc │ └── versioning.adoc ├── general_standard │ └── relations_to_other_standards.adoc └── index.adoc ├── docker-compose.yml ├── local_build_tools ├── asciidoctor.bat ├── compose.yml └── windows_convert_symlinks(ADMIN).bat └── spelling ├── abbreviations.txt ├── file_endings.txt ├── file_names.txt ├── function_names.txt ├── general_names.txt ├── human_names.txt └── spelling_wordlist.txt /.antora/antora.yml: -------------------------------------------------------------------------------- 1 | # Component name (without spaces!). All content repositories with the same component name are merged in Antora. 2 | name: asamosi 3 | # CENTRAL DOCUMENT ONLY!!! Display name of the component. Define only once per component! 4 | title: ASAM OSI 5 | version: 6 | # Update version number accordingly. This is the version for the main branch 7 | main: 'current' 8 | master: 'current' 9 | v(*)-antora: V$1 10 | x-antora-v(*): V$1 11 | v(*): V$1 12 | V(*): V$1 13 | # 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/") 14 | (*): 'V3.6.0-$1' 15 | # CENTRAL DOCUMENT ONLY!!! First page of the component. Define only once per component! 16 | start_page: specification:index.adoc 17 | 18 | # THE FOLLOWING MAY ONLY DEFINED FOR THE CENTRAL DOCUMENT!!! 19 | asciidoc: # Sets global AsciiDoc attributes that are applied for every page of this component (from all repositories with the same version and component name!) 20 | attributes: 21 | # START - Mandatory ASAM attributes 22 | use-antora-rules: true 23 | THIS_STANDARD: ASAM OSI® # Normal attribute 24 | THIS_STANDARD_TITLE: 'ASAM OSI^®^' # Normal attribute 25 | # THIS_STANDARD: ASAM OSI # PDF version attribute 26 | # THIS_STANDARD_TITLE: 'ASAM OSI' # PDF version attribute 27 | partials-path: partial$ 28 | root-path: page$ 29 | appendix-caption: Annex 30 | # appendix-offset: 1 31 | asam-terminology: v0.0.1@ASAM_Terminology:ROOT:partial$terms_and_definitions_opendrive.adoc 32 | topicdir: topics 33 | reusedir: reuse 34 | imagesoutdir: ./images/generated_images 35 | images_open_simulation_interface: 'interface:' 36 | doc_open_simulation_interface: 'interface:' 37 | doc_osi-sensor-model-packaging: 'sensor-model:' 38 | page-repository-links: [["https://github.com/OpenSimulationInterface/open-simulation-interface", "Open Simulation Interface"],["https://github.com/OpenSimulationInterface/osi-sensor-model-packaging","OSI Sensor Model Packaging"],["https://github.com/OpenSimulationInterface/osi-validation","OSI Validation"]] 39 | asamBibliography: 'specification:general_docs/bibliography.bib' 40 | 41 | # END - Mandatory ASAM attributes 42 | # doxygen_interface_version: "v3.2.0" # The interface version that needs to be retrieved 43 | # doxygen_document_date: "01.01.2000" # The date associated with the document (optional) 44 | doxygen_module: "gen" # The module in which the output is stored 45 | # doxygen_module_path: "gen" # Path within module 46 | doxygen_source_repo: "https://github.com/OpenSimulationInterface/open-simulation-interface.git" 47 | # doxygen_source_folder: open-simulation-interface 48 | 49 | nav: 50 | - modules/specification/nav_introduction.adoc 51 | - modules/interface/nav.adoc 52 | - modules/sensor-model/nav.adoc 53 | - modules/specification/nav_contribution.adoc 54 | - modules/gen/doxynav.adoc 55 | - modules/specification/nav_loft.adoc 56 | # Add more items here as required. 57 | # Recommended: One navigation file per document/repository! 58 | # Recommended: Name your module (folder) as your document type, e.g. "standard" or "concept" or "topic-guidelines" 59 | # Format: - modules//.adoc 60 | -------------------------------------------------------------------------------- /.antora/modules/specification/images: -------------------------------------------------------------------------------- 1 | ../../../content/_static/images -------------------------------------------------------------------------------- /.antora/modules/specification/nav_contribution.adoc: -------------------------------------------------------------------------------- 1 | * Contributing to ASAM OSI 2 | 3 | ** xref:contributing/start_contributing.adoc[] 4 | 5 | ** xref:contributing/reporting_issues.adoc[] 6 | 7 | ** Contributing changes 8 | 9 | *** xref:contributing/licensing.adoc[] 10 | 11 | *** xref:contributing/dco.adoc[] 12 | 13 | *** xref:contributing/signing_off_commits.adoc[] 14 | 15 | *** xref:contributing/writing_commit_messages.adoc[] 16 | 17 | *** xref:contributing/contribution_rules.adoc[] 18 | 19 | *** xref:contributing/naming_conventions.adoc[] 20 | 21 | *** xref:contributing/branching_member.adoc[] 22 | 23 | *** xref:contributing/forking_no_member.adoc[] 24 | 25 | // *** xref:contributing/contributing_docs.adoc[] 26 | 27 | *** xref:contributing/commenting_messages.adoc[] 28 | 29 | *** xref:contributing/commenting_fields_enums.adoc[] 30 | 31 | *** xref:contributing/creating_references.adoc[] 32 | 33 | // *** xref:contributing/creating_images.adoc[] 34 | 35 | ** xref:contributing/test_scripts.adoc[] 36 | 37 | ** Reviewing contributions 38 | 39 | *** xref:contributing/review_author.adoc[] 40 | 41 | *** xref:contributing/review_reviewer.adoc[] 42 | 43 | [glossary] 44 | * xref:general_docs/glossary.adoc[] 45 | 46 | 47 | [bibliography] 48 | * xref:general_docs/bibliography.adoc[] 49 | 50 | [appendix] 51 | * Release Notes 52 | 53 | :sectnums!: 54 | ** xref:appendix/releases/v03.07.adoc[] 55 | :sectnums!: 56 | ** xref:appendix/releases/v03.06.adoc[] 57 | :sectnums!: 58 | ** xref:appendix/releases/v03.05.adoc[] 59 | :sectnums!: 60 | ** xref:appendix/releases/v03.04.adoc[] 61 | :sectnums!: 62 | ** xref:appendix/releases/v03.03.01.adoc[] 63 | :sectnums!: 64 | ** xref:appendix/releases/v03.03.00.adoc[] 65 | :sectnums!: 66 | ** xref:appendix/releases/v03.02.adoc[] 67 | :sectnums!: 68 | ** xref:appendix/releases/v03.01.02.adoc[] 69 | :sectnums!: 70 | ** xref:appendix/releases/v03.01.01.adoc[] 71 | :sectnums!: 72 | ** xref:appendix/releases/v03.01.00.adoc[] 73 | :sectnums!: 74 | ** xref:appendix/releases/v03.00.01.adoc[] 75 | :sectnums!: 76 | ** xref:appendix/releases/v03.00.00.adoc[] 77 | :sectnums!: 78 | ** xref:appendix/releases/v02.02.01.adoc[] 79 | :sectnums!: 80 | ** xref:appendix/releases/v02.02.00.adoc[] 81 | :sectnums!: 82 | ** xref:appendix/releases/v02.01.adoc[] 83 | :sectnums!: 84 | ** xref:appendix/releases/v02.00.adoc[] 85 | -------------------------------------------------------------------------------- /.antora/modules/specification/nav_introduction.adoc: -------------------------------------------------------------------------------- 1 | 2 | * Introduction 3 | ** xref:general_docs/changes.adoc[] 4 | ** xref:general_docs/deliverables.adoc[] 5 | ** xref:general_docs/osi_repos.adoc[] 6 | ** xref:general_docs/statements.adoc[] 7 | ** xref:general_docs/conventions.adoc[] 8 | ** xref:general_docs/versioning.adoc[] 9 | ** xref:general_standard/relations_to_other_standards.adoc[] 10 | -------------------------------------------------------------------------------- /.antora/modules/specification/nav_loft.adoc: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OpenSimulationInterface/osi-documentation/9882f2229dc0a22e328ef3264896a6d287d69189/.antora/modules/specification/nav_loft.adoc -------------------------------------------------------------------------------- /.antora/modules/specification/pages: -------------------------------------------------------------------------------- 1 | ../../../content -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/bug_report.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Bug report 3 | about: Create a report to help us improve 4 | title: '' 5 | labels: bug 6 | assignees: '' 7 | 8 | --- 9 | 10 | #### Describe the bug 11 | A clear and concise description of what the bug is. 12 | 13 | #### Describe how to reproduce the bug 14 | Steps to reproduce the behavior: 15 | 1. Go to '...' 16 | 2. Click on '....' 17 | 3. Scroll down to '....' 18 | 4. See error 19 | 20 | #### Describe the expected behavior 21 | A clear and concise description of what you expected to happen. 22 | 23 | #### Show some screenshots 24 | If applicable, add screenshots to help explain your problem. 25 | 26 | #### Describe the OS you are using 27 | - OS: [e.g. iOS, Ubuntu 18.04, Windows 10, ...] 28 | - Browser: [Chrome, Opera. Firefox, ...] 29 | - Language: [e.g. C++, Python, ...] 30 | - Version [e.g. 3.6.8] 31 | 32 | #### Additional context 33 | Add any other context about the bug here. 34 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/feature_request.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Feature request 3 | about: Suggest an idea for this project 4 | title: '' 5 | labels: feature request 6 | assignees: '' 7 | 8 | --- 9 | 10 | #### Describe the feature 11 | Is your feature request related to a problem with the documentation? 12 | A clear and concise description of what the problem is. 13 | Example: I am always frustrated when [...]. 14 | 15 | #### Describe the solution you would like 16 | A clear and concise description of what you want to happen. 17 | 18 | #### Describe alternatives you have considered 19 | A clear and concise description of any alternative solutions or features you have considered. 20 | 21 | #### Additional context 22 | Add any other context or screenshots about the feature request here. 23 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/question.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Question 3 | about: Ask a question if you do not understand something or just want clarifications. 4 | title: '' 5 | labels: question 6 | assignees: '' 7 | 8 | --- 9 | 10 | #### Describe the problem 11 | I want to do ... in my application, but what I am actually getting is.... 12 | Here is a screenshot that illustrates the problem: 13 | 14 | `image.png` 15 | 16 | #### Describe what you have already tried 17 | This is the most simplified version of my code that I have been able to get, which still produces the problem I described above. 18 | 19 | // my code 20 | ... 21 | 22 | Basically, what the code is doing is.... 23 | Changing ... does not work because it gives the following error: 24 | 25 | 26 | Some error 27 | 28 | 29 | #### Describe your research 30 | [The documentation here] mentioned ... but did not provide a clear example of how that is done. 31 | [This Stack Overflow question] describes a similar problem, but mine is different because.... 32 | 33 | #### Ask your question 34 | So my basic question is, how do I...? 35 | 36 | #### Additional context 37 | Add any other context or screenshots about the question here. 38 | -------------------------------------------------------------------------------- /.github/pull_request_template.md: -------------------------------------------------------------------------------- 1 | #### Reference to a related issue in the repository 2 | Add a reference to a related issue in the repository or the OSI organization. 3 | 4 | #### Add a description 5 | Add a description of the changes proposed in the pull request. 6 | 7 | **Some questions to ask**: 8 | What is this change? 9 | What does it fix? 10 | Is this a bug fix or a feature? Does it break any existing functionality or force me to update to a new version? 11 | How has it been tested? 12 | 13 | #### Mention a member 14 | Add @mentions of the person or team responsible for reviewing proposed changes. 15 | 16 | #### Check the checklist 17 | 18 | - [ ] I have performed a self-review of my own code/documentation. 19 | - [ ] My documentation changes are related to another repository in the organization. Here is the link to the issue/repo. 20 | - [ ] My changes generate no new warnings during the documentation generation. 21 | - [ ] The existing travis ci which pushes the documentation to gh-pages passes with my changes. -------------------------------------------------------------------------------- /.github/workflows/antora-build.yml: -------------------------------------------------------------------------------- 1 | name: Antora Documentation Build 2 | 3 | on: 4 | push: 5 | branches: [ master ] 6 | pull_request: 7 | branches: [ master ] 8 | 9 | jobs: 10 | trigger_antora: 11 | name: Trigger antora generator 12 | 13 | runs-on: Ubuntu-latest 14 | 15 | env: 16 | MUP_KEY: ${{ secrets.MACHINE_USER_PAT }} 17 | 18 | steps: 19 | - name: Trigger generator 20 | if: ${{ env.MUP_KEY != '' }} 21 | uses: peter-evans/repository-dispatch@v3 22 | with: 23 | token: ${{ secrets.MACHINE_USER_PAT }} 24 | event-type: antora-build-trigger 25 | repository: OpenSimulationInterface/osi-antora-generator 26 | client-payload: '{"src": "${{ github.repository }}", "ref": "${{ github.ref }}", "sha": "${{ github.sha }}", "head_ref": "${{ github.head_ref }}"}' 27 | 28 | -------------------------------------------------------------------------------- /.github/workflows/asciidoc-build.yml: -------------------------------------------------------------------------------- 1 | name: AsciiDoc Documentation Build 2 | 3 | on: 4 | create: # new branches or tags 5 | release: # new releases 6 | pull_request: 7 | branches: [ master ] 8 | push: # on push. This may be removed later 9 | schedule: # periodic - needed because some of the content is from the other repos 10 | - cron: '30 5,20 * * *' # this is pretty often. Only needed during review phase 11 | 12 | jobs: 13 | asciidoctor-build: 14 | name: Run Asciidoctor on Documentation 15 | 16 | runs-on: ubuntu-22.04 17 | 18 | steps: 19 | # Checkout osi documentation 20 | - name: Checkout osi-documentation 21 | uses: actions/checkout@v2 22 | with: 23 | submodules: true 24 | fetch-depth: 0 25 | 26 | # Checkout all other OSI repositories with branch "migration" and nested into osi-documentation 27 | - name: Checkout open-simulation-interface 28 | uses: actions/checkout@v2 29 | with: 30 | repository: OpenSimulationInterface/open-simulation-interface 31 | path: content/open-simulation-interface 32 | fetch-depth: 0 33 | 34 | 35 | - name: Checkout OSI Sensor Model Packaging 36 | uses: actions/checkout@v2 37 | with: 38 | repository: OpenSimulationInterface/osi-sensor-model-packaging 39 | path: content/osi-sensor-model-packaging 40 | 41 | - name: Checkout proto2cpp 42 | uses: actions/checkout@v2 43 | with: 44 | repository: OpenSimulationInterface/proto2cpp 45 | path: proto2cpp 46 | 47 | # Versioning 48 | - name: Get versioning 49 | id: get_version 50 | working-directory: content/open-simulation-interface 51 | run: echo ::set-output name=VERSION::$(git describe --always) 52 | 53 | # replaces the placeholder for versioning in the main mapping file 54 | - name: Apply versioning to Adoc 55 | run: | 56 | grep ":revnumber:" content/_config.adoc 57 | sed -i -e "s/--localbuild--/main (${{ steps.get_version.outputs.VERSION }})/" content/_config.adoc 58 | grep ":revnumber:" content/_config.adoc 59 | 60 | - name: Remove docdate for online hosted document 61 | run: sed 's/^:revdate:.*/:!revdate:/' content/_config.adoc 62 | 63 | # run Asciidoctor 64 | - name: Build HTML 65 | uses: avattathil/asciidoctor-action@master 66 | with: 67 | program: "asciidoctor -D . --failure-level WARN -r asciidoctor-diagram -r asciidoctor-bibtex -a mathjax --trace --backend=html5 content/index.adoc -o open-simulation-interface_V${{ steps.get_version.outputs.VERSION }}.html" 68 | 69 | # Upload artifact. 70 | - name: Upload HTML Artifact 71 | uses: actions/upload-artifact@v2 72 | if: ${{ github.event_name == 'pull_request' }} 73 | with: 74 | name: HTML document 75 | path: open-simulation-interface_V${{ steps.get_version.outputs.VERSION }}.html 76 | if-no-files-found: error 77 | 78 | # Publish the artifact when pipeline runs on master 79 | - name: rename file for deploy to gh-page 80 | if: ${{ github.ref == 'refs/heads/master' }} 81 | run: | 82 | mkdir html/ 83 | cp open-simulation-interface_V${{ steps.get_version.outputs.VERSION }}.html html/index.html 84 | 85 | - name: deploy to gh-pages if push to master branch 86 | if: ${{ github.ref == 'refs/heads/master' }} 87 | uses: peaceiris/actions-gh-pages@v3 88 | with: 89 | github_token: ${{ secrets.GITHUB_TOKEN }} 90 | publish_dir: ./html 91 | -------------------------------------------------------------------------------- /.github/workflows/remote_release.yml: -------------------------------------------------------------------------------- 1 | name: Remote Tagging 2 | 3 | on: 4 | repository_dispatch: 5 | types: [update-tag] 6 | 7 | permissions: 8 | contents: write 9 | repository-projects: write 10 | 11 | jobs: 12 | submodule: 13 | name: Update submodule and create tag 14 | runs-on: Ubuntu-latest 15 | steps: 16 | - name: Checkout 17 | uses: actions/checkout@v3 18 | with: 19 | fetch-depth: 0 # otherwise, there would be errors pushing refs to the destination repository. 20 | 21 | - name: Create tag 22 | run: git tag ${{ github.event.client_payload.tag }} 23 | 24 | - name: GitHub Push 25 | uses: ad-m/github-push-action@v0.6.0 26 | with: 27 | # Token for the repo. Can be passed in using $\{{ secrets.GITHUB_TOKEN }} 28 | github_token: ${{ secrets.MACHINE_USER_PAT }} 29 | # Determines if --tags is used 30 | tags: true 31 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | vpython/ 2 | _build/ 3 | .vscode/ 4 | _templates/ 5 | local_build_tools/*.html -------------------------------------------------------------------------------- /.gitmodules: -------------------------------------------------------------------------------- 1 | [submodule "asciidoc-resources"] 2 | path = asciidoc-resources 3 | url = https://code.asam.net/common/style-resources.git 4 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Creative Commons Legal Code 2 | 3 | Attribution 3.0 Unported 4 | 5 | CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE 6 | LEGAL SERVICES. DISTRIBUTION OF THIS LICENSE DOES NOT CREATE AN 7 | ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS 8 | INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES 9 | REGARDING THE INFORMATION PROVIDED, AND DISCLAIMS LIABILITY FOR 10 | DAMAGES RESULTING FROM ITS USE. 11 | 12 | License 13 | 14 | THE WORK (AS DEFINED BELOW) IS PROVIDED UNDER THE TERMS OF THIS CREATIVE 15 | COMMONS PUBLIC LICENSE ("CCPL" OR "LICENSE"). THE WORK IS PROTECTED BY 16 | COPYRIGHT AND/OR OTHER APPLICABLE LAW. ANY USE OF THE WORK OTHER THAN AS 17 | AUTHORIZED UNDER THIS LICENSE OR COPYRIGHT LAW IS PROHIBITED. 18 | 19 | BY EXERCISING ANY RIGHTS TO THE WORK PROVIDED HERE, YOU ACCEPT AND AGREE 20 | TO BE BOUND BY THE TERMS OF THIS LICENSE. TO THE EXTENT THIS LICENSE MAY 21 | BE CONSIDERED TO BE A CONTRACT, THE LICENSOR GRANTS YOU THE RIGHTS 22 | CONTAINED HERE IN CONSIDERATION OF YOUR ACCEPTANCE OF SUCH TERMS AND 23 | CONDITIONS. 24 | 25 | 1. Definitions 26 | 27 | a. "Adaptation" means a work based upon the Work, or upon the Work and 28 | other pre-existing works, such as a translation, adaptation, 29 | derivative work, arrangement of music or other alterations of a 30 | literary or artistic work, or phonogram or performance and includes 31 | cinematographic adaptations or any other form in which the Work may be 32 | recast, transformed, or adapted including in any form recognizably 33 | derived from the original, except that a work that constitutes a 34 | Collection will not be considered an Adaptation for the purpose of 35 | this License. For the avoidance of doubt, where the Work is a musical 36 | work, performance or phonogram, the synchronization of the Work in 37 | timed-relation with a moving image ("synching") will be considered an 38 | Adaptation for the purpose of this License. 39 | b. "Collection" means a collection of literary or artistic works, such as 40 | encyclopedias and anthologies, or performances, phonograms or 41 | broadcasts, or other works or subject matter other than works listed 42 | in Section 1(f) below, which, by reason of the selection and 43 | arrangement of their contents, constitute intellectual creations, in 44 | which the Work is included in its entirety in unmodified form along 45 | with one or more other contributions, each constituting separate and 46 | independent works in themselves, which together are assembled into a 47 | collective whole. A work that constitutes a Collection will not be 48 | considered an Adaptation (as defined above) for the purposes of this 49 | License. 50 | c. "Distribute" means to make available to the public the original and 51 | copies of the Work or Adaptation, as appropriate, through sale or 52 | other transfer of ownership. 53 | d. "Licensor" means the individual, individuals, entity or entities that 54 | offer(s) the Work under the terms of this License. 55 | e. "Original Author" means, in the case of a literary or artistic work, 56 | the individual, individuals, entity or entities who created the Work 57 | or if no individual or entity can be identified, the publisher; and in 58 | addition (i) in the case of a performance the actors, singers, 59 | musicians, dancers, and other persons who act, sing, deliver, declaim, 60 | play in, interpret or otherwise perform literary or artistic works or 61 | expressions of folklore; (ii) in the case of a phonogram the producer 62 | being the person or legal entity who first fixes the sounds of a 63 | performance or other sounds; and, (iii) in the case of broadcasts, the 64 | organization that transmits the broadcast. 65 | f. "Work" means the literary and/or artistic work offered under the terms 66 | of this License including without limitation any production in the 67 | literary, scientific and artistic domain, whatever may be the mode or 68 | form of its expression including digital form, such as a book, 69 | pamphlet and other writing; a lecture, address, sermon or other work 70 | of the same nature; a dramatic or dramatico-musical work; a 71 | choreographic work or entertainment in dumb show; a musical 72 | composition with or without words; a cinematographic work to which are 73 | assimilated works expressed by a process analogous to cinematography; 74 | a work of drawing, painting, architecture, sculpture, engraving or 75 | lithography; a photographic work to which are assimilated works 76 | expressed by a process analogous to photography; a work of applied 77 | art; an illustration, map, plan, sketch or three-dimensional work 78 | relative to geography, topography, architecture or science; a 79 | performance; a broadcast; a phonogram; a compilation of data to the 80 | extent it is protected as a copyrightable work; or a work performed by 81 | a variety or circus performer to the extent it is not otherwise 82 | considered a literary or artistic work. 83 | g. "You" means an individual or entity exercising rights under this 84 | License who has not previously violated the terms of this License with 85 | respect to the Work, or who has received express permission from the 86 | Licensor to exercise rights under this License despite a previous 87 | violation. 88 | h. "Publicly Perform" means to perform public recitations of the Work and 89 | to communicate to the public those public recitations, by any means or 90 | process, including by wire or wireless means or public digital 91 | performances; to make available to the public Works in such a way that 92 | members of the public may access these Works from a place and at a 93 | place individually chosen by them; to perform the Work to the public 94 | by any means or process and the communication to the public of the 95 | performances of the Work, including by public digital performance; to 96 | broadcast and rebroadcast the Work by any means including signs, 97 | sounds or images. 98 | i. "Reproduce" means to make copies of the Work by any means including 99 | without limitation by sound or visual recordings and the right of 100 | fixation and reproducing fixations of the Work, including storage of a 101 | protected performance or phonogram in digital form or other electronic 102 | medium. 103 | 104 | 2. Fair Dealing Rights. Nothing in this License is intended to reduce, 105 | limit, or restrict any uses free from copyright or rights arising from 106 | limitations or exceptions that are provided for in connection with the 107 | copyright protection under copyright law or other applicable laws. 108 | 109 | 3. License Grant. Subject to the terms and conditions of this License, 110 | Licensor hereby grants You a worldwide, royalty-free, non-exclusive, 111 | perpetual (for the duration of the applicable copyright) license to 112 | exercise the rights in the Work as stated below: 113 | 114 | a. to Reproduce the Work, to incorporate the Work into one or more 115 | Collections, and to Reproduce the Work as incorporated in the 116 | Collections; 117 | b. to create and Reproduce Adaptations provided that any such Adaptation, 118 | including any translation in any medium, takes reasonable steps to 119 | clearly label, demarcate or otherwise identify that changes were made 120 | to the original Work. For example, a translation could be marked "The 121 | original work was translated from English to Spanish," or a 122 | modification could indicate "The original work has been modified."; 123 | c. to Distribute and Publicly Perform the Work including as incorporated 124 | in Collections; and, 125 | d. to Distribute and Publicly Perform Adaptations. 126 | e. For the avoidance of doubt: 127 | 128 | i. Non-waivable Compulsory License Schemes. In those jurisdictions in 129 | which the right to collect royalties through any statutory or 130 | compulsory licensing scheme cannot be waived, the Licensor 131 | reserves the exclusive right to collect such royalties for any 132 | exercise by You of the rights granted under this License; 133 | ii. Waivable Compulsory License Schemes. In those jurisdictions in 134 | which the right to collect royalties through any statutory or 135 | compulsory licensing scheme can be waived, the Licensor waives the 136 | exclusive right to collect such royalties for any exercise by You 137 | of the rights granted under this License; and, 138 | iii. Voluntary License Schemes. The Licensor waives the right to 139 | collect royalties, whether individually or, in the event that the 140 | Licensor is a member of a collecting society that administers 141 | voluntary licensing schemes, via that society, from any exercise 142 | by You of the rights granted under this License. 143 | 144 | The above rights may be exercised in all media and formats whether now 145 | known or hereafter devised. The above rights include the right to make 146 | such modifications as are technically necessary to exercise the rights in 147 | other media and formats. Subject to Section 8(f), all rights not expressly 148 | granted by Licensor are hereby reserved. 149 | 150 | 4. Restrictions. The license granted in Section 3 above is expressly made 151 | subject to and limited by the following restrictions: 152 | 153 | a. You may Distribute or Publicly Perform the Work only under the terms 154 | of this License. You must include a copy of, or the Uniform Resource 155 | Identifier (URI) for, this License with every copy of the Work You 156 | Distribute or Publicly Perform. You may not offer or impose any terms 157 | on the Work that restrict the terms of this License or the ability of 158 | the recipient of the Work to exercise the rights granted to that 159 | recipient under the terms of the License. You may not sublicense the 160 | Work. You must keep intact all notices that refer to this License and 161 | to the disclaimer of warranties with every copy of the Work You 162 | Distribute or Publicly Perform. When You Distribute or Publicly 163 | Perform the Work, You may not impose any effective technological 164 | measures on the Work that restrict the ability of a recipient of the 165 | Work from You to exercise the rights granted to that recipient under 166 | the terms of the License. This Section 4(a) applies to the Work as 167 | incorporated in a Collection, but this does not require the Collection 168 | apart from the Work itself to be made subject to the terms of this 169 | License. If You create a Collection, upon notice from any Licensor You 170 | must, to the extent practicable, remove from the Collection any credit 171 | as required by Section 4(b), as requested. If You create an 172 | Adaptation, upon notice from any Licensor You must, to the extent 173 | practicable, remove from the Adaptation any credit as required by 174 | Section 4(b), as requested. 175 | b. If You Distribute, or Publicly Perform the Work or any Adaptations or 176 | Collections, You must, unless a request has been made pursuant to 177 | Section 4(a), keep intact all copyright notices for the Work and 178 | provide, reasonable to the medium or means You are utilizing: (i) the 179 | name of the Original Author (or pseudonym, if applicable) if supplied, 180 | and/or if the Original Author and/or Licensor designate another party 181 | or parties (e.g., a sponsor institute, publishing entity, journal) for 182 | attribution ("Attribution Parties") in Licensor's copyright notice, 183 | terms of service or by other reasonable means, the name of such party 184 | or parties; (ii) the title of the Work if supplied; (iii) to the 185 | extent reasonably practicable, the URI, if any, that Licensor 186 | specifies to be associated with the Work, unless such URI does not 187 | refer to the copyright notice or licensing information for the Work; 188 | and (iv) , consistent with Section 3(b), in the case of an Adaptation, 189 | a credit identifying the use of the Work in the Adaptation (e.g., 190 | "French translation of the Work by Original Author," or "Screenplay 191 | based on original Work by Original Author"). The credit required by 192 | this Section 4 (b) may be implemented in any reasonable manner; 193 | provided, however, that in the case of a Adaptation or Collection, at 194 | a minimum such credit will appear, if a credit for all contributing 195 | authors of the Adaptation or Collection appears, then as part of these 196 | credits and in a manner at least as prominent as the credits for the 197 | other contributing authors. For the avoidance of doubt, You may only 198 | use the credit required by this Section for the purpose of attribution 199 | in the manner set out above and, by exercising Your rights under this 200 | License, You may not implicitly or explicitly assert or imply any 201 | connection with, sponsorship or endorsement by the Original Author, 202 | Licensor and/or Attribution Parties, as appropriate, of You or Your 203 | use of the Work, without the separate, express prior written 204 | permission of the Original Author, Licensor and/or Attribution 205 | Parties. 206 | c. Except as otherwise agreed in writing by the Licensor or as may be 207 | otherwise permitted by applicable law, if You Reproduce, Distribute or 208 | Publicly Perform the Work either by itself or as part of any 209 | Adaptations or Collections, You must not distort, mutilate, modify or 210 | take other derogatory action in relation to the Work which would be 211 | prejudicial to the Original Author's honor or reputation. Licensor 212 | agrees that in those jurisdictions (e.g. Japan), in which any exercise 213 | of the right granted in Section 3(b) of this License (the right to 214 | make Adaptations) would be deemed to be a distortion, mutilation, 215 | modification or other derogatory action prejudicial to the Original 216 | Author's honor and reputation, the Licensor will waive or not assert, 217 | as appropriate, this Section, to the fullest extent permitted by the 218 | applicable national law, to enable You to reasonably exercise Your 219 | right under Section 3(b) of this License (right to make Adaptations) 220 | but not otherwise. 221 | 222 | 5. Representations, Warranties and Disclaimer 223 | 224 | UNLESS OTHERWISE MUTUALLY AGREED TO BY THE PARTIES IN WRITING, LICENSOR 225 | OFFERS THE WORK AS-IS AND MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY 226 | KIND CONCERNING THE WORK, EXPRESS, IMPLIED, STATUTORY OR OTHERWISE, 227 | INCLUDING, WITHOUT LIMITATION, WARRANTIES OF TITLE, MERCHANTIBILITY, 228 | FITNESS FOR A PARTICULAR PURPOSE, NONINFRINGEMENT, OR THE ABSENCE OF 229 | LATENT OR OTHER DEFECTS, ACCURACY, OR THE PRESENCE OF ABSENCE OF ERRORS, 230 | WHETHER OR NOT DISCOVERABLE. SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION 231 | OF IMPLIED WARRANTIES, SO SUCH EXCLUSION MAY NOT APPLY TO YOU. 232 | 233 | 6. Limitation on Liability. EXCEPT TO THE EXTENT REQUIRED BY APPLICABLE 234 | LAW, IN NO EVENT WILL LICENSOR BE LIABLE TO YOU ON ANY LEGAL THEORY FOR 235 | ANY SPECIAL, INCIDENTAL, CONSEQUENTIAL, PUNITIVE OR EXEMPLARY DAMAGES 236 | ARISING OUT OF THIS LICENSE OR THE USE OF THE WORK, EVEN IF LICENSOR HAS 237 | BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. 238 | 239 | 7. Termination 240 | 241 | a. This License and the rights granted hereunder will terminate 242 | automatically upon any breach by You of the terms of this License. 243 | Individuals or entities who have received Adaptations or Collections 244 | from You under this License, however, will not have their licenses 245 | terminated provided such individuals or entities remain in full 246 | compliance with those licenses. Sections 1, 2, 5, 6, 7, and 8 will 247 | survive any termination of this License. 248 | b. Subject to the above terms and conditions, the license granted here is 249 | perpetual (for the duration of the applicable copyright in the Work). 250 | Notwithstanding the above, Licensor reserves the right to release the 251 | Work under different license terms or to stop distributing the Work at 252 | any time; provided, however that any such election will not serve to 253 | withdraw this License (or any other license that has been, or is 254 | required to be, granted under the terms of this License), and this 255 | License will continue in full force and effect unless terminated as 256 | stated above. 257 | 258 | 8. Miscellaneous 259 | 260 | a. Each time You Distribute or Publicly Perform the Work or a Collection, 261 | the Licensor offers to the recipient a license to the Work on the same 262 | terms and conditions as the license granted to You under this License. 263 | b. Each time You Distribute or Publicly Perform an Adaptation, Licensor 264 | offers to the recipient a license to the original Work on the same 265 | terms and conditions as the license granted to You under this License. 266 | c. If any provision of this License is invalid or unenforceable under 267 | applicable law, it shall not affect the validity or enforceability of 268 | the remainder of the terms of this License, and without further action 269 | by the parties to this agreement, such provision shall be reformed to 270 | the minimum extent necessary to make such provision valid and 271 | enforceable. 272 | d. No term or provision of this License shall be deemed waived and no 273 | breach consented to unless such waiver or consent shall be in writing 274 | and signed by the party to be charged with such waiver or consent. 275 | e. This License constitutes the entire agreement between the parties with 276 | respect to the Work licensed here. There are no understandings, 277 | agreements or representations with respect to the Work not specified 278 | here. Licensor shall not be bound by any additional provisions that 279 | may appear in any communication from You. This License may not be 280 | modified without the mutual written agreement of the Licensor and You. 281 | f. The rights granted under, and the subject matter referenced, in this 282 | License were drafted utilizing the terminology of the Berne Convention 283 | for the Protection of Literary and Artistic Works (as amended on 284 | September 28, 1979), the Rome Convention of 1961, the WIPO Copyright 285 | Treaty of 1996, the WIPO Performances and Phonograms Treaty of 1996 286 | and the Universal Copyright Convention (as revised on July 24, 1971). 287 | These rights and subject matter take effect in the relevant 288 | jurisdiction in which the License terms are sought to be enforced 289 | according to the corresponding provisions of the implementation of 290 | those treaty provisions in the applicable national law. If the 291 | standard suite of rights granted under applicable copyright law 292 | includes additional rights not granted under this License, such 293 | additional rights are deemed to be included in the License; this 294 | License is not intended to restrict the license of any rights under 295 | applicable law. 296 | 297 | 298 | Creative Commons Notice 299 | 300 | Creative Commons is not a party to this License, and makes no warranty 301 | whatsoever in connection with the Work. Creative Commons will not be 302 | liable to You or any party on any legal theory for any damages 303 | whatsoever, including without limitation any general, special, 304 | incidental or consequential damages arising in connection to this 305 | license. Notwithstanding the foregoing two (2) sentences, if Creative 306 | Commons has expressly identified itself as the Licensor hereunder, it 307 | shall have all rights and obligations of Licensor. 308 | 309 | Except for the limited purpose of indicating to the public that the 310 | Work is licensed under the CCPL, Creative Commons does not authorize 311 | the use by either party of the trademark "Creative Commons" or any 312 | related trademark or logo of Creative Commons without the prior 313 | written consent of Creative Commons. Any permitted use will be in 314 | compliance with Creative Commons' then-current trademark usage 315 | guidelines, as may be published on its website or otherwise made 316 | available upon request from time to time. For the avoidance of doubt, 317 | this trademark restriction does not form part of this License. 318 | 319 | Creative Commons may be contacted at https://creativecommons.org/. 320 | -------------------------------------------------------------------------------- /README.adoc: -------------------------------------------------------------------------------- 1 | = OSI Documentation 2 | 3 | This repo hosts the AsciiDoc-based part of the documentation. 4 | It contains generals parts of the content and a CI-pipeline that renders the document with Antora. 5 | 6 | // TODO: Update if Asciidoctor is completely dropped! 7 | 8 | == ASAM OSI (R) official documentation 9 | 10 | See the documentation https://opensimulationinterface.github.io/osi-antora-generator/asamosi/latest/specification/index.html[here]. 11 | 12 | 13 | == Build pipeline 14 | // === Asciidoctor pipeline 15 | 16 | // The Asciidoctor pipline is no longer active, see Antora pipeline. 17 | 18 | // image::https://github.com/OpenSimulationInterface/osi-documentation/actions/workflows/asciidoc-build.yml/badge.svg[link=https://github.com/OpenSimulationInterface/osi-documentation/actions/workflows/asciidoc-build.yml] 19 | 20 | // The pipeline collects the documentation from both https://github.com/OpenSimulationInterface/open-simulation-interface[open-simulation-interface] and https://github.com/OpenSimulationInterface/osi-sensor-model-packaging[osi-sensor-model-packaging] and integrates it into skeleton of this repo. 21 | // As with all ASAM Asciidoctor projects, the complete document structure is described in the mapping file https://github.com/OpenSimulationInterface/osi-documentation/blob/master/index.adoc[index.adoc]. 22 | 23 | === Antora pipeline 24 | image::https://github.com/OpenSimulationInterface/osi-antora-generator/actions/workflows/site-build.yml/badge.svg?branch=main[link=https://github.com/OpenSimulationInterface/osi-antora-generator/actions/workflows/site-build.yml] 25 | 26 | NOTE: This pipeline runs on https://github.com/OpenSimulationInterface/osi-antora-generator. 27 | 28 | 29 | == How To build and change documentation locally 30 | 31 | IMPORTANT: These instructions relate ONLY to the Asciidoctor build. 32 | For Antora, check the https://github.com/OpenSimulationInterface/osi-antora-generator[ASAM OSI Antora generator]. 33 | 34 | 35 | The following instructions show how to build the document locally. 36 | Take note that the document is built with a version 'localbuild' in the document and filename. 37 | 38 | The instruction should work on Windows, Linux, and MacOS. 39 | 40 | . *Precondition*: have docker and docker-compose installed. 41 | + 42 | TIP: Official installation can be found https://docs.docker.com/get-docker/[here]. 43 | 44 | . Clone this repository with submodules. 45 | + 46 | [source, shell] 47 | ---- 48 | git clone https://github.com/OpenSimulationInterface/osi-documentation.git 49 | git submodule update --init 50 | ---- 51 | 52 | . Clone OSI and OSMP with submodules *into* the osi-documentation folder 53 | + 54 | [source, shell] 55 | ---- 56 | cd osi-documentation 57 | git clone https://github.com/OpenSimulationInterface/open-simulation-interface.git 58 | git clone https://github.com/OpenSimulationInterface/osi-sensor-model-packaging.git 59 | ---- 60 | 61 | . Check file ``docker-compose.yml`` with the following content: 62 | + 63 | [source, yaml] 64 | ---- 65 | version: "2" 66 | 67 | services: 68 | asciidoctor: 69 | image: asciidoctor/docker-asciidoctor:1 70 | volumes: 71 | - .:/documents 72 | working_dir: /documents 73 | entrypoint: asciidoctor -D . --failure-level WARN -r asciidoctor-bibtex -r asciidoctor-diagram -a mathjax --trace --backend=html5 index.adoc -o open-simulation-interface_localbuild.html 74 | ---- 75 | 76 | . Run 77 | + 78 | [source, shell] 79 | ---- 80 | docker-compose run asciidoctor 81 | ---- 82 | 83 | . *Result*: Document is build as `open-simulation-interface_localbuild.html` in the folder osi-documentation. 84 | -------------------------------------------------------------------------------- /content/_config.adoc: -------------------------------------------------------------------------------- 1 | 2 | // This file contains AsciiDoc attributes that shall be used in every AsciiDoc file. 3 | // NOTE: Its content is only applied for Asciidoctor! 4 | // If the same attribute is defined in the antora.yml (without @), the antora.yml definition takes precedence for Antora. 5 | 6 | ifndef::root-path[:root-path: ./] 7 | 8 | :asciidoc-resources: {root-path}../asciidoc-resources 9 | // :asciidoc-resources: ../asciidoc-resources 10 | :appendix-caption: Annex 11 | 12 | // ifndef::use-antora-rules,include-only-once[] 13 | ifndef::include-only-once[] 14 | :GLO_VAR_STA_ASAM_OpenCRG: ASAM OpenCRG 15 | :glo_var_sta_asam_opencrg: {GLO_VAR_STA_ASAM_OpenCRG} 16 | :GLO_VAR_STA_ASAM_OpenDRIVE: ASAM OpenDRIVE 17 | :GLO_VAR_STA_ASAM_OpenLABEL: ASAM OpenLABEL 18 | :GLO_VAR_STA_ASAM_OpenODD: ASAM OpenODD 19 | :GLO_VAR_STA_ASAM_OSI: ASAM OSI® 20 | :GLO_VAR_STA_ASAM_OpenSCENARIO: ASAM OpenSCENARIO 21 | :GLO_VAR_STA_ASAM_OpenXOntology: ASAM OpenXOntology 22 | :GLO_VAR_STA_BSI_PAS_1883: BSI PAS 1883 23 | :revnumber: --localbuild-- 24 | :revdate: {docdate} 25 | :bibtex-file: ./content/general_docs/bibliography.bib 26 | // Replace PLACEHOLDER with the name of your standard, e.g. OpenDRIVE 27 | :THIS_STANDARD: {GLO_VAR_STA_ASAM_OSI} 28 | :THIS_STANDARD_TITLE: {GLO_VAR_STA_ASAM_OSI} 29 | :asam-terminology: https://code.asam.net/common/asam-terminology/-/raw/main/terms_and_definitions_opendrive.adoc 30 | :imagesdir: {root-path}_static/images 31 | :include-only-once: true 32 | :topicdir: topics 33 | :reusedir: reuse 34 | :toclevels: 3 35 | :xrefstyle: full 36 | // :images_osi-sensor-model-packaging: ../../osi-sensor-model-packaging/doc/images 37 | :doc_open_simulation_interface: open-simulation-interface/doc/ 38 | :doc_osi-sensor-model-packaging: osi-sensor-model-packaging/doc/ 39 | :images_open_simulation_interface: ../images 40 | // Since a document spanning multiple repos is rendered here, the pathing regarding images is a bit involved. 41 | // We create a variable for every repo that is included. It point to the repo in question. 42 | // If the subrepo is rendered seperatly, then the variable is set to just "./images" with ifdef. 43 | // Please note that this variable has to used in all image includes. Includes here have to use "image::./images..." 44 | // :images_osi_sensor_model_packaging: ./osi-sensor-model-packaging/doc/images // example 45 | :imagesoutdir: ./images/generated_images 46 | :page-feedbackurl: https://github.com/OpenSimulationInterface/osi-documentation/issues/new 47 | 48 | endif::[] 49 | 50 | ifndef::use-antora-rules[] 51 | include::{asciidoc-resources}/preamble.adoc[] 52 | endif::[] 53 | 54 | ifdef::env-gitlab[] 55 | :relfilesuffix: .adoc 56 | endif::[] 57 | 58 | ifdef::local[] 59 | :doc_open_simulation_interface: ../../open-simulation-interface/doc/ 60 | :doc_osi-sensor-model-packaging: ../../osi-sensor-model-packaging/doc/ 61 | :images_open_simulation_interface: ../images 62 | :data-uri: 63 | endif::[] 64 | -------------------------------------------------------------------------------- /content/_static/images/osi-context.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OpenSimulationInterface/osi-documentation/9882f2229dc0a22e328ef3264896a6d287d69189/content/_static/images/osi-context.png -------------------------------------------------------------------------------- /content/_static/images/osi-traffic-participant-advanced.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OpenSimulationInterface/osi-documentation/9882f2229dc0a22e328ef3264896a6d287d69189/content/_static/images/osi-traffic-participant-advanced.png -------------------------------------------------------------------------------- /content/_static/images/osi-traffic-participant-principle.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OpenSimulationInterface/osi-documentation/9882f2229dc0a22e328ef3264896a6d287d69189/content/_static/images/osi-traffic-participant-principle.png -------------------------------------------------------------------------------- /content/_static/images/osi-traffic-participant-use-case-1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OpenSimulationInterface/osi-documentation/9882f2229dc0a22e328ef3264896a6d287d69189/content/_static/images/osi-traffic-participant-use-case-1.png -------------------------------------------------------------------------------- /content/_static/images/osi-traffic-participant-use-case-2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OpenSimulationInterface/osi-documentation/9882f2229dc0a22e328ef3264896a6d287d69189/content/_static/images/osi-traffic-participant-use-case-2.png -------------------------------------------------------------------------------- /content/_static/images/osi-traffic-participant-use-case-3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OpenSimulationInterface/osi-documentation/9882f2229dc0a22e328ef3264896a6d287d69189/content/_static/images/osi-traffic-participant-use-case-3.png -------------------------------------------------------------------------------- /content/_static/images/osi-traffic-participant-use-case-4.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OpenSimulationInterface/osi-documentation/9882f2229dc0a22e328ef3264896a6d287d69189/content/_static/images/osi-traffic-participant-use-case-4.png -------------------------------------------------------------------------------- /content/_static/images/osilogo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OpenSimulationInterface/osi-documentation/9882f2229dc0a22e328ef3264896a6d287d69189/content/_static/images/osilogo.png -------------------------------------------------------------------------------- /content/appendix/releases/compatibility.adoc: -------------------------------------------------------------------------------- 1 | ifndef::include-only-once[] 2 | :root-path: ../../ 3 | include::{root-path}_config.adoc[] 4 | endif::[] 5 | = Compatibility 6 | 7 | Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. 8 | Et malesuada fames ac turpis egestas. 9 | Mauris pharetra et ultrices neque ornare aenean euismod elementum nisi. 10 | Nulla facilisi morbi tempus iaculis urna id. Justo eget magna fermentum iaculis. 11 | Sed augue lacus viverra vitae congue eu. 12 | Velit ut tortor pretium viverra suspendisse. 13 | Amet commodo nulla facilisi nullam vehicula ipsum a. 14 | Nibh nisl condimentum id venenatis a. 15 | Diam vel quam elementum pulvinar etiam non quam lacus suspendisse. -------------------------------------------------------------------------------- /content/appendix/releases/v02.00.adoc: -------------------------------------------------------------------------------- 1 | ifndef::include-only-once[] 2 | :root-path: ../../ 3 | include::{root-path}_config.adoc[] 4 | endif::[] 5 | ifdef::use-antora-rules[] 6 | :reftext: v2.0.0 - OSI Initial Commit 7 | = https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v2.0.0[{reftext}] 8 | endif::[] 9 | ifndef::use-antora-rules[] 10 | = https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v2.0.0[v2.0.0 - OSI Initial Commit] 11 | endif::[] 12 | 13 | This is the initial version of the Open Simulation Interface (OSI). 14 | 15 | *Overview* 16 | 17 | OSI is a generic interface for the environmental perception of automated driving functions in virtual scenarios. 18 | It is primarily conceived to enable easy and straightforward compatibility between automated driving functions and the variety of driving simulation frameworks available. 19 | The data description has been derived from the perspective of sensor modeling for automated test and validation of highly automated driving functions. 20 | 21 | *Implementation* 22 | 23 | OSI primarily contains an object based environment description using the message format of the protocol buffers library developed and maintained by Google. 24 | 25 | *Detailed description* 26 | 27 | 28 | Top level interfaces:: 29 | OSI consists of two individual top level interfaces for object data: The ``OSI::GroundTruth`` and the ``OSI::SensorData`` interface. 30 | + 31 | * The ``OSI::GroundTruth`` interface provides an exact view on the simulated objects in a global coordinate system. 32 | This message is populated using the internally available data of the used (driving)-simulation framework and is afterwards published to external subscribers with an exporter plugin. 33 | * The ``OSI::SensorData`` interface describes the objects in the reference frame of a sensor for environmental perception. 34 | It is generated from a ``OSI::GroundTruth`` message and can either be used to directly connect to an automated driving function using ideal simulated data, or may serve as input for a sensor model simulating limited perception as a replication of real world sensor behavior. 35 | 36 | Low level interfaces:: 37 | + 38 | Additionally to the two top level interfaces, OSI contains an ``OSI::LowLevelData`` message. 39 | This message describes the output of a (physical) model of the measurement process before tracking and object hypothesis. 40 | It does not deal with object data, but may comprise the geometrical influence of 3D simulations e.g. generating Lidar point clouds with a ray-tracer plugin. 41 | In addition this message supports generic radar reflection lists and will be extended to supporting low level camera data in the future. 42 | -------------------------------------------------------------------------------- /content/appendix/releases/v02.01.adoc: -------------------------------------------------------------------------------- 1 | ifndef::include-only-once[] 2 | :root-path: ../../ 3 | include::{root-path}_config.adoc[] 4 | endif::[] 5 | ifdef::use-antora-rules[] 6 | :reftext: v2.1.0 - OSI "Agile Andretti" 7 | = https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v2.1.0[{reftext}] 8 | endif::[] 9 | ifndef::use-antora-rules[] 10 | = https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v2.1.0[v2.1.0 - OSI "Agile Andretti"] 11 | endif::[] 12 | 13 | *Purpose* 14 | 15 | This is the initial BASE VERSION for Tool Development. 16 | 17 | https://github.com/OpenSimulationInterface/open-simulation-interface/milestone/1?closed=1[Content/Changes] 18 | 19 | *Remarks* 20 | 21 | We will now release the versions using the name of a https://en.wikipedia.org/wiki/List_of_Formula_One_drivers[Formula 1 driver]! 22 | Naming convention: "adjective + last name driver" -> Alliteration necessary! -------------------------------------------------------------------------------- /content/appendix/releases/v02.02.00.adoc: -------------------------------------------------------------------------------- 1 | ifndef::include-only-once[] 2 | :root-path: ../../ 3 | include::{root-path}_config.adoc[] 4 | endif::[] 5 | ifdef::use-antora-rules[] 6 | :reftext: v2.2.0 - OSI "Brave Brabham"4 7 | = https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v2.2.0[{reftext}] 8 | endif::[] 9 | ifndef::use-antora-rules[] 10 | = https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v2.2.0[v2.2.0 - OSI "Brave Brabham"4] 11 | endif::[] 12 | 13 | *Purpose* 14 | 15 | This release focuses on optimizing the build process and documentation. 16 | 17 | *https://github.com/OpenSimulationInterface/open-simulation-interface/milestone/2?closed=1[Content/Changes]* 18 | 19 | * Added a shared library target to the CMake build script. 20 | * Generated a proper doxygen documentation. 21 | * Placed the version number in one file (VERSION). 22 | * Added unit testing mechanism including style guide checking. 23 | * Redefined precipitation and added a fog definition to the environmental conditions message. 24 | * Added layer id to low level point cloud data. 25 | * Reworked large parts of the build instructions in the WIKI. 26 | -------------------------------------------------------------------------------- /content/appendix/releases/v02.02.01.adoc: -------------------------------------------------------------------------------- 1 | ifndef::include-only-once[] 2 | :root-path: ../../ 3 | include::{root-path}_config.adoc[] 4 | endif::[] 5 | ifdef::use-antora-rules[] 6 | :reftext: v2.2.1 - OSI "Brave Brabham", Update 1 7 | = https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v2.2.1[{reftext}] 8 | endif::[] 9 | ifndef::use-antora-rules[] 10 | = https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v2.2.1[v2.2.1 - OSI "Brave Brabham", Update 1] 11 | endif::[] 12 | 13 | *Purpose* 14 | 15 | This release focuses on optimizing the build process and ensures the proper installation of different versions of OSI on a single system. 16 | 17 | *https://github.com/OpenSimulationInterface/open-simulation-interface/compare/maintenance/v2.2.x[Content/Changes]* 18 | 19 | * Allowing several OSI versions on the same computer. 20 | * Improves CI builds to also test the installation cmake targets for proper completion. 21 | -------------------------------------------------------------------------------- /content/appendix/releases/v03.00.00.adoc: -------------------------------------------------------------------------------- 1 | ifndef::include-only-once[] 2 | :root-path: ../../ 3 | include::{root-path}_config.adoc[] 4 | endif::[] 5 | ifdef::use-antora-rules[] 6 | :reftext: v3.0.0 - OSI "Cosmic Coulthard" 7 | = https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.0.0[{reftext}] 8 | endif::[] 9 | ifndef::use-antora-rules[] 10 | = https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.0.0[v3.0.0 - OSI "Cosmic Coulthard"] 11 | endif::[] 12 | 13 | *Purpose* 14 | 15 | This release is a complete rework including the feedback from many OSI users. 16 | Thank you! 17 | We are aligned with the ongoing discussions for the upcoming ISO 23150 cite:[iso23150] standard for hardware sensor outputs in order to bring simulation and the hardware in the car closer together. 18 | 19 | *https://github.com/OpenSimulationInterface/open-simulation-interface/pulls?page=1&q=is%3Apr+is%3Aclosed+milestone%3Av3.0.0[Content/Changes]* 20 | 21 | * Added major version to package label (osi3), allowing concurrent use of OSI 2.x and OSI 3.x in one process. 22 | * Added new top-level messages (new concept SensorView (Configuration),etc.). 23 | ** GroundTruth. 24 | ** SensorView. 25 | ** SensorData / FeatureData. 26 | ** SensorViewConfiguration (used for auto-configuration of SensorView). 27 | * Added technology-specific SensorView sub-messages to aid physical models. 28 | * Introduced conceptual separation of “SensorModels” and “LogicModels”. 29 | * Extended enumerations (e.g. traffic sign Type according to StVO, vehicle Type, etc.). 30 | * Improved messages and definitions (additional RoadConditions, country code in GT, AmbientIllumination, etc.). 31 | * Use ISO 8855 cite:[iso8855] coordinate systems (incompatible with earlier OSI versions). 32 | * Redefined DetectedXXX messages. 33 | * Introduced DetectedStationaryObjects. 34 | * Merged MovingObjects and Vehicle messages. 35 | * Redefined Lane messages (with separated lane boundary messages and intersections). 36 | * Redefined TrafficLight messages. 37 | * Redefined TrafficSigns (1 x MainSign + n x SupplementarySign inclusive BaseStationary). 38 | * New FeatureData messages (rework of previous LowLevelData message) - aligned with an upcoming standard ISO 23150 cite:[iso23150]. 39 | * FeatureData usable for fusion units. 40 | * Extension and clarification of the existing doxygen documentation. 41 | * Improved doxygen collaboration diagrams. 42 | * Build process improvements, added install targets. 43 | * Made proto definitions compatible with proto3 restrictions to allow concurrent use with proto3-only implementations in the future. 44 | * Fixed version-checking of transmitted data. 45 | * AND MUCH MORE ENJOY!!! 46 | 47 | https://github.com/OpenSimulationInterface/open-simulation-interface/files/2297162/osi_overview_v2.2_vs_v3.0.pdf>[See for more information the `changelog`] 48 | -------------------------------------------------------------------------------- /content/appendix/releases/v03.00.01.adoc: -------------------------------------------------------------------------------- 1 | ifndef::include-only-once[] 2 | :root-path: ../../ 3 | include::{root-path}_config.adoc[] 4 | endif::[] 5 | ifdef::use-antora-rules[] 6 | :reftext: v3.0.1 - OSI "Cosmic Coulthard", Update 1 7 | = https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.0.1[{reftext}] 8 | endif::[] 9 | ifndef::use-antora-rules[] 10 | = https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.0.1[v3.0.1 - OSI "Cosmic Coulthard", Update 1] 11 | endif::[] 12 | 13 | https://www.youtube.com/watch?v=yG0oBPtyNb0[Summertime :)] 14 | 15 | *Purpose* 16 | 17 | This release is a patch reworking parts of the documentation in order to avoid ambiguities and improving the build/installation process of OSI. 18 | 19 | *https://github.com/OpenSimulationInterface/open-simulation-interface/pulls?page=1&q=is%3Apr+is%3Aclosed+milestone%3Av3.0.1[Content/Changes]* 20 | 21 | * Added script to automatically convert the messages from proto2 to proto3 with on the wire compatibility 22 | * cmake enhancements to enable multi-version support of OSI 2 and OSI 3 23 | * Added Python 3 support 24 | * Clarification of multiple comments 25 | * Added explanatory images in the documentation 26 | * centerline definition improved 27 | * signal_strength definition in LidarSensorView corrected 28 | * FeatureData::ambiguity_id definition clarified 29 | * RadarSensorViewConfiguration::AntennaDiagram::response definition clarified 30 | -------------------------------------------------------------------------------- /content/appendix/releases/v03.01.00.adoc: -------------------------------------------------------------------------------- 1 | ifndef::include-only-once[] 2 | :root-path: ../../ 3 | include::{root-path}_config.adoc[] 4 | endif::[] 5 | ifdef::use-antora-rules[] 6 | :reftext: v3.1.0 - OSI "Dynamic Duncan" 7 | = https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.1.0[{reftext}] 8 | endif::[] 9 | ifndef::use-antora-rules[] 10 | = https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.1.0[v3.1.0 - OSI "Dynamic Duncan"] 11 | endif::[] 12 | 13 | https://www.youtube.com/watch?v=fu3uA8K6ApQ>[(O SI)lent night] 14 | 15 | *Purpose* 16 | 17 | This time of the year Santa comes with presents and has also thought about the sensor modelers of this planet. 18 | We introduce the current state of the ISO 23150 cite:[iso23150]] discussions including Ultrasonic and Camera Detections. 19 | The traffic signs have been reworked and the documentation has been extended for a perfect user experience. 20 | Trust me - it's amazing! 21 | 22 | *https://github.com/OpenSimulationInterface/open-simulation-interface/pulls?q=is%3Apr+is%3Aclosed+milestone%3Av3.1.0>[Content/Changes]* 23 | 24 | * Complete rework of traffic signs including images in documentation. 25 | * Added Camera Detections in osi_featuredata.proto. 26 | * Added Ultrasonic Detections in osi_featuredata.proto. 27 | * Introduced light states for emergency and service vehicles. 28 | * Added orientation_acceleration and updated formulas. 29 | * Extended documentation with svg images. 30 | * Added model_reference for static and moving objects. 31 | * Added map_reference in ground truth. 32 | * Added proj4 string for coordinate transformations. 33 | * Introduced raster_lidar_proposal from innoviz. 34 | * Improved documentation with HTML tables and images for all traffic signs. 35 | -------------------------------------------------------------------------------- /content/appendix/releases/v03.01.01.adoc: -------------------------------------------------------------------------------- 1 | ifndef::include-only-once[] 2 | :root-path: ../../ 3 | include::{root-path}_config.adoc[] 4 | endif::[] 5 | ifdef::use-antora-rules[] 6 | :reftext: v3.1.1 - OSI "Dynamic Duncan", Update 1 7 | = https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.1.1[{reftext}] 8 | endif::[] 9 | ifndef::use-antora-rules[] 10 | = https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.1.1[v3.1.1 - OSI "Dynamic Duncan", Update 1] 11 | endif::[] 12 | 13 | *https://github.com/OpenSimulationInterface/open-simulation-interface/pulls?q=is%3Apr+is%3Aclosed+milestone%3Av3.1.1[Content/Changes]* 14 | 15 | * **Bug Fix**: Changed open_simulation_interface target back from being a static library to a shared library, as before (this reverts an inadvertent change in v3.1.0 from previous releases). 16 | v3.1.0 breaks all users of the shared library (i.e. everyone building on Linux/Unix systems, and even some using the DLL on Windows). 17 | -------------------------------------------------------------------------------- /content/appendix/releases/v03.01.02.adoc: -------------------------------------------------------------------------------- 1 | ifndef::include-only-once[] 2 | :root-path: ../../ 3 | include::{root-path}_config.adoc[] 4 | endif::[] 5 | ifdef::use-antora-rules[] 6 | :reftext: v3.1.2 - OSI "Dynamic Duncan", Update 2 7 | = https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.1.2[{reftext}] 8 | endif::[] 9 | ifndef::use-antora-rules[] 10 | = https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.1.2[v3.1.2 - OSI "Dynamic Duncan", Update 2] 11 | endif::[] 12 | 13 | *https://github.com/OpenSimulationInterface/open-simulation-interface/pulls?q=is%3Apr+is%3Aclosed+milestone%3Av3.1.2[Content/Changes]* 14 | 15 | * **Bugfix**: The version number is now correct in the VERSION file. 16 | -------------------------------------------------------------------------------- /content/appendix/releases/v03.02.adoc: -------------------------------------------------------------------------------- 1 | ifndef::include-only-once[] 2 | :root-path: ../../ 3 | include::{root-path}_config.adoc[] 4 | endif::[] 5 | ifdef::use-antora-rules[] 6 | :reftext: v3.2.0 - OSI "Editorial Eaton" 7 | = https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.2.0[{reftext}] 8 | endif::[] 9 | ifndef::use-antora-rules[] 10 | = https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.2.0[v3.2.0 - OSI "Editorial Eaton"] 11 | endif::[] 12 | 13 | https://www.youtube.com/watch?v=SJUhlRoBL8M[Think p(OSI)tive!] 14 | 15 | *Purpose* 16 | 17 | The work on the OSI project was until now mainly organized by the BMW AG. 18 | In order to enable as many interested parties as possible to contribute to the success of the Open Simulation Interface the project has been transferred to the https://www.asam.net/[ASAM e.V.] which has been made public in the https://www.asam.net/news-media/news/detail/news/bmw-transfers-open-simulation-interface-osi-to-asam/[ASAM press release]. 19 | A new chapter in the development of OSI is now opened with the https://www.asam.net/conferences-events/detail/asam-osi-kick-off-workshop/[kickoff workshop] leading to hopefully many project proposals streamlining the efficient future development of the interface. 20 | Due to this we decided to focus on the improvement of processes and documentation with this release. 21 | 22 | *https://github.com/OpenSimulationInterface/open-simulation-interface/pulls?q=is%3Apr+is%3Aclosed+milestone%3Av3.2.0[Content/Changes]* 23 | 24 | 25 | * Updated README according to K(eep) I(t) S(imply) S(tupid) principle 26 | * Added Issue and Pullrequest templates 27 | * Travis CI updated 28 | ** Update to bionic 18.04 29 | ** Added tests for building protobuf 2.6 and 3.0 in parallel 30 | ** Bugfixed the display of doubled documentation 31 | * Fixed several typos in the comments 32 | * Added a centralized documentation in https://github.com/OpenSimulationInterface/osi-documentation[OSI-Documentation] 33 | ** Added contributors guidelines 34 | ** Added commenting style guidelines 35 | ** Added uniform citation style according to APA 36 | ** Updated installation guides for osi in Linux and Windows 37 | ** Added a reference in sphinx based on the generated doxygen documentation 38 | * Added rules to the comments in order to enforce osi message validation with the https://github.com/OpenSimulationInterface/osi-validation[OSI-Validator] 39 | * Added the rule definitions in the rules.yml 40 | * Modularized testing of commenting style into python unit tests 41 | * Defined a standardazied a file format for reading trace files (*.osi) 42 | * Defined naming conventions of osi files 43 | * Added a *.txt to *.osi file converter for backward compatibility 44 | * Added a script to make traces readable for plausibility checks 45 | * Corrected the citing style for OSI Bibtex 46 | * Corrected unit specifications and references according to DIN (e.g. removed Unit: []) 47 | * Added timestamp in osi_environment 48 | * Added is_out_of_service bool to traffic light / traffic sign 49 | -------------------------------------------------------------------------------- /content/appendix/releases/v03.03.00.adoc: -------------------------------------------------------------------------------- 1 | ifndef::include-only-once[] 2 | :root-path: ../../ 3 | include::{root-path}_config.adoc[] 4 | endif::[] 5 | ifdef::use-antora-rules[] 6 | :reftext: v3.3.0 - OSI "Fabulous Fangio" 7 | = https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.3.0[{reftext}] 8 | endif::[] 9 | ifndef::use-antora-rules[] 10 | = https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.3.0[v3.3.0 - OSI "Fabulous Fangio"] 11 | endif::[] 12 | 13 | Stay p(OSI)tive! 14 | 15 | *Purpose* 16 | 17 | As a part of the increasing adoption of OSI in the industry, and its movement to ASAM as its home, several new use cases and extensions for OSI have been identified. 18 | This minor release highlights the work that has been done on several working packages including the introduction of brand new top level messages which extend OSI's scope beyond the specialized world of sensor modeling. 19 | 20 | *https://github.com/OpenSimulationInterface/open-simulation-interface/milestone/13?closed=1[Content/Changes]* 21 | 22 | * Introduced the TrafficCommand top-level message which enables event-based control of traffic participant models, e.g. with regard to a scenario specification. 23 | * Introduced the TrafficUpdate top-level message to send updated properties of traffic participant models. 24 | * Add new LogicalDetectionData message to SensorData, which provides detection data with respect to the reference frame of the logical/virtual sensor. 25 | * Added a new submessage to further specify wheel data. 26 | * Added a new field to support future trajectories of moving objects. 27 | * Added a new subtype message to osi_lane to better align with OpenDrive's lane type information and enable traffic participant models to identify lanes on which they are supposed to move. 28 | * Extended traffic lights and signs messages to include the model_references attribute that can be used to point out to a 3D-model. 29 | * Add global model reference to ground truth that can be used to specify the 3D model representing the environment. 30 | * Extended the camera sensor view configuration to better support the configuration of the simulation environment. 31 | * Added a new field to describe the position of the steering wheel. 32 | * Added a message MovingObjectClassification for classify-able attributes that are shared between different moving object types. 33 | Introduced the assigned lane id and the assigned lane percentage of a moving object there. 34 | 35 | * Updated to checklist for pull requests to provide clearer orientation for all users. 36 | * Updated the documentation of centerline and lane boundaries (ordering of the points, describing those lines). 37 | * Updated the documentation of 3D bounding boxes. 38 | * Update the documentation of ground clearance. 39 | 40 | * Make handling of enums in rules check more robust, especially ones. 41 | * Set the default compiler to C++ 11 to support protobuf>3.6. 42 | -------------------------------------------------------------------------------- /content/appendix/releases/v03.03.01.adoc: -------------------------------------------------------------------------------- 1 | ifndef::include-only-once[] 2 | :root-path: ../../ 3 | include::{root-path}_config.adoc[] 4 | endif::[] 5 | ifdef::use-antora-rules[] 6 | :reftext: v3.3.1 - OSI "Fabulous Fangio", Update 1 7 | = https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.3.1[{reftext}] 8 | endif::[] 9 | ifndef::use-antora-rules[] 10 | = https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.3.1[v3.3.1 - OSI "Fabulous Fangio", Update 1] 11 | endif::[] 12 | 13 | *https://github.com/OpenSimulationInterface/open-simulation-interface/milestone/18?closed=1[Content/Changes]* 14 | 15 | * **Bug Fix**: Fixed outdated version information in VERSION file in 3.3.0. 16 | This led to wrong versioning in proto definitions and Doxygen documentation. 17 | * **Bug Fix**: Removed outdated picture in README.md. 18 | -------------------------------------------------------------------------------- /content/appendix/releases/v03.04.adoc: -------------------------------------------------------------------------------- 1 | ifndef::include-only-once[] 2 | :root-path: ../../ 3 | include::{root-path}_config.adoc[] 4 | endif::[] 5 | ifdef::use-antora-rules[] 6 | :reftext: v3.4.0 - OSI "Gallant Glock" 7 | = https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.4.0[{reftext}] 8 | endif::[] 9 | ifndef::use-antora-rules[] 10 | = https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.4.0[v3.4.0 - OSI "Gallant Glock"] 11 | endif::[] 12 | 13 | Stay p(OSI)tive! 14 | 15 | *Purpose* 16 | 17 | In this minor release, several interface messages have been updated and extended to better ensure consistency within the standard itself and harmonization with other OpenX-Standards like ASAM OpenDRIVE. 18 | Moreover, this release provides a first glance on the on-going efforts for OSI's documentation improvements and migration to AsciiDoc. 19 | 20 | *https://github.com/OpenSimulationInterface/open-simulation-interface/milestone/14?closed=1[Content/Changes]* 21 | 22 | //tag::content[] 23 | Documentation Updates:: 24 | - Updated the documentation's structure and migrated it to AsciiDoc. 25 | - Updated the description of OSI's top level messages. 26 | - Updates on additional descriptions, like those for trace file formats, naming conventions and installation instructions for Linux/Windows. 27 | 28 | Technical Updates:: 29 | - Extended SensorViewConfiguration message to allow the consumer to choose to not include static content in the SensorView ground truth information. 30 | - Updated StationaryObject classification enums to avoid "pylon" duplication. 31 | - Extended StationaryObject classification message to include speed bumps. 32 | - Extended StationaryObject to include emitting structures of electromagnetic waves (for example this can be used to define a streetlamp). 33 | - Extended the TrafficSign classification message, by adding attributes country, country_revision, code and sub_code, to better support internationalization and to align with ASAM OpenDRIVE. 34 | - Updated the color coding message description to better align with ASAM OpenDRIVE. 35 | - Update the color coding message description to include Grey, RGB, RGBIR, HSV, LUV and thus align with ISO-23150. 36 | - Added an enum for dashed lane boundaries to disambiguate start and end of those. 37 | - Extended HostVehcileData with more comprehensive on-board information, and promoted the message to a top-level message for exchange between simulation environments and (external) dynamic models. 38 | - Extended LidarDetection message under feature data to include echo pulse width information to better support several sensor outputs that are currently on the market. 39 | - Extended OSI to include a generic external reference message to enable traceability for data from other standards, including other ASAM OpenX standards. 40 | - Added support for using OSI with Flatbuffers encoding for OSI messages instead of ProtoBuffers, in preparation for a potential switch of default encoding in a future major release. 41 | - Extended LaneBoundary message to include additional types, to better align with ASAM OpenDRIVE. 42 | //end::content[] 43 | -------------------------------------------------------------------------------- /content/appendix/releases/v03.05.adoc: -------------------------------------------------------------------------------- 1 | ifndef::include-only-once[] 2 | :root-path: ../../ 3 | include::{root-path}_config.adoc[] 4 | endif::[] 5 | ifdef::use-antora-rules[] 6 | :reftext: v3.5.0 - OSI "Hard-fighting Hunt" 7 | = https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.5.0[{reftext}] 8 | endif::[] 9 | ifndef::use-antora-rules[] 10 | = https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.5.0[v3.5.0 - OSI "Hard-fighting Hunt"] 11 | endif::[] 12 | 13 | L(OSI)ng is not an option! 14 | 15 | This is an official ASAM release of OSI. The standard can also be downloaded on the ASAM website. 16 | 17 | *Purpose* 18 | 19 | //tag::content[] 20 | In this minor release, several interface messages have been updated and extended to better ensure consistency within the standard itself and harmonization with other OpenX-Standards like ASAM OpenDRIVE or OpenScenario. 21 | In this context the extension of GroundTruth by logical lane information - to empower a better traffic participant modelling - was one of the key achievements for this release. 22 | 23 | *https://github.com/OpenSimulationInterface/open-simulation-interface/milestone/19?closed=1[Content/Changes]* 24 | 25 | - Added logical lane information (including st-representation) for traffic participant usage. 26 | - Added route message TrafficCommandUpdate to offer a backchannel for (un)executed TrafficCommands. 27 | - Extended EnvironmentalConditions regarding sun, wind and cloud state. 28 | - Added dash property to boundary points. 29 | - Extended HostVehicleData by automated driving function states and operating states. 30 | - Added friction coefficient to moving object. 31 | - Improved description of trucks in VehicleClassification. 32 | - Added Role to VehicleClassification. 33 | - Concretized LaneBoundary modelling. 34 | - Removed protobuf version recommendation. 35 | - CMake: Project usable via FetchContent. 36 | - Doxygen: Improved output. 37 | - CI: Moved to current protobuf release. 38 | - Updated documentation of coordinate systems and their transformations. 39 | //end::content[] 40 | -------------------------------------------------------------------------------- /content/appendix/releases/v03.06.adoc: -------------------------------------------------------------------------------- 1 | ifndef::include-only-once[] 2 | :root-path: ../../ 3 | include::{root-path}_config.adoc[] 4 | endif::[] 5 | ifdef::use-antora-rules[] 6 | :reftext: v3.6.0 - OSI "Inspiring Irvine" 7 | = https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.6.0[{reftext}] 8 | endif::[] 9 | ifndef::use-antora-rules[] 10 | = https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.6.0[v3.6.0 - OSI "Inspiring Irvine"] 11 | endif::[] 12 | 13 | Limitless P(OSI)bilities! 14 | 15 | *Purpose* 16 | 17 | //tag::content[] 18 | In this minor release, a new streaming update interface message has been added for low-latency applications, as well as a HAD function output interface message. 19 | 20 | The additions of detailed pedestrian skeleton information, host vehicle kinematics, lane road name information, an enhanced lane reference line ST definition, enhanced traffic sign variability information, added radial velocity and echo pulse width information in sensor detection data, and pixel_order information for camera sensor view data are further enhancements of this release. 21 | 22 | Beyond that, many clarifications, improvements in definitions and documentation, enhanced installation information and enhanced/fixed flatbuffer support are key improvements in this release. 23 | 24 | *https://github.com/OpenSimulationInterface/open-simulation-interface/milestone/20?closed=1[Content/Changes]* 25 | 26 | - Build: Create base Antora setup. 27 | - Fix path to asciidoc-resources. 28 | - Added one more missing step. 29 | - Build/master branch naming. 30 | - Never trigger antora builds for PRs from forks. 31 | - Fix traffic sign variability attribute description. 32 | - Fixing title of Fig. 10 with coordinate systems. 33 | - Add new traffic sign variability types. 34 | - Add new enum Type in vehicle classification for stand-up scooters. 35 | - Adapt ReferenceLine ST definition to avoid transformation ambiguity and discontinuities. 36 | - Add DAY to TrafficSign-Value-Unit and change DAY to WEEKDAY. 37 | - Update host vehicle data with kinematics data. 38 | - Adding the missing field for echo pulse width to logical detections. 39 | - Logical lanes: add street name. 40 | - Add sensor-specific data to detected stationary objects. 41 | - Feature/tp/had output. 42 | - Build: Create a release pipeline that replaces the manual creation of a deliverable package. 43 | - (feat SensorModelling) add pixel_order field. 44 | - Links in README and example moved to docu. 45 | - Fix sensordata reference frame definitions. 46 | - Fix documentation on coordinate systems and transformations. 47 | - Clean README and enhanced install instructions for protobuf in Docu. 48 | - Move missing vcpkg information to prerequisites. 49 | - Fix flatbuffer builds for upcoming release. 50 | - Added radial_velocity to LidarDetection. 51 | - Streaming Interface. 52 | - Add detailed pedestrian description to MovingObject. 53 | //end::content[] 54 | -------------------------------------------------------------------------------- /content/appendix/releases/v03.07.adoc: -------------------------------------------------------------------------------- 1 | ifndef::include-only-once[] 2 | :root-path: ../../ 3 | include::{root-path}_config.adoc[] 4 | endif::[] 5 | ifdef::use-antora-rules[] 6 | :reftext: v3.7.0 - OSI "Jolly Jones" 7 | = https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.7.0[{reftext}] 8 | endif::[] 9 | ifndef::use-antora-rules[] 10 | = https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.7.0[v3.7.0 - OSI "Jolly Jones"] 11 | endif::[] 12 | 13 | Ambr(OSI)al Features! 14 | 15 | *Purpose* 16 | 17 | //tag::content[] 18 | This minor release contains a number of incremental enhancements and improvements: 19 | 20 | - Sub-bounding boxes can be provided for ground truth objects to model e.g. concave non-rectangular objects in more realistic ways without resorting to full 3D models. 21 | - Logical lanes can contain effective speed limit information to avoid the need to process traffic signs for speed selection. 22 | - Routing information can be transmitted as part of HostVehicleData. 23 | - Orientation rates can be transmitted as part of pedestrian skeleton information. 24 | - A virtual detection area can be supplied in SensorData to visualize or indicate the currently active nominal detection area of a sensor. 25 | - The system time of a source of SensorData can be supplied in addition to the simulation measurement timestamp to aid timing simulation and measurement use cases. 26 | - An offset has been introduced that is to be added to the cartesian global ground truth coordinate system prior to mapping into a geodetic coordinate system with the proj.4 string. This harmonizes OSI with OpenDRIVE and allows the easier provision of false easting/northing in the coordinate transformation. 27 | - The set of car types has been reduced to better harmonize with other OpenX standards as part of overall harmonization efforts. 28 | 29 | Beyond that, many clarifications, improvements in definitions and documentation, enhanced installation information and enhanced Python support, including provisioning of Python packages on PyPI are key improvements in this release. 30 | 31 | *https://github.com/OpenSimulationInterface/open-simulation-interface/milestone/21?closed=1[Content/Changes]* 32 | 33 | - Add beam ID to LidarDetection. 34 | - Update release.yml. 35 | - Add osi_trafficcommandupdate.proto to CMakeLists. 36 | - Make CMAKE_CXX_STANDARD overridable (fix #741). 37 | - Update build workflow for modular protobuf version support. 38 | - Workflow: Update Python and Actions + Black formatting Python files. 39 | - feat: New OSI message osi_route. 40 | - Add orientation rate to PedestrianAttributes::Bone. 41 | - Define mandatory field with checker rules. 42 | - Removal of the historical .txt trace file format and related scripts. 43 | - Fix typos in proto files. 44 | - Add new message for sub-bounding boxes. 45 | - Update github actions for release workflow. 46 | - Add check that all proto files are included in build. 47 | - feat: Add virtual detection area. 48 | - Modernize python build setup, protoc dependency. 49 | - Remove OSC todo comment from source_reference. 50 | - Fix documentation on FeatureData messages. 51 | - Feature/proj offset. 52 | - Add system time to sensor data. 53 | - Add pyspelling html filter. 54 | - Deprecate various car types in favor of new alias TYPE_CAR. 55 | - Fix streaming principle image reference. 56 | - Logical Traffic Rules and Speed Limit. 57 | //end::content[] 58 | -------------------------------------------------------------------------------- /content/contributing/branching_member.adoc: -------------------------------------------------------------------------------- 1 | ifndef::include-only-once[] 2 | :root-path: ../ 3 | include::{root-path}_config.adoc[] 4 | endif::[] 5 | = Branching workflow for member contributors 6 | 7 | Members of the OSI project can contribute to the ASAM OSI repositories directly. 8 | 9 | **Prerequisites** 10 | 11 | - You have a GitHub account. 12 | - You are a member of the ASAM OSI project. 13 | 14 | **Steps** 15 | 16 | . Create an issue describing the intended change. 17 | . Clone the corresponding repository on your local machine. 18 | . Create a branch with a meaningful name. 19 | Follow the branch-name conventions. 20 | . Commit and push your changes to the branch. 21 | Follow the commit messages guidelines. 22 | . When your changes are ready for review, create a pull request. 23 | If possible, add references to corresponding issues and appropriate labels. 24 | . Ask reviewers to review your changes. 25 | . When discussions about the changes are done, add the _ReadyForCCBReview_ label. 26 | Pull request with this label will be discussed at the next meeting of the _Change Control Board_. 27 | . When the Change Control Board approves the changes, the pull request is labelled as _ReadyToMerge_. 28 | This label indicates that the changes in the pull request can be merged. 29 | . Merge the changes into the repository's master branch. 30 | 31 | **Related topics** 32 | 33 | - <> 34 | - <> -------------------------------------------------------------------------------- /content/contributing/commenting_fields_enums.adoc: -------------------------------------------------------------------------------- 1 | ifndef::include-only-once[] 2 | :root-path: ../ 3 | include::{root-path}_config.adoc[] 4 | endif::[] 5 | [#top-commenting_on_fields_and_enums] 6 | = Commenting on fields and enums 7 | 8 | The {THIS_STANDARD} reference documentation is created using _Doxygen_. 9 | The reference documentation's content is generated from comments in the `.proto` files. 10 | Follow these steps when creating comments on fields and enums to keep the documentation style consistent. 11 | 12 | **Prerequisites** 13 | 14 | * You have created a field or enum. 15 | 16 | **Steps** 17 | 18 | . Add a description to the field or enum followed by an empty comment line. 19 | . Add the unit of the field using the format `Unit: UNIT` followed by an empty comment line. 20 | . Optionally, add notes using the keyword `\note`. 21 | . Optionally, add literary references to the comments. 22 | The list of references starts with `\par References:` followed by the references. 23 | Every reference starts on a new line. 24 | Every reference begins with a reference number in the format `[n]`. 25 | Every reference ends with `\n`, except the last reference. 26 | . Optionally, add rules encapsulated between `\rules` and `\endrules`. 27 | 28 | **Example** 29 | 30 | [source,protobuf,linenums] 31 | ---- 32 | // \brief The conditions of the environment. 33 | // 34 | // \image html EnvironmentalConditions.svg 35 | // 36 | // Definition of light, weather conditions and other environmental conditions. 37 | // 38 | // \note These conditions apply locally around the host vehicle. 39 | // 40 | message EnvironmentalConditions 41 | { 42 | // Atmospheric pressure in Pascal at z = 0.0 m in world frame (about 101325 Pa) [1, 2]. 43 | // 44 | // Unit: Pa 45 | // 46 | // \note 100000 Pa = 1 bar 47 | // 48 | // \par References: 49 | // [1] DIN Deutsches Institut fuer Normung e. V. (1982). DIN 5031-3 Strahlungsphysik im optischen Bereich und Lichttechnik - Groessen, Formelzeichen und Einheiten der Lichttechnik. (DIN 5031-3:1982-03). Berlin, Germany. \n 50 | // [2] Rapp, C. (2017). Grundlagen der Physik. In Hydraulik fuer Ingenieure und Naturwissenschaftler (pp.23-36). Springer Vieweg. Wiesbaden, Germany. https://doi.org/10.1007/978-3-658-18619-7_3. p. 105. 51 | // 52 | // \rules 53 | // is_optional 54 | // is_greater_than_or_equal_to: 90000 55 | // is_less_than_or_equal_to: 200000 56 | // \endrules 57 | // 58 | optional double atmospheric_pressure = 1; 59 | } 60 | ---- 61 | 62 | **Related topics** 63 | 64 | - <> -------------------------------------------------------------------------------- /content/contributing/commenting_messages.adoc: -------------------------------------------------------------------------------- 1 | ifndef::include-only-once[] 2 | :root-path: ../ 3 | include::{root-path}_config.adoc[] 4 | endif::[] 5 | [#top-commenting_on_messages] 6 | = Commenting on messages 7 | 8 | The {THiS_STANDARD} reference documentation is created using _Doxygen_. 9 | The content of the reference documentation is generated from comments in the `.proto` files. 10 | Follow these steps when creating comments on messages to keep the documentation style consistent. 11 | 12 | **Prerequisites** 13 | 14 | * You have created a new message. 15 | 16 | **Steps** 17 | 18 | . Add a brief description using the `\brief` keyword followed by an empty comment line. 19 | . Optionally, add an image using the `\image html` keyword followed by an empty comment line. 20 | The image must be stored at `./open-simulation-interface/docs/images` 21 | . Optionally, add a detailed description spanning multiple lines followed by an empty comment line. 22 | . Optionally, add notes using the keyword `\note`. 23 | 24 | **Example** 25 | 26 | [source,protobuf,linenums] 27 | ---- 28 | // \brief The conditions of the environment. 29 | // 30 | // \image html EnvironmentalConditions.svg 31 | // 32 | // Definition of light, weather conditions and other environmental conditions. 33 | // 34 | // \note These conditions apply locally around the host vehicle. 35 | // 36 | message EnvironmentalConditions 37 | { 38 | } 39 | ---- 40 | -------------------------------------------------------------------------------- /content/contributing/contributing_docs.adoc: -------------------------------------------------------------------------------- 1 | ifndef::include-only-once[] 2 | :root-path: ../ 3 | include::{root-path}_config.adoc[] 4 | endif::[] 5 | = Contributing to the documentation 6 | 7 | Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. 8 | Et malesuada fames ac turpis egestas. 9 | Mauris pharetra et ultrices neque ornare aenean euismod elementum nisi. 10 | Nulla facilisi morbi tempus iaculis urna id. Justo eget magna fermentum iaculis. 11 | Sed augue lacus viverra vitae congue eu. 12 | Velit ut tortor pretium viverra suspendisse. 13 | Amet commodo nulla facilisi nullam vehicula ipsum a. 14 | Nibh nisl condimentum id venenatis a. 15 | Diam vel quam elementum pulvinar etiam non quam lacus suspendisse. -------------------------------------------------------------------------------- /content/contributing/contribution_rules.adoc: -------------------------------------------------------------------------------- 1 | ifndef::include-only-once[] 2 | :root-path: ../ 3 | include::{root-path}_config.adoc[] 4 | endif::[] 5 | [#top-guidelines_for_contributions] 6 | = Guidelines for contributions 7 | 8 | Commit guidelines exist to ensure the transparency and intelligibility of the commit history. 9 | {THIS_STANDARD} enforces the following commit guidelines: 10 | 11 | - Prefer small atomic commits over large ones that do many things. 12 | - Do not mix refactoring and new features. 13 | - Do not mix style changes, for example indentation changes, with actual code changes. 14 | - If you add new messages to a *.proto file, add appropriate documentation as well. 15 | - Run the unit tests for comment compliance to check if you followed the correct syntax guidelines for *.proto files. 16 | - Follow the guidelines for commit messages. 17 | - Sign off commit messages. 18 | - Name branches meaningfully and consistently. 19 | - If a commit contains work-in-progress, add the _WIP_ label to the commit message. 20 | 21 | **Related topics** 22 | 23 | - <> 24 | - <> 25 | - <> 26 | - <> 27 | - <> -------------------------------------------------------------------------------- /content/contributing/creating_images.adoc: -------------------------------------------------------------------------------- 1 | ifndef::include-only-once[] 2 | :root-path: ../ 3 | include::{root-path}_config.adoc[] 4 | endif::[] 5 | = Creating vector images 6 | 7 | Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. 8 | Et malesuada fames ac turpis egestas. 9 | Mauris pharetra et ultrices neque ornare aenean euismod elementum nisi. 10 | Nulla facilisi morbi tempus iaculis urna id. Justo eget magna fermentum iaculis. 11 | Sed augue lacus viverra vitae congue eu. 12 | Velit ut tortor pretium viverra suspendisse. 13 | Amet commodo nulla facilisi nullam vehicula ipsum a. 14 | Nibh nisl condimentum id venenatis a. 15 | Diam vel quam elementum pulvinar etiam non quam lacus suspendisse. -------------------------------------------------------------------------------- /content/contributing/creating_references.adoc: -------------------------------------------------------------------------------- 1 | ifndef::include-only-once[] 2 | :root-path: ../ 3 | include::{root-path}_config.adoc[] 4 | endif::[] 5 | [#top-guidelines_for_creating_literary_references] 6 | = Guidelines for creating literary references 7 | 8 | When citing literature in the reference documentation, adhere to the following guidelines: 9 | 10 | * Refer to 11 | //#TODO add link to latest version when available xref:https://internal.pages.asam.net/asam-editorial-guide/editorial-guide-generator/editorialguide-asciidoc/latest/Editorial_guide.html[ 12 | rule ASM-22 of the ASAM Editorial Guide 13 | //] 14 | for detailed guidelines. 15 | * In the text, cite sources using `cite:[]`, with being the unique key defined in the bibliography.bib. 16 | 17 | //Replaced by ASM-22, see #75 18 | //// 19 | When citing literature in the reference documentation, adhere to the following guidelines: 20 | 21 | * All sources shall be primary sources. Sources like Wikipedia are not allowed. 22 | * OSI uses _APA style_ references from the American Psychological Association. 23 | * In the text, sources are cited using numbers in brackets. 24 | * In the references list, the number in brackets is resolved to a full citation. 25 | * Titles shall be written in italic, using `title`. 26 | * If the list contains more than one entry, add `\n` at the end of the line to create a line break within the list. 27 | * Author names shall be written as , . 28 | * Editor names shall be written as . 29 | * Page numbers are optional and may be used with long texts or for referencing specific sections. 30 | 31 | **Templates** 32 | 33 | Use the following templates for creating properly styled references: 34 | 35 | Compilation:: 36 | ---- 37 | , , & . (). Contribution in a compilation title. . . . . . . . 38 | ---- 39 | Book:: 40 | ---- 41 | , & . (). . . . . . 42 | ---- 43 | Chapter in a book:: 44 | ---- 45 | & . (). . In & (Eds.), (). . . . 46 | ---- 47 | Article in a journal:: 48 | ---- 49 | & . (). . . . . . . 50 | ---- 51 | Phd thesis:: 52 | ---- 53 | . (). . Phd. thesis. . . . . 54 | ---- 55 | Online article:: 56 | ---- 57 | . (, ). . Retrieved , , from . 58 | ---- 59 | Standard:: 60 | ---- 61 | . (). </em>. (<standard identifier>). <location>. 62 | ---- 63 | Patent:: 64 | ---- 65 | <author>. (<year>). <em><patent title and id></em>. <location>. <organisation>. 66 | ---- 67 | 68 | More sample templates are available at https://apastyle.apa.org. 69 | 70 | 71 | **Example** 72 | 73 | [source,protobuf,linenums] 74 | ---- 75 | // [...] 76 | // \par References: 77 | // [1] DIN Deutsches Institut fuer Normung e. V. (1982). <em>DIN 5031-3 Strahlungsphysik im optischen Bereich und Lichttechnik - Groessen, Formelzeichen und Einheiten der Lichttechnik</em>. (DIN 5031-3:1982-03). Berlin, Germany. \n 78 | // [2] Rapp, C. (2017). Grundlagen der Physik. In <em>Hydraulik fuer Ingenieure und Naturwissenschaftler</em> (pp.23-36). Springer Vieweg. Wiesbaden, Germany. https://doi.org/10.1007/978-3-658-18619-7_3. p. 105. 79 | // 80 | optional double atmospheric_pressure = 1; 81 | } 82 | ---- 83 | //// -------------------------------------------------------------------------------- /content/contributing/dco.adoc: -------------------------------------------------------------------------------- 1 | ifndef::include-only-once[] 2 | :root-path: ../ 3 | include::{root-path}_config.adoc[] 4 | endif::[] 5 | [#top-developer_certificate_of_origin_dco] 6 | = Developer Certificate of Origin (DCO) 7 | 8 | To make a good-faith effort to ensure licensing criteria are met, the Developer-Certificate-of-Origin (DCO) process shall be followed. 9 | 10 | When contributing a change, the contributor must agree to the DCO. 11 | The DCO is a commitment that the contributor has the right to submit the change. 12 | 13 | The text of the DCO is shown below or can be accessed at https://developercertificate.org/. 14 | 15 | ---- 16 | Developer Certificate of Origin 17 | Version 1.1 18 | 19 | Copyright (C) 2004, 2006 The Linux Foundation and its contributors. 20 | 1 Letterman Drive 21 | Suite D4700 22 | San Francisco, CA, 94129 23 | 24 | Everyone is permitted to copy and distribute verbatim copies of this 25 | license document, but changing it is not allowed. 26 | 27 | 28 | Developer's Certificate of Origin 1.1 29 | 30 | By making a contribution to this project, I certify that: 31 | 32 | (a) The contribution was created in whole or in part by me and I 33 | have the right to submit it under the open source license 34 | indicated in the file; or 35 | 36 | (b) The contribution is based upon previous work that, to the best 37 | of my knowledge, is covered under an appropriate open source 38 | license and I have the right under that license to submit that 39 | work with modifications, whether created in whole or in part 40 | by me, under the same open source license (unless I am 41 | permitted to submit under a different license), as indicated 42 | in the file; or 43 | 44 | (c) The contribution was provided directly to me by some other 45 | person who certified (a), (b) or (c) and I have not modified 46 | it. 47 | 48 | (d) I understand and agree that this project and the contribution 49 | are public and that a record of the contribution (including all 50 | personal information I submit with it, including my sign-off) is 51 | maintained indefinitely and may be redistributed consistent with 52 | this project or the open source license(s) involved. 53 | ---- 54 | 55 | Contributors agree to the DCO by adding a ``Signed-off-by`` statement to the commit message. 56 | -------------------------------------------------------------------------------- /content/contributing/forking_no_member.adoc: -------------------------------------------------------------------------------- 1 | ifndef::include-only-once[] 2 | :root-path: ../ 3 | include::{root-path}_config.adoc[] 4 | endif::[] 5 | = Forking for non-member contributors 6 | 7 | External contributors must fork the OSI repositories and contribute their changes via a pull request. 8 | 9 | **Prerequisites** 10 | 11 | - You have a GitHub account. 12 | 13 | **Steps** 14 | 15 | . Create an issue describing the intended change. 16 | . Fork the corresponding OSI repository on GitHub. 17 | . Clone the forked repository on your local machine. 18 | . Create a branch with a meaningful name. 19 | Follow the branch-name conventions. 20 | . Commit and push your changes to the branch. 21 | Follow the commit messages guidelines. 22 | . When your changes are ready for review, create a pull request. 23 | If possible, add references to corresponding issues and appropriate labels. 24 | . Ask reviewers to review your changes. 25 | . When discussions about the changes are done, add the _ReadyForCCBReview_ label. 26 | Pull request with this label will be discussed in the next meeting of the _Change Control Board_. 27 | . When the Change Control Board approves of the changes, the pull request is labelled as _ReadyToMerge_. 28 | This label indicates that the changes in the pull request can be merged. 29 | . Merge the changes into the master branch of the repository. 30 | 31 | **Related topics** 32 | 33 | - <<top-reporting_issues>> 34 | - <<top-guidelines_for_contributions>> -------------------------------------------------------------------------------- /content/contributing/licensing.adoc: -------------------------------------------------------------------------------- 1 | ifndef::include-only-once[] 2 | :root-path: ../ 3 | include::{root-path}_config.adoc[] 4 | endif::[] 5 | = License 6 | 7 | OSI uses the https://www.mozilla.org/en-US/MPL/2.0/[Mozilla Public License, v. 2.0]. 8 | All contributions are released under this license. 9 | 10 | Before contributing to OSI repositories, read the `LICENSE` file in the corresponding repository. 11 | -------------------------------------------------------------------------------- /content/contributing/naming_conventions.adoc: -------------------------------------------------------------------------------- 1 | ifndef::include-only-once[] 2 | :root-path: ../ 3 | include::{root-path}_config.adoc[] 4 | endif::[] 5 | [#top-interface_conventions] 6 | = Interface conventions 7 | 8 | OSI messages, enums, field messages, and field enums shall comply with OSI interface conventions. 9 | These conventions ensure that message definitions and the corresponding classes are consistently named and easy to read. 10 | 11 | Message names shall use _PascalCase_. 12 | 13 | [source,protobuf,linenums] 14 | ---- 15 | message EnvironmentalConditions 16 | { 17 | } 18 | ---- 19 | 20 | Message field names shall use _snake_case_. 21 | 22 | [source,protobuf,linenums] 23 | ---- 24 | message EnvironmentalConditions 25 | { 26 | optional double atmospheric_pressure = 1; 27 | } 28 | ---- 29 | 30 | Enum names shall use _PascalCase_. 31 | 32 | [source,protobuf,linenums] 33 | ---- 34 | message EnvironmentalConditions 35 | { 36 | optional double atmospheric_pressure = 1; 37 | 38 | enum AmbientIllumination 39 | { 40 | } 41 | } 42 | ---- 43 | 44 | Enum field value names shall use _UPPER_SNAKE_CASE_. 45 | Enum field value names shall always be prefixed with the name of the corresponding enum. 46 | 47 | For enum fields that are concerned with ground truth or sensor data, the first two enum values shall always be defined with the following rules: 48 | The first enum field value shall always use the suffix _UNKNOWN_. 49 | The second enum field value shall always use the suffix _OTHER_. 50 | 51 | [source,protobuf,linenums] 52 | ---- 53 | message EnvironmentalConditions 54 | { 55 | optional double atmospheric_pressure = 1; 56 | 57 | enum AmbientIllumination 58 | { 59 | AMBIENT_ILLUMINATION_UNKNOWN = 0; 60 | 61 | AMBIENT_ILLUMINATION_OTHER = 1; 62 | 63 | AMBIENT_ILLUMINATION_LEVEL1 = 2; 64 | } 65 | } 66 | ---- 67 | 68 | Other enum fields, especially purely technical fields, can deviate from the rules for the first two field values. 69 | -------------------------------------------------------------------------------- /content/contributing/reporting_issues.adoc: -------------------------------------------------------------------------------- 1 | ifndef::include-only-once[] 2 | :root-path: ../ 3 | include::{root-path}_config.adoc[] 4 | endif::[] 5 | [#top-reporting_issues] 6 | = Reporting issues 7 | 8 | Reporting issues is a simple way of contributing to OSI. 9 | 10 | **Prerequisites** 11 | 12 | * You have a GitHub account. 13 | 14 | **Steps** 15 | 16 | . Identify the repository that your issue relates to and open the repository on GitHub. 17 | . Create a new issue. 18 | . Select the correct issue type: 19 | Bug report:: Report an error. 20 | Feature request:: Suggest an idea for the project. 21 | Question:: Ask a question if you do not understand something or need clarification. 22 | Blank issue:: Use this issue type if no other type fits your issue. 23 | . Fill out the title and description field. 24 | Follow the instructions in the template. 25 | . Add suitable labels. 26 | . When you are done editing the fields and labels, click **Submit new issue**. 27 | 28 | **Related topics** 29 | 30 | - <<top-repositories>> -------------------------------------------------------------------------------- /content/contributing/review_author.adoc: -------------------------------------------------------------------------------- 1 | ifndef::include-only-once[] 2 | :root-path: ../ 3 | include::{root-path}_config.adoc[] 4 | endif::[] 5 | = Review guidelines for authors 6 | 7 | Code review enhances the quality of the code and reduces the likelihood of introducing new bugs in the code base. 8 | Reviewing code is a technical discussion, not an exam. 9 | It is a common effort to learn from each other. 10 | 11 | Before asking for a review, make sure your changes meet the following requirements: 12 | 13 | * Code is readable and easy to understand. 14 | * Code does not contain commented-out lines and deprecated comments. 15 | * Code contains helpful comments to be used in the reference documentation. 16 | * Variable and function names follow the naming convention. 17 | * Commit messages are meaningful and follow the convention. 18 | * All commits are signed off. 19 | 20 | **Related topics** 21 | 22 | - <<top-interface_conventions>> 23 | - <<top-guidelines_for_writing_commit_messages>> 24 | - <<top-signing_off_commits>> 25 | -------------------------------------------------------------------------------- /content/contributing/review_reviewer.adoc: -------------------------------------------------------------------------------- 1 | ifndef::include-only-once[] 2 | :root-path: ../ 3 | include::{root-path}_config.adoc[] 4 | endif::[] 5 | = Review guidelines for reviewers 6 | 7 | Code reviews can be challenging at times. 8 | Follow these suggestions when reviewing code to avoid common pitfalls: 9 | 10 | Ask questions:: 11 | What is the purpose of this change? 12 | If this requirement changes, what else would have to change? 13 | How could we make this more maintainable? 14 | 15 | Discuss in person for more detailed points:: 16 | Online comments are useful for focused technical questions. 17 | In the case of more detailed discussions, it will often be more productive to discuss the matter in person. 18 | 19 | Explain your reasons:: 20 | Sometimes it is best to both ask if there is a better alternative and at the same time justify why a problem in the code is worth fixing. 21 | Criticism with no explanation can appear confrontational. 22 | 23 | Make it about the code:: 24 | It is easy to take notes from code reviews personally, especially if we take pride in our work. 25 | It is better to have a discussion about the code than about the developer. 26 | 27 | Indicate the importance of fixes:: 28 | When offering many suggestions at once, highlight the point that not all of them need to be acted upon at once. 29 | Indicate the importance of your suggestions. 30 | This lets developers improve their work incrementally. 31 | 32 | Take the developer’s opinion into consideration:: 33 | Imposing a particular design choice based on personal preferences and with no real explanation will incentivize the developer to be passive instead of active and creative. 34 | 35 | Do not re-write, remove, or re-do all the work:: 36 | It sometimes appears easier to re-do the work yourself, which means discarding the developer's work. 37 | This can give the impression that the developer's work is worthless. 38 | It also creates additional work for the reviewer, who is effectively taking on responsibility for the code. 39 | 40 | Consider the person you are reviewing:: 41 | Developers are human beings. 42 | Consider their personality and experience when reviewing their code. 43 | 44 | Avoid confrontational and authoritative language:: 45 | The way we communicate has an impact on the receiver. 46 | Consider these two statements which communicate a problem in the code: 47 | The statement “This operation is wrong, please fix it.” is confrontational and authoritative. 48 | Instead, explain the specific error and ask the developer to review the code again. -------------------------------------------------------------------------------- /content/contributing/signing_off_commits.adoc: -------------------------------------------------------------------------------- 1 | ifndef::include-only-once[] 2 | :root-path: ../ 3 | include::{root-path}_config.adoc[] 4 | endif::[] 5 | [#top-signing_off_commits] 6 | = Signing off commits 7 | 8 | Contributing to OSI projects, it is necessary to agree to the Developer Certificate of Origin (DCO). 9 | Contributors agree to the DCO by adding a ``Signed-off-by`` statement to the commit message. 10 | 11 | ---- 12 | Signed-off-by: Firstname Lastname <email@address.com> 13 | ---- 14 | 15 | If a commit does not include the ``Signed-off-by`` statement, this commit cannot be merged into the master branch. 16 | 17 | To add a sign-off statement to a commit add ``-s`` or ``--signoff`` to the commit command: 18 | 19 | ---- 20 | git commit -m "Commit message" -s 21 | ---- 22 | 23 | 24 | **Related topics** 25 | 26 | - <<top-developer_certificate_of_origin_dco>> -------------------------------------------------------------------------------- /content/contributing/start_contributing.adoc: -------------------------------------------------------------------------------- 1 | ifndef::include-only-once[] 2 | :root-path: ../ 3 | include::{root-path}_config.adoc[] 4 | endif::[] 5 | = Getting started with contributing 6 | 7 | Before you start, familiarize yourself with {THIS_STANDARD} and how to contribute by reading this documentation and the reference documentation of {THIS_STANDARD}. 8 | 9 | You should also familiarize yourself with the following topics: 10 | 11 | * Google's _Protocol Buffers_ 12 | * _Git_ 13 | * _GitHub_ 14 | -------------------------------------------------------------------------------- /content/contributing/test_scripts.adoc: -------------------------------------------------------------------------------- 1 | ifndef::include-only-once[] 2 | :root-path: ../ 3 | include::{root-path}_config.adoc[] 4 | endif::[] 5 | = Test scripts 6 | 7 | The following collection of test scripts is designed to automate the validation and enforcement of coding standards, documentation quality, and specific syntactical conventions within a software development project. 8 | These scripts cover a broad spectrum of checks, from Python package initialization, adherence to comment standards, and validation of Doxygen documentation output, to ensuring the integrity of Protocol Buffer (.proto) files. 9 | Each script focuses on a specific aspect of the code or documentation, automating the process of identifying common errors, enforcing naming conventions, and ensuring that documentation is both accurate and adheres to defined standards. 10 | Through these automated tests, the project aims to maintain high quality in coding and documentation standards, facilitating a more reliable and efficient development process. 11 | 12 | == `\\__init__.py` 13 | 14 | This script indicates the use of the directory as a Python Package, allowing Python to consider the directory as part of a module. 15 | 16 | == `test_comment_type.py` 17 | 18 | Automates the administration of comment standards. 19 | It locates all `.proto` files using the glob module and includes different test cases inherited from `unittest.TestCase`. 20 | These test cases perform checks on the comment description's brevity, length, and existence. Additionally, it includes a utility method `convert` for transforming camel case names into uppercase snake case, ensuring high documentation and coding standards in Protocol Buffer Files. 21 | 22 | == `test_doxygen_output.py` 23 | 24 | Validates the output of Doxygen documentation files to ensure the absence of errors or issues in documentation syntax or Doxygen's interpretation of comments. 25 | It checks for hash characters `(#)`, slash triplets `(///)`, and backslash triplets `(\\\)` that might indicate documentation errors, maintaining the quality of Doxygen-generated HTML documentation. 26 | 27 | == `test_invalid_comment.py` 28 | 29 | Ensures the integrity of comments within Protocol buffer files, checking for the use of more than two consecutive forward slashes `(///)` and block comment delimiters ``(/* and */)``, which are not supported in Protocol Buffers syntax. 30 | 31 | == `test_invalid_enum.py` 32 | 33 | Checks `.proto` files for issues related to enum naming and usage, verifying that enum names follow a PascalCase naming convention and that enum types are in uppercase, ensuring adherence to naming conventions. 34 | 35 | == `test_invalid_html.py` 36 | 37 | Validates the use of HTML and Doxygen-specific comment syntax within `.proto` files, checking for incorrect usage of slashes `(/,\)`, hash `(#)` characters, `@` symbols outside of `htmlonly` sections, and ensuring that every `htmlonly` section is properly closed. 38 | 39 | == `test_invalid_message.py` 40 | 41 | Defines tests for common issues in `.proto` files, such as naming conventions and field definitions, ensuring that message names, field names, and nested message types adhere to specified naming conventions and that fields specify their multiplicity correctly. 42 | 43 | == `test_invalid_punctuation.py` 44 | 45 | Aims to ensure the absence of double underscores `(__)` in `.proto` files, indicating a formatting error when such punctuation is found. 46 | 47 | == `test_invalid_tabs.py` 48 | 49 | Prohibits the use of tab characters for indentation or alignment in `.proto` files, considering their use a formatting error. 50 | 51 | == `test_newline.py` 52 | 53 | Ensures that all Protocol Buffer `(.proto)` files end with a newline character `(\n)`, maintaining code quality and interoperability across different environments. 54 | 55 | == `test_non_ascii.py` 56 | 57 | Ensures that Protocol Buffer `(.proto)` files do not contain non-ASCII characters, checking for the presence of special characters outside the ASCII set `(eg. ä,ü,ö etc.)` and failing the test if any are found. 58 | 59 | == `test_osi_trace.py` 60 | 61 | Serves as a unit test for the `OSITrace` class, ensuring correct processing of OSI SensorView messages and their conversion into a human-readable format. 62 | 63 | == `test_rules.py` 64 | 65 | Ensures compliance with specific rules for Protocol Buffer `(.proto)` files as defined in a YAML configuration file `(rules.yml)`, checking for rule violations and providing feedback for corrections. 66 | 67 | == `test_units.py` 68 | 69 | Validates the syntax of unit documentation within Protocol Buffer (.proto) files, ensuring that units are documented correctly according to the specified syntax without any enclosing brackets or braces. 70 | -------------------------------------------------------------------------------- /content/contributing/writing_commit_messages.adoc: -------------------------------------------------------------------------------- 1 | ifndef::include-only-once[] 2 | :root-path: ../ 3 | include::{root-path}_config.adoc[] 4 | endif::[] 5 | [#top-guidelines_for_writing_commit_messages] 6 | = Guidelines for writing commit messages 7 | 8 | Apart from a sign-off message, {THIS_STANDARD} requires commit messages to follow a specific format. 9 | This format enables other people to understand the motivation behind your commits more easily. 10 | OSI enforces these requirements only for commits to protected branches. 11 | However, you should always follow these guidelines to help other people understand your commits. 12 | 13 | Commit messages shall have the following structure: 14 | 15 | ---- 16 | <type>[optional scope]: <description> 17 | 18 | [optional body] 19 | 20 | [optional footer(s)] 21 | ---- 22 | 23 | Commits can have one of the following types: 24 | 25 | fix:: 26 | Change fixes an error. 27 | These changes usually correspond to a PATCH release. 28 | 29 | feat:: 30 | Change introduces a new feature. 31 | If the change is backward compatible, it corresponds to a MINOR release. 32 | If the change is not backward compatible, it corresponds to a MAJOR release. 33 | 34 | style:: 35 | Change affects only the style, not the meaning of the code. 36 | Examples include white-space changes or code formatting. 37 | 38 | build:: 39 | Change affects the building components. 40 | Examples include changes to the CI pipeline or the project version. 41 | 42 | The scope indicates which part of OSI is affected by the commit. 43 | With OSI, commits can have one of the following scopes: 44 | 45 | code:: 46 | Change affects the OSI code. 47 | 48 | inlinedocs:: 49 | Change affects the inline documentation. 50 | 51 | docs:: 52 | Change affects the accompanying documentation. 53 | 54 | The description gives a concise summary of the change. 55 | The description shall adhere to the following rules: 56 | 57 | - Use imperative mode and present tense to indicate what happens when the change is applied. 58 | - Do not capitalize the first letter. 59 | - Do not end the description with a full stop. 60 | 61 | The optional body contains information on the motivation for the change. 62 | This includes references to GitHub issues by ID. 63 | GitHub uses these IDs to create links between the issues and the commit history. 64 | 65 | The optional footer contains a note if the changes are breaking backwards compatibility. 66 | This note starts with `BREAKING CHANGES:` followed by a concise description of what this change breaks. 67 | 68 | The following example shows a commit message meeting all requirements: 69 | 70 | ---- 71 | feat(model): Prevent empty StopTriggers 72 | 73 | refers to #23 74 | 75 | BREAKING CHANGES: StopTrigger can no longer be empty 76 | Signed-off-by: Max Mustermann <max.mustermann@email.address> 77 | ---- -------------------------------------------------------------------------------- /content/general_docs/bibliography.adoc: -------------------------------------------------------------------------------- 1 | ifndef::include-only-once[] 2 | :root-path: ../ 3 | include::{root-path}_config.adoc[] 4 | endif::[] 5 | = Bibliography 6 | bibliography::[] -------------------------------------------------------------------------------- /content/general_docs/bibliography.bib: -------------------------------------------------------------------------------- 1 | % Encoding: UTF-8 2 | 3 | @Standard{fmi2.0, 4 | title = {__{Modelica Association}__, https://github.com/modelica/fmi-standard/releases/download/v2.0.4/FMI-Specification-2.0.4.pdf[__FMI 2.0.4__^], Functional Mock-up Interface for Model Exchange and Co-Simulation 2.0.4, __2022__} 5 | } 6 | 7 | @Standard{fmi3.0, 8 | title = {__{Modelica Association}__, https://fmi-standard.org/docs/3.0.1[__FMI 3.0.1__^], Functional Mock-up Interface Specification 3.0.1, __2023__} 9 | } 10 | 11 | @Standard{ssp1.0, 12 | title = {__{Modelica Association}__, https://ssp-standard.org/publications/SSP101/SystemStructureAndParameterization101.pdf[__SSP 1.0.1__^], System Structure and Parameterization 1.0.1, __2022__} 13 | } 14 | 15 | @Standard{IEEE_754-2019, 16 | title = {https://ieeexplore.ieee.org/document/8766229[__IEEE 754-2019__^], IEEE Standard for Floating-Point Arithmetic} 17 | } 18 | 19 | @Standard{iso23150, 20 | title = {https://www.iso.org/standard/74741.html[__ISO 23150:2021__^], Road vehicles — Data communication between sensors and data fusion unit for automated driving functions — Logical interface} 21 | } 22 | 23 | @Standard{iso8601, 24 | title = {https://www.iso.org/iso-8601-date-and-time-format.html[__ISO 8601:2019__^], Date and time format } 25 | } 26 | 27 | @Standard{iso8855, 28 | title = {https://www.beuth.de/de/norm/din-iso-8855/170878818[__DIN ISO 8855:2013-11__^], Road vehicles - Vehicle dynamics and road-holding ability - Vocabulary} 29 | } 30 | 31 | @Standard{opencrg, 32 | title = {https://www.asam.net/index.php?eID=dumpFile&t=f&f=3950&token=21a7ae456ec0eb0f9ec3aee5bae3e8c9ebaea140[__ASAM OpenCRG 1.2.0__^], __2020__} 33 | } 34 | 35 | @Standard{opendrive, 36 | title = {https://www.asam.net/index.php?eID=dumpFile&t=f&f=4422&token=e590561f3c39aa2260e5442e29e93f6693d1cccd[__ASAM OpenDRIVE 1.7.0__^], __2021__} 37 | } 38 | 39 | @Standard{openscenario, 40 | title = {https://www.asam.net/index.php?eID=dumpFile&t=f&f=4908&token=ae9d9b44ab9257e817072a653b5d5e98ee0babf8[__ASAM OpenSCENARIO 1.2.0__^], __2022__} 41 | } 42 | 43 | @misc{protobuf, 44 | title = {https://developers.google.com/protocol-buffers[Protocol Buffers^]}, 45 | note = {[viewed 2008-07]} 46 | } 47 | 48 | @misc{wiki_rotation_matrix, 49 | author = {{Wikipedia}}, 50 | title = {https://en.wikipedia.org/wiki/Rotation_matrix[Rotation Matrix^]}, 51 | note = {[viewed 2022-01]} 52 | } 53 | 54 | @misc{wiki_euler_angles, 55 | author = {{Wikipedia}}, 56 | title = {https://en.wikipedia.org/wiki/Euler_angles[Euler Angles^]}, 57 | note = {[viewed 2022-01]} 58 | } 59 | 60 | @book{reuper2020, 61 | author = {Reuper, Björn}, 62 | title = {Multi-Frequency GNSS Sensor Fusion With Quality Assessment for Automotive Applications}, 63 | address = {Darmstadt, Germany}, 64 | publisher = {Technische Universität}, 65 | year = {2020} 66 | } 67 | 68 | 69 | @Comment{jabref-meta: databaseType:bibtex;} 70 | -------------------------------------------------------------------------------- /content/general_docs/changes.adoc: -------------------------------------------------------------------------------- 1 | ifndef::include-only-once[] 2 | :root-path: ../ 3 | include::{root-path}_config.adoc[] 4 | endif::[] 5 | = What has changed 6 | 7 | include::../appendix/releases/v03.07.adoc[tag=content] 8 | -------------------------------------------------------------------------------- /content/general_docs/conventions.adoc: -------------------------------------------------------------------------------- 1 | ifndef::include-only-once[] 2 | :root-path: ../ 3 | include::{root-path}_config.adoc[] 4 | endif::[] 5 | = Conventions 6 | 7 | == Units 8 | 9 | Every field has its own unit that is defined in the proto files. 10 | For more information, see <<top-commenting_on_fields_and_enums, the example in the contribution guidelines.>> 11 | 12 | [#sec-273d9649-afab-45d3-b6c9-73c0e64971a0] 13 | include::{asciidoc-resources}/modal_verbs.adoc[leveloffset=+1] 14 | 15 | == Typographic conventions 16 | 17 | This documentation uses the following typographical conventions: 18 | 19 | [#tab-typographical-conventions] 20 | .Typographical conventions 21 | [%header, cols=2*] 22 | |=== 23 | |Mark-up |Definition 24 | |`Code elements` |This format is used for code elements, such as technical names of classes and attributes, as well as attribute values. 25 | | Technical concepts |This format is used for technical concepts. Technical concepts as opposed to code elements do not have a special highlighting. 26 | |```[blue]#Code snippets#``` |This format is used for excerpts of code that serve as an example for implementation. 27 | |_Terms_ |This format is used to introduce glossary terms, new terms and to emphasize terms. 28 | |`[green]#Mathematical elements#` |This format is used for calculations and mathematical elements. 29 | |`[green]#<element>#` |This describes a tag for an XML element 30 | |`@attribute` |The "@" identifies an attribute of an XML element. 31 | |=== -------------------------------------------------------------------------------- /content/general_docs/deliverables.adoc: -------------------------------------------------------------------------------- 1 | ifndef::include-only-once[] 2 | :root-path: ../ 3 | include::{root-path}_config.adoc[] 4 | endif::[] 5 | = Deliverables 6 | 7 | The following deliverables are provided for {THIS_STANDARD}: 8 | 9 | * User guide, that is, this document (partly normative) 10 | * .proto files (normative) 11 | * xref:gen:index.adoc[Doxygen reference documentation] (not normative) 12 | * OSMP packaging (OSMP packaging has its own version number, but is compatible with the version of {THIS_STANDARD}.) 13 | 14 | **Related topics** 15 | 16 | - <<top-normative_and_non_normative_statements>> 17 | - <<top-repositories>> -------------------------------------------------------------------------------- /content/general_docs/foreword.adoc: -------------------------------------------------------------------------------- 1 | ifndef::include-only-once[] 2 | :root-path: ../ 3 | include::{root-path}_config.adoc[] 4 | endif::[] 5 | = Foreword 6 | 7 | The {THIS_STANDARD} (Open Simulation Interface) is a specification for interfaces between models and components of a distributed simulation. 8 | OSI is strongly focused on the environmental perception of automated driving functions. 9 | 10 | The complexity of automated driving functions is rapidly increasing, which means the requirements for testing and development methods are growing too. 11 | Testing in virtual environments makes it possible to control and reproduce environmental conditions. 12 | 13 | To enable the widespread use of driving simulators for developers of functions, generic and standardized interfaces are needed for the connection between the function-development framework and the simulation environment. 14 | OSI permits easy and straight-forward compatibility between automated driving functions and the variety of driving-simulation frameworks that are available. 15 | OSI addresses the emerging standard ISO 23150 cite:[iso23150] for a real sensors’ standardized communication interface. 16 | OSI defines generic interfaces to ensure the modularity, integrability, and interchangeability of the individual components. 17 | 18 | The vision is to make it possible to connect any automated driving function to any driving simulator and emerging new hardware sensor generations using a standardized ISO 23150 cite:[iso23150] interface. 19 | This will simplify integration, significantly strengthening the accessibility and usefulness of virtual testing in the process. 20 | 21 | -------------------------------------------------------------------------------- /content/general_docs/glossary.adoc: -------------------------------------------------------------------------------- 1 | ifndef::include-only-once[] 2 | :root-path: ../ 3 | include::{root-path}_config.adoc[] 4 | endif::[] 5 | [glossary] 6 | = Terms and definitions 7 | 8 | //Writing style adopted from https://www.iso.org/glossary.html 9 | Co-simulation:: 10 | Type of Functional Mockup Unit (FMU). + 11 | Co-simulation FMUs contain their own numerical solver. 12 | This importing tool sets the FMU inputs, asks the FMU to step forward a given time, and reads the FMU output after the step is completed. 13 | With OSMP, models are packaged as valid _FMI-2.0 FMU for co-simulation_. + 14 | + 15 | See also: https://fmi-standard.org/ 16 | 17 | Ego vehicle:: 18 | Externally controlled vehicle used for scenario descriptions. + 19 | For evaluation of automated driving systems, the ego vehicle is the vehicle that is controlled by the system-under-test. 20 | For human-driver experiments, the ego vehicle is the vehicle that is driven by the human driver. 21 | 22 | Environmental effect model:: 23 | Information set that deals with effects and phenomena caused by, for example, shadows and occlusions, weather effects, the physics of a sensor, or the pre-processing of raw sensor data. 24 | An environmental effect model has a `SensorView` message as input, which comes from the environment simulation, and a `SensorView` message as output. 25 | The output is sent to the sensor model. 26 | 27 | FMI (Functional Mockup Interface):: 28 | Free standard that defines a container and an interface to exchange dynamic models using a combination of XML files, binaries, and C code zipped into a single file. + 29 | + 30 | See also: https://fmi-standard.org/ 31 | 32 | FMU (Functional Mockup Unit):: 33 | 34 | Simulation model that adheres to the FMI standard. + 35 | + 36 | See also: https://fmi-standard.org/ 37 | 38 | GroundTruth:: 39 | Information set that describes the whole simulated environment around any simulated vehicle. 40 | It is based on data available to the simulation environment. 41 | 42 | Logical model:: 43 | Logical models consume `SensorData` messages and produce `SensorData` messages. 44 | 45 | Examples: 46 | - Sensor-fusion model: Combines the output of multiple sensor models to produce data with less uncertainty 47 | - Fault-injection model which, contrary to a sensor-fusion model, may be used to increase uncertainties 48 | 49 | Object coordinate system:: 50 | Local coordinate system whose origin may be identical to the center of the object's bounding box. 51 | If the origin is not identical to the center of the object's bounding box, the object documentation provides the actual definition. 52 | 53 | OSI (Open Simulation Interface):: 54 | Specification for interfaces between models and components of a distributed simulation. 55 | OSI has a strong focus on environmental perception of automated driving functions. 56 | It also specifies interfaces for modeling traffic participants. 57 | 58 | OSMP (OSI Sensor Model Packaging):: 59 | Specifies how models that use Open Simulation Interface (OSI) in simulation environments are packaged in accordance with the Functional Mock-up Interface 2.0 (FMI 2.0). 60 | 61 | Sensor coordinate system:: 62 | Coordinate system for all entities that are part of `SensorData`. 63 | The origin is the mounting position of the physical sensor or a virtual mounting position, depending on the OSI message. 64 | 65 | Sensor model:: 66 | From OSI's perspective, a sensor model refers to the part of a sensor system model that includes processing algorithms at an object detection level. 67 | Sensor models consume `SensorView` messages and produce `SensorData` messages. 68 | Sensor model output does not represent raw data but detected features or classified objects. 69 | 70 | SensorView:: 71 | Information set that is derived from ground truth and used as input to sensor models, environmental effect models, or traffic participant models. 72 | 73 | Traffic participant model:: 74 | Information set that models the dynamic behavior of moving objects by deciding how to change position, orientation, and other states of the dedicated moving object. 75 | To do this, it reacts on input given by `SensorView` and `TrafficCommand` resulting in `TrafficUpdate` as output. 76 | 77 | Global coordinate system:: 78 | Coordinate system for all entities that are part of ground truth. 79 | The global coordinate system is an inertial x/y/z-coordinate system. 80 | The origin is the global reference point that is determined by the environment simulation. 81 | This reference point may be derived from map data or other considerations. -------------------------------------------------------------------------------- /content/general_docs/osi_repos.adoc: -------------------------------------------------------------------------------- 1 | ifndef::include-only-once[] 2 | :root-path: ../ 3 | include::{root-path}_config.adoc[] 4 | endif::[] 5 | [#top-repositories] 6 | = {THIS_STANDARD_TITLE} repositories 7 | 8 | {THIS_STANDARD} is an open-source standardization project. 9 | OSI and its supporting tools are developed publicly on GitHub. 10 | 11 | The source code and documentation for OSI and OSI-related tools are spread over several repositories: 12 | 13 | https://github.com/OpenSimulationInterface/open-simulation-interface[open-simulation-interface]:: 14 | Main repository containing the interface description based on Google's Protocol Buffers, including helper scripts and test scripts. Hosts the .proto files as well as the https://opensimulationinterface.github.io/open-simulation-interface/[Doxygen reference documentation]. 15 | 16 | https://github.com/OpenSimulationInterface/osi-documentation[osi-documentation]:: Source for the OSI user guide sources and hosts the https://opensimulationinterface.github.io/osi-documentation/[{THIS_STANDARD} user guide]. 17 | 18 | https://github.com/OpenSimulationInterface/osi-sensor-model-packaging[osi-sensor-model-packaging]:: Packaging specification for OSI models used in FMI 2.0 cite:[fmi2.0] simulation environments, including examples. 19 | 20 | https://github.com/OpenSimulationInterface/proto2cpp[proto2cpp]:: Doxygen filter for creating the reference documentation from OSI .proto files. -------------------------------------------------------------------------------- /content/general_docs/statements.adoc: -------------------------------------------------------------------------------- 1 | ifndef::include-only-once[] 2 | :root-path: ../ 3 | include::{root-path}_config.adoc[] 4 | endif::[] 5 | [#top-normative_and_non_normative_statements] 6 | = Normative and non-normative statements 7 | 8 | 9 | This specification uses a standard information structure. 10 | The following rules apply regarding normativity of the different sections: 11 | 12 | * Statements expressed as requirements, permissions, or prohibitions according to the use of modal verbs, as defined in <<sec-273d9649-afab-45d3-b6c9-73c0e64971a0, Section 1.5.2, "Modal verbs">>, are normative. 13 | * Rules in "Rules" sections are normative. 14 | * .proto files are normative. 15 | * Examples, use case descriptions, and instructions are non-normative. 16 | * Doxygen reference documentation is non-normative. -------------------------------------------------------------------------------- /content/general_docs/versioning.adoc: -------------------------------------------------------------------------------- 1 | ifndef::include-only-once[] 2 | :root-path: ../ 3 | include::{root-path}_config.adoc[] 4 | endif::[] 5 | = Versioning and compatibility 6 | 7 | The version number is defined in `InterfaceVersion::version_number` in `osi_version.proto` as the field's default value. 8 | 9 | OSI uses https://semver.org/[Semantic Versioning^]. 10 | 11 | Major:: 12 | A change in the major version makes the code and recorded proto messages incompatible. 13 | + 14 | Major changes include: 15 | + 16 | * An existing field with a number changing its meaning. 17 | Example: `optional double field = 1;` changes to `repeated double field = 1;`. 18 | * Changing the definition of units or the interpretation of a field. 19 | * Deleting a field and reusing the field number. 20 | * Changing the technology from Protocol Buffers to FlatBuffers. 21 | 22 | Minor:: 23 | A change in the minor version indicates there is still compatibility with previously recorded files. 24 | However, the code needs fixing. 25 | + 26 | Minor changes include: 27 | + 28 | * Renaming a field without changing the field number. 29 | * Changing the names of messages. 30 | * Adding a new field in a message without changing the numbering of other fields. 31 | 32 | Patch:: 33 | Both recorded files and code still have compatibility. 34 | + 35 | Patches include: 36 | + 37 | * File or folder structure that does not affect integration of the code in other projects. 38 | * Changing or adding comments. 39 | * Clarifying text passages explaining the message content. 40 | -------------------------------------------------------------------------------- /content/general_standard/relations_to_other_standards.adoc: -------------------------------------------------------------------------------- 1 | ifndef::include-only-once[] 2 | :root-path: ../ 3 | include::{root-path}_config.adoc[] 4 | endif::[] 5 | = Relationships with other standards 6 | 7 | == Positioning of {THIS_STANDARD} within ASAM activities 8 | 9 | {THIS_STANDARD} (Open Simulation Interface) is part of the ASAM simulation standards that focus on simulation data for the automotive environment. 10 | Next to {THIS_STANDARD}, ASAM provides other standards for the simulation domain, like OpenDRIVE cite:[opendrive], OpenSCENARIO cite:[openscenario] and OpenCRG cite:[opencrg]. 11 | 12 | OpenDRIVE defines a storage format for the static description of road networks. 13 | In combination with OpenCRG it is possible to add very detailed road surface descriptions to the road network. 14 | OpenDRIVE and OpenCRG only contain static content. 15 | To add dynamic content, OpenSCENARIO is needed. 16 | Combining all three standards provides a scenario-driven description of traffic simulation that contains static and dynamic content. 17 | 18 | == References to other standards 19 | 20 | * DIN ISO 8855:2013-11: Road vehicles - Vehicle dynamics and road-holding ability - Vocabulary cite:[iso8855] 21 | * ISO 23150: Road vehicles — Data communication between sensors and data fusion unit for automated driving functions — Logical interface cite:[iso23150] 22 | * FMI 2.0: https://github.com/modelica/fmi-standard/releases/download/v2.0.4/FMI-Specification-2.0.4.pdf[Functional Mock-up Interface for Model Exchange and Co-Simulation 2.0.4] cite:[fmi2.0] 23 | * FMI 3.0: https://fmi-standard.org/docs/3.0.1/[Functional Mock-up Interface Specification 3.0.1] cite:[fmi3.0] 24 | * SSP 1.0: https://ssp-standard.org/publications/SSP101/SystemStructureAndParameterization101.pdf[System Structure and Parameterization 1.0.1] cite:[ssp1.0] 25 | -------------------------------------------------------------------------------- /content/index.adoc: -------------------------------------------------------------------------------- 1 | :root-path: 2 | include::{root-path}_config.adoc[] 3 | = {THIS_STANDARD} (Open Simulation Interface) 4 | 5 | [IMPORTANT] 6 | .Disclaimer 7 | ==== 8 | This document is the copyrighted property of ASAM e.V. 9 | Any use is limited to the scope described in the https://www.asam.net/license[license terms]. 10 | ==== 11 | 12 | ifndef::use-antora-rules[] 13 | :asciidoc-resources: ../{asciidoc-resources} 14 | <<< 15 | toc::[] 16 | 17 | endif::[] 18 | 19 | ifdef::use-antora-rules[] 20 | [preface] 21 | include::./general_docs/foreword.adoc[leveloffset=+1] 22 | endif::[] 23 | 24 | ifndef::use-antora-rules[] 25 | 26 | [foreword] 27 | include::./general_docs/foreword.adoc[leveloffset=+1] 28 | 29 | == Introduction 30 | 31 | include::./general_docs/changes.adoc[leveloffset=+2] 32 | 33 | include::./general_docs/deliverables.adoc[leveloffset=+2] 34 | 35 | include::./general_docs/osi_repos.adoc[leveloffset=+2] 36 | 37 | include::./general_docs/statements.adoc[leveloffset=+2] 38 | 39 | include::./general_docs/conventions.adoc[leveloffset=+2] 40 | 41 | include::./general_docs/versioning.adoc[leveloffset=+2] 42 | 43 | include::./general_standard/relations_to_other_standards.adoc[leveloffset=+2] 44 | 45 | // START: including the documentation of other osi repositories 46 | :imagesdir: {doc_open_simulation_interface}images 47 | include::{doc_open_simulation_interface}open-simulation-interface_user_guide.adoc[leveloffset=+1] 48 | 49 | :imagesdir: {doc_osi-sensor-model-packaging}images 50 | include::{doc_osi-sensor-model-packaging}osi-sensor-model-packaging_spec.adoc[leveloffset=+1] 51 | 52 | :imagesdir: ./images 53 | // osi-validation and osi-visualizer are considered supplementary tooling that is not normative. They are therefore not part of the ASAM standard release. 54 | // include::./osi-validation/doc/osi-validator_user_guide.adoc[leveloffset=+1,opts=optional] 55 | 56 | // include::./osi-visualizer/doc/osi-visualizer_user_guide.adoc[leveloffset=+1,opts=optional] 57 | 58 | // proto2cpp is an tooling that is internally used to create the DOXYGEN documentation. It doc shall not the part of the OSI specification. 59 | // include::./proto2cpp/doc/proto2ccp_user_guide.adoc[leveloffset=+1] 60 | 61 | // END: including the documentation of other osi repositories 62 | 63 | == Contributing to ASAM OSI 64 | 65 | include::./contributing/start_contributing.adoc[leveloffset=+2] 66 | 67 | include::./contributing/reporting_issues.adoc[leveloffset=+2] 68 | 69 | === Contributing changes 70 | 71 | include::./contributing/licensing.adoc[leveloffset=+3] 72 | 73 | include::./contributing/dco.adoc[leveloffset=+3] 74 | 75 | include::./contributing/signing_off_commits.adoc[leveloffset=+3] 76 | 77 | include::./contributing/writing_commit_messages.adoc[leveloffset=+3] 78 | 79 | include::./contributing/contribution_rules.adoc[leveloffset=+3] 80 | 81 | include::./contributing/naming_conventions.adoc[leveloffset=+3] 82 | 83 | include::./contributing/branching_member.adoc[leveloffset=+3] 84 | 85 | include::./contributing/forking_no_member.adoc[leveloffset=+3] 86 | 87 | //include::./contributing/contributing_docs.adoc[leveloffset=+3] 88 | 89 | include::./contributing/commenting_messages.adoc[leveloffset=+3] 90 | 91 | include::./contributing/commenting_fields_enums.adoc[leveloffset=+3] 92 | 93 | include::./contributing/creating_references.adoc[leveloffset=+3] 94 | 95 | //include::./contributing/creating_images.adoc[leveloffset=+3] 96 | 97 | === Reviewing contributions 98 | 99 | include::./contributing/review_author.adoc[leveloffset=+3] 100 | 101 | include::./contributing/review_reviewer.adoc[leveloffset=+3] 102 | 103 | 104 | include::./general_docs/glossary.adoc[leveloffset=+1] 105 | 106 | 107 | [bibliography] 108 | include::./general_docs/bibliography.adoc[leveloffset=+1] 109 | 110 | [appendix] 111 | == Release Notes 112 | :sectnums!: 113 | 114 | include::./appendix/releases/v03.07.adoc[leveloffset=+2] 115 | include::./appendix/releases/v03.06.adoc[leveloffset=+2] 116 | include::./appendix/releases/v03.05.adoc[leveloffset=+2] 117 | include::./appendix/releases/v03.04.adoc[leveloffset=+2] 118 | include::./appendix/releases/v03.03.01.adoc[leveloffset=+2] 119 | include::./appendix/releases/v03.03.00.adoc[leveloffset=+2] 120 | include::./appendix/releases/v03.02.adoc[leveloffset=+2] 121 | include::./appendix/releases/v03.01.02.adoc[leveloffset=+2] 122 | include::./appendix/releases/v03.01.01.adoc[leveloffset=+2] 123 | include::./appendix/releases/v03.01.00.adoc[leveloffset=+2] 124 | include::./appendix/releases/v03.00.01.adoc[leveloffset=+2] 125 | include::./appendix/releases/v03.00.00.adoc[leveloffset=+2] 126 | include::./appendix/releases/v02.02.01.adoc[leveloffset=+2] 127 | include::./appendix/releases/v02.02.00.adoc[leveloffset=+2] 128 | include::./appendix/releases/v02.01.adoc[leveloffset=+2] 129 | include::./appendix/releases/v02.00.adoc[leveloffset=+2] 130 | 131 | endif::[] 132 | -------------------------------------------------------------------------------- /docker-compose.yml: -------------------------------------------------------------------------------- 1 | version: "2" 2 | 3 | services: 4 | asciidoctor: 5 | image: asciidoctor/docker-asciidoctor:1 6 | volumes: 7 | - .:/documents 8 | working_dir: /documents 9 | entrypoint: asciidoctor -D . --failure-level WARN -r asciidoctor-bibtex -r asciidoctor-diagram -a mathjax --trace --backend=html5 content/index.adoc -o open-simulation-interface_localbuild.html -------------------------------------------------------------------------------- /local_build_tools/asciidoctor.bat: -------------------------------------------------------------------------------- 1 | @ECHO OFF 2 | docker-compose up -d 3 | PAUSE -------------------------------------------------------------------------------- /local_build_tools/compose.yml: -------------------------------------------------------------------------------- 1 | version: "2" 2 | 3 | services: 4 | asciidoctor: 5 | image: asciidoctor/docker-asciidoctor 6 | volumes: 7 | - ../:/documents 8 | - ../../open-simulation-interface:/open-simulation-interface 9 | - ../../osi-sensor-model-packaging:/osi-sensor-model-packaging 10 | entrypoint: asciidoctor -a local=true --failure-level WARN -r asciidoctor-kroki -a mathjax -r asciidoctor-bibtex --trace content/index.adoc -o local_build_tools/HTML_content_local_build.html -------------------------------------------------------------------------------- /local_build_tools/windows_convert_symlinks(ADMIN).bat: -------------------------------------------------------------------------------- 1 | @ECHO OFF 2 | SET Targetpath=..\.antora\modules\specification 3 | SET Symlinkroot=..\..\.. 4 | 5 | mklink /D %Targetpath%\images %Symlinkroot%\content\_static\images 6 | 7 | mklink /D %Targetpath%\pages %Symlinkroot%\content 8 | 9 | @REM mklink /D %Targetpath%\partials %Symlinkroot%\_additional_content 10 | 11 | @REM mklink /D %Targetpath%\attachments %Symlinkroot%\_attachments 12 | 13 | PAUSE -------------------------------------------------------------------------------- /spelling/abbreviations.txt: -------------------------------------------------------------------------------- 1 | OSI 2 | osi 3 | FMI 4 | fmi 5 | FMU 6 | fmu 7 | iOS 8 | CI 9 | ci -------------------------------------------------------------------------------- /spelling/file_endings.txt: -------------------------------------------------------------------------------- 1 | xml 2 | cpp 3 | proto 4 | yml 5 | pb 6 | py 7 | txth 8 | cmake 9 | CMake 10 | svg 11 | png 12 | jpg 13 | jpeg 14 | pyc 15 | ce 16 | ee 17 | cc 18 | txt 19 | zip 20 | tar 21 | deb 22 | sqlite -------------------------------------------------------------------------------- /spelling/file_names.txt: -------------------------------------------------------------------------------- 1 | datarecording 2 | detectedtrafficsign 3 | detectedtrafficlight 4 | detectedroadmarking 5 | detectedobject 6 | detectedoccupant 7 | detectedlane 8 | hostvehicledata 9 | trafficsign 10 | trafficlight 11 | roadmarking 12 | featuredata 13 | FeatureData 14 | sensorviewconfiguration 15 | sensorspecific 16 | kTypeGhost 17 | modelDescription 18 | doxyfile -------------------------------------------------------------------------------- /spelling/function_names.txt: -------------------------------------------------------------------------------- 1 | calculatedParameter 2 | enum 3 | enums 4 | proj 5 | params -------------------------------------------------------------------------------- /spelling/general_names.txt: -------------------------------------------------------------------------------- 1 | Brabham 2 | Coulthard -------------------------------------------------------------------------------- /spelling/human_names.txt: -------------------------------------------------------------------------------- 1 | Chacon 2 | van 3 | Straub 4 | Carlo 5 | Driesten -------------------------------------------------------------------------------- /spelling/spelling_wordlist.txt: -------------------------------------------------------------------------------- 1 | Atlassian 2 | atlassian 3 | modularity 4 | integrability 5 | behaviour 6 | conformant 7 | DoStep 8 | tunable 9 | designator 10 | osivalidator 11 | doxygen 12 | validator 13 | mkdir 14 | linux 15 | whitespace 16 | centerline 17 | codebase 18 | SensorModels 19 | LogicModels 20 | Dockerfile 21 | protobuf 22 | lidar 23 | config 24 | cd 25 | nvidia 26 | NVidia 27 | parameterization 28 | repo 29 | graphviz 30 | groundtruth 31 | GroundTruth 32 | sensorview 33 | SensorView 34 | sensordata 35 | SensorData 36 | incentivize 37 | github 38 | rebase 39 | sensormodel 40 | sensormodels 41 | logicmodels 42 | detections 43 | innoviz 44 | Nvidia 45 | unicity 46 | subfield 47 | subfields 48 | synthetized 49 | precessed 50 | assignees 51 | assignee 52 | timestep 53 | timesteps --------------------------------------------------------------------------------