Package com.io7m.jtensors.core.quaternions

# Class Quaternions4F

java.lang.Object
com.io7m.jtensors.core.quaternions.Quaternions4F

    public final class Quaternions4F
    extends java.lang.Object

Functions over `Quaternion4F` values.

See "Mathematics for 3D Game Programming and Computer Graphics" 2nd Ed for the derivations of most of the code in this class (ISBN: 1-58450-277-0).

Since:
  8.0.0

- ## Nested Class Summary

  Nested Classes
  Modifier and Type | Class | Description
  --- | --- | ---
  `static interface` | `Quaternions4F.ComponentComparatorType` | The type of comparison functions for values of type `Quaternion4F`.

- ## Method Summary

  Modifier and Type | Method | Description
  --- | --- | ---
  `static Quaternion4F` | `add​(Quaternion4F q0, Quaternion4F q1)` | Add `q0` to `q1`.
  `static Quaternion4F` | `conjugate​(Quaternion4F q)` | Calculate the conjugate of the input quaternion `q`.
  `static double` | `dotProduct​(Quaternion4F q0, Quaternion4F q1)` | Calculate the scalar product of the quaternions `q0` and `q1`.
  `static Quaternion4F` | `identity()` | The identity quaternion.
  `static Quaternion4F` | `interpolateLinear​(Quaternion4F q0, Quaternion4F q1, double alpha)` | Linearly interpolate between `q0` and `q1` by the amount `alpha`, such that:
  `static Quaternion4F` | `interpolateSphericalLinear​(Quaternion4F q0, Quaternion4F q1, double alpha)` | Interpolate between `q0` and `q1`, using spherical linear interpolation, by the amount `alpha`, such that:
  `static boolean` | `isNegationOf​(Quaternions4F.ComponentComparatorType c, Quaternion4F qa, Quaternion4F qb)` | Return `true` iff `qa` is the negation of `qb`.
  `static double` | `magnitude​(Quaternion4F q0)` | Calculate the magnitude of the quaternion `q0`.
  `static double` | `magnitudeSquared​(Quaternion4F q0)` | Calculate the squared magnitude of the quaternion `q0`.
  `static Quaternion4F` | `multiply​(Quaternion4F q0, Quaternion4F q1)` | Multiply the quaternion `q0` by the quaternion `q1`.
  `static Quaternion4F` | `negate​(Quaternion4F q)` | Calculate the negation of the input quaternion `q`.
  `static Quaternion4F` | `normalize​(Quaternion4F q0)` | Normalize the quaternion `q0`.
  `static Quaternion4F` | `ofAxisAngle​(double axis_x, double axis_y, double axis_z, double r)` | Calculate a quaternion that represents a rotation of `r` radians around the axis `(axis_x, axis_y, axis_z)`.
  `static Quaternion4F` | `ofMatrix4x4​(Matrix4x4F m)` | Calculate a quaternion that represents the rotation given by the matrix `m`.
  `static <A,​ B> Quaternion4F` | `ofPMatrix4x4​(PMatrix4x4F<A,​B> m)` | Calculate a quaternion that represents the rotation given by the matrix `m`.
  `static Quaternion4F` | `scale​(Quaternion4F q0, double r)` | Scale `q0` by `r`.
  `static Quaternion4F` | `subtract​(Quaternion4F q0, Quaternion4F q1)` | Add `q0` to `q1`.
  `static Matrix4x4F` | `toMatrix4x4​(Quaternion4F q)` | Create a 4x4 matrix from the quaternion `q`.
  `static <A,​ B> PMatrix4x4F<A,​B>` | `toPMatrix4x4​(Quaternion4F q)` | Create a 4x4 matrix from the quaternion `q`.
  `static Quaternion4F` | `zero()` | The zero quaternion.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Method Details

  - ### add

    public static Quaternion4F add​(Quaternion4F q0, Quaternion4F q1)
    Add `q0` to `q1`.
    Parameters:
      `q0` - The left quaternion
      `q1` - The right quaternion
    Returns:
      `(q0.x + q1.x, q0.y + q0.y, q0.z + q1.z, q0.w + q1.w)`

  - ### conjugate

    public static Quaternion4F conjugate​(Quaternion4F q)
    Calculate the conjugate of the input quaternion `q`.
    Parameters:
      `q` - The input quaternion
    Returns:
      The conjugate of the input quaternion

  - ### dotProduct

    public static double dotProduct​(Quaternion4F q0, Quaternion4F q1)
    Calculate the scalar product of the quaternions `q0` and `q1`.
    Parameters:
      `q0` - The left input quaternion
      `q1` - The right input quaternion
    Returns:
      The scalar product of the two quaternions

  - ### identity

    public static Quaternion4F identity()
    The identity quaternion.
    Returns:
      `(0, 0, 0, 1)`

  - ### interpolateLinear

    public static Quaternion4F interpolateLinear​(Quaternion4F q0, Quaternion4F q1, double alpha)

    Linearly interpolate between `q0` and `q1` by the amount `alpha`, such that:

    - `interpolateLinear(q0, q1, 0.0) = q0`
    - `interpolateLinear(q0, q1, 1.0) = q1`
    Parameters:
      `q0` - The left input quaternion
      `q1` - The right input quaternion
      `alpha` - The interpolation value, between `0.0` and `1.0`
    Returns:
      `(1 - alpha) * q0 + alpha * q1`

  - ### interpolateSphericalLinear

    public static Quaternion4F interpolateSphericalLinear​(Quaternion4F q0, Quaternion4F q1, double alpha)

    Interpolate between `q0` and `q1`, using spherical linear interpolation, by the amount `alpha`, such that:

    - `interpolateSphericalLinear(q0, q1, 0.0) = normalize(q0)`
    - `interpolateSphericalLinear(q0, q1, 1.0) = normalize(q1)`

    Note that unlike simple linear interpolation, this function is guaranteed to return a normalized quaternion.

    Parameters:
      `q0` - The left input quaternion
      `q1` - The right input quaternion
      `alpha` - The interpolation value, between `0.0` and `1.0`
    Returns:
      A spherical-linearly interpolated quaternion between `q0` and `q1`

  - ### isNegationOf

    public static boolean isNegationOf​(Quaternions4F.ComponentComparatorType c, Quaternion4F qa, Quaternion4F qb)

    Return `true` iff `qa` is the negation of `qb`.

    Parameters:
      `qa` - The left quaternion
      `qb` - The right quaternion
    Returns:
      `true` iff `qa` is the negation of `qb`

  - ### magnitudeSquared

    public static double magnitudeSquared​(Quaternion4F q0)
    Calculate the squared magnitude of the quaternion `q0`.
    Parameters:
      `q0` - The quaternion
    Returns:
      The squared magnitude of the quaternion

  - ### magnitude

    public static double magnitude​(Quaternion4F q0)
    Calculate the magnitude of the quaternion `q0`.
    Parameters:
      `q0` - The quaternion
    Returns:
      The magnitude of the quaternion

  - ### multiply

    public static Quaternion4F multiply​(Quaternion4F q0, Quaternion4F q1)

    Multiply the quaternion `q0` by the quaternion `q1`.

    Note that this operation is not commutative.

    The function is most often used to concatenate quaternions to combine rotations. As an example, assuming that:

    - `qx` represents some rotation around the X axis
    - `qy` represents some rotation around the Y axis
    - `qz` represents some rotation around the Z axis

    The following code produces a quaternion `qr1` that represents a rotation around the X axis, followed by a rotation around the Y axis, followed by a rotation around the Z axis:

    `qr0 = multiply(qy, qx); qr1 = multiply(qz, qy);`
    Parameters:
      `q0` - The left input quaternion
      `q1` - The right input quaternion
    Returns:
      The multiplication of the input quaternions

  - ### normalize

    public static Quaternion4F normalize​(Quaternion4F q0)

    Normalize the quaternion `q0`.

    If the magnitude of the quaternion is zero, the function returns `q0`.

    Parameters:
      `q0` - The quaternion
    Returns:
      A normalized copy of `q0`

  - ### negate

    public static Quaternion4F negate​(Quaternion4F q)
    Calculate the negation of the input quaternion `q`.
    Parameters:
      `q` - The input quaternion
    Returns:
      The negation of the input quaternion

  - ### ofAxisAngle

    public static Quaternion4F ofAxisAngle​(double axis_x, double axis_y, double axis_z, double r)
    Calculate a quaternion that represents a rotation of `r` radians around the axis `(axis_x, axis_y, axis_z)`.
    Parameters:
      `r` - The rotation in radians
      `axis_x` - The X component of the axis
      `axis_y` - The Y component of the axis
      `axis_z` - The Z component of the axis
    Returns:
      A quaternion

  - ### ofMatrix4x4

    public static Quaternion4F ofMatrix4x4​(Matrix4x4F m)
    Calculate a quaternion that represents the rotation given by the matrix `m`.
    Parameters:
      `m` - The matrix
    Returns:
      A quaternion

  - ### ofPMatrix4x4

    public static <A,​ B> Quaternion4F ofPMatrix4x4​(PMatrix4x4F<A,​B> m)
    Calculate a quaternion that represents the rotation given by the matrix `m`.
    Type Parameters:
      `A` - A phantom type parameter, possibly representing a source coordinate system
      `B` - A phantom type parameter, possibly representing a target coordinate system
    Parameters:
      `m` - The matrix
    Returns:
      A quaternion

  - ### scale

    public static Quaternion4F scale​(Quaternion4F q0, double r)
    Scale `q0` by `r`.
    Parameters:
      `q0` - The left quaternion
      `r` - The scaling value
    Returns:
      `(q0.x * r, q0.y * r, q0.z * r, q0.w * r)`

  - ### subtract

    public static Quaternion4F subtract​(Quaternion4F q0, Quaternion4F q1)
    Add `q0` to `q1`.
    Parameters:
      `q0` - The left quaternion
      `q1` - The right quaternion
    Returns:
      `(q0.x - q1.x, q0.y - q0.y, q0.z - q1.z, q0.w - q1.w)`

  - ### toMatrix4x4

    public static Matrix4x4F toMatrix4x4​(Quaternion4F q)
    Create a 4x4 matrix from the quaternion `q`.
    Parameters:
      `q` - The quaternion
    Returns:
      A matrix based on q

  - ### toPMatrix4x4

    public static <A,​ B> PMatrix4x4F<A,​B> toPMatrix4x4​(Quaternion4F q)
    Create a 4x4 matrix from the quaternion `q`.
    Type Parameters:
      `A` - A phantom type parameter, possibly representing a source coordinate system
      `B` - A phantom type parameter, possibly representing a target coordinate system
    Parameters:
      `q` - The quaternion
    Returns:
      A matrix based on q

  - ### zero

    public static Quaternion4F zero()
    The zero quaternion.
    Returns:
      `(0, 0, 0, 0)`