### proscene

# Class PSQuaternion

- `java.lang.Object`
- - `proscene.PSQuaternion`

`public class PSQuaternion`
`extends java.lang.Object`

A 4 element unit quaternion represented by single precision floating point x,y,z,w coordinates.

  ## Field Summary
  `float` | `w` The w coordinate which corresponds to the scalar part of the PSQuaternion.
  `float` | `x` The x coordinate, i.e., the x coordinate of the vector part of the PSQuaternion.
  `float` | `y` The y coordinate, i.e., the y coordinate of the vector part of the PSQuaternion.
  `float` | `z` The z coordinate, i.e., the z coordinate of the vector part of the PSQuaternion.

  ## Constructor Summary
  `PSQuaternion()` Constructs and initializes a PSQuaternion to (0.0,0.0,0.0,1.0), i.e., an identity rotation.
  `PSQuaternion(PSQuaternion q1)` Copy constructor.
  `PSQuaternion(PVector from, PVector to)` Constructs a PSQuaternion that will rotate from the `from` direction to the `to` direction.
  `PSQuaternion(PVector axis, float angle)` Constructs and initializes a PSQuaternion from the specified rotation `axis` (non null) and `angle` (in radians).
  `PSQuaternion(float x, float y, float z, float w)` Default constructor for PSQuaternion(float x, float y, float z, float w, boolean normalize), with `normalize=true`.
  `PSQuaternion(float x, float y, float z, float w, boolean normalize)` Constructs and initializes a PSQuaternion from the specified xyzw coordinates.
  `PSQuaternion(float[] q)` Default constructor for PSQuaternion(float[] q, boolean normalize) with `normalize=true`.
  `PSQuaternion(float[] q, boolean normalize)` Constructs and initializes a PSQuaternion from the array of length 4.

  ## Method Summary
  `float` | `angle()` Returns the `angle` (in radians) of the rotation represented by the PSQuaternion.
  `PVector` | `axis()` Returns the normalized axis direction of the rotation represented by the PSQuaternion.
  `void` | `conjugate()` Sets the value of this PSQuaternion to the conjugate of itself.
  `void` | `conjugate(PSQuaternion q1)` Sets the value of this PSQuaternion to the conjugate of PSQuaternion q1.
  `float` | `dotProduct(PSQuaternion b)` Returns the "dot" product of this PSQuaternion and `b`: `this.x * b.x + this.y * b.y + this.z * b.z + this.w * b.w`
  `static float` | `dotProduct(PSQuaternion a, PSQuaternion b)` Returns the "dot" product of `a` and `b`: `a.x * b.x + a.y * b.y + a.z * b.z + a.w * b.w`
  `PSQuaternion` | `exp()` Returns the exponential of the PSQuaternion.
  `void` | `fromAxisAngle(PVector axis, float angle)` Sets the PSQuaternion as a rotation of `axis` and `angle` (in radians).
  `void` | `fromMatrix(PMatrix3D pM)` Set the PSQuaternion from a (supposedly correct) 3x3 rotation matrix given in the upper left 3x3 sub-matrix of the PMatrix3D.
  `void` | `fromRotatedBasis(PVector X, PVector Y, PVector Z)` Sets the PSQuaternion from the three rotated vectors of an orthogonal basis.
  `void` | `fromRotationMatrix(m[][] )` Set the PSQuaternion from a (supposedly correct) 3x3 rotation matrix.
  `void` | `fromTo(PVector from, PVector to)` Sets the PSQuaternion as a rotation from the `from` direction to the `to` direction.
  `PSQuaternion` | `inverse()` Returns the inverse PSQuaternion (inverse rotation).
  `PMatrix3D` | `inverseMatrix()` Returns the associated inverse rotation processing PMatrix3D.
  `PVector` | `inverseRotate(PVector v)` Returns the image of `v` by the PSQuaternion `inverse()` rotation.
  `float[][]` | `inverseRotationMatrix()` Returns the 3x3 inverse rotation matrix associated with the PSQuaternion.
  `void` | `invert()` Sets the value of this PSQuaternion to the inverse of itself.
  `void` | `invert(PSQuaternion q1)` Sets the value of this PSQuaternion to the PSQuaternion inverse of `q1`.
  `static PSQuaternion` | `lnDif(PSQuaternion a, PSQuaternion b)` Simply returns
  `PSQuaternion` | `log()` Returns the logarithm of the PSQuaternion.
  `PMatrix3D` | `matrix()` Returns the PMatrix3D (processing matrix) which represents the rotation matrix associated with the PSQuaternion.
  `void` | `multiply(PSQuaternion q1)` Sets the value of this PSQuaternion to the PSQuaternion product of itself and `q1`, (i.e., `this = this * q1`).
  `static PSQuaternion` | `multiply(PSQuaternion q1, PSQuaternion q2)` Returns the PSQuaternion which is product of quaternions `q1` and `q2`.
  `static PVector` | `multiply(PSQuaternion q1, PVector v)` Returns the image of `v` by the rotation `q1`.
  `PVector` | `multiply(PVector v)` Returns the image of `v` by the rotation of this vector.
  `void` | `multiplyInverse(PSQuaternion q1)` Multiplies this PSQuaternion by the inverse of PSQuaternion `q1` and places the value into this PSQuaternion (i.e., `this = this * q^-1`).
  `static PSQuaternion` | `multiplyInverse(PSQuaternion q1, PSQuaternion q2)` Returns the product of PSQuaternion `q1` by the inverse of PSQuaternion `q2` (i.e., `q1 * q2^-1`).
  `void` | `negate()` Negates all the coefficients of the PSQuaternion.
  `float` | `normalize()` Normalizes the value of this PSQuaternion in place and return its `norm`.
  `static PSQuaternion` | `randomQuaternion()` Returns a random unit PSQuaternion.
  `PVector` | `rotate(PVector v)` Returns the image of `v` by the PSQuaternion rotation.
  `float[][]` | `rotationMatrix()` Returns the 3x3 rotation matrix associated with the PSQuaternion.
  `static PSQuaternion` | `slerp(PSQuaternion a, PSQuaternion b, float t)` Wrapper function that simply calls `slerp(a, b, t, true)`.
  `static PSQuaternion` | `slerp(PSQuaternion a, PSQuaternion b, float t, boolean allowFlip)` Returns the slerp interpolation of quaternions `a` and `b`, at time `t`.
  `static PSQuaternion` | `squad(PSQuaternion a, PSQuaternion tgA, PSQuaternion tgB, PSQuaternion b, float t)` Returns the slerp interpolation of the two quaternions `a` and `b`, at time `t`, using tangents `tgA` and `tgB`.
  `static PSQuaternion` | `squadTangent(PSQuaternion before, PSQuaternion center, PSQuaternion after)` Returns a tangent PSQuaternion for `center`, defined by `before` and `after` quaternions.
  `static float` | `squaredNorm(PSQuaternion q)` Utility function that returns the squared norm of the PSQuaternion.

