# `BB.Estimator.Ahrs.Quaternion`
[🔗](https://github.com/beam-bots/bb_estimator_ahrs/blob/main/lib/bb/estimator/ahrs/quaternion.ex#L6)

Scalar (w, x, y, z) quaternion used internally by the AHRS algorithms.

Kept separate from `BB.Math.Quaternion` (Nx-backed) because the AHRS
filters run at hundreds of Hz and the Nx dispatch overhead per
operation dominates the actual arithmetic. Conversion to
`BB.Math.Quaternion` happens at each estimator's input / output
boundary.

Ported from
[gworkman/ahrs](https://github.com/gworkman/ahrs)' `Ahrs.Quaternion`.

# `t`

```elixir
@type t() :: %BB.Estimator.Ahrs.Quaternion{
  w: float(),
  x: float(),
  y: float(),
  z: float()
}
```

# `conjugate`

```elixir
@spec conjugate(t()) :: t()
```

Returns the conjugate of a unit quaternion (also its inverse).

# `from_bb`

```elixir
@spec from_bb(BB.Math.Quaternion.t()) :: t()
```

Constructs from a `BB.Math.Quaternion`.

# `gyro_derivative`

```elixir
@spec gyro_derivative(t(), float(), float(), float()) ::
  {float(), float(), float(), float()}
```

Calculates `q̇`, the time-derivative of a quaternion under angular
velocity `(gx, gy, gz)` in rad/s. Returns a `{ẇ, ẋ, ẏ, ż}` 4-tuple.

# `identity`

```elixir
@spec identity() :: t()
```

Identity quaternion (no rotation).

# `multiply`

```elixir
@spec multiply(t(), t()) :: t()
```

Hamilton-product multiplication. Non-commutative; composes the
right-hand rotation first, then the left.

# `normalise`

```elixir
@spec normalise(t()) :: t()
```

Normalises a quaternion to a unit quaternion. Returns the input
unchanged when its norm is zero.

# `to_bb`

```elixir
@spec to_bb(t()) :: BB.Math.Quaternion.t()
```

Converts to a `BB.Math.Quaternion` for use in a message payload.

---

*Consult [api-reference.md](api-reference.md) for complete listing*