Misc smaller changes

- fix links and ToDo's
- Remove/Hide TOC on index.md
- Add download link for demo to getting started
- Add links to new calib docs to getting started
- Delete syntax test section
- Add How to cite
- other small changes

docs/requirements.txt

@@ -4,4 +4,5 @@ sphinx-book-theme==1.0.1
 sphinx-favicon==1.0.1
 sphinx-notfound-page==1.0.0
 myst-parser==2.0.0
-sphinx-tippy==0.4.1
\ No newline at end of file
+sphinx-tippy==0.4.1
+sphinx-copybutton==0.5.2
\ No newline at end of file

docs/source/calibration/extrinsic_calibration.md

@@ -45,10 +45,10 @@ into PeTrack.
 
 With the combined image of all coordinate points and the point file created, you can now perform the extrinsic calibration
 in PeTrack. For that, open the image of all combined coordinate points (Figure 1) in PeTrack or drag and drop it into the
-[tab view](/user_interface).
+[tab view](/user_interface/user_interface.md).
 
 ::: {Tip}
-To avoid shifting the coordinate system while clicking and dragging the mouse in the [video tab](/user_interface) it is
+To avoid shifting the coordinate system while clicking and dragging the mouse in the [video tab](/user_interface/user_interface.md) it is
 recommended to check the `fix` checkbox in the `coordinate system` and in the `alignment grid` section
 at the bottom of the `calibration tab`.
 :::
@@ -63,7 +63,7 @@ by zooming into the image. In case you are unhappy with the selected point you c
 
 :::{Tip}
 If the green circles that appear around the chosen points are too large for your taste, go to the `tracking` tab in the
-[tab view](/user_interface) and scroll to the `path` section on the page. Here you can uncheck the `head size` checkbox
+[tab view](/user_interface/user_interface.md) and scroll to the `path` section on the page. Here you can uncheck the `head size` checkbox
 to the right of `show current point` and now you are able to enter a smaller value of your own choosing. This value
 represents the size of the green circles.
 :::

docs/source/calibration/intrinsic_calibration.md

@@ -12,7 +12,7 @@ side balanced so a particular view is not overrepresented. [More Information...]
 :::
 
 ## PeTrack Workflow
-After opening PeTrack, the calibration tab will be the opened tab in the [tab view](/user_interface).
+After opening PeTrack, the calibration tab will be the opened tab in the [tab view](/user_interface/user_interface.md).
 For the intrinsic calibration we will focus on the `intrinsic parameters` section in the middle
 of the calibration tab. 
 
@@ -25,7 +25,7 @@ Intrinsic calibration section in PeTrack
 
 :::{Tip}
 To be able to see the changes that occur or the quality of the calibration, it can be helpful to load e.g.
-a video of the experiments into PeTrack. For that, drag a video into the [tab view](/user_interface)
+a video of the experiments into PeTrack. For that, drag a video into the [tab view](/user_interface/user_interface.md)
 of PeTrack.
 :::
 <br>

docs/source/conf.py

@@ -10,33 +10,37 @@ copyright = f"{current_year}, Forschungszentrum Jülich GmbH, IAS-7"
 
 import os
 import re
+
 dir_path = os.path.dirname(os.path.realpath(__file__))
 
 with open(f"{dir_path}/../../CMakeLists.txt") as file:
     for line in file:
-        match = re.search("project\(petrack LANGUAGES CXX VERSION ([0-9]+\.[0-9]+\.[0-9]+)\)", line)
+        match = re.search(
+            "project\(petrack LANGUAGES CXX VERSION ([0-9]+\.[0-9]+\.[0-9]+)\)", line
+        )
         if match is not None:
             version = match[1]
             break
     else:
         raise RuntimeError("Version not found")
 
