From f78eb7c669c5ace1bbce10c4d664d4fabddaf2e4 Mon Sep 17 00:00:00 2001 From: Timm Ruppert Date: Mon, 11 Nov 2024 19:11:08 +0100 Subject: [PATCH] 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