## Field Details

### w

    public float w

> The w coordinate which corresponds to the scalar part of the PSQuaternion.

### x

    public float x

> The x coordinate, i.e., the x coordinate of the vector part of the PSQuaternion.

### y

    public float y

> The y coordinate, i.e., the y coordinate of the vector part of the PSQuaternion.

### z

    public float z

> The z coordinate, i.e., the z coordinate of the vector part of the PSQuaternion.

## Constructor Details

### PSQuaternion

    public PSQuaternion()

> Constructs and initializes a PSQuaternion to (0.0,0.0,0.0,1.0), i.e., an identity rotation.

### PSQuaternion

    public PSQuaternion(PSQuaternion q1)

> Copy constructor.
> Parameters:
>   `q1` - the PSQuaternion containing the initialization x y z w data

### PSQuaternion

    public PSQuaternion(PVector from,
                        PVector to)

> Constructs a PSQuaternion that will rotate from the `from` direction to the `to` direction.
> Parameters:
>   `from` - the first PVector
>   `to` - the second PVector
> See Also:
>   `fromTo(PVector,PVector)`

### PSQuaternion

    public PSQuaternion(PVector axis,
                        float angle)

> Constructs and initializes a PSQuaternion from the specified rotation `axis` (non null) and `angle` (in radians).
> Parameters:
>   `axis` - the PVector representing the axis
>   `angle` - the angle in radians
> See Also:
>   `fromAxisAngle(PVector,float)`

