Quaternion

java.lang.Object
- graphicslib3D.Quaternion

All Implemented Interfaces:

java.lang.Cloneable
```
public class Quaternion
extends java.lang.Object
implements java.lang.Cloneable
```
This class defines a quaternion -- an object representing an orientation in space. Every quaternion has a scalar part and a vector part; the vector part encodes an axis of rotation in 3D space and the scalar part encodes an angle of rotation about that axis. Note that these encoded values are related to the angle and axis-of-rotation of the quaternion, but are not precisely equal to them. Specifically, if w is the scalar part and [x,y,z] is the vector part of a quaternion, then the quaternion represents an orientation comprised of an angle of rotation about an axis of rotation as follows:
```
                angle = 2 * arccos(w)
                axis = [ x/sin(angle/2), y/sin(angle/2), z/sin(angle/2) ]
 
```
Author:

John Clevenger, Ben Botto

Constructor Summary

Constructors
Constructor and Description
`Quaternion()` Constructs a Quaternion with default values (1, [0 0 0]), which is the Identity quaternion representing zero rotation.
`Quaternion(double[] angleAxis)` Constructs a quaternion representing an orientation specified by an angle of rotation and an axis of rotation represented with real values.
`Quaternion(double scalarPart, double[] vectorPart)` Constructs a quaternion with the specified scalar and vector parts.
`Quaternion(double angle, Vector3D axis)` Constructs a quaternion representing an orientation specified by an angle of rotation and a `Vector3D` giving the axis of rotation.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`Quaternion`	`add(Quaternion other)` Returns a new quaternion which is the result of adding this quaternion to the specified other quaternion.
`java.lang.Object`	`clone()` Returns a new `Quaternion` which is a deep clone of this Quaternion.
`Quaternion`	`conjugate()` Returns a new `Quaternion` which is the conjugate of this `Quaternion`.
`double`	`dot(Quaternion other)` Returns the dot-product of this quaternion with the specified quaternion.
`double[]`	`getAngleAxis()` Returns the angle and axis of rotation specified by this quaternion.
`double[]`	`getV()` Returns the vector part of this quaternion.
`double`	`getW()` Returns the scalar part of this quaternion.
`double`	`magnitude()` Returns the magnitude of this quaternion, where magnitude equals the square root of the sum of the squares of the four constituent parts of the quaternion (the scalar part and the three components of the axis part).
`Point3D`	`mult(Point3D point)` Rotate the point about this quaternion.
`Vector3D`	`mult(Vector3D vec)` Multiply this Quaternion by a vec, and return the new Vector3D.
`Quaternion`	`multiplyBy(double scaleFactor)` Returns a new quaternion which is the result of multiplying (scaling) this quaternion by the specified scale factor.
`Quaternion`	`multiplyBy(Quaternion q)` Returns a new quaternion which is the product of this quaternion post-multiplied by the specified quaternion.
`void`	`normalize()` Normalizes this quaternion; that is, forces it to be of unit length.
`Point3D`	`pivot(Point3D point, Point3D about)` Overload of pivot(Vector3D, Point3D).
`Vector3D`	`pivot(Vector3D vec, Point3D about)` Pivot a vector about a point using the rotation defined by this quaternion.
`Vector3D`	`rotate(Vector3D v)` Returns a `Vector3D` which is the result of applying the rotation specified by this quaternion to the specified `Vector3D`.
`void`	`setV(double[] v)` Specifies a new vector part for this quaternion.
`void`	`setW(double w)` Specifies a new value for the scalar part of this quaternion.
`Quaternion`	`slerp(Quaternion quat, double amount)` Spherical interpolation between this quaternion and quat.
`Matrix3D`	`toMatrix3D()` Convert this Quaternion to a rotation matrix.
`java.lang.String`	`toString()` Returns a String representation of this quaternion.

Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Constructor Detail
  - Quaternion
```
public Quaternion()
```
    Constructs a Quaternion with default values (1, [0 0 0]), which is the Identity quaternion representing zero rotation.
  - Quaternion
```
public Quaternion(double scalarPart,
                  double[] vectorPart)
```
    Constructs a quaternion with the specified scalar and vector parts. Note that the values passed in to this constructor are interpreted as the scalar and vector parts of the new quaternion, not the angle/axis values of the corresponding rotation in 3D space (see the class header comments for a description of the relationship between the scalar and vector parts and the corresponding angle and axis of rotation). Note in particular that this means that the scalar part must lie in the range -1..1, since the scalar part of a quaternion represents a cosine.
    
    Parameters:
    
    scalarPart - A double representing the scalar part of the quaternion
    
    vectorPart - An array of doubles representing the [x,y,z] vector part of the quaternion
    
    See Also:
    
    Quaternion(double[])
  - Quaternion
