Describe trace file formats and naming

doc/architecture/formatting_scripts.adoc

@@ -1,12 +1,48 @@
-= Formatting scripts
+= Trace-file formatting scripts
 
-TODO: Add general description.
+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/`
 
-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`.

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

doc/architecture/trace_file_naming.adoc

@@ -1,9 +1,50 @@
 = 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.
+**Name format**
+
+Names of OSI trace files should have the following format:
+
+[source]
+----
+<type>_<osi-version>_<protobuf-version>_<frame-number>_<custom-trace-name>.osi
+----
+
+**Types**
+
+`sd`::
+Trace file contains sensor-data messages.
+
+`sv`::
+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
+----