From 1325927571d3763ca799da50cd9340248847bbc4 Mon Sep 17 00:00:00 2001
From: Tamas Gal <himself@tamasgal.com>
Date: Wed, 3 Jul 2024 13:30:18 +0200
Subject: [PATCH] Update docs on calibration/orientation
---
docs/src/api.md | 2 ++
docs/src/manual/calibration.md | 38 ++++++++++++++++++++++++++++++++--
2 files changed, 38 insertions(+), 2 deletions(-)
diff --git a/docs/src/api.md b/docs/src/api.md
index 48b31501..ee6070d9 100644
--- a/docs/src/api.md
+++ b/docs/src/api.md
@@ -93,8 +93,10 @@ read(filename::AbstractString, T::Type{AcousticsTriggerParameter})
calibrate
calibratetime
combine
+Orientations
floordist
slew
+slerp
```
## Physics
diff --git a/docs/src/manual/calibration.md b/docs/src/manual/calibration.md
index f0a5deec..0dd13974 100644
--- a/docs/src/manual/calibration.md
+++ b/docs/src/manual/calibration.md
@@ -1,5 +1,39 @@
# Calibration
-It's implemented but not documented here yet. Check out the docs `calibrate`
-function's docstring!
+In general, data related to detector calibration are either stored in the
+database or in the [Calibration
+Archive](https://git.km3net.de/auxiliary_data/calibration).
+## Hits
+
+Hit calibration is implemented but not documented here yet. Check out the docs for [`calibrate()`](@ref).
+
+## Module Orientations
+
+Module orientation data is stored in ROOT files which are generated by the Jpp
+framework. The corresponding ROOT files, which are the output of the [dynamic
+calibration
+procedure](https://common.pages.km3net.de/jpp/Position_calibration.PDF), are
+stored in the [Calibration
+Archive](https://git.km3net.de/auxiliary_data/calibration) under
+`orientations/`.
+
+`KM3io.jl` extends the `Base.read` function with a method which reads the whole
+orientations file at once in an object of type [`Orientations`](@ref). This
+object can be called to calculate the orientation of a module (as a quaternion)
+for a given time, as long as the time is within the time range of the
+orientation data. The quaternions from the orientation data are interpolated for
+the given time using [`slerp()`](@ref).
+
+The following example shows how to read the orientation data and obtain the
+orientation quaternion for a module at a given time.
+
+```@example 1
+using KM3io, KM3NeTTestData
+
+o = read(datapath("calib", "KM3NeT_00000133_D_1.0.0_00017397_00017496_1.orientations.root"), Orientations)
+
+module_id = 817589211
+
+q = o(module_id, 1693408347)
+```
--
GitLab