```
public Quaternion(double[] angleAxis)
```
    Constructs a quaternion representing an orientation specified by an angle of rotation and an axis of rotation represented with real values. Note that unlike the constructor Quaternion(double,double[]), this constructor expects as input the angle of rotation and axis of rotation in 3D space.
    
    Parameters:
    
    angleAxis - An array of doubles where [0] specifies an angle of rotation in degrees and [1][2][3] specify the [x y z] components of an axis of rotation.
    
    See Also:
    
    Quaternion(double, double[])
  - Quaternion
```
public Quaternion(double angle,
                  Vector3D axis)
```
    Constructs a quaternion representing an orientation specified by an angle of rotation and a Vector3D giving the axis of rotation. Note that unlike the constructor Quaternion(double,double[]), this constructor expects as input the angle of rotation in degrees and axis of rotation in 3D space.
    
    Parameters:
    
    angle - The angle of rotation in degrees represented by this quaternion
    
    axis - The axis of rotation represented by this quaternion
- Method Detail
  - getAngleAxis
```
public double[] getAngleAxis()
```
    Returns the angle and axis of rotation specified by this quaternion. The returned angle of rotation is in degrees.
    
    Returns:
    
    [0] the current angle of rotation in degrees; [1] [2] [3] the x, y, and z components respectively of the current axis of rotation
  - magnitude
```
public double magnitude()
```
    Returns the magnitude of this quaternion, where magnitude equals the square root of the sum of the squares of the four constituent parts of the quaternion (the scalar part and the three components of the axis part).
    
    Returns:
    
    the magnitude of this quaternion.
  - normalize
```
public void normalize()
```
    Normalizes this quaternion; that is, forces it to be of unit length. Note that normalization is done "in place"; that is, this method alters the current quaternion and returns nothing (void).
  - multiplyBy
```
public Quaternion multiplyBy(Quaternion q)
```
    Returns a new quaternion which is the product of this quaternion post-multiplied by the specified quaternion. Note that this method returns a new quaternion; it does not alter this quaternion. Note also that the returned quaternion is not necessarily a unit quaternion.
    The definition of the product of two quaternions is that of quaternion multiplication:
```
                For quaternions  q1 = (w1, v1[x1,y1,z1])  and  q2 = (w2, v2[x2,y2,z2]),
 
                q1 * q2 = [ ( w1*w2 - (v1 dot v2) ), ( w1*v2 + w2*v1 + (v1 cross v2) ) ]
 
```
    where 'w' represents the scalar part of a quaternion and v represents the vector part of a quaternion.
    Parameters:
    
    q - the quaternion to be post-multiplied with this quaternion
    
    Returns:
    
    a new quaterion qnew = thisQuaternion * q
  - multiplyBy
```
public Quaternion multiplyBy(double scaleFactor)
```
    Returns a new quaternion which is the result of multiplying (scaling) this quaternion by the specified scale factor. The definition of multiplying a quaternion by a scalar value is that it produces a new quaternion where each component of the original has been multiplied by the scalar value. Note that this method returns a new quaternion; it does not alter this quaternion. Note also that the returned quaternion is not necessarily a unit quaternion.
    
    Parameters:
    
    scaleFactor - The multiplier which is applied to this quaternion to produce the new (returned) quaternion.
    
    Returns:
    
    A new quaternion with is the result of multiplying each component of this quaternion by the specified scale factor.
  - conjugate
```
public Quaternion conjugate()
```
    Returns a new Quaternion which is the conjugate of this Quaternion. The conjugate q' of a quaternion q=(w, [x,y,z]) is defined as q' = (w, [-x,-y,-z]). This method does not affect the current quaternion.
  - rotate
```
public Vector3D rotate(Vector3D v)
```
    Returns a Vector3D which is the result of applying the rotation specified by this quaternion to the specified Vector3D. The resultant Vector3D is generated by multiplying this quaternion by the specified Vector3D and then multiplying the result by the conjugate of this quaternion. That is, the result is computed by applying the quaternion rotation formula
```
                newV = Q * V * Q' ,
 
```
    where Q is a quaternion, V is a vector, and Q' is the conjugate of Q.
  - getW
```
public double getW()
```
    Returns the scalar part of this quaternion. Note that the scalar part of a quaternion is related to, but is not precisely the same as, the angle of rotation represented by the quaternion; see the Quaternion class header comments for details on the relationship of the parts of a quaternion to the orientation represented by the quaternion.
    
    Returns:
    
    The scalar part of the quaternion.
  - setW
