Skip to content

trace_file_mcap_format.adoc

Latest commit

 

History

History
121 lines (94 loc) · 6.1 KB

trace_file_mcap_format.adoc

File metadata and controls

121 lines (94 loc) · 6.1 KB

../_config.adoc = MCAP Format

General Requirements

  • Must comply with the 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

  • Must contain only a single scenario with a unique global time

  • An MCAP file is considered a single dataset

Schema

  • name field: Full message type name, including package (e.g., osi3.SensorData)

  • encoding field: Must be protobuf

  • data field: String-encoded google::protobuf::FileDescriptorSet for the OSI top-level message

Channel

  • 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.

Message

  • publish_time 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 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 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

  • 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 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

    • openDrive Reference

    • 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

Naming Convention

mcap files must follow this naming convention:
<opt. prefix>_<opt. timestamp>_<type>_<opt. suffix>.mcap

When not using an optional field, the corresponding underscore delimiter must be omitted so that no double underscore is present.

Table 1. MCAP file naming convention
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 messages, this time must represent the zero time. The format must adhere to ISO 8601 [cite:iso8601].

type

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.
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 as the optional prefix or be used to specify further details like the minimum required OSI version. May not contain any _ characters.

Examples

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.