-#version = '0.1.0'
+# version = '0.1.0'
 release = version
 
 # -- General configuration
 
 extensions = [
-    'sphinx.ext.duration',
-    'sphinx.ext.doctest',
-    'sphinx.ext.intersphinx',
+    "sphinx.ext.duration",
+    "sphinx.ext.doctest",
+    "sphinx.ext.intersphinx",
     "sphinx_design",
     "sphinx.ext.napoleon",
     "sphinx.ext.mathjax",
     "sphinx_favicon",
     "notfound.extension",
+    "sphinx_copybutton",
     "myst_parser",
-    "sphinx_tippy"
+    "sphinx_tippy",
 ]
 
 myst_enable_extensions = [
@@ -45,7 +49,7 @@ myst_enable_extensions = [
     "attrs_inline",
     "attrs_block",
     "dollarmath",
-    "deflist"
+    "deflist",
 ]
 
 myst_url_schemes = {
@@ -59,16 +63,16 @@ myst_heading_anchors = 7
 
 
 intersphinx_mapping = {
-    'python': ('https://docs.python.org/3/', None),
-    'sphinx': ('https://www.sphinx-doc.org/en/master/', None),
+    "python": ("https://docs.python.org/3/", None),
+    "sphinx": ("https://www.sphinx-doc.org/en/master/", None),
 }
-intersphinx_disabled_domains = ['std']
+intersphinx_disabled_domains = ["std"]
 
-templates_path = ['_templates']
+templates_path = ["_templates"]
 
 # -- Options for HTML output
 
-html_theme = 'sphinx_book_theme'
+html_theme = "sphinx_book_theme"
 html_static_path = ["_static"]
 
 html_logo = "_static/logo.png"
@@ -97,7 +101,7 @@ html_theme_options = {
         },
     ],
     "show_toc_level": 3,
-    "announcement": "🚧 This documentation is still under construction! In the meanwhile, please visit <a href='https://go.fzj.de/petrack-wiki'>the wiki</a> instead. 🚧"
+    "announcement": "🚧 This documentation is still under construction! In the meanwhile, please visit <a href='https://go.fzj.de/petrack-wiki'>the wiki</a> instead. 🚧",
 }
 
 html_sidebars = {
@@ -105,4 +109,4 @@ html_sidebars = {
 }
 
 # -- Options for EPUB output
-epub_show_urls = 'footnote'
+epub_show_urls = "footnote"

docs/source/contribute/documentation.md

@@ -8,8 +8,7 @@ is needed.
 
 ## Environment Setup
 
-First of all, you need to have cloned the repository. (**TODO**: link to other
-document, explaining how to clone (and build) PeTrack). Note that you **do not
+First of all, you need to have cloned the repository (for how to do that, see the section [Get the code](../contribute/code_contribution/build_from_source.md#get-the-code) of the source code contribution documentation). Note that you **do not
 need to build PeTrack**, you just need the repository for the documentation
 files. Then you can edit the markdown files in the `docs/source/` directory. Any
 texteditor can be used for this. If you do not have an preferred text editor, we

docs/source/getting_started.md

 # Getting Started 
 
+This page goes through an exemplary project. You can download this example project [here](https://go.fzj.de/petrack-demo-download).
+
 ## Experimental Setup
 
 ### Prepare cameras
@@ -23,8 +25,7 @@ We have made good experiences with the practice to measure and mark points on th
 
 Additional helpers to define the positions of the calibration points: ![helper_01](images/helper_02.png)
 
-**TODO: Make calibration manual into part of this docs**
-For additional help, check out our detailed intrinsic & extrinsic calibration manual Calibration_Manual.pdf
+For additional help, check out our detailed documentation on calibration in the "Planning of Experiments" section: [](planning/calibration.md)
 
 ### After the experiments
 
@@ -34,7 +35,7 @@ For additional help, check out our detailed intrinsic & extrinsic calibration ma
 
 ## Using PeTrack
 
-The usage and some settings will be explained with the provided demo project ('demo' folder) , the folder contains all necessary files to set up a PeTrack project. <!--Make sure also to read our [best practices guide](usage/Best-Practices).-->
+The usage and some settings will be explained with the provided demo project ('demo' folder) , the folder contains all necessary files to set up a PeTrack project. You can download this example project [here](https://go.fzj.de/petrack-demo-download). <!--Make sure also to read our [best practices guide](usage/Best-Practices).-->
 
 ### Calibration
 

docs/source/index.md

@@ -27,10 +27,10 @@ A guide to all things to consider **before** using PeTrack or doing the experime
 ::::
 
 
-## Contents
-
 :::{toctree}
 :maxdepth: 1
+:hidden:
+
 getting_started
 planning/planning
 user_interface/user_interface
@@ -41,5 +41,4 @@ correction/correction
 export/export
 misc/misc
 contribute/contribute
-section/MeinTest
 :::

docs/source/misc/FAQ.md

@@ -2,11 +2,14 @@
 
 Frequently Asked Questions
 
-### Where can I get help when I encounter a bug?
+## How do I cite PeTrack?
+
+See [](citation.md)
+
+## 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?
+
+## 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/citation.md

 # How to cite
 
-How to cite PeTrack correctly.
\ No newline at end of file
+Please cite the general paper as well as the corresponding software version in your publication if PeTrack helps your research.
+
+**General Paper**:  
+Boltes, M. and Seyfried, A.: Collecting Pedestrian Trajectories; In: Neurocomputing, Special Issue on Behaviours in Video, vol. 100, pp. 127-133 (2013)
+
+:::{dropdown} BibTeX General Paper
+```
+@article{BOLTES2013127,
+    title = {Collecting pedestrian trajectories},
+    journal = {Neurocomputing},
+    volume = {100},
+    pages = {127-133},
+    year = {2013},
+    note = {Special issue: Behaviours in video},
+    issn = {0925-2312},
+    doi = {https://doi.org/10.1016/j.neucom.2012.01.036},
+    author = {Maik Boltes and Armin Seyfried},
+    keywords = {Pedestrian detection, Laboratory experiment},
+}
+```
+:::
+
+**Software (version) citation**:  
+For the software citation, you can go to [https://helmholtz.software/software/petrack](https://helmholtz.software/software/petrack) and select the version you used. Then you can either use the DOI of the software version or directly generate the BibTeX entry for the used software version on the website.
\ No newline at end of file

docs/source/recognition/aruco.md

 # Code Marker
 
-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**). 
+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. We recommend at least 8 pixels per bit of the code.
 
 ## Marker Options
 
@@ -18,6 +18,10 @@ The code marker has a lot of options and it is beyond the scope of this document
 In our experience the `adaptive thresholding window` parameters are very influential
 :::
 
+:::{important}
+Select the correct dictionary! It needs to match the dictionary used to print out the codes.
+:::
+
 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

docs/source/recognition/multicolor.md

 # Multicolor Marker
 
-The multicolor marker is a colored hat that pedestrians wear. For a quick rundown on when to use which type of marker, see **TODO ref to Maiks section**. But in a nutshell, the multicolor marker is easy to prepare and works even with low resolution cameras. It can be combined with an code-marker as well, if some cameras are high-resolution and some are not. Then, low-resolution cams fall back to the multicolor marker in case the code cannot be read.
+The multicolor marker is a colored hat that pedestrians wear. The multicolor marker is easy to prepare and works even with low resolution cameras. It can be combined with an code-marker as well, if some cameras are high-resolution and some are not. Then, low-resolution cams fall back to the multicolor marker in case the code cannot be read.
 
 There are two places for settings parameters of the multicolor marker. The parameter window as well as the recognition tab.
 
@@ -17,7 +17,7 @@ In the parameter window, we have a plethora of options:
 The first options concern themselves with combinations of the multicolor marker with other markers, namely the hermes marker and code marker. When the multicolor marker is combined with another marker, first the multicolor detection is run. Afterwards, on the area around the detected head, the other marker is searched. The idea is to combine the robust, but slightly inaccurate multicolor marker with a more accurate and "structured" marker.
 
 use black dot
-: The multicolor marker can be used with a black dot added, essentially creating a combination between the hermes marker and the multicolor marker. **TODO: add picture** This gives a bit more structure for tracking and a smaller specific point in the image to locate. If one does use this, this checkbox should be enabled and the size set to the size of the point in cm. Else, this option can be turned off.
+: The multicolor marker can be used with a black dot added, essentially creating a combination between the hermes marker and the multicolor marker. This gives a bit more structure for tracking and a smaller specific point in the image to locate. If one does use this, this checkbox should be enabled and the size set to the size of the point in cm. Else, this option can be turned off.
 
 use code marker
 : The multicolor marker can be combined with the [code marker](aruco), which is called code marker here. A click onto the `parameter`-button opens the parameter window for the code marker. There the options for the detection of the code marker can be changed. Please refer to the [documentation of the code marker](aruco) for further information on this.
@@ -46,7 +46,7 @@ If you enable `auto correct perspective view`, it is recommended to also enable
 :::
 
 show mask
-: When enabled, we show a mask visualizing the color selection **TODO: true, what about the other mask?**
+: When enabled, we show a mask visualizing the color selection
 
 close radius
 : Closing is a morphological operation to remove small holes. A larger value means, larger holes will be filled. The filter is only applied if `use` is checked.

docs/source/recognition/setting-up.md

@@ -42,7 +42,7 @@ full image
 adjust automatically
 : Sets the ROI as one head size smaller than the tracking ROI
 
-The ROI can be adjusted in the image, by resizing and moving with the mouse. **TODO: Image or GIF of manipulation of ROI**
+The ROI can be adjusted in the image, by resizing and moving with the mouse.
 
 :::{warning}
 The tracking ROI must be larger than the recognition ROI. Any detection outside the tracking ROI will create an entirely new, one point trajectory. We recommend setting the tracking ROI first and then using `adjust automatically` for the recognition ROI

docs/source/section/MeinTest.md

-# This is a test
-
-I want to test some things.
-This is **strong** or *cursive* or _cursive_ or
-
-```
-Some
-unformatted
-text
-```
-
-(subheading-target)=
-## Subheading
-
-With some text asdfjnasöfhaöshf asjföds föijsa följsad kfjsdljflkdsajfjlks jfksa jlkds jösadj föjdsaf ölksj flkajs flksdj fölsaj fölksadj fölkjdsa fölkjdsa fölkdsa fölkadsj fölksaj 
-
-::::{figure-md} abb
-
-:::{image} ../_static/logo.png
-:width: 50%
-:::
-
-This is my caption
-::::
-
-:::{note}
-:name: notiz
-This is a note.
-:::
-
-:::{warning}
-This is a warning
-:::
-
-:::{important}
-This is important!!!!
-:::
-
-:::{tip}
-This is a tip
-:::
-
-:::{math}
-:label: formel
-v = ta + (1-t)b, \qquad t \in [0;1]
-:::
-
-$$ 
-v + x^3 
-$$ (eqn:test)
-
-Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.
-
-(absatz-target)=
-Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. 
-
-Duis autem vel eum iriure dolor in hendrerit in vulputate velit esse molestie consequat, vel illum dolore eu feugiat nulla facilisis at vero eros et accumsan et iusto odio dignissim qui blandit praesent luptatum zzril delenit augue duis dolore te feugait nulla facilisi. Lorem ipsum dolor sit amet, consectetuer adipiscing elit, sed diam nonummy nibh euismod tincidunt ut laoreet dolore magna aliquam erat volutpat. 
-
-Ut wisi enim ad minim veniam, quis nostrud exerci tation ullamcorper suscipit lobortis nisl ut aliquip ex ea commodo consequat. Duis autem vel eum iriure dolor in hendrerit in vulputate velit esse molestie consequat, vel illum dolore eu feugiat nulla facilisis at vero eros et accumsan et iusto odio dignissim qui blandit praesent luptatum zzril delenit augue duis dolore te feugait nulla facilisi. 
-
-Nam liber tempor cum soluta nobis eleifend option congue nihil imperdiet doming id quod mazim placerat facer possim assum. Lorem ipsum dolor sit amet, consectetuer adipiscing elit, sed diam nonummy nibh euismod tincidunt ut laoreet dolore magna aliquam erat volutpat. Ut wisi enim ad minim veniam, quis nostrud exerci tation ullamcorper suscipit lobortis nisl ut aliquip ex ea commodo consequat. 
-
-Duis autem vel eum iriure dolor in hendrerit in vulputate velit esse molestie consequat, vel illum dolore eu feugiat nulla facilisis. 
-
-Test fuer ein paar Referenzen, z.B. auf eine [Abbildung](#abb) oder eine [Notiz](#notiz). Dafuer muss `:name: NAME` mit angegeben werden. Fuer eine Formel sollte man `:label:` verwenden und kriegt eine Referenz der Form [](#formel), [](eqn:test). Fuer Ueberschriften (und Absaetze) kann man mit `(heading-target)=` einen Namen definieren. Dabei kommt diese Markierung **vor** dem Target. Die Referenz sieht so aus: [Ueberschrift](#subheading-target), [Absatz](#absatz-target). Links zu anderen Dokumenten (z.B. [](/getting_started.md), [](/getting_started.md#calibration)) gehen natuerlich auch.
-
-Einen DOI-Link kann man Einbinden mit `<doi:10.1016/j.neucom.2012.01.036>`, das ergibt: <doi:10.1016/j.neucom.2012.01.036>
-
-::::{grid} 2
-:::{grid-item-card}  Title 1
-:class-card: intro-card
-:link: ../index
-:link-type: doc
-:link-alt: To the user guide
-A link to the api documentation page.
-:::
-:::{grid-item-card}  Title 2
-Second card
-:::
-::::
-
-```{toctree}
-content.md
-```
\ No newline at end of file

docs/source/section/content.md

-# Mein toller conent
-
-sadkjf skjda fkjds hfkjsad fkjds hfkjdsa hfjsa hflkjsa hflksah flkjs hflkjds hflkjdsa hflkjdsa hflkas hf
\ No newline at end of file

docs/source/user_interface/user_interface.md

@@ -82,7 +82,7 @@ Timecode
 : This part of the status bar displays the timecode corresponding to the current frame. Since the timecode is taken from the video file, this does not necessarily correspond to either the real world time nor does it need to start at zero. In stereo recordings, this can also show the time given by a time file.
 
 Current Framerate
-: This shows the framerate at which the player is currently playing. Note that there is sime *intertia* to how fast this display updates. The color indicated whether we play slower than realtime (red) or at realtime or faster (green). (**TODO: we can also click on it to fix speeds... do we want to document that? There now is a more intuitive entry in the menu bar for it**)
+: This shows the framerate at which the player is currently playing. Note that there is sime *intertia* to how fast this display updates. The color indicated whether we play slower than realtime (red) or at realtime or faster (green).
 
 Probing Height
 : The following data fields contain some information about the position of the pixel under the mouse cursor. Due to the perspective projection onto the camera, this information can only be given when assuming a certain height, i.e. the position of the pixel under the cursor is different, if the object under the cursor is 180cm or 150cm high. This box is for changing the height used for the next few fields