```
public void setW(double w)
```
    Specifies a new value for the scalar part of this quaternion. Note that the received value w is interpreted as the new scalar part of the quaternion, not as the angle of rotation represented by the quaternion. See the Quaternion class header comments for details on the relationship of the parts of a quaternion to the orientation represented by the quaternion.
    
    Parameters:
    
    w - The new value for the scalar part of the quaternion.
  - getV
```
public double[] getV()
```
    Returns the vector part of this quaternion. Note that the vector part of a quaternion is related to, but is not precisely the same as, the axis of rotation represented by the quaternion; see the Quaternion class header comments for details on the relationship of the parts of a quaternion to the orientation represented by the quaternion. To obtain the axis of rotation represented by this quaternion, use the axis portion of the values returned by getAngleAxis().
    
    Returns:
    
    An array of doubles containing the [x y z] vector part of this quaternion.
  - setV
```
public void setV(double[] v)
```
    Specifies a new vector part for this quaternion. Note that the received value v is interpreted as the new vector part of the quaternion, not as the axis of rotation represented by the quaternion. See the Quaternion class header comments for details on the relationship of the parts of a quaternion to the orientation represented by the quaternion.
    
    Parameters:
    
    v - An array of doubles representing the new vector part of the quaternion.
  - clone
```
public java.lang.Object clone()
```
    Returns a new Quaternion which is a deep clone of this Quaternion.
    
    Overrides:
    
    clone in class java.lang.Object
  - toString
```
public java.lang.String toString()
```
    Returns a String representation of this quaternion.
    
    Overrides:
    
    toString in class java.lang.Object
  - dot
```
public double dot(Quaternion other)
```
    Returns the dot-product of this quaternion with the specified quaternion. The dot-product of two quaternions is defined as the sum of the products of the corresponding components (w, x, y, and z) of each quaternion. This method alters neither this quaternion nor the specified other quaternion.
    
    Parameters:
    
    other - A quaternion whose components are multiplied with the corresponding components of this quaternion
    
    Returns:
    
    The sum of the products of the component-wise mulitplication of this quaternion with the specified other quaternion.
  - add
```
public Quaternion add(Quaternion other)
```
    Returns a new quaternion which is the result of adding this quaternion to the specified other quaternion. The definition of adding two quaternions is that it produces a quaternion whose components are each the sum of the corresponding components of the two operand quaternions. Note that this method returns a new quaternion; it alters neither this quaternion nor the specified other quaternion.
    
    Parameters:
    
    other - A quaternion to be added to this quaternion
    
    Returns:
    
    A new quaternion whose components are respectively the sum of the corresponding components in this quaternion and the specified other quaternion.
  - toMatrix3D
```
public Matrix3D toMatrix3D()
```
    Convert this Quaternion to a rotation matrix. Note that the Quaternion is not normalized herein, so it is the programmer's responsibility to ensure that this quaternion is normalized prior to utilizing this method.
  - slerp
```
public Quaternion slerp(Quaternion quat,
                        double amount)
```
    Spherical interpolation between this quaternion and quat.
    
    Parameters:
    
    quat - The quaternion with which this quaternion should be interpolated.
    
    amount - The amount to interpolate.
  - pivot
```
public Vector3D pivot(Vector3D vec,
                      Point3D about)
```
    Pivot a vector about a point using the rotation defined by this quaternion. Note that this quaternion is not normalized (for efficiency); the user of this method should ensure that this quaternion is normalized.
    
    Parameters:
    
    vec - The vector to pivot.
    
    about - The point to pivot about.
  - pivot
```
public Point3D pivot(Point3D point,
                     Point3D about)
```
    Overload of pivot(Vector3D, Point3D). Refer to that method for documentation. This effectively casts point to a Vector3D and calls pivot(Vector3D, Point3D).
    
    Parameters:
    
    point - The point to pivot.
    
    about - The point to pivot about.
  - mult
```
public Vector3D mult(Vector3D vec)
```
    Multiply this Quaternion by a vec, and return the new Vector3D. This effectively rotates vec by the rotation specified in this quaternion. Note that this quaternion is not normalized (for efficiency); the user of this method should ensure that this quaternion is normalized.
    
    Parameters:
    
    vec - The Vector3D which should be rotated using this Quaternion.
  - mult
```
public Point3D mult(Point3D point)
```
    Rotate the point about this quaternion. This effectively casts point as a Vector3D and calls mult(Vector3D). Refer to mult(Vector3D).
    
    Parameters:
    
    point - The point to rotate using this quaternion.

Class Quaternion

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Quaternion

Quaternion

Quaternion

Quaternion

Method Detail

getAngleAxis

magnitude

normalize

multiplyBy

multiplyBy

conjugate

rotate

getW

setW

getV

setV

clone

toString

dot

add

toMatrix3D

slerp

pivot

pivot

mult

mult