Package com.io7m.jtensors.core.quaternions

# Class Quaternions4F

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

public final class Quaternions4F extends 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:
      `axis_x` - The X component of the axis
      `axis_y` - The Y component of the axis
      `axis_z` - The Z component of the axis
      `r` - The rotation in radians
    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)`