From 38249ce9d58125136e7ed0d417c057a697526e2f Mon Sep 17 00:00:00 2001 From: Timm Ruppert Date: Thu, 10 Oct 2024 16:26:26 +0200 Subject: [PATCH 01/12] MCAP spec proposal added Signed-off-by: Timm Ruppert --- doc/architecture/formatting_script.adoc | 29 ------- ...le_binary_and_human_readable_formats.adoc} | 13 +++- doc/architecture/trace_file_example.adoc | 78 ------------------- doc/architecture/trace_file_mcap_format.adoc | 39 ++++++++++ ... => trace_file_overview_file_formats.adoc} | 17 ++-- doc/open-simulation-interface_user_guide.adoc | 14 +--- 6 files changed, 62 insertions(+), 128 deletions(-) delete mode 100644 doc/architecture/formatting_script.adoc rename doc/architecture/{trace_file_naming.adoc => trace_file_binary_and_human_readable_formats.adoc} (73%) delete mode 100644 doc/architecture/trace_file_example.adoc create mode 100644 doc/architecture/trace_file_mcap_format.adoc rename doc/architecture/{trace_file_formats.adoc => trace_file_overview_file_formats.adoc} (52%) diff --git a/doc/architecture/formatting_script.adoc b/doc/architecture/formatting_script.adoc deleted file mode 100644 index d8beec595..000000000 --- a/doc/architecture/formatting_script.adoc +++ /dev/null @@ -1,29 +0,0 @@ -ifndef::include-only-once[] -:root-path: ../ -include::{root-path}_config.adoc[] -endif::[] -= Trace-file formatting script - -The OSI repository contains a Python script for converting trace files from one format to another. -The formatting script is stored in `open-simulation-interface/osi3trace/`. - -**osi2read.py** - -`osi2read.py` converts trace files to human-readable `.txth` trace files. -This script takes the following parameters: - -`--data`, `-d`:: -String containing the path to the file with serialized data. - -`--type`, `-t`:: -Optional string describing the message type used to serialize data. -`'SensorView'`, `'GroundTruth'`, or `'SensorData'` are permitted values. -The default value is `'SensorView'`. - -`--output`, `-o`:: -Optional string containing the name of the output file. -The default value is `None`, in which case the output file name is set to the name of the input file, with the file extension being replaced by `.txth`. - -**Related topics** - -* <> \ No newline at end of file diff --git a/doc/architecture/trace_file_naming.adoc b/doc/architecture/trace_file_binary_and_human_readable_formats.adoc similarity index 73% rename from doc/architecture/trace_file_naming.adoc rename to doc/architecture/trace_file_binary_and_human_readable_formats.adoc index 1c73ed90c..32135ca8c 100644 --- a/doc/architecture/trace_file_naming.adoc +++ b/doc/architecture/trace_file_binary_and_human_readable_formats.adoc @@ -2,11 +2,16 @@ ifndef::include-only-once[] :root-path: ../ include::{root-path}_config.adoc[] endif::[] -= OSI trace file naming conventions += Native binary and Human-readable Formats -**Name format** +== Binary .osi Format +Messages are separated by a four-byte, little-endian, unsigned integer specifying the length of each message. -The names of OSI trace files should have the following format: +== Human-readable .txth Format +Messages are stored as plain text, separated by newlines. + +== Naming Convention +Binary .osi and human-readable .txth files should follow this naming convention: ---- _____.osi @@ -76,3 +81,5 @@ The recommended file name is: ---- 20210818T150542Z_sv_312_300_1523_highway.osi ---- + +NOTE: This naming convention does not apply to .mcap files. \ No newline at end of file diff --git a/doc/architecture/trace_file_example.adoc b/doc/architecture/trace_file_example.adoc deleted file mode 100644 index 9de8dd43b..000000000 --- a/doc/architecture/trace_file_example.adoc +++ /dev/null @@ -1,78 +0,0 @@ -ifndef::include-only-once[] -:root-path: ../ -include::{root-path}_config.adoc[] -endif::[] -[#top-osi_trace_file_example] -= OSI trace file example - -[source, python] ----- -# generate_osi_messages.py -from osi3.osi_sensorview_pb2 import SensorView -import struct - -NANO_INCREMENT = 10000000 -MOVING_OBJECT_LENGTH = 5 -MOVING_OBJECT_WIDTH = 2 -MOVING_OBJECT_HEIGHT = 1 - -def main(): - """Initialize SensorView""" - f = open("sv_330_361_1000_movingobject.osi", "ab") - sensorview = SensorView() - - sv_ground_truth = sensorview.global_ground_truth - sv_ground_truth.version.version_major = 3 - sv_ground_truth.version.version_minor = 5 - sv_ground_truth.version.version_patch = 0 - - sv_ground_truth.timestamp.seconds = 0 - sv_ground_truth.timestamp.nanos = 0 - - moving_object = sv_ground_truth.moving_object.add() - moving_object.id.value = 42 - - # Generate 1000 OSI messages for a duration of 10 seconds - for i in range(1000): - - # Increment the time - if sv_ground_truth.timestamp.nanos > 1000000000: - sv_ground_truth.timestamp.seconds += 1 - sv_ground_truth.timestamp.nanos = 0 - sv_ground_truth.timestamp.nanos += NANO_INCREMENT - - moving_object.vehicle_classification.type = 2 - - moving_object.base.dimension.length = MOVING_OBJECT_LENGTH - moving_object.base.dimension.width = MOVING_OBJECT_WIDTH - moving_object.base.dimension.height = MOVING_OBJECT_HEIGHT - - moving_object.base.position.x += 0.5 - moving_object.base.position.y = 0.0 - moving_object.base.position.z = 0.0 - - moving_object.base.orientation.roll = 0.0 - moving_object.base.orientation.pitch = 0.0 - moving_object.base.orientation.yaw = 0.0 - - """Serialize""" - bytes_buffer = sensorview.SerializeToString() - f.write(struct.pack(" Date: Fri, 18 Oct 2024 12:09:12 +0200 Subject: [PATCH 02/12] Refinement of MCAP Specification Signed-off-by: Timm Ruppert --- doc/architecture/trace_file_mcap_format.adoc | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/doc/architecture/trace_file_mcap_format.adoc b/doc/architecture/trace_file_mcap_format.adoc index 036126d36..c49491b64 100644 --- a/doc/architecture/trace_file_mcap_format.adoc +++ b/doc/architecture/trace_file_mcap_format.adoc @@ -4,6 +4,7 @@ - Must comply with the https://mcap.dev/spec[MCAP format specification] version `0x30` - Must allow other non-OSI data to be present in the MCAP file - Message records must be written into `chunk records` for indexed files +- Only OSI top-level messages containing a timestamp field are permitted to be directly stored in MCAP channels == Schema - `name` field: Full message type name, including package (e.g., `osi3.SensorData`) @@ -12,12 +13,13 @@ == Channel - `message_encoding` field: Must be "protobuf" -- `metadata` field: Should include a brief description of data origin and purpose +- `metadata` field: + - Must include an `osi_version` key, specifying the OSI SemVer version of the message contained within the channel + - Should include a `description` key explaining the data's origin and purpose == Message - `publish_time` field: - Must reflect the timestamp of the stored OSI top-level message if it contains a timestamp field - - Should represent a plausible value to express message order in relation to timestamps of other top-level messages if the message doesn't contain a timestamp (e.g. SensorViewConfiguration) - Must be in nanoseconds - `log_time` field: Must reflect the time when the message was enqueued for MCAP file addition - Must reflect the time when the top-level OSI message was enqueued for addition to the MCAP file @@ -26,7 +28,7 @@ == Metadata - Must include metadata with the name `versions` containing at least the following key-value pairs: - * `osi`: SemVer version of OSI specification + * `osi`: SemVer version of the minimum required OSI version * `protobuf`: SemVer version of protobuf library - Must include metadata with the name `creation_date` containing at least the following key-value pairs: * `timestamp`: ISO 8601 formatted creation time @@ -35,5 +37,4 @@ - Additional custom metadata may be added == Compression -- OSI-compliant tooling must support compression types: `none`, `lz4`, and `zstd` -- Recommended compression in use should be either `lz4` or `zstd` \ No newline at end of file +- OSI-compliant tooling must support compression types: `none`, `lz4`, and `zstd` \ No newline at end of file From beb6d47be1daf75a39ee780ea325a565510c3cfc Mon Sep 17 00:00:00 2001 From: Timm Ruppert Date: Mon, 21 Oct 2024 12:43:20 +0200 Subject: [PATCH 03/12] Refinement of MCAP Specification Signed-off-by: Timm Ruppert --- ...ile_binary_and_human_readable_formats.adoc | 2 +- doc/architecture/trace_file_mcap_format.adoc | 76 +++++++++++++++++-- 2 files changed, 70 insertions(+), 8 deletions(-) diff --git a/doc/architecture/trace_file_binary_and_human_readable_formats.adoc b/doc/architecture/trace_file_binary_and_human_readable_formats.adoc index 32135ca8c..33c5c87f9 100644 --- a/doc/architecture/trace_file_binary_and_human_readable_formats.adoc +++ b/doc/architecture/trace_file_binary_and_human_readable_formats.adoc @@ -82,4 +82,4 @@ The recommended file name is: 20210818T150542Z_sv_312_300_1523_highway.osi ---- -NOTE: This naming convention does not apply to .mcap files. \ No newline at end of file +NOTE: This naming convention does not apply to .mcap files, they must follow the naming convention described in their section. \ No newline at end of file diff --git a/doc/architecture/trace_file_mcap_format.adoc b/doc/architecture/trace_file_mcap_format.adoc index c49491b64..276bcf5ba 100644 --- a/doc/architecture/trace_file_mcap_format.adoc +++ b/doc/architecture/trace_file_mcap_format.adoc @@ -1,3 +1,7 @@ +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] = MCAP Format == General Requirements @@ -14,22 +18,23 @@ == Channel - `message_encoding` field: Must be "protobuf" - `metadata` field: - - Must include an `osi_version` key, specifying the OSI SemVer version of the message contained within the channel - - Should include a `description` key explaining the data's origin and purpose + - Must include an `osi_version` key, specifying the OSI SemVer version of the OSI top-level message contained within the channel + - Must include a `protobuf` key, specifying the protobuf SemVer version used to create the OSI top-level message contained within the channel + - Should include a `description` key, explaining the data's origin and purpose in natural language. + == Message - `publish_time` field: - - Must reflect the timestamp of the stored OSI top-level message if it contains a timestamp field + - Must reflect the timestamp of the stored OSI top-level message - Must be in nanoseconds - `log_time` field: Must reflect the time when the message was enqueued for MCAP file addition - - Must reflect the time when the top-level OSI message was enqueued for addition to the MCAP file - - Zero time doesn't need to coincide with the Unix epoch, but it is recommended + - Must reflect the timestamp of the stored OSI top-level message - Must be in nanoseconds + == Metadata - Must include metadata with the name `versions` containing at least the following key-value pairs: * `osi`: SemVer version of the minimum required OSI version - * `protobuf`: SemVer version of protobuf library - Must include metadata with the name `creation_date` containing at least the following key-value pairs: * `timestamp`: ISO 8601 formatted creation time - Must include metadata with the name `description` containing at least the following key-value pairs: @@ -37,4 +42,61 @@ - Additional custom metadata may be added == Compression -- OSI-compliant tooling must support compression types: `none`, `lz4`, and `zstd` \ No newline at end of file +- OSI-compliant tooling must support compression types: `none`, `lz4`, and `zstd` + + +== Naming Convention +.mcap files must follow this naming convention: + + +---- +___.cap +---- + +When not using an optional field, the corresponding `_` delimiter must be omitted so that no double `_` is present. + +[#tab-MCAP-file-naming-convention] +.MCAP file naming convention +[cols="1,1"] +|=== +|Field |Explanation + +|opt. prefix +|An optional prefix which may be used to specify the type of scenario (e.g. `cut-in`) or uniqueness of the setup (e.g. `target-5m`). May not contain any `_` characters. + +|opt. timestamp +|Defines the absolute start time for a scenario or recording. If following the recommended zero time for the timestamps of the top-level message, this time must represent the zero time. The format must adhere to ISO 8601 [cite:iso8601]. + + +|type +| Specifies contained the top-level message(s) and must be one of the following values: + +`sv` file contains only `SensorView` messages. + +`gt` file contains only `GroundTruth` messages. + +`hvd` file contains only `HostVehicleData` messages. + +`sd` file contains only SensorData` messages. + +`tc` file contains only `TrafficCommand` messages.+ +`tcu` file contains only `TrafficCommandUpdate` messages. +`tu` file contains only `TrafficUpdate` messages. +`mr` file contains only `MotionRequest` messages. +`su` file contains only `StreamingUpdate` messages. +`multi` file contains multiple, different types of of top-level messages (not including different channels of the same type). + +|opt. suffix +|An optional suffix which may be used the same way like the optional prefix or be used to specify further details like the minimum required OSI version. May not contain any `_` characters. + + +|=== + + +**Example** + +The following list shows examples of valid OSI MCAP file names: +- `20210818T150542Z_highway_sv.mcap` +- `20210818T150542Z_highway_sv_run-1.mcap` +- `20210818T150542Z_highway_gt_OSI-3-7.mcap` +- `Highway_sd_version-1.mcap` +- `Highway-cut-in-no-collision_sd.mcap` +- `Target-5m_sd_resimulated-measurement.mcap` + +NOTE: This naming convention does not apply to .osi and .txt files, they should follow the naming convention described in their section. \ No newline at end of file From f78eb7c669c5ace1bbce10c4d664d4fabddaf2e4 Mon Sep 17 00:00:00 2001 From: Timm Ruppert Date: Mon, 11 Nov 2024 19:11:08 +0100 Subject: [PATCH 04/12] refine metadata Signed-off-by: Timm Ruppert --- doc/architecture/trace_file_mcap_format.adoc | 32 +++++++++++++++----- 1 file changed, 25 insertions(+), 7 deletions(-) diff --git a/doc/architecture/trace_file_mcap_format.adoc b/doc/architecture/trace_file_mcap_format.adoc index 276bcf5ba..119380264 100644 --- a/doc/architecture/trace_file_mcap_format.adoc +++ b/doc/architecture/trace_file_mcap_format.adoc @@ -9,6 +9,8 @@ endif::[] - Must allow other non-OSI data to be present in the MCAP file - Message records must be written into `chunk records` for indexed files - Only OSI top-level messages containing a timestamp field are permitted to be directly stored in MCAP channels +- Must contain only a single scenario with a unique global time +- A MCAP file is condidered a single dataset == Schema - `name` field: Full message type name, including package (e.g., `osi3.SensorData`) @@ -32,14 +34,30 @@ endif::[] - Must be in nanoseconds -== Metadata +== File-wide Metadata - Must include metadata with the name `versions` containing at least the following key-value pairs: * `osi`: SemVer version of the minimum required OSI version -- Must include metadata with the name `creation_date` containing at least the following key-value pairs: - * `timestamp`: ISO 8601 formatted creation time -- Must include metadata with the name `description` containing at least the following key-value pairs: - * `text`: Scenario description -- Additional custom metadata may be added +- Must include metadata with the name `asam_osi` containing at least the following key-value pairs: + * `zero_time`: ISO 8601 YYYYMMDDThhmmss.f formatted point in time representing the zero time of the scenario + * `timestamp`: ISO 8601 YYYYMMDDThhmmss.f formatted creation time of the file +- It is strongly recommended to include metadata with the name `asam_osi` containing the following key-value pairs: + * `description`: Short human-readable scenario description + * `creator`: csv of person or company (not tool) creating the file + * 'license' csv of spdx identifiers + * 'data_sources' csv of model, scenario player, etc. +- Additional custom metadata may be added, but it is recommended to add a category with the name `context` where the key represents a prefix and the value pointing to the specification of the metadate. This allows to add other (channel-wise) metadata with the stated prefix. Thus, it becomes clear what a metadata is about and where it is specified. The following examples are given: + - GAIA-X4PLC-AAD SHACL Shape + - Assume you want to embed the hdmap of a scenario in the MCAP file. + - The `context` category contains the key `GAIA-X4PLC-AAD-hdmap ` with the value `https://github.com/GAIA-X4PLC-AAD/ontology-management-base/blob/main/hdmap/hdmap_shacl.ttl` + - A channel metadata contains the key `GAIA-X4PLC-AAD-hdmap` with the value of the hdmap data in the given SHACLE shape. + - openDrive Reference + - Assume you want to express that oncoming traffic passes on the right side of the road. + - The `context` category contains the key `openDrive` with the value `https://publications.pages.asam.net/standards/ASAM_OpenDRIVE/ASAM_OpenDRIVE_Specification/1.8.1/specification/index.html` + - A file metadata in a new metadata category with the arbitrary name `specification` contains the key `openDrive-road-rule` with the value `RHT` + - Cycle time variation of a sensor + - Assume you want to express the interface cycle time variation of a sensor. + - The `context` category contains the key `iso_23150` with the value` ISO 23150:2011` + - A channel containing `OSI3::SensorData` messages has metadata with the key `iso_23150-cycle-time-variation:` and the value `80` == Compression - OSI-compliant tooling must support compression types: `none`, `lz4`, and `zstd` @@ -65,7 +83,7 @@ When not using an optional field, the corresponding `_` delimiter must be omitte |An optional prefix which may be used to specify the type of scenario (e.g. `cut-in`) or uniqueness of the setup (e.g. `target-5m`). May not contain any `_` characters. |opt. timestamp -|Defines the absolute start time for a scenario or recording. If following the recommended zero time for the timestamps of the top-level message, this time must represent the zero time. The format must adhere to ISO 8601 [cite:iso8601]. +|Defines the absolute start time for a scenario or recording. If following the recommended zero time for the timestamps of the top-level messages, this time must represent the zero time. The format must adhere to ISO 8601 [cite:iso8601]. |type From 6c8a35f18eb5840d437e7695e45a3b77868d53ac Mon Sep 17 00:00:00 2001 From: ClemensLinnhoff Date: Tue, 12 Nov 2024 08:47:22 +0100 Subject: [PATCH 05/12] Editorial fixes Signed-off-by: ClemensLinnhoff --- doc/architecture/trace_file_mcap_format.adoc | 77 ++++++++++---------- 1 file changed, 39 insertions(+), 38 deletions(-) diff --git a/doc/architecture/trace_file_mcap_format.adoc b/doc/architecture/trace_file_mcap_format.adoc index 119380264..f15fa0bac 100644 --- a/doc/architecture/trace_file_mcap_format.adoc +++ b/doc/architecture/trace_file_mcap_format.adoc @@ -10,7 +10,7 @@ endif::[] - Message records must be written into `chunk records` for indexed files - Only OSI top-level messages containing a timestamp field are permitted to be directly stored in MCAP channels - Must contain only a single scenario with a unique global time -- A MCAP file is condidered a single dataset +- An MCAP file is considered a single dataset == Schema - `name` field: Full message type name, including package (e.g., `osi3.SensorData`) @@ -18,46 +18,46 @@ endif::[] - `data` field: String-encoded `google::protobuf::FileDescriptorSet` for the OSI top-level message == Channel -- `message_encoding` field: Must be "protobuf" +- `message_encoding` field: Must be `protobuf`` - `metadata` field: - - Must include an `osi_version` key, specifying the OSI SemVer version of the OSI top-level message contained within the channel - - Must include a `protobuf` key, specifying the protobuf SemVer version used to create the OSI top-level message contained within the channel - - Should include a `description` key, explaining the data's origin and purpose in natural language. +** Must include an `osi_version` key, specifying the OSI SemVer version of the OSI top-level message contained within the channel +** Must include a `protobuf` key, specifying the protobuf SemVer version used to create the OSI top-level message contained within the channel +** Should include a `description` key, explaining the data's origin and purpose in natural language. == Message - `publish_time` field: - - Must reflect the timestamp of the stored OSI top-level message - - Must be in nanoseconds +** Must reflect the timestamp of the stored OSI top-level message +** Must be in nanoseconds - `log_time` field: Must reflect the time when the message was enqueued for MCAP file addition - - Must reflect the timestamp of the stored OSI top-level message - - Must be in nanoseconds +** Must reflect the timestamp of the stored OSI top-level message +** Must be in nanoseconds == File-wide Metadata - Must include metadata with the name `versions` containing at least the following key-value pairs: - * `osi`: SemVer version of the minimum required OSI version +** `osi`: SemVer version of the minimum required OSI version - Must include metadata with the name `asam_osi` containing at least the following key-value pairs: - * `zero_time`: ISO 8601 YYYYMMDDThhmmss.f formatted point in time representing the zero time of the scenario - * `timestamp`: ISO 8601 YYYYMMDDThhmmss.f formatted creation time of the file +** `zero_time`: ISO 8601 YYYYMMDDThhmmss.f formatted point in time representing the zero time of the scenario +** `timestamp`: ISO 8601 YYYYMMDDThhmmss.f formatted creation time of the file - It is strongly recommended to include metadata with the name `asam_osi` containing the following key-value pairs: - * `description`: Short human-readable scenario description - * `creator`: csv of person or company (not tool) creating the file - * 'license' csv of spdx identifiers - * 'data_sources' csv of model, scenario player, etc. -- Additional custom metadata may be added, but it is recommended to add a category with the name `context` where the key represents a prefix and the value pointing to the specification of the metadate. This allows to add other (channel-wise) metadata with the stated prefix. Thus, it becomes clear what a metadata is about and where it is specified. The following examples are given: - - GAIA-X4PLC-AAD SHACL Shape - - Assume you want to embed the hdmap of a scenario in the MCAP file. - - The `context` category contains the key `GAIA-X4PLC-AAD-hdmap ` with the value `https://github.com/GAIA-X4PLC-AAD/ontology-management-base/blob/main/hdmap/hdmap_shacl.ttl` - - A channel metadata contains the key `GAIA-X4PLC-AAD-hdmap` with the value of the hdmap data in the given SHACLE shape. - - openDrive Reference - - Assume you want to express that oncoming traffic passes on the right side of the road. - - The `context` category contains the key `openDrive` with the value `https://publications.pages.asam.net/standards/ASAM_OpenDRIVE/ASAM_OpenDRIVE_Specification/1.8.1/specification/index.html` - - A file metadata in a new metadata category with the arbitrary name `specification` contains the key `openDrive-road-rule` with the value `RHT` - - Cycle time variation of a sensor - - Assume you want to express the interface cycle time variation of a sensor. - - The `context` category contains the key `iso_23150` with the value` ISO 23150:2011` - - A channel containing `OSI3::SensorData` messages has metadata with the key `iso_23150-cycle-time-variation:` and the value `80` +** `description`: Short human-readable scenario description +** `creator`: csv of person or company (not tool) creating the file +** `license`` csv of spdx identifiers +** `data_sources` csv of model, scenario player, etc. +- Additional custom metadata may be added, but it is recommended to add a category with the name `context` where the key represents a prefix and the value pointing to the specification of the metadata. This allows to add other (channel-wise) metadata with the stated prefix. Thus, it becomes clear what a metadata is about and where it is specified. The following examples are given: +** GAIA-X4PLC-AAD SHACL Shape +*** Assume you want to embed the hdmap of a scenario in the MCAP file. +*** The `context` category contains the key `GAIA-X4PLC-AAD-hdmap` with the value `https://github.com/GAIA-X4PLC-AAD/ontology-management-base/blob/main/hdmap/hdmap_shacl.ttl` +*** A channel metadata contains the key `GAIA-X4PLC-AAD-hdmap` with the value of the hdmap data in the given SHACL shape. +** openDrive Reference +*** Assume you want to express that oncoming traffic passes on the right side of the road. +*** The `context` category contains the key `openDrive` with the value `https://publications.pages.asam.net/standards/ASAM_OpenDRIVE/ASAM_OpenDRIVE_Specification/1.8.1/specification/index.html` +*** A file metadata in a new metadata category with the arbitrary name `specification` contains the key `openDrive-road-rule` with the value `RHT` +** Cycle time variation of a sensor +*** Assume you want to express the interface cycle time variation of a sensor. +*** The `context` category contains the key `iso_23150` with the value` ISO 23150:2011` +*** A channel containing `OSI3::SensorData` messages has metadata with the key `iso_23150-cycle-time-variation:` and the value `80` == Compression - OSI-compliant tooling must support compression types: `none`, `lz4`, and `zstd` @@ -68,10 +68,10 @@ endif::[] ---- -___.cap +___.mcap ---- -When not using an optional field, the corresponding `_` delimiter must be omitted so that no double `_` is present. +When not using an optional field, the corresponding underscore delimiter must be omitted so that no double underscore is present. [#tab-MCAP-file-naming-convention] .MCAP file naming convention @@ -87,21 +87,21 @@ When not using an optional field, the corresponding `_` delimiter must be omitte |type -| Specifies contained the top-level message(s) and must be one of the following values: +| Specifies the type of the contained the top-level message(s) and must be one of the following values: `sv` file contains only `SensorView` messages. + `gt` file contains only `GroundTruth` messages. + `hvd` file contains only `HostVehicleData` messages. + `sd` file contains only SensorData` messages. + -`tc` file contains only `TrafficCommand` messages.+ -`tcu` file contains only `TrafficCommandUpdate` messages. -`tu` file contains only `TrafficUpdate` messages. -`mr` file contains only `MotionRequest` messages. -`su` file contains only `StreamingUpdate` messages. +`tc` file contains only `TrafficCommand` messages. + +`tcu` file contains only `TrafficCommandUpdate` messages. + +`tu` file contains only `TrafficUpdate` messages. + +`mr` file contains only `MotionRequest` messages. + +`su` file contains only `StreamingUpdate` messages. + `multi` file contains multiple, different types of of top-level messages (not including different channels of the same type). |opt. suffix -|An optional suffix which may be used the same way like the optional prefix or be used to specify further details like the minimum required OSI version. May not contain any `_` characters. +|An optional suffix which may be used the same way as the optional prefix or be used to specify further details like the minimum required OSI version. May not contain any `_` characters. |=== @@ -110,6 +110,7 @@ When not using an optional field, the corresponding `_` delimiter must be omitte **Example** The following list shows examples of valid OSI MCAP file names: + - `20210818T150542Z_highway_sv.mcap` - `20210818T150542Z_highway_sv_run-1.mcap` - `20210818T150542Z_highway_gt_OSI-3-7.mcap` From 7cd3ad475c5cd7c0392d8b7d04768f05e18dd8c5 Mon Sep 17 00:00:00 2001 From: ClemensLinnhoff Date: Tue, 12 Nov 2024 08:47:59 +0100 Subject: [PATCH 06/12] Minor fix Signed-off-by: ClemensLinnhoff --- doc/architecture/trace_file_mcap_format.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/architecture/trace_file_mcap_format.adoc b/doc/architecture/trace_file_mcap_format.adoc index f15fa0bac..cc148147f 100644 --- a/doc/architecture/trace_file_mcap_format.adoc +++ b/doc/architecture/trace_file_mcap_format.adoc @@ -35,7 +35,7 @@ endif::[] == File-wide Metadata -- Must include metadata with the name `versions` containing at least the following key-value pairs: +- Must include metadata with the name `versions` containing at least the following key-value pair: ** `osi`: SemVer version of the minimum required OSI version - Must include metadata with the name `asam_osi` containing at least the following key-value pairs: ** `zero_time`: ISO 8601 YYYYMMDDThhmmss.f formatted point in time representing the zero time of the scenario @@ -107,7 +107,7 @@ When not using an optional field, the corresponding underscore delimiter must be |=== -**Example** +**Example**s The following list shows examples of valid OSI MCAP file names: From ccb3bb4458f07acd89a672a348c0f137627c6785 Mon Sep 17 00:00:00 2001 From: ClemensLinnhoff Date: Tue, 12 Nov 2024 13:47:27 +0100 Subject: [PATCH 07/12] Fix typo Signed-off-by: ClemensLinnhoff --- doc/architecture/trace_file_mcap_format.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/architecture/trace_file_mcap_format.adoc b/doc/architecture/trace_file_mcap_format.adoc index cc148147f..f2b7254f9 100644 --- a/doc/architecture/trace_file_mcap_format.adoc +++ b/doc/architecture/trace_file_mcap_format.adoc @@ -107,7 +107,7 @@ When not using an optional field, the corresponding underscore delimiter must be |=== -**Example**s +**Example** The following list shows examples of valid OSI MCAP file names: From f8c648fea4b0ebb28cbc2ea2b6513ce4176c300e Mon Sep 17 00:00:00 2001 From: Timm Ruppert Date: Tue, 12 Nov 2024 19:14:44 +0100 Subject: [PATCH 08/12] fix _version missing for protobuf Signed-off-by: Timm Ruppert --- doc/architecture/trace_file_mcap_format.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/architecture/trace_file_mcap_format.adoc b/doc/architecture/trace_file_mcap_format.adoc index f2b7254f9..b37910fa6 100644 --- a/doc/architecture/trace_file_mcap_format.adoc +++ b/doc/architecture/trace_file_mcap_format.adoc @@ -21,7 +21,7 @@ endif::[] - `message_encoding` field: Must be `protobuf`` - `metadata` field: ** Must include an `osi_version` key, specifying the OSI SemVer version of the OSI top-level message contained within the channel -** Must include a `protobuf` key, specifying the protobuf SemVer version used to create the OSI top-level message contained within the channel +** Must include a `protobuf_version` key, specifying the protobuf SemVer version used to create the OSI top-level message contained within the channel ** Should include a `description` key, explaining the data's origin and purpose in natural language. From ae058853e2e1175b3140a08d69822379ace4a458 Mon Sep 17 00:00:00 2001 From: Timm Ruppert Date: Wed, 13 Nov 2024 11:37:36 +0100 Subject: [PATCH 09/12] add missing TZD Signed-off-by: Timm Ruppert --- doc/architecture/trace_file_mcap_format.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/architecture/trace_file_mcap_format.adoc b/doc/architecture/trace_file_mcap_format.adoc index b37910fa6..06722f226 100644 --- a/doc/architecture/trace_file_mcap_format.adoc +++ b/doc/architecture/trace_file_mcap_format.adoc @@ -38,8 +38,8 @@ endif::[] - Must include metadata with the name `versions` containing at least the following key-value pair: ** `osi`: SemVer version of the minimum required OSI version - Must include metadata with the name `asam_osi` containing at least the following key-value pairs: -** `zero_time`: ISO 8601 YYYYMMDDThhmmss.f formatted point in time representing the zero time of the scenario -** `timestamp`: ISO 8601 YYYYMMDDThhmmss.f formatted creation time of the file +** `zero_time`: ISO 8601 YYYYMMDDThhmmss.fTZD formatted point in time representing the zero time of the scenario +** `timestamp`: ISO 8601 YYYYMMDDThhmmss.fTZD formatted creation time of the file - It is strongly recommended to include metadata with the name `asam_osi` containing the following key-value pairs: ** `description`: Short human-readable scenario description ** `creator`: csv of person or company (not tool) creating the file From 9603aadd9cbc418d02e3cbe67de4518421c44a1d Mon Sep 17 00:00:00 2001 From: TimmRuppert <158559152+TimmRuppert@users.noreply.github.com> Date: Wed, 13 Nov 2024 15:13:25 +0100 Subject: [PATCH 10/12] MCAP Format use a single spdx identifier Signed-off-by: TimmRuppert <158559152+TimmRuppert@users.noreply.github.com> --- doc/architecture/trace_file_mcap_format.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/architecture/trace_file_mcap_format.adoc b/doc/architecture/trace_file_mcap_format.adoc index 06722f226..898f090d3 100644 --- a/doc/architecture/trace_file_mcap_format.adoc +++ b/doc/architecture/trace_file_mcap_format.adoc @@ -43,7 +43,7 @@ endif::[] - It is strongly recommended to include metadata with the name `asam_osi` containing the following key-value pairs: ** `description`: Short human-readable scenario description ** `creator`: csv of person or company (not tool) creating the file -** `license`` csv of spdx identifiers +** `license`` spdx identifier ** `data_sources` csv of model, scenario player, etc. - Additional custom metadata may be added, but it is recommended to add a category with the name `context` where the key represents a prefix and the value pointing to the specification of the metadata. This allows to add other (channel-wise) metadata with the stated prefix. Thus, it becomes clear what a metadata is about and where it is specified. The following examples are given: ** GAIA-X4PLC-AAD SHACL Shape From 2c063e9c8b12c8b15c2216678c3411b2385cc980 Mon Sep 17 00:00:00 2001 From: TimmRuppert <158559152+TimmRuppert@users.noreply.github.com> Date: Wed, 13 Nov 2024 15:15:34 +0100 Subject: [PATCH 11/12] Write out csv once Signed-off-by: TimmRuppert <158559152+TimmRuppert@users.noreply.github.com> --- doc/architecture/trace_file_mcap_format.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/architecture/trace_file_mcap_format.adoc b/doc/architecture/trace_file_mcap_format.adoc index 898f090d3..b620971c5 100644 --- a/doc/architecture/trace_file_mcap_format.adoc +++ b/doc/architecture/trace_file_mcap_format.adoc @@ -42,7 +42,7 @@ endif::[] ** `timestamp`: ISO 8601 YYYYMMDDThhmmss.fTZD formatted creation time of the file - It is strongly recommended to include metadata with the name `asam_osi` containing the following key-value pairs: ** `description`: Short human-readable scenario description -** `creator`: csv of person or company (not tool) creating the file +** `creator`: Comma-separated values (csv) of persons or companies (not tools) creating the file ** `license`` spdx identifier ** `data_sources` csv of model, scenario player, etc. - Additional custom metadata may be added, but it is recommended to add a category with the name `context` where the key represents a prefix and the value pointing to the specification of the metadata. This allows to add other (channel-wise) metadata with the stated prefix. Thus, it becomes clear what a metadata is about and where it is specified. The following examples are given: From 12a32414eb9c745bdae40ee943899bea0a6e36fc Mon Sep 17 00:00:00 2001 From: TimmRuppert <158559152+TimmRuppert@users.noreply.github.com> Date: Wed, 13 Nov 2024 15:19:05 +0100 Subject: [PATCH 12/12] Fix mcap naming example Signed-off-by: TimmRuppert <158559152+TimmRuppert@users.noreply.github.com> --- doc/architecture/trace_file_mcap_format.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/architecture/trace_file_mcap_format.adoc b/doc/architecture/trace_file_mcap_format.adoc index b620971c5..9f1b331b4 100644 --- a/doc/architecture/trace_file_mcap_format.adoc +++ b/doc/architecture/trace_file_mcap_format.adoc @@ -111,7 +111,7 @@ When not using an optional field, the corresponding underscore delimiter must be The following list shows examples of valid OSI MCAP file names: -- `20210818T150542Z_highway_sv.mcap` +- `20210818T150542Z_sv_highway.mcap` - `20210818T150542Z_highway_sv_run-1.mcap` - `20210818T150542Z_highway_gt_OSI-3-7.mcap` - `Highway_sd_version-1.mcap`