### PSQuaternion

    public PSQuaternion(float x,
                        float y,
                        float z,
                        float w)

> Default constructor for PSQuaternion(float x, float y, float z, float w, boolean normalize), with `normalize=true`.

### PSQuaternion

    public PSQuaternion(float x,
                        float y,
                        float z,
                        float w,
                        boolean normalize)

> Constructs and initializes a PSQuaternion from the specified xyzw coordinates.
> Parameters:
>   `x` - the x coordinate
>   `y` - the y coordinate
>   `z` - the z coordinate
>   `w` - the w scalar component
>   `normalize` - tells whether or not the constructed PSQuaternion should be normalized.

### PSQuaternion

    public PSQuaternion(float[] q)

> Default constructor for PSQuaternion(float[] q, boolean normalize) with `normalize=true`.

### PSQuaternion

    public PSQuaternion(float[] q,
                        boolean normalize)

> Constructs and initializes a PSQuaternion from the array of length 4.
> Parameters:
>   `q` - the array of length 4 containing xyzw in order

## Method Details

### angle

    public final float angle()

> Returns the `angle` (in radians) of the rotation represented by the PSQuaternion.

> This value is always in the range `[0-pi]`. Larger rotational angles are obtained by inverting the `axis()` direction.
> See Also:
>   `axis()`

### axis

    public final PVector axis()

> Returns the normalized axis direction of the rotation represented by the PSQuaternion.

> The result is null for an identity PSQuaternion.
> See Also:
>   `angle()`

### conjugate

    public final void conjugate()

> Sets the value of this PSQuaternion to the conjugate of itself.

### conjugate

    public final void conjugate(PSQuaternion q1)

> Sets the value of this PSQuaternion to the conjugate of PSQuaternion q1.
> Parameters:
>   `q1` - the source vector

### dotProduct

    public final float dotProduct(PSQuaternion b)

> Returns the "dot" product of this PSQuaternion and `b`:

> `this.x * b.x + this.y * b.y + this.z * b.z + this.w * b.w`
> Parameters:
>   `b` - the PSQuaternion

### dotProduct

    public static final float dotProduct(PSQuaternion a,
                                         PSQuaternion b)

> Returns the "dot" product of `a` and `b`:

> `a.x * b.x + a.y * b.y + a.z * b.z + a.w * b.w`
> Parameters:
>   `a` - the first PSQuaternion
>   `b` - the second PSQuaternion

### exp

    public final PSQuaternion exp()

> Returns the exponential of the PSQuaternion.
> See Also:
>   `log()`

### fromAxisAngle

    public void fromAxisAngle(PVector axis,
                              float angle)

> Sets the PSQuaternion as a rotation of `axis` and `angle` (in radians).

> The `axis` does not need to be normalized. A null `axis` will result in an identity PSQuaternion.
> Parameters:
>   `axis` - the PVector representing the axis
>   `angle` - the angle in radians

### fromMatrix

    public final void fromMatrix(PMatrix3D pM)

> Set the PSQuaternion from a (supposedly correct) 3x3 rotation matrix given in the upper left 3x3 sub-matrix of the PMatrix3D.
> See Also:
>   `fromRotationMatrix(float[][])`

### fromRotatedBasis

    public final void fromRotatedBasis(PVector X,
                                       PVector Y,
                                       PVector Z)

> Sets the PSQuaternion from the three rotated vectors of an orthogonal basis.

> The three vectors do not have to be normalized but must be orthogonal and direct (i,e., `X^Y=k*Z, with k>0`).
> Parameters:
>   `X` - the first PVector
>   `Y` - the second PVector
>   `Z` - the third PVector
> See Also:
>   `fromRotationMatrix(float[][])`, `PSQuaternion(PVector,PVector)`

### fromRotationMatrix

    public final void fromRotationMatrix(m[][] )

