Describe using OSI visualizer (#62)

Signed-off-by: Maximilian Rosin <maximilian.rosin@parson-europe.com>

doc/osi-visualizer_user_guide.adoc

@@ -7,6 +7,7 @@
 
 :topicdir: topics
 :reusedir: reuse
+:imagesdir: _images
 
 // header & footer for html
 // html themes
@@ -49,5 +50,3 @@ include::./use/saving_messages.adoc[leveloffset=+2]
 include::./use/comparing_messages.adoc[leveloffset=+2]
 
 include::./use/configuring_view.adoc[leveloffset=+2]
-
-include::./use/playing_large_files.adoc[leveloffset=+2]

doc/use/comparing_messages.adoc

@@ -1,11 +1,14 @@
 = Comparing OSI message files
 
-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.
+OSI Visualizer comprises a standalone tool to compare two OSI trace files.
+
+**Prerequisites**
+
+* OSI Visualizer is running.
+
+**Steps**
+
+. Open the **File** menu.
+. Select **Python Compare**.
+. Enter the full paths to the two OSI trace files.
+. To export the result, click **Compare**.

doc/use/configuring_view.adoc

@@ -1,11 +1,11 @@
 = Configuring the view
 
-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.
+You can configure the view of the OSI Visualizer in the **View** menu
+
+**Prerequisites**
+
+**Steps**
+
+* Activate **Combine Channels** to play both channels simultaneously.
+* Activate **Show Grid** to show the grid in the canvas.
+* Activate **Show Object** details to display the position, velocity and acceleration of an object selected in the **Objecs Overview** tree

doc/use/playing_messages.adoc

@@ -1,11 +1,32 @@
 = Playing back messages from a trace file
 
-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.
+OSI Visualizer can visualize the content of an OSI trace file.
+
+[[image-playback]]
+image::playback.png[title = "Playback section in the configuration panel."]
+
+**Prerequisites**
+
+OSI Visualizer is running.
+
+**Steps**
+
+. In the configuration panel of the channel, select **Playback**.
+. From the **ZMQ** drop-down list, select the ZMQ pattern you want to use.
+. In the **Load** field, select the OSI trace file.
+. From the **Data** drop-down list, select the ZMQ pattern you want to use.
+. In the **Delay** field, enter the delta-delay in milliseconds.
+  The delta-delay slows down the playback speed by delaying each message by the given value.
+. If you want to publish the messages to localhost, select **Send to Port** and enter the port number you want to send OSI messages to.
+. If you want to add a FMU, check the **FMU** box and select the appropriate FMU file.
+. Once you have configured the channel correctly, press the **Play** button to start the playback. 
+
+**Result**
+
+The channel is playing back the OSI trace file.
+If **Send to Port** is enabled, the messages are sent to localhost at the given port.
+
+**Troubleshooting**
+
+When playing back large trace files, the visualization may not render smoothly.
+In this case, increase the delta-delay.

doc/use/receiving_network.adoc

@@ -1,11 +1,23 @@
 = Receiving OSI messages from a network
 
-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.
+OSI Visualizer can visualize OSI messages received over a network.
+
+[[image-connection]]
+image::connection.png[title = "Connection section in the configuration panel."]
+
+**Prerequisites**
+
+OSI Visualizer is running.
+
+**Steps**
+
+. In the configuration panel of the channel, select **Connection**.
+. In the **IP** field, enter the IP adress of the network.
+. In the **Port** field, enter the port number you want to receive OSI messages at.
+. From the **ZMQ** drop-down list, select the ZMQ pattern you want to use.
+. If you want to add a FMU, check the **FMU** box and select the appropriate FMU file.
+. From the **Data** drop-down list, select the ZMQ pattern you want to use.
+
+**Result**
+
+The channel is set up for receiving OSI messages over the network.

doc/use/running_visualizer.adoc

@@ -1,11 +1,22 @@
-= Running OSI visualizer
-
-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.
+= Running OSI Visualizer
+
+OSI Visualizer is started via the command line.
+
+**Prerequisites**
+
+You have built OSI Visualizer.
+
+**Steps**
+
+. Open a command line interpreter.
+. Change to the OSI Visualizer repository.
+. Run the following command to start OSI Visualizer.
++
+[source]
+----
+./build/osi-visualizer
+----
+
+**Results**
+
+OSI Visualizer is running.

doc/use/running_visualizer_docker.adoc

@@ -1,11 +1,47 @@
-= Running OSI visualizer using Docker
-
-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.
+= Running OSI Visualizer using Docker
+
+Using Docker enables running OSI Visualizer on non-Linux plattforms.
+
+**Prerequisites**
+
+You have built OSI Visualizer Docker image.
+
+**Steps**
+
+. Open a command line interpreter.
+. Change to the OSI Visualizer repository.
+. Run the following command to start OSI Visualizer.
++
+[source]
+----
+sh run-nvidia-docker.sh
+----
++
+. Place Protobuffer files in `osi_pb/` to make them available to OSI Visualizer.
+  This directory is mounted as a volume to the Docker image.
+
+**Results**
+
+OSI Visualizer is running.
+The Protobuffer files are available to OSI Visualizer
+
+**Troubleshooting**
+
+Currently OSI Visualizer is set up and tested to work with the playback option.
+For using other functionalities, for example socket communication, you may need to change the Docker file.
+After running the image, the following error may appear:
+
+[source]
+----
+Creating network “osi-visualizer_default” with the default driver
+No protocol specified QXcbConnection: Could not connect to display:1
+----
+
+If this error message appears, add the following command to the end of the Docker file and run the image again:
+
+[source]
+----
+sudo xhost +
+----
+
+You do not have to build the Docker image again.

doc/use/saving_messages.adoc

@@ -1,11 +1,21 @@
 = Saving OSI messages
 
-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.
+OSI Visualizer can log an OSI message stream and save it to a file.
+By default, OSI Visualizer saves up to 1.000.000 messages.
+can change this threshold via `osiMsgSaveThreshold_` in `appconfig.cpp`.
+
+[[image-save_osi_message]]
+image::save_osi_message.png[title = "Save OSI message button."]
+
+**Prerequisites**
+
+* OSI Visualizer is running.
+* OSI Visualizer is playing messages.
+
+**Steps**
+
+Click **Save OSI Message**.
+
+**Result**
+
+The channel is set up for playing back OSI trace files.

doc/use/showing_field_of_view.adoc

@@ -1,11 +1,22 @@
 = Showing the field of view of a sensor
 
-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.
+OSI Visualizer can visualize the field of view of sensors.
+
+[[image-field_of_view]]
+image::field_of_view.png[title = "Save OSI message button."]
+
+**Prerequisites**
+
+* OSI Visualizer is running.
+
+**Steps**
+
+. In the configuration panel, select **Show Field of View**.
+. In the **MinR** field, enter the minimum range in meter.
+. In the **MaxR** field, enter the maximum range in meter.
+. In the **AP** field, enter the azimuth positive angle in degree.
+. In the **AN** field, enter the azimuth negative angle in degree.
+
+**Result**
+
+The field of view is displayed on the grid.