diff --git a/.antora/modules/specification/images.adoc b/.antora/modules/specification/images.adoc deleted file mode 100644 index b753fb0b..00000000 --- a/.antora/modules/specification/images.adoc +++ /dev/null @@ -1 +0,0 @@ -../../../content/images \ No newline at end of file diff --git a/.antora/modules/specification/images/overview_open_x.png b/.antora/modules/specification/images/overview_open_x.png new file mode 100644 index 00000000..990ec256 Binary files /dev/null and b/.antora/modules/specification/images/overview_open_x.png differ diff --git a/.antora/modules/specification/pages.adoc b/.antora/modules/specification/pages.adoc deleted file mode 100644 index f0bfb077..00000000 --- a/.antora/modules/specification/pages.adoc +++ /dev/null @@ -1 +0,0 @@ -../../../content \ No newline at end of file diff --git a/.antora/modules/specification/pages/_config.adoc b/.antora/modules/specification/pages/_config.adoc new file mode 100644 index 00000000..170830b5 --- /dev/null +++ b/.antora/modules/specification/pages/_config.adoc @@ -0,0 +1,37 @@ + +// This file contains AsciiDoc attributes that shall be used in every AsciiDoc file. +// NOTE: Its content is only applied for Asciidoctor! +// If the same attribute is defined in the antora.yml (without @), the antora.yml definition takes precedence for Antora. + +ifndef::root-path[:root-path: ./] + +:partials-path: {root-path}../_additional_content +:asciidoc-resources: ../asciidoc-resources +:appendix-caption: Annex + +// ifndef::use-antora-rules,include-only-once[] +ifndef::include-only-once[] +:GLO_VAR_STA_ASAM_OpenCRG: ASAM OpenCRG +:GLO_VAR_STA_ASAM_OpenDRIVE: ASAM OpenDRIVE +:GLO_VAR_STA_ASAM_OpenLABEL: ASAM OpenLABEL +:GLO_VAR_STA_ASAM_OpenODD: ASAM OpenODD +:GLO_VAR_STA_ASAM_OSI: ASAM OSI +:GLO_VAR_STA_ASAM_OpenSCENARIO: ASAM OpenSCENARIO +:GLO_VAR_STA_ASAM_OpenXOntology: ASAM OpenXOntology +:GLO_VAR_STA_BSI_PAS_1883: BSI PAS 1883 +:revnumber: --localbuild-- +:revdate: {docdate} +:bibtex-file: content/bibliography.bib +// Replace PLACEHOLDER with the name of your standard, e.g. OpenDRIVE +:THIS_STANDARD: ASAM OpenMATERIAL +:imagesdir: {root-path}/_images +:include-only-once: true +endif::[] + +ifndef::use-antora-rules[] +include::{asciidoc-resources}/preamble.adoc[] +endif::[] + +ifdef::env-gitlab[] +:relfilesuffix: .adoc +endif::[] diff --git a/.antora/modules/specification/pages/_images/overview_open_x.png b/.antora/modules/specification/pages/_images/overview_open_x.png new file mode 100644 index 00000000..990ec256 Binary files /dev/null and b/.antora/modules/specification/pages/_images/overview_open_x.png differ diff --git a/.antora/modules/specification/pages/bibliography.adoc b/.antora/modules/specification/pages/bibliography.adoc new file mode 100644 index 00000000..acf5bf2a --- /dev/null +++ b/.antora/modules/specification/pages/bibliography.adoc @@ -0,0 +1,3 @@ += Bibliography +[bibliography] +bibliography::[] \ No newline at end of file diff --git a/.antora/modules/specification/pages/bibliography.bib b/.antora/modules/specification/pages/bibliography.bib new file mode 100644 index 00000000..0ac159ce --- /dev/null +++ b/.antora/modules/specification/pages/bibliography.bib @@ -0,0 +1,47 @@ +% Encoding: UTF-8 + +@Standard{ocr, + title = {https://www.asam.net/index.php?eID=dumpFile&t=f&f=3950&token=21a7ae456ec0eb0f9ec3aee5bae3e8c9ebaea140[__ASAM OpenCRG__^], __1.2.0__} +} + +@Standard{osc, + title = {https://www.asam.net/index.php?eID=dumpFile&t=f&f=4908&token=ae9d9b44ab9257e817072a653b5d5e98ee0babf8[__ASAM OpenSCENARIO^], __1.2.0__} +} + +@Standard{iso3166-1, + title = {https://www.iso.org/standard/72482.html[__ISO 3166-1:2020__^], Codes for the representation of names of countries and their subdivisions, Part 1: Country code} +} + +@Standard{iso3166-2, + title = {https://www.iso.org/standard/72483.html[__ISO 3166-2:2020__^], Codes for the representation of names of countries and their subdivisions, Part 2: Country subdivision code} +} + +@Standard{iso8601, + title = {https://www.iso.org/iso-8601-date-and-time-format.html[__ISO 8601:2019__^], Date and time format} +} + +@Standard{iso8855, + title = {https://www.iso.org/standard/51180.html[__ISO 8855:2011__^], Road vehicles — Vehicle dynamics and road-holding ability, Vocabulary} +} + +@Standard{iso19111, + title = {https://www.iso.org/standard/74039.html[__ISO 19111:2019__^], Geographic information, Referencing by coordinates} +} + +@Standard{omguml, + title = {__OMG®️__, https://www.omg.org/spec/UML/2.5.1/About-UML[__Unified Modeling Language®️ (OMG UML®️)__^], __2.5.1__} +} + +@Standard{w3cxml, + title = {__W3C__, https://www.w3.org/TR/2008/REC-xml-20081126[__Extensible Markup Language (XML)__^], __1.0 (Fifth Edition)__} +} + +@Standard{w3cxmlschema, + title = {__W3C__, https://www.w3.org/TR/xmlschema-1[__XML Schema Part 1__^], __Structures Second Edition__} +} + +@misc{EPSG, + author = {EPSG.io}, + title = {https://epsg.io[Coordinate Systems Worldwide^]}, + note = {[viewed 2024-03-18]} +} diff --git a/.antora/modules/specification/pages/general_docs/abbreviations.adoc b/.antora/modules/specification/pages/general_docs/abbreviations.adoc new file mode 100644 index 00000000..f985e7a6 --- /dev/null +++ b/.antora/modules/specification/pages/general_docs/abbreviations.adoc @@ -0,0 +1,21 @@ +[#top-abbreviations-abbreviations] += Abbreviations + +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] + +ASAM:: +Association for Standardization of Automation and Measuring Systems + +ECU:: +Electronic Control Unit + +UML:: +Unified Modeling Language + +XML:: +Extensible Markup Language + +> Update as needed \ No newline at end of file diff --git a/.antora/modules/specification/pages/general_docs/backward_compatibility.adoc b/.antora/modules/specification/pages/general_docs/backward_compatibility.adoc new file mode 100644 index 00000000..37387a04 --- /dev/null +++ b/.antora/modules/specification/pages/general_docs/backward_compatibility.adoc @@ -0,0 +1,11 @@ +[#top-backward_compatibility-backward_compatibility] += Backward compatibility + +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] + +{THIS_STANDARD} is backwards compatible with {THIS_STANDARD} + + diff --git a/.antora/modules/specification/pages/general_docs/foreword.adoc b/.antora/modules/specification/pages/general_docs/foreword.adoc new file mode 100644 index 00000000..577b323d --- /dev/null +++ b/.antora/modules/specification/pages/general_docs/foreword.adoc @@ -0,0 +1,17 @@ +[#top-preface-foreword] += Foreword + +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] + +ASAM e.V. (Association for Standardization of Automation and Measuring Systems) is a non-profit organization that promotes standardization of tool chains in automotive development and testing. +Our members are international car manufacturers, suppliers, tool vendors, engineering service providers, and research institutes. +ASAM standards are developed by experts from our member companies and are based on real use cases. +ASAM is the legal owner of these standards and is responsible for their distribution and marketing. + +ASAM standards span a wide range of use cases in automotive development, test, and validation. +They define file formats, data models, protocols, and interfaces. +The standards enable easy exchange of data and tools within and across tool chains. +They are applied worldwide. diff --git a/.antora/modules/specification/pages/general_docs/introduction.adoc b/.antora/modules/specification/pages/general_docs/introduction.adoc new file mode 100644 index 00000000..e8dfc80f --- /dev/null +++ b/.antora/modules/specification/pages/general_docs/introduction.adoc @@ -0,0 +1,79 @@ +[#top-preface-introduction] += Introduction + +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] + +== Overview +Overview of {THIS_STANDARD}. + +== Conventions and notations + +[#sec-modal-verbs] +=== Modal verbs + +To ensure compliance with the {THIS_STANDARD} specification, users need to be able to distinguish between requirements, recommendations, permissions, possibilities and capabilities, and external constraints. + +The following rules for using modal verbs apply: + +[#tab-modal-verbs] +.Verbal forms for expressions of provisions +[%header, cols="20, 15, 65"] +|=== +|Provision |Verbal form |Definition +|Requirement |shall, shall not |A requirement conveys objectively verifiable criteria to be fulfilled and from which no deviation is permitted if conformance with the document is to be claimed. +|Recommendation |should, should not |A recommendation conveys a suggested possible choice or course of action deemed to be particularly suitable without necessarily mentioning or excluding others. +|Permission |may |A permission conveys consent or liberty (or opportunity) to do something. +|Possibility and capability |can, cannot |A possibility conveys expected or conceivable material, physical or causal outcome. + + A capability conveys the ability, fitness, or quality necessary to do or achieve a specified thing. +|External constraint |must |An external constraint or obligation on the user of the document, for example laws of nature or particular conditions existing in some countries or regions, that is not stated as a provision of the document. + External constraints are not requirements of the document. + They are given for the information of the user. +|=== + +[#sec-normative-and-informative-content] +=== Normative and informative content + +Content in this specification can be normative or informative. +The sections listed in <> are normative or informative per definition. +Further informative content is shown in table <>. + +[#tab-normative-informative-content] +.Normative and informative sections +[%header, cols=2*] +|=== +|Section |Indication +|Foreword |Informative +|Introduction |Informative +|Scope |Normative +|Normative references |Informative +|Terms and definitions |Normative +|Abbreviations |Normative +|Backward compatibility |Normative +|First to last specification-specific section |Normative +|Annexes |Annexes can be normative or informative. The annex heading contains the indication "(normative)" or "(informative)". +|Bibliography |Informative +|=== + +All other sections in this specification are normative. + +[#tab-informative-text-components] +.Informative text components +[%header, cols="30, 70"] +|=== +|Text components |Hints +|Notes |The document shall be usable without notes. +|Footnotes |The document shall be usable without footnotes. +|Examples |The document shall be usable without examples. +|Sequence diagrams |The document shall be usable without sequence diagrams. +|=== + +Notes, footnotes, and examples shall not contain requirements or any information considered indispensable for the use of the document, for example, instructions or permission. + +== Deliverables + +The following deliverables are provided for {THIS_STANDARD}: + +> Define the deliverables of this project here diff --git a/.antora/modules/specification/pages/general_docs/normative_references.adoc b/.antora/modules/specification/pages/general_docs/normative_references.adoc new file mode 100644 index 00000000..583851fb --- /dev/null +++ b/.antora/modules/specification/pages/general_docs/normative_references.adoc @@ -0,0 +1,25 @@ +[#top-normative_references-normative_references] += Normative references + +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] + +The following documents are referred to in the text in such a way that some or all of their content constitutes requirements of this document. +For dated references, only the edition cited applies. +For undated references, the latest edition of the referenced document (including any amendments) applies. + +Standards referenced in this section are normative in such a way that parts or the whole standard shall be applied when implementing the referenced functionality. +Standards referenced in this section shall be cited normatively in the text. + +* {GLO_VAR_STA_ASAM_OpenCRG} cite:[ocr] +* ASAM OpenSCENARIO cite:[osc] +* ISO 3166-1 cite:[iso3166-1] +* ISO 3166-2 cite:[iso3166-2] +* ISO 8855 cite:[iso8855] +* ISO 8601 cite:[iso8601] +* ISO 19111 cite:[iso19111] +* OMG® UML 2.5.1 cite:[omguml] +* W3C XML cite:[w3cxml] +* W3C XML Schema cite:[w3cxmlschema] diff --git a/.antora/modules/specification/pages/general_docs/scope.adoc b/.antora/modules/specification/pages/general_docs/scope.adoc new file mode 100644 index 00000000..bb018962 --- /dev/null +++ b/.antora/modules/specification/pages/general_docs/scope.adoc @@ -0,0 +1,11 @@ +[#top-scope-scope] += Scope + +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] + +{THIS_STANDARD} specifies ... + +> Define the scope of this document/standard \ No newline at end of file diff --git a/.antora/modules/specification/pages/index.adoc b/.antora/modules/specification/pages/index.adoc new file mode 100644 index 00000000..3029fc78 --- /dev/null +++ b/.antora/modules/specification/pages/index.adoc @@ -0,0 +1,60 @@ +[#top-this-standard] +:root-path: ./ +include::{root-path}_config.adoc[] +//NOTE: All central attributes for Asciidoctor have to be defined in the _config.adoc AND in the antora.yml in the .antora folder in root += ASAM OpenMATERIAL +// DO NOT USE THE ATTRIBUTE {THIS_STANDARD} in the document title, it will break with Antora build pipeline! + +// DO NOT CHANGE!!! +// +:titleoffset!: +:sectnums!: + + +[IMPORTANT] +.Disclaimer +==== +This document is the copyrighted property of ASAM e.V. +In alteration to the regular https://www.asam.net/license[license terms], ASAM allows unrestricted distribution of this standard. §2 (1) of ASAM's regular https://www.asam.net/license[license terms] is therefore substituted by the following clause: "The licensor grants everyone a basic, non-exclusive and unlimited license to use the standard {THIS_STANDARD}". +==== +// +// DO NOT CHANGE!!! + + +:antora_mapping: true +ifndef::use-antora-rules[] + +[preface] +include::general_docs/foreword.adoc[leveloffset=+1] +[preface] +include::general_docs/introduction.adoc[leveloffset=+1] + +:sectnums: +include::general_docs/scope.adoc[leveloffset=+1] + +include::general_docs/normative_references.adoc[leveloffset=+1] + +include::terms_and_definitions/terms_and_definitions.adoc[leveloffset=+1] + +include::general_docs/abbreviations.adoc[leveloffset=+1] + +include::general_docs/backward_compatibility.adoc[leveloffset=+1] + +// Add further sections and chapters here as needed + +:sectnums!: +== Annexes +[appendix] +//include::annexes/REPLACE_ME.adoc[leveloffset=+2] +// Add further annexes here as needed and replace the placeholder one above + +[bibliography] +include::bibliography.adoc[leveloffset=+1] + +:sectnums!: +include::loft/list_of_figures.adoc[leveloffset=+1] + +:sectnums!: +include::loft/list_of_tables.adoc[leveloffset=+1] +endif::[] +:!antora_mapping: \ No newline at end of file diff --git a/.antora/modules/specification/pages/loft/list_of_figures.adoc b/.antora/modules/specification/pages/loft/list_of_figures.adoc new file mode 100644 index 00000000..6c158cfc --- /dev/null +++ b/.antora/modules/specification/pages/loft/list_of_figures.adoc @@ -0,0 +1,2 @@ +// AUTOMATICALLY GENERATED -- DO NOT CHANGE += List of figures \ No newline at end of file diff --git a/.antora/modules/specification/pages/loft/list_of_tables.adoc b/.antora/modules/specification/pages/loft/list_of_tables.adoc new file mode 100644 index 00000000..5cf30f0b --- /dev/null +++ b/.antora/modules/specification/pages/loft/list_of_tables.adoc @@ -0,0 +1,2 @@ +// AUTOMATICALLY GENERATED -- DO NOT CHANGE += List of tables \ No newline at end of file diff --git a/.antora/modules/specification/pages/terms_and_definitions/terms_and_definitions.adoc b/.antora/modules/specification/pages/terms_and_definitions/terms_and_definitions.adoc new file mode 100644 index 00000000..190beafc --- /dev/null +++ b/.antora/modules/specification/pages/terms_and_definitions/terms_and_definitions.adoc @@ -0,0 +1,12 @@ +[#top-terms_and_definitions-terms_and_definitions] += Terms and definitions + +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] + +TODO: Add terms and definitions + +Static road network:: +Collection of connected roads enriched by static objects that do not change during runtime of a simulation. diff --git a/.github/workflows/antora-build.yml b/.github/workflows/antora-build.yml new file mode 100644 index 00000000..c796a187 --- /dev/null +++ b/.github/workflows/antora-build.yml @@ -0,0 +1,27 @@ +name: Antora Documentation Build +# Based on https://github.com/OpenSimulationInterface/osi-documentation/blob/master/.github/workflows/antora-build.yml +on: + push: + branches: [ main ] + pull_request: + branches: [ main ] + +jobs: + trigger_antora: + name: Trigger antora generator + + runs-on: Ubuntu-latest + + env: + MUP_KEY: ${{ secrets.MACHINE_USER_PAT }} + + steps: + - name: Trigger generator + if: ${{ env.MUP_KEY != '' }} + uses: peter-evans/repository-dispatch@v3 + with: + token: ${{ secrets.MACHINE_USER_PAT }} + event-type: antora-build-trigger + repository: # Add fork of https://code.asam.net/common/templates/antora-base-repo-example + client-payload: '{"src": "${{ github.repository }}", "ref": "${{ github.ref }}", "sha": "${{ github.sha }}", "head_ref": "${{ github.head_ref }}"}' +