Initial commit of fourth draft

.gitignore

+build
\ No newline at end of file

GNUmakefile

+# SPDX-License-Identifier: GPL-3.0-or-later
+
+BUILD_DIR ?= ./build
+
+MKDIR ?= mkdir -p
+RMDIR ?= $(RM) -r
+EMACS ?= emacs
+LATEXMK ?= latexmk
+
+SRCS := $(shell find $(SRC_DIRS) -name *.c)
+OBJS := $(SRCS:%=$(BUILD_DIR)/%.o)
+
+.PHONY: pdf
+pdf: $(BUILD_DIR)/src/main.pdf
+
+$(BUILD_DIR)/%.pdf: $(BUILD_DIR)/%.tex
+	$(LATEXMK) -pdf -pdflatex="pdflatex -interaction=nonstopmode" -cd $<
+
+$(BUILD_DIR)/%.tex: %.org
+	$(EMACS) --batch --load publish.el $< latex
+
+.PHONY: clean
+
+clean:
+	$(RMDIR) $(BUILD_DIR)

publish.el

+;; SPDX-License-Identifier: GPL-3.0-or-later
+
+(setq backup-inhibited t)
+
+(org-babel-do-load-languages
+ 'org-babel-load-languages '((latex . t)))
+
+(setq org-confirm-babel-evaluate nil)
+(setq org-publish-use-timestamps-flag nil)
+
+(setq org-publish-project-alist
+		`(("project"
+			:base-directory "."
+			:exclude ".*"
+			:include [,(elt argv 0)]
+			:publishing-directory "build"
+			:publishing-function ,(cond
+										  ((equal (elt argv 1) "latex") 'org-latex-publish-to-latex)
+										  )
+			)))
+(org-publish "project")

src/main.org

+# SPDX-License-Identifier: GPL-3.0-or-later
+
+#+title: RoboFish Track Format 
+#+subtitle: Draft 4
+
+#+author: Moritz Maxeiner
+#+email: moritz.maxeiner@fu-berlin.de
+
+#+options: toc:nil email:t
+
+#+latex_class: article
+#+latex_header: \usepackage{tikz}
+#+latex_header: \usepackage{float}
+#+latex_header: \usepackage{parskip}
+#+latex_header: \usetikzlibrary{trees}
+#+latex_header: \usetikzlibrary{shapes.geometric}
+
+* Purpose
+
+This document serves as an interface specification so that \((1)\) all components of the RoboFish system can exchange tracking data in a standardized format and \((2)\) people have an easier time familiarizing themselves with RoboFish.
+
+* Definitions
+
+The \emph{world} is the rectangular environment in which entities may exist, move around, and interact. It uses a coordinate system with the origin at the center of the world and centimeters as the unit of distance; its coordinate space is called the \emph{world space}.
+
+#+begin_src latex :results (cl-case org-export-current-backend (latex "replace") (t "none"))
+\begin{figure}[H]
+\centering
+\begin{tikzpicture}
+    \draw [-] (-2,-2) rectangle (2,2);
+
+    \draw [->,thick] (-2,0) -- (2,0) node (xaxis) [right] {\(x\)};
+    \draw [->,thick] (0,-2) -- (0,2) node (yaxis) [above] {\(y\)};
+\end{tikzpicture}
+\caption{World space}
+\end{figure}
+#+end_src
+
+The \emph{pose} of an entity is the tuple \((x,y,\hat{x},\hat{y})\) which configures it in world space, at some point in time, with position \((x,y)\) and normalized orientation \((\hat{x},\hat{y})\). It maps the entity's internal coordinate space (\emph{entity space}) to world space as follows: Rotate by \(\angle((0,1), (\hat{x},\hat{y}))\), then translate by \((x,y)\).
+
+The \emph{outline} of an entity is a simple polygonal chain \((O_1,\ldots,O_n)\) of points in entity space that forms a hull around the entity.
+
+* Data format
+
+#+begin_src latex :results (cl-case org-export-current-backend (latex "replace") (t "none"))
+\begin{figure}[H]
+\centering
+\begin{tikzpicture}[ %
+grow via three points={one child at (0.5,-0.7) and two children at (0.5,-0.7) and (0.5,-1.4)},
+edge from parent path={(\tikzparentnode.south)|-(\tikzchildnode.west)}%
+]
+    \tikzset{every node/.style={draw=black,thick,anchor=west}}
+
+    \node[rounded corners]{root}
+    %
+    child{node[rounded corners]{entities}
+        child{node[rounded corners]{fish}
+            child{node{poses}}
+            child{node{outlines}}
+            child{node[rounded corners]{time}
+                child{node{monotonic points}}
+                child{node{calendar points}}
+            }
+        }
+    };
+\end{tikzpicture}
+\caption{Example HDF file structure for a single tracked fish}
+\end{figure}
+#+end_src
+
+An HDF 5 file with the following hierarchy must be used:
+
+The root group of the file must have the following attributes:
+
+#+attr_latex: :align |c|c|c|c|
+|---------------------------+----------------+-------------+-------------------------------|
+| *name*                      | *type*           | *cardinality* | *description*                   |
+|---------------------------+----------------+-------------+-------------------------------|
+| version                   | 32-bit integer | scalar      | Specification version         |
+| world size | 32-bit float   | 2           | width and height of the world |
+|---------------------------+----------------+-------------+-------------------------------|
+
+Any other global metadata must be represented by additional attributes of the root group.
+
+The root group must have the child group \emph{entities}, each child of which must be a group describing a single entity.
+
+An entity group may have any non-empty name, but no two such groups may have the same name.
+
+An entity's poses must be represented in its group by a 2-dimensional 32-bit float dataset named \emph{poses} with the axes time, coordinate. If the dataset's first dimension has size \(1\), the entity is considered \emph{fixed in place}.
+
+If an entity's group contains a child named \emph{outlines}, it must be a 3-dimensional 32-bit float dataset representing the entity's outlines with the axes time, point, coordinate. Any outline with less points than the size of \emph{outlines}' second dimension must pad with trailing \((\emph{NaN},\emph{NaN})\). If the dataset's first dimension has size \(1\), the entity is considered to have a \emph{fixed outline}.
+
+The entity's points in time must be represented in its group by a child group named \emph{time}, which must have exactly one of the following:
+    - a scalar 32-bit integer attribute named \emph{monotonic step}, which specifies the number of milliseconds between two adjacent points in time.
+    - a 1-dimensional 64-bit integer dataset named \emph{monotonic points}, which specifies each point in time as milliseconds on a monotonic clock.
+    - neither of the above, in which case the entity must be both \emph{fixed in place} and have a \emph{fixed outline}.
+
+If an entity's \emph{time} group contains a child named \emph{calendar points}, it must be a 1-dimensional string dataset, each specifying a point in time as a date on the Gregorian calendar and a time relative to that date in ISO 8601 extended format with millisecond precision and time zone designator, e.g. "2020-11-18T13:21:34.117+01:00".