Merge branch 'orientations-example' into 'main'

Orientations example

See merge request !33

docs/Project.toml

 [deps]
+CairoMakie = "13f3f980-e62b-5c42-98c6-ff1f3baf88f0"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 FHist = "68837c9b-b678-4cd5-9925-8a54edc8f695"
 HDF5 = "f67ccb44-e63f-5c2f-98bd-6dc0ccc4ba2f"
@@ -10,4 +11,4 @@ PGFPlotsX = "8314cec4-20b6-5062-9cdb-752b83310925"
 [compat]
 Documenter = "1"
 FHist = "^0.11"
-KM3NeTTestData = "^0.4.14"
+KM3NeTTestData = "^0.4.15"

docs/make.jl

@@ -24,6 +24,7 @@ makedocs(;
             "examples/online_data.md",
             "examples/offline_data.md",
             "examples/cherenkov_times.md",
+            "examples/orientations.md",
             "examples/controlhost.md",
             "examples/hdf5.md",
         ],

docs/src/api.md

@@ -95,6 +95,7 @@ calibratetime
 combine
 Orientations
 Compass
+Quaternion
 floordist
 slew
 slerp

docs/src/examples/orientations.md

+# Orientations
+
+The following example shows how to read orientations from a calibration output
+(ROOT file) and plot the yaw, pitch and roll values for an optical module.
+
+The data used in this example is provided by [KM3NeTTestData.jl](https://git.km3net.de/km3py/km3net-testdata).
+
+```@example 1
+using KM3io
+using KM3NeTTestData
+using CairoMakie
+using Dates
+```
+
+We use [`Makie`](https://makie.org) for plotting:
+```@example 1
+fig = Figure(size=(900, 400), fontsize=16)
+ax_yaw =  Axis(fig[1, 1])
+ax_pitch_and_roll =  Axis(fig[1, 2])
+```
+
+We load the orientations data and extract the quaternions including the corresponding times from it:
+
+```@example 1
+o = read(datapath("calib", "KM3NeT_00000049_0.0.0_00007631_00007676_1.orientations.root"), Orientations)
+qdata = o(808972593)
+```
+
+The times are converted to `DateTime` objects, which Makie will understand and
+display them in a human readable way.
+
+```@example 1
+times = unix2datetime.(qdata.t)
+```
+
+We convert the [`Quaternion`](@ref)s to [`Compass`](@ref)es to be able to access
+the yaw, pitch and roll values.
+
+```@example 1
+compasses = Compass.(qdata.q)
+yaws = [c.yaw for c in compasses]
+pitches = [c.pitch for c in compasses]
+rolls = [c.roll for c in compasses]
+```
+
+...and we populate the plots:
+
+```@example 1
+scatter!(ax_yaw, times, yaws, label="yaw")
+axislegend(ax_yaw, position = :rb)
+
+scatter!(ax_pitch_and_roll, times, pitches, label="pitch")
+scatter!(ax_pitch_and_roll, times, rolls, label="roll")
+axislegend(ax_pitch_and_roll, position = :rt)
+
+fig
+```

src/types.jl

@@ -29,6 +29,11 @@ struct Track
     t::Float64
 end
 
+"""
+
+A simple quaternion derived from a `FieldVector` of StaticArrays, no more, no less.
+
+"""
 struct Quaternion{T} <: FieldVector{4, T}
     q0::T
     qx::T