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 70% rename from doc/architecture/trace_file_naming.adoc rename to doc/architecture/trace_file_binary_and_human_readable_formats.adoc index 1c73ed90c..33c5c87f9 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, they must follow the naming convention described in their section. \ 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("___.mcap +---- + +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 +[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 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. + + +|=== + + +**Example** + +The following list shows examples of valid OSI MCAP file names: + +- `20210818T150542Z_sv_highway.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 diff --git a/doc/architecture/trace_file_formats.adoc b/doc/architecture/trace_file_overview_file_formats.adoc similarity index 52% rename from doc/architecture/trace_file_formats.adoc rename to doc/architecture/trace_file_overview_file_formats.adoc index 60f2d2a4b..317ad15b2 100644 --- a/doc/architecture/trace_file_formats.adoc +++ b/doc/architecture/trace_file_overview_file_formats.adoc @@ -3,22 +3,25 @@ ifndef::include-only-once[] include::{root-path}_config.adoc[] endif::[] [#top-osi_trace_file_formats] -= OSI trace file formats += Overview file formats -There are two formats for storing multiple serialized OSI messages in one trace file. +There are three formats for storing OSI messages in trace files: *.osi:: -Binary trace file. -Messages are separated by a length specification before each message. -The length is represented by a four-byte, little-endian, unsigned integer. -The length does not include the integer itself. +Native binary trace file. *.txth:: Human-readable plain-text trace file. -Messages are separated by newlines. + +*.mcap:: +Binary trace file supporting more advanced features like indexed data, additional metadata and more. NOTE: Previous releases of OSI also supported a so-called plain-text trace file format, with file extension `.txt`. This legacy format did not contain plain-text, but rather binary protobuf messages separated by a special separator. For obvious reasons the format was deprecated and fully replaced with the `.osi` binary file format. This release no longer contains any support for the legacy `.txt` file format. These files may be used for manual checks. + + +TIP: For efficient handling of trace files, you can utilize the specification-compliant tools and libraries provided in the companion https://github.com/OpenSimulationInterface/osi-utilities[osi-utilities] repository. For example, convenient writer and reader classes are provided handling OSI messages for the different file formats. + diff --git a/doc/open-simulation-interface_user_guide.adoc b/doc/open-simulation-interface_user_guide.adoc index 394b81448..16a7491ef 100644 --- a/doc/open-simulation-interface_user_guide.adoc +++ b/doc/open-simulation-interface_user_guide.adoc @@ -61,19 +61,11 @@ include::./architecture/packaging_layer.adoc[leveloffset=+3] === OSI trace files -include::./architecture/trace_file_formats.adoc[leveloffset=+3] +include::./architecture/trace_file_overview_file_formats.adoc[leveloffset=+3] -include::./architecture/trace_file_naming.adoc[leveloffset=+3] +include::./architecture/trace_file_binary_and_human_readable_formats.adoc[leveloffset=+3] -// === Files and scripts - -// include::./architecture/proto-files.adoc[leveloffset=+3] - -// include::./architecture/test_scripts.adoc[leveloffset=+3] - -include::./architecture/trace_file_example.adoc[leveloffset=+3] - -include::./architecture/formatting_script.adoc[leveloffset=+3] +include::./architecture/trace_file_mcap_format.adoc[leveloffset=+3] // Setting up OSI