> Set the PSQuaternion from a (supposedly correct) 3x3 rotation matrix.

> The matrix is expressed in European format: its three columns are the images by the rotation of the three vectors of an orthogonal basis.

> `fromRotatedBasis(PVector,PVector,PVector)` sets a PSQuaternion from the three axis of a rotated frame. It actually fills the three columns of a matrix with these rotated basis vectors and calls this method.
> Parameters:

### fromTo

    public void fromTo(PVector from,
                       PVector to)

> Sets the PSQuaternion as a rotation from the `from` direction to the `to` direction.

> Attention: this rotation is not uniquely defined. The selected axis is usually orthogonal to `from` and `to`, minimizing the rotation angle. This method is robust and can handle small or almost identical vectors.
> See Also:
>   `fromAxisAngle(PVector,float)`

### inverse

    public final PSQuaternion inverse()

> Returns the inverse PSQuaternion (inverse rotation).

> The result has a negated `axis()` direction and the same `angle()`.

> A composition of a PSQuaternion and its `inverse()` results in an identity function. Use `invert()` to actually modify the PSQuaternion.
> See Also:
>   `invert()`

### inverseMatrix

    public final PMatrix3D inverseMatrix()

> Returns the associated inverse rotation processing PMatrix3D. This is simply `matrix()` of the `inverse()`.

> Attention: The result is only valid until the next call to `inverseMatrix()`. Use it immediately (as in `applyMatrix(q.inverseMatrix())`).

### inverseRotate

    public final PVector inverseRotate(PVector v)

> Returns the image of `v` by the PSQuaternion `inverse()` rotation.

> `rotate(PVector)` performs an inverse transformation.
> Parameters:
>   `v` - the PVector

### inverseRotationMatrix

    public final float[][] inverseRotationMatrix()

> Returns the 3x3 inverse rotation matrix associated with the PSQuaternion.

> Attention: This is the classical mathematical rotation matrix.

### invert

    public final void invert()

> Sets the value of this PSQuaternion to the inverse of itself.
> See Also:
>   `inverse()`

### invert

    public final void invert(PSQuaternion q1)

> Sets the value of this PSQuaternion to the PSQuaternion inverse of `q1`.
> Parameters:
>   `q1` - the PSQuaternion to be inverted

### lnDif

    public static final PSQuaternion lnDif(PSQuaternion a,
                                           PSQuaternion b)

> Simply returns `log(a. inverse() * b)`.

> Useful for `squadTangent(PSQuaternion,PSQuaternion,PSQuaternion)`.
> Parameters:
>   `a` - the first PSQuaternion
>   `b` - the second PSQuaternion

### log

    public final PSQuaternion log()

> Returns the logarithm of the PSQuaternion.
> See Also:
>   `exp()`

### matrix

    public final PMatrix3D matrix()

> Returns the PMatrix3D (processing matrix) which represents the rotation matrix associated with the PSQuaternion.
> See Also:
>   `rotationMatrix()`

### multiply

    public final void multiply(PSQuaternion q1)

> Sets the value of this PSQuaternion to the PSQuaternion product of itself and `q1`, (i.e., `this = this * q1`).
> Parameters:
>   `q1` - the other PSQuaternion

### multiply

    public static final PSQuaternion multiply(PSQuaternion q1,
                                              PSQuaternion q2)

> Returns the PSQuaternion which is product of quaternions `q1` and `q2`.
> Parameters:
>   `q1` - the first PSQuaternion
>   `q2` - the second PSQuaternion

### multiply

    public static final PVector multiply(PSQuaternion q1,
                                         PVector v)

> Returns the image of `v` by the rotation `q1`. Same as `q1.rotate(v).`
> Parameters:
>   `q1` - the PSQuaternion
>   `v` - the PVector
> See Also:
>   `rotate(PVector)`, `inverseRotate(PVector)`

### multiply

    public final PVector multiply(PVector v)

> Returns the image of `v` by the rotation of this vector. Same as `this.rotate(v).`
> Parameters:
>   `v` - the PVector
> See Also:
>   `rotate(PVector)`, `inverseRotate(PVector)`

### multiplyInverse

    public final void multiplyInverse(PSQuaternion q1)

> Multiplies this PSQuaternion by the inverse of PSQuaternion `q1` and places the value into this PSQuaternion (i.e., `this = this * q^-1`). The value of the argument PSQuaternion is preserved.
> Parameters:
>   `q1` - the other PSQuaternion

### multiplyInverse

    public static final PSQuaternion multiplyInverse(PSQuaternion q1,
                                                     PSQuaternion q2)

> Returns the product of PSQuaternion `q1` by the inverse of PSQuaternion `q2` (i.e., `q1 * q2^-1`). The value of both argument quaternions is preserved.
> Parameters:
>   `q1` - the first PSQuaternion
>   `q2` - the second PSQuaternion

### negate

    public final void negate()

> Negates all the coefficients of the PSQuaternion.

### normalize

    public final float normalize()

> Normalizes the value of this PSQuaternion in place and return its `norm`.

### randomQuaternion

    public static final PSQuaternion randomQuaternion()

> Returns a random unit PSQuaternion.

> You can create a randomly directed unit vector using:

> `PVector randomDir = new PVector(1.0f, 0.0f, 0.0f);`
> `randomDir = PSQuaternion.multiply(PSQuaternion.randomQuaternion(), randomDir);`

### rotate

    public final PVector rotate(PVector v)

> Returns the image of `v` by the PSQuaternion rotation.
> Parameters:
>   `v` - the PVector

### rotationMatrix

    public final float[][] rotationMatrix()

> Returns the 3x3 rotation matrix associated with the PSQuaternion.

> Attention: The method returns the European mathematical representation of the rotation matrix.
> See Also:
>   `inverseRotationMatrix()`

### slerp

    public static final PSQuaternion slerp(PSQuaternion a,
                                           PSQuaternion b,
                                           float t)

> Wrapper function that simply calls `slerp(a, b, t, true)`.

> See `slerp(PSQuaternion,PSQuaternion,float,boolean)` for details.

### slerp

    public static final PSQuaternion slerp(PSQuaternion a,
                                           PSQuaternion b,
                                           float t,
                                           boolean allowFlip)

> Returns the slerp interpolation of quaternions `a` and `b`, at time `t`.

> `t` should range in `[0,1]`. Result is a when `t=0` and `b` when `t=1`.

> When `allowFlip` is true (default) the slerp interpolation will always use the "shortest path" between the quaternions' orientations, by "flipping" the source PSQuaternion if needed (see `negate()`).
> Parameters:
>   `a` - the first PSQuaternion
>   `b` - the second PSQuaternion
>   `t` - the t interpolation parameter
>   `allowFlip` - tells whether or not the interpolation allows axis flip

### squad

    public static final PSQuaternion squad(PSQuaternion a,
                                           PSQuaternion tgA,
                                           PSQuaternion tgB,
                                           PSQuaternion b,
                                           float t)

> Returns the slerp interpolation of the two quaternions `a` and `b`, at time `t`, using tangents `tgA` and `tgB`.

> The resulting PSQuaternion is "between" `a` and `b` (result is `a` when `t=0` and `b` for `t=1`).

> Use `squadTangent(PSQuaternion,PSQuaternion,PSQuaternion)` to define the PSQuaternion tangents `tgA` and `tgB`.
> Parameters:
>   `a` - the first PSQuaternion
>   `tgA` - the first tangent PSQuaternion
>   `tgB` - the second tangent PSQuaternion
>   `b` - the second PSQuaternion
>   `t` - the t interpolation parameter

### squadTangent

    public static final PSQuaternion squadTangent(PSQuaternion before,
                                                  PSQuaternion center,
                                                  PSQuaternion after)

> Returns a tangent PSQuaternion for `center`, defined by `before` and `after` quaternions.
> Parameters:
>   `before` - the first PSQuaternion
>   `center` - the second PSQuaternion
>   `after` - the third PSQuaternion

### squaredNorm

    public static float squaredNorm(PSQuaternion q)

> Utility function that returns the squared norm of the PSQuaternion.

processing library glgraphics by Andres Colubri. (c) 2008