Add docs for recognition, user interface and exports

docs/source/conf.py

@@ -44,7 +44,8 @@ myst_enable_extensions = [
     "html_image",
     "attrs_inline",
     "attrs_block",
-    "dollarmath"
+    "dollarmath",
+    "deflist"
 ]
 
 myst_url_schemes = {

docs/source/export/export.md

+# Input and Output
+
+PeTrack works with a variety of files in different formats. This section of the documentation shows what different kind of files PeTrack consumes and what kind of files PeTrack can export itself.
+
+## Contents
+
+```{toctree}
+:maxdepth: 1
+trajectory
+video
+```
\ No newline at end of file

docs/source/export/trajectory.md

+# Trajectory Import and Export
+
+PeTrack supports a few custom trajectory formats. These formats can be exported from PeTrack as well as re-imported into PeTrack.
+
+## TXT-File
+
+### File Format
+
+The `.txt` file is the current main export target for external consumption of the trajectories (e.g. for analysis). The basic format of a `.txt` file is the following:
+
+```
+# PeTrack project: multicolor.pet
+# raw trajectory file: multicolor_truth_selbst.trc
+# framerate: 25 fps
+# z: can be 3d position or height of person (alternating or not)
+# id frame x/m y/m z/m
+1 0 13.7271 1.02799 1.58
+1 1 13.7288 1.03453 1.58
+1 2 13.7288 1.03453 1.58
+1 3 13.7293 1.03445 1.58
+1 4 13.7242 1.02797 1.58
+...
+```
+
+The file starts with a header of comments, all of which start with an `#`. These contain the used PeTrack project file, the `.trc` file containing the raw trajectories, the fps of the video or image sequence and a small explanation what variables are listed in what order.
+
+That is followed by all values, each data point being in one line and containing space separated values.
+
+The information you see in the example above is part of any exported `.txt` file. Depending on the used marker, you can enable even more data to be added to the `.txt` file.
+
+### Export Options
+
+PeTrack has a lot of export options. They either add output to the exported file or perform some additional calculation on export.
+
+insert miss. frames
+: When this option is enabled, PeTrack uses an algorithm to detect frame drops. These dropped frames are then inserted into the export. The position on these dropped frames is linearly interpolated.
+
+:::{note}
+The calculation of missing/dropped frames is expensive. If you know there are no frame drops in your video, let this option disabled.
+:::
+
+recalc. height
+: This option is only relevant for project using a **stereo** camera. This recalculates the height of the pedestrian using the median height of the measured 3D points.
+
+alt. height 
+: This options allows `z` to alternate. This is relevant when alternating height information is available (e.g. when using stereo) and the pedestrians are not at the same height for the whole recording. This could be the case e.g. at staircases. If disabled all `z` coordinates are just the height of the pedestrian.
+
+elim. tp. wo. hgt.
+: This option discards points for which no height was measured. This option only takes effect if `alt. height` is also selected. Note that PeTrack prints a warning for each discarded point, so remember to save the output of PeTrack during the export into a log file.
+
+elim. trj. wo. hgt.
+: This option discards all trajectories which include a point for which no height was measured. This option only takes effect if `alt. height` is also selected. Note that PeTrack prints a warning for each discarded trajectory, so remember to save the output of PeTrack during the export into a log file.
+
+smooth
+: This option smooths the `z` component of trajectories. This has no real effect if `alt. height` is not enabled.
+
+:::{warning}
+The `smooth` option changes the trajectories in-place! That is, when trajectories are exported multiple times with this option enabled, they are also smoothed multiple times!
+:::
+
+add head direction
+: Adds the head direction to the `.txt` file. Head directions can be extracted for different markers. From the currently recommended markers, the code marker as well as the combined multicolor and code marker support this export option. The head direction is saved as a vector with the entires: `viewDirX` and `viewDirY`
+
+add angle of view
+: Adds the angle between the line from the camera to the point and the line from the camera perpendicularly to the ground in radians
+
+use meter
+: Use meter in export instead of centimeter. (**Recommended**)
+
+add comment
+: PeTrack allows to attach comments to pedestrians (`right mouse button > Edit comment`). Enabling this option exports these comments as well
+
+add marker ID
+: Adds the ID of code markers to the export as well. Note that the ID of the person will be put at every point in the trajectory, not only at the points at which the marker was recognized
+
+
+## TRC-File
+
+The `.trc` files are the internal trajectory file format from PeTrack. They are not meant for consumption by any other program but PeTrack and no guarantees on the stability of the format are made.
+
+The `.trc` files can be exported and imported. They are the only files that contain **all** information PeTrack has about a trajectory and therefore the only file which recreates the original trajectories perfectly in import.
+
+When a `.trc` file is exported, its project associated itself with it. If PeTrack find the file when the project is opened again, it is imported automatically. For finding the file PeTrack uses both, the absolute path to the file as well as the relative path of the `.trc` file to the `.pet` project file.
+
+Export options do not apply to `.trc` files.
\ No newline at end of file

docs/source/export/video.md

+# Video View Import and Export
+
+## Import
+
+PeTrack internally uses [ffmpeg](https://ffmpeg.org/) for reading video files. This should support virtually any video file format of practical relevance. PeTrack also supports reading in image series. In this case, the images need to be named with the same stem, followed by an increasing number. In the simplest case, the images are named by numbers only, e.g.
+
+```
+000100000.jpg
+000100001.jpg
+000100002.jpg
+000100003.jpg
+000100004.jpg
+```
+
+## Export
+
+PeTrack allows you to export the video. All of the options related to video export are in the `File` menu from the menu bar.
+
+Export Video
+: Export as video as is, i.e. without undistortion or overlays. Can be used to get video out of image sequence.
+
+Export Video View
+: Export as video as is shown in PeTrack. That is undistortion is applied and all visualizations (e.g. trajectories) are part of the exported video
+
+Export Image
+: Export currently shown frame with undistortion and border, but without any overlays
+
+Export Image Sequence
+: Export as image sequence with undistortion and border, but without any overlays. Can be used to get an image sequence out of a video.
+
+Export View
+: Export currently shown frame with undistortion and overlays
+
+Export View Sequence
+: Export as image sequence with undistortion and overlays.
\ No newline at end of file

docs/source/index.md

@@ -9,15 +9,36 @@ Different kinds of markers (e.g. with height information, head direction, indivi
 
 An executable of `PeTrack` is available [here](https://go.fzj.de/petrack-download).
 
+::::{grid} 2
+:::{grid-item-card}  Getting Started
+:class-card: intro-card
+:link: getting_started
+:link-type: doc
+:link-alt: To getting started
+A guide through a small demo project
+:::
+:::{grid-item-card}  Planning of Experiments
+:class-card: intro-card
+:link: planning/planning
+:link-type: doc
+:link-alt: To planning experiments
+A guide to all things to consider **before** using PeTrack or doing the experiments themselves. Recommended reading during planning to get good quality data.
+:::
+::::
+
+
+## Contents
+
 :::{toctree}
 :maxdepth: 1
 getting_started
-user_interface
 planning/planning
+user_interface/user_interface
 calibration/calibration
 recognition/recognition
 tracking/tracking
 correction/correction
+export/export
 misc/misc
 contribute/contribute
 section/MeinTest

docs/source/misc/FAQ.md

@@ -2,5 +2,11 @@
 
 Frequently Asked Questions
 
-**Where can I get help when I encounter a bug?**  
-Please [open an issue](https://jugit.fz-juelich.de/ped-dyn-emp/petrack/-/issues/new) in our GitLab repository. Mention the expected behaviour, the bug and don't forget to mention the version of PeTrack you used as well as your operaating system.
\ No newline at end of file
+### Where can I get help when I encounter a bug?
+Please [open an issue](https://jugit.fz-juelich.de/ped-dyn-emp/petrack/-/issues/new) in our GitLab repository. Mention the expected behavior, the bug and don't forget to mention the version of PeTrack you used as well as your operating system.
+
+<!--
+### How can I contact the authors?
+
+We can be contacted via the email-address `petrack (at) fz-juelich.de`. Feel free to contact us for advice on experiment setups and similar. However, if your enquiry is about a bug, please [open an issue](https://jugit.fz-juelich.de/ped-dyn-emp/petrack/-/issues/new) instead.
+-->
\ No newline at end of file

docs/source/misc/combine.md

-# Combine Trajectories From Different Videos
-
-Sth. about combining trajectories from different cameras. Combine-Script currently is not public, how do we want to deal with that?
\ No newline at end of file

docs/source/misc/misc.md

@@ -9,5 +9,4 @@ Title page of misc topics, probably just a table of contents
 FAQ
 citation
 batch_processing
-combine
 :::
\ No newline at end of file

docs/source/recognition/aruco.md

-# Aruco Marker
+# Code Marker
 
-Here are the docs on how to use the aruco marker and what its options are
\ No newline at end of file
+The code marker is an aruco marker, a special fiducial tag. This means that not only is the marker designed to be easy and robust to detect, it also contains a code number. Therefore the code marker enables an association of trajectories with other data, e.g. questionnaires. However, the code marker needs a comparatively high resolution (**TODO: reference to Maiks part**). 
+
+## Marker Options
+
+The options for the code marker are entirely contained within the parameter dialog of the marker.
+
+:::{figure-md} aruco-options
+![code marker parameter dialog](images/aurco_options.png)
+
+The option dialog for the code marker.
+:::
+
+The code marker has a lot of options and it is beyond the scope of this documentation to explain all of them. We refer to the [documentation of OpenCV](https://docs.opencv.org/4.5.3/d1/dcd/structcv_1_1aruco_1_1DetectorParameters.html#details) for a more detailed explanation of the parameters (also accessible via the `more infos...` button in the parameter dialog). 
+
+:::{tip}
+In our experience the `adaptive thresholding window` parameters are very influential
+:::
+
+The only option that is unique to PeTrack is `show detected candidates`. When this checkbox is enabled, all candidates are drawn onto the screen. 
+
+:::{figure-md} aruco-candidates
+
+![code marker candidate viz](images/aruco_viz.png)
+
+Visualization of code marker candidates. Successful detections are green, mark the upper left corner and show the id of the marker. Candidates which did not result in a detection, because of an unreadable code, are shown in red. Accordingly, without id.
+:::
+
+## Extra export options
+
+The usage of the code marker enables two new export options to be enabled:
+
+- `add marker id`  
+  Adds the id of the detected code marker to the txt export
+- `add head direction`  
+  The code marker has a fixed orientation. Therefore, its orientation can be detected and exported. If care is given that the orientation of the marker aligns with the orientation of the pedestrian head, this is a measurement of the head view direction.
\ No newline at end of file