From 06246aea5d5e08d1f58197341d4f70844197f8e8 Mon Sep 17 00:00:00 2001 From: Maximilian Rosin Date: Tue, 18 May 2021 09:38:02 +0200 Subject: [PATCH 1/4] Describe trace files (#520) Signed-off-by: Maximilian Rosin --- doc/architecture/formatting_scripts.adoc | 52 ++++++++++++++++++++---- doc/architecture/trace_file_formats.adoc | 23 +++++++---- doc/architecture/trace_file_naming.adoc | 26 ++++++++---- 3 files changed, 79 insertions(+), 22 deletions(-) diff --git a/doc/architecture/formatting_scripts.adoc b/doc/architecture/formatting_scripts.adoc index de9f61dc1..a3c0de484 100644 --- a/doc/architecture/formatting_scripts.adoc +++ b/doc/architecture/formatting_scripts.adoc @@ -1,12 +1,48 @@ -= Formatting scripts +# Trace-file formatting scripts -TODO: Add general description. +OSI provides Python scripts for converting trace files from one format to the other. +The formatting scripts are stored in `open-simulation-interface/format/` -osi2read.py:: -TODO: Add description. +**txt2osi.py** -OSITrace.py:: -TODO: Add description. +`txt2osi.py` converts plain-text trace files to binary `.osi` trace files. +This script takes the following parameters: -txt2osi.py:: -TODO: Add description. +`--data`, `-d`:: +String containing the path to the file with serialized data. + +`--type`, `-t`:: +Optional string containing the name of the type used to serialize data. +Allowed values are `'SensorView'`, `'GroundTruth'`, and `'SensorData'`. +The default value is `'SensorView'`. + +`--output`, `-o`:: +Optional string containing the name of the output file., +The default value is 'converted.osi'. + +`--compress`, `-c`:: +Optional boolean controlling whether to compress the output to a lzma file.. +Allowed values are `'True'`, and `False`. +The default value is `False`. + +**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 containing the name of the type used to serialize data. +Allowed values are `'SensorView'`, `'GroundTruth'`, and `'SensorData'`. +The default value is `'SensorView'`. + +`--output`, `-o`:: +Optional string containing the name of the output file., +The default value is 'converted.txth'. + +`--format`, `-f`:: +Optional string containing the format type of the trace. +Allowed values are `'separated'`, and `None`. +The default value is `None`. \ No newline at end of file diff --git a/doc/architecture/trace_file_formats.adoc b/doc/architecture/trace_file_formats.adoc index 8367a3a53..9831b8834 100644 --- a/doc/architecture/trace_file_formats.adoc +++ b/doc/architecture/trace_file_formats.adoc @@ -1,9 +1,18 @@ = OSI trace file formats -Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. -Et malesuada fames ac turpis egestas. -Mauris pharetra et ultrices neque ornare aenean euismod elementum nisi. -Nulla facilisi morbi tempus iaculis urna id. Justo eget magna fermentum iaculis. -Sed augue lacus viverra vitae congue eu. Velit ut tortor pretium viverra suspendisse. -Amet commodo nulla facilisi nullam vehicula ipsum a. Nibh nisl condimentum id venenatis a. -Diam vel quam elementum pulvinar etiam non quam lacus suspendisse. \ No newline at end of file +There are multiple formats for storing multiple serialized OSI messages into one trace file + +*.osi:: +Binary trace file. +Messages are separated by a length specifications before each message. +The length is represented by a four-byte, little-endian, unsigned integer. +The length does not include the integer itself. + +*.txt:: +Plain-text trace file. +Messages are separated by `$$__$$`. + +*.txth:: +Human-readable plain-text trace file. +Messages are separated by newlines. +Such a filen may be used for manual checks. diff --git a/doc/architecture/trace_file_naming.adoc b/doc/architecture/trace_file_naming.adoc index c2c717835..dcd20e497 100644 --- a/doc/architecture/trace_file_naming.adoc +++ b/doc/architecture/trace_file_naming.adoc @@ -1,9 +1,21 @@ = OSI trace file naming conventions -Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. -Et malesuada fames ac turpis egestas. -Mauris pharetra et ultrices neque ornare aenean euismod elementum nisi. -Nulla facilisi morbi tempus iaculis urna id. Justo eget magna fermentum iaculis. -Sed augue lacus viverra vitae congue eu. Velit ut tortor pretium viverra suspendisse. -Amet commodo nulla facilisi nullam vehicula ipsum a. Nibh nisl condimentum id venenatis a. -Diam vel quam elementum pulvinar etiam non quam lacus suspendisse. \ No newline at end of file +**Name format** + +Names of OSI trace files should have the following format: + +[source] +---- +____.osi +---- + +**Types** + +`sd`:: +Trace file contains sensor-data messages. + +`sv`:: +Trace file contains sensor-view messages. + +`gt`:: +Trace file contains ground-truth messages. From 8d3f953206e02489a4db16ac55462dc0fd7d46e5 Mon Sep 17 00:00:00 2001 From: Maximilian Rosin Date: Tue, 18 May 2021 09:47:43 +0200 Subject: [PATCH 2/4] Fix typos (#520) Signed-off-by: Maximilian Rosin --- doc/architecture/formatting_scripts.adoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/architecture/formatting_scripts.adoc b/doc/architecture/formatting_scripts.adoc index a3c0de484..fde9bac4f 100644 --- a/doc/architecture/formatting_scripts.adoc +++ b/doc/architecture/formatting_scripts.adoc @@ -18,11 +18,11 @@ The default value is `'SensorView'`. `--output`, `-o`:: Optional string containing the name of the output file., -The default value is 'converted.osi'. +The default value is `'converted.osi'`. `--compress`, `-c`:: Optional boolean controlling whether to compress the output to a lzma file.. -Allowed values are `'True'`, and `False`. +Allowed values are `True`, and `False`. The default value is `False`. **osi2read.py** @@ -40,7 +40,7 @@ The default value is `'SensorView'`. `--output`, `-o`:: Optional string containing the name of the output file., -The default value is 'converted.txth'. +The default value is `'converted.txth'`. `--format`, `-f`:: Optional string containing the format type of the trace. From 5ba539462c3629fc2d09d05cc88b159e86bef3cd Mon Sep 17 00:00:00 2001 From: Maximilian Rosin Date: Thu, 24 Jun 2021 10:59:46 +0200 Subject: [PATCH 3/4] fix(docs): Fix typos, add example file name (#520) Signed-off-by: Maximilian Rosin --- doc/architecture/formatting_scripts.adoc | 8 +++---- doc/architecture/trace_file_formats.adoc | 2 +- doc/architecture/trace_file_naming.adoc | 29 ++++++++++++++++++++++++ 3 files changed, 34 insertions(+), 5 deletions(-) diff --git a/doc/architecture/formatting_scripts.adoc b/doc/architecture/formatting_scripts.adoc index fde9bac4f..4536f7264 100644 --- a/doc/architecture/formatting_scripts.adoc +++ b/doc/architecture/formatting_scripts.adoc @@ -1,4 +1,4 @@ -# Trace-file formatting scripts += Trace-file formatting scripts OSI provides Python scripts for converting trace files from one format to the other. The formatting scripts are stored in `open-simulation-interface/format/` @@ -17,11 +17,11 @@ Allowed values are `'SensorView'`, `'GroundTruth'`, and `'SensorData'`. The default value is `'SensorView'`. `--output`, `-o`:: -Optional string containing the name of the output file., +Optional string containing the name of the output file. The default value is `'converted.osi'`. `--compress`, `-c`:: -Optional boolean controlling whether to compress the output to a lzma file.. +Optional boolean controlling whether to compress the output to a lzma file. Allowed values are `True`, and `False`. The default value is `False`. @@ -39,7 +39,7 @@ Allowed values are `'SensorView'`, `'GroundTruth'`, and `'SensorData'`. The default value is `'SensorView'`. `--output`, `-o`:: -Optional string containing the name of the output file., +Optional string containing the name of the output file. The default value is `'converted.txth'`. `--format`, `-f`:: diff --git a/doc/architecture/trace_file_formats.adoc b/doc/architecture/trace_file_formats.adoc index 9831b8834..6ebda516e 100644 --- a/doc/architecture/trace_file_formats.adoc +++ b/doc/architecture/trace_file_formats.adoc @@ -1,6 +1,6 @@ = OSI trace file formats -There are multiple formats for storing multiple serialized OSI messages into one trace file +There are multiple formats for storing multiple serialized OSI messages into one trace file. *.osi:: Binary trace file. diff --git a/doc/architecture/trace_file_naming.adoc b/doc/architecture/trace_file_naming.adoc index dcd20e497..951b17c69 100644 --- a/doc/architecture/trace_file_naming.adoc +++ b/doc/architecture/trace_file_naming.adoc @@ -19,3 +19,32 @@ Trace file contains sensor-view messages. `gt`:: Trace file contains ground-truth messages. + +**Example** + +Given an OSI trace file with the following information: + +[cols="1,1"] +|=== +|Type +|SensorView + +|OSI Version +|3.1.2 + +|Protobuf Version +|3.0.0 + +|Number of frames +|1523 + +|Scenario name +|highway +|=== + +The recommend file name is: + +[source] +---- +sv_312_300_1523_highway.osi +---- From 3806ef078791d7e76c7ffcf34063ed131932234d Mon Sep 17 00:00:00 2001 From: Maximilian Rosin Date: Wed, 7 Jul 2021 10:41:57 +0200 Subject: [PATCH 4/4] fix(docs): Improve wording after review (#520) Signed-off-by: Maximilian Rosin --- doc/architecture/formatting_scripts.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/architecture/formatting_scripts.adoc b/doc/architecture/formatting_scripts.adoc index 4536f7264..306efa65b 100644 --- a/doc/architecture/formatting_scripts.adoc +++ b/doc/architecture/formatting_scripts.adoc @@ -1,6 +1,6 @@ = Trace-file formatting scripts -OSI provides Python scripts for converting trace files from one format to the other. +The OSI repository contains Python scripts for converting trace files from one format to the other. The formatting scripts are stored in `open-simulation-interface/format/` **txt2osi.py**