com.io7m.jtensors

## Class QuaternionI4D

- java.lang.Object
- - com.io7m.jtensors.QuaternionI4D

- All Implemented Interfaces:
    QuaternionReadable4DType, VectorReadable2DType, VectorReadable3DType, VectorReadable4DType

      @EqualityStructural
       @Immutable
      public final class QuaternionI4D
      extends Object
      implements QuaternionReadable4DType

  A four-dimensional immutable quaternion type with `double` elements.

  Values of this type are immutable and can therefore be safely accessed from multiple threads.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `QuaternionI4D.Context` The ContextQM4F type contains the minimum storage required for all of the functions of the `QuaternionI4D` class.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static QuaternionI4D` | `IDENTITY` The "identity" quaternion, [0.0 0.0 0.0 1.0]

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `QuaternionI4D()` Default constructor, initializing the quaternion with values `[0.0, 0.0, 0.0, 1.0]`
    `QuaternionI4D(double in_x, double in_y, double in_z, double in_w)` Construct a quaternion initialized with the given values.
    `QuaternionI4D(QuaternionReadable4DType q)` Construct a quaternion initialized with the values contained in `q`.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static QuaternionI4D` | `add(QuaternionReadable4DType q0, QuaternionReadable4DType q1)` Calculate the element-wise sum of the quaternions `q0` and `q1`.
    `static boolean` | `almostEqual(com.io7m.jequality.AlmostEqualDouble.ContextRelative context, QuaternionReadable4DType qa, QuaternionReadable4DType qb)` Determine whether or not the quaternions `qa` and `qb` are equal to within the degree of error given in `context`.
    `static QuaternionI4D` | `conjugate(QuaternionReadable4DType q)` Calculate the conjugate of the input quaternion `q`.
    `static double` | `dotProduct(QuaternionReadable4DType q0, QuaternionReadable4DType q1)` Calculate the scalar product of the quaternions `q0` and `q1`.
    `boolean` | `equals(Object obj)`
    `double` | `getWD()`
    `double` | `getXD()`
    `double` | `getYD()`
    `double` | `getZD()`
    `int` | `hashCode()`
    `static QuaternionI4D` | `interpolateLinear(QuaternionReadable4DType q0, QuaternionReadable4DType 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`
    `static boolean` | `isNegationOf(com.io7m.jequality.AlmostEqualDouble.ContextRelative context, QuaternionReadable4DType qa, QuaternionReadable4DType qb)` Return `true` iff `qa` is the negation of `qb`.
    `static QuaternionI4D` | `lookAt(QuaternionI4D.Context context, VectorReadable3DType origin, VectorReadable3DType target, VectorReadable3DType up)` Produce a quaternion that represents a rotation that "looks at" the point at `target` assuming the viewer is at `origin`, using `up` as the "up" vector.
    `static double` | `magnitude(QuaternionReadable4DType q)` Calculate the magnitude of the quaternion `q`.
    `static double` | `magnitudeSquared(QuaternionReadable4DType q)` Calculate the squared magnitude of the quaternion `q`.
    `static QuaternionI4D` | `makeFromAxisAngle(VectorReadable3DType axis, double angle)` Produce a quaternion that represents a rotation of `angle` degrees around the axis specified by `axis`.
    `static QuaternionI4D` | `makeFromRotationMatrix3x3(MatrixReadable3x3DType m)` Produce a quaternion equivalent to the rotation matrix `m`.
    `static QuaternionI4D` | `makeFromRotationMatrix4x4(MatrixReadable4x4DType m)` Produce a quaternion equivalent to the rotation matrix `m`, writing the result to `out`.
    `static <M extends MatrixWritable3x3DType> M` | `makeRotationMatrix3x3(QuaternionReadable4DType q, M m)` Produce a rotation matrix from the quaternion `q`, saving the result to `m`.
    `static <M extends MatrixWritable4x4DType> M` | `makeRotationMatrix4x4(QuaternionReadable4DType q, M m)` Produce a rotation matrix from the quaternion `q`, saving the result to `m`.
    `static QuaternionI4D` | `multiply(QuaternionReadable4DType q0, QuaternionReadable4DType q1)` Multiply the quaternion `q0` by the quaternion `q1` .
    `static QuaternionI4D` | `negate(QuaternionReadable4DType q)` Negate the elements of `q`.
    `static QuaternionI4D` | `normalize(QuaternionReadable4DType q)` Normalize the quaternion `q`, preserqing its direction but reducing it to unit length.
    `static QuaternionI4D` | `scale(QuaternionReadable4DType q, double r)` Scale the quaternion `q` by the scalar `r`.
    `static QuaternionI4D` | `subtract(QuaternionReadable4DType q0, QuaternionReadable4DType q1)` Subtract the quaternion `q0` from the quaternion `q1`.
    `String` | `toString()`

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

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### IDENTITY

          public static final QuaternionI4D IDENTITY

      The "identity" quaternion, [0.0 0.0 0.0 1.0]

  - ### Constructor Detail

    - #### QuaternionI4D

          public QuaternionI4D()

      Default constructor, initializing the quaternion with values `[0.0, 0.0, 0.0, 1.0]`

    - #### QuaternionI4D

          public QuaternionI4D(double in_x,
                               double in_y,
                               double in_z,
                               double in_w)

      Construct a quaternion initialized with the given values.
      Parameters:
        `in_x` - The `x` value
        `in_y` - The `y` value
        `in_z` - The `z` value
        `in_w` - The `w` value

    - #### QuaternionI4D

          public QuaternionI4D(QuaternionReadable4DType q)

      Construct a quaternion initialized with the values contained in `q`.
      Parameters:
        `q` - The source quaternion

  - ### Method Detail

    - #### add

          public static QuaternionI4D add(QuaternionReadable4DType q0,
                                          QuaternionReadable4DType q1)

      Calculate the element-wise sum of the quaternions `q0` and `q1`.
      Parameters:
        `q0` - The left input quaternion
        `q1` - The right input quaternion
      Returns:
        `(q0.x + q1.x, q0.y + q1.y, q0.z + q1.z, q0.w + q1.w)`

    - #### almostEqual

          public static boolean almostEqual(com.io7m.jequality.AlmostEqualDouble.ContextRelative context,
                                            QuaternionReadable4DType qa,
                                            QuaternionReadable4DType qb)

      Determine whether or not the quaternions `qa` and `qb` are equal to within the degree of error given in `context`.
      Parameters:
        `context` - The equality context
        `qa` - The left input quaternion
        `qb` - The right input quaternion
      Returns:
        `true` if the quaternions are almost equal
      Since:
        5.0.0
      See Also:
        `AlmostEqualDouble.almostEqual(ContextRelative, double, double)`

    - #### conjugate

          public static QuaternionI4D conjugate(QuaternionReadable4DType 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(QuaternionReadable4DType q0,
                                          QuaternionReadable4DType 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

    - #### interpolateLinear

          public static QuaternionI4D interpolateLinear(QuaternionReadable4DType q0,
                                                        QuaternionReadable4DType 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`

    - #### isNegationOf

          public static boolean isNegationOf(com.io7m.jequality.AlmostEqualDouble.ContextRelative context,
                                             QuaternionReadable4DType qa,
                                             QuaternionReadable4DType qb)

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

      Each element is compared with `(ContextRelative, double, double)`.

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

    - #### lookAt

          public static QuaternionI4D lookAt(QuaternionI4D.Context context,
                                             VectorReadable3DType origin,
                                             VectorReadable3DType target,
                                             VectorReadable3DType up)

      Produce a quaternion that represents a rotation that "looks at" the point at `target` assuming the viewer is at `origin`, using `up` as the "up" vector.

      The function uses storage preallocated in `context` to avoid any new allocations.

      Parameters:
        `context` - Preallocated storage
        `origin` - The origin point
        `target` - The target point
        `up` - The up vector
      Returns:
        A quaternion looking at the target
      Since:
        7.0.0

    - #### magnitude

          public static double magnitude(QuaternionReadable4DType q)

      Calculate the magnitude of the quaternion `q`. Correspondingly, `magnitude(normalize(q)) == 1.0`.
      Parameters:
        `q` - The input quaternion
      Returns:
        The magnitude of the input quaternion

    - #### magnitudeSquared

          public static double magnitudeSquared(QuaternionReadable4DType q)

      Calculate the squared magnitude of the quaternion `q`.
      Parameters:
        `q` - The input quaternion
      Returns:
        The squared magnitude of the input quaternion

    - #### makeFromAxisAngle

          public static QuaternionI4D makeFromAxisAngle(VectorReadable3DType axis,
                                                        double angle)

      Produce a quaternion that represents a rotation of `angle` degrees around the axis specified by `axis`. `axis` is assumed to be of unit length.
      Parameters:
        `axis` - The normalized vector representing the axis
        `angle` - The angle to rotate, in radians
      Returns:
        A quaternion representing the rotation
      See Also:
        `VectorI3D.normalize(VectorReadable3DType)`, `VectorI4D.normalize(VectorReadable4DType)`

    - #### makeFromRotationMatrix3x3

          public static QuaternionI4D makeFromRotationMatrix3x3(MatrixReadable3x3DType m)

      Produce a quaternion equivalent to the rotation matrix `m`.
      Parameters:
        `m` - The rotation matrix
      Returns:
        A quaternion representing the rotation matrix
      Since:
        5.0.0

    - #### makeFromRotationMatrix4x4

          public static QuaternionI4D makeFromRotationMatrix4x4(MatrixReadable4x4DType m)

      Produce a quaternion equivalent to the rotation matrix `m`, writing the result to `out`.
      Parameters:
        `m` - The rotation matrix
      Returns:
        A quaternion representing the rotation matrix
      Since:
        5.0.0

    - #### makeRotationMatrix3x3

          public static <M extends MatrixWritable3x3DType> M makeRotationMatrix3x3(QuaternionReadable4DType q,
                                                                                   M m)

      Produce a rotation matrix from the quaternion `q`, saving the result to `m`.
      Type Parameters:
        `M` - The precise type of output matrix
      Parameters:
        `q` - The input quaternion
        `m` - The output matrix
      Returns:
        `m`
      Since:
        5.0.0

    - #### makeRotationMatrix4x4

          public static <M extends MatrixWritable4x4DType> M makeRotationMatrix4x4(QuaternionReadable4DType q,
                                                                                   M m)

      Produce a rotation matrix from the quaternion `q`, saving the result to `m`.
      Type Parameters:
        `M` - The precise type of matrix
      Parameters:
        `q` - The input quaternion
        `m` - The output matrix
      Returns:
        `m`
      Since:
        7.0.0

    - #### multiply

          public static QuaternionI4D multiply(QuaternionReadable4DType q0,
                                               QuaternionReadable4DType 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 = QuaternionI4D.multiply(qy, qx); qr1 = QuaternionI4D .multiply(qz, qy);`
      Parameters:
        `q0` - The left input quaternion
        `q1` - The right input quaternion
      Returns:
        The multiplication of the input quaternions

    - #### negate

          public static QuaternionI4D negate(QuaternionReadable4DType q)

      Negate the elements of `q`.
      Parameters:
        `q` - The source quaternion
      Returns:
        The negation of `q`
      Since:
        5.0.0

    - #### normalize

          public static QuaternionI4D normalize(QuaternionReadable4DType q)

      Normalize the quaternion `q`, preserqing its direction but reducing it to unit length.
      Parameters:
        `q` - The input quaternion
      Returns:
        A quaternion with the same orientation as `q` but with magnitude equal to `1.0`

    - #### scale

          public static QuaternionI4D scale(QuaternionReadable4DType q,
                                            double r)

      Scale the quaternion `q` by the scalar `r`.
      Parameters:
        `q` - The input quaternion
        `r` - The scaling value
      Returns:
        `(q.x * r, q.y * r, q.z * r, q.w * r)`

    - #### subtract

          public static QuaternionI4D subtract(QuaternionReadable4DType q0,
                                               QuaternionReadable4DType q1)

      Subtract the quaternion `q0` from the quaternion `q1`.
      Parameters:
        `q0` - The left input quaternion
        `q1` - The right input quaternion
      Returns:
        `(q0.x - q1.x, q0.y - q1.y, q0.z - q1.z)`

    - #### equals

          public boolean equals(@Nullable
                                Object obj)

      Overrides:
        `equals` in class `Object`

    - #### getWD

          public double getWD()

      Specified by:
        `getWD` in interface `VectorReadable4DType`
      Returns:
        The W value of the given vector.

    - #### getXD

          public double getXD()

      Specified by:
        `getXD` in interface `VectorReadable2DType`
      Returns:
        The X value of the given vector.

    - #### getYD

          public double getYD()

      Specified by:
        `getYD` in interface `VectorReadable2DType`
      Returns:
        The Y value of the given vector.

    - #### getZD

          public double getZD()

      Specified by:
        `getZD` in interface `VectorReadable3DType`
      Returns:
        The Z value of the given vector.

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `Object`

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

Copyright © 2016 <code@io7m.com> http://io7m.com