maspack.matrix
Class Quaternion

java.lang.Object
  maspack.matrix.VectorObject
      maspack.matrix.Quaternion

public class Quaternion

extends VectorObject

Implements a quaternion as a fixed-size 4 element vector. Element 0 is the scalar element, while elements 1-3 are the vector components.

Field Summary

double	s Scalar element
Vector3d	u Vector element

Constructor Summary

Quaternion()
Creates a Quaternion and initializes its elements to 0.

Quaternion(double s, double ux, double uy, double uz)
Creates a Quaternion with the supplied element values.

Quaternion(Quaternion q)
Creates a Quaternion by copying an existing one.

Method Summary

void	add(Quaternion q1) Adds this quaternion to q1 and places the result in this quaternion.
void	add(Quaternion q1, Quaternion q2) Adds q1 quaternion to q2 and places the result in this quaternion.
void	combine(double r1, Quaternion q1, double r2, Quaternion q2) Computes r1 q1 + r2 q2 and places the result in this quaternion.
void	conjugate() Conjugates this quaternion in place.
void	conjugate(Quaternion q1) Sets this quaternion to the conjugate of q1.
double	distance(Quaternion q) Returns the Euclidean distance between this quaternion and quaternion q.
double	distanceSquared(Quaternion q) Returns the squared of the Euclidean distance between this quaternion and quaternion q.
double	dot(Quaternion q1) Returns the dot product of this quaternion and q1.
boolean	epsilonEquals(Quaternion q1, double eps) Returns true if the elements of this quaternion equal those of quaternion q1within a prescribed tolerance epsilon.
boolean	equals(Quaternion q1) Returns true if the elements of this quaternion exactly equal those of quaternion q1.
void	get(double[] values) Copies the elements of this quaternion into an array of doubles.
double	get(int i) Gets a single element of this quaternion.
double	infinityNorm() Returns the infinity norm of this quaternion.
void	interpolate(double r, Quaternion q1) Computes the interpolation (1-r) this + r q1 and places the result in this quaternion.
void	interpolate(Quaternion q1, double r, Quaternion q2) Computes the interpolation (1-r) q1 + r q2 and places the result in this quaternion.
void	invert() Inverts this quaternion in place.
void	invert(Quaternion q1) Sets this quaternion to the inverse of q1.
double	length() Returns the 2 norm of this quaternion.
double	lengthSquared() Returns the square of the 2 norm of this quaternion.
void	mul(Quaternion q1) Multiplies this quaternion by quaternion q1 and places the result in this quaternion.
void	mul(Quaternion q1, Quaternion q2) Multiplies quaternion q1 by quaternion q2 and places the result in this quaternion.
void	mulInverse(Quaternion q1) Post-multiplies this quaternion by the inverse of quaternion q1 and places the result in this quaternion.
void	mulInverseBoth(Quaternion q1, Quaternion q2) Multiplies the inverse of quaternion q1 by the inverse of quaternion q2 and places the result in this quaternion.
void	mulInverseLeft(Quaternion q1, Quaternion q2) Multiplies the inverse of quaternion q1 by quaternion q2 and places the result in this quaternion.
void	mulInverseRight(Quaternion q1, Quaternion q2) Multiplies quaternion q1 by the inverse of quaternion q2 and places the result in this quaternion.
void	negate() Negates this quaternion in place.
void	negate(Quaternion q1) Sets this quaternion to the negative of q1.
void	normalize() Normalizes this quaternion in place.
void	normalize(Quaternion q1) Computes a unit quaternion in the direction of q1 and places the result in this quaternion.
void	normalizedInterpolate(double r, Quaternion q1) Computes a normalized rotational interpolation between this quaternion and q1 and places the result in this quaternion.
void	normalizedInterpolate(Quaternion q1, double r, Quaternion q2) Computes a normalized rotational interpolation between quaternions q1 and q2 and places the result in this quaternion.
double	oneNorm() Returns the 1 norm of this quaternion.
double	rotationAngle(Quaternion q1) Returns the angular distance between the rotations represented by this quaternion and q1.
void	scale(double r) Scales the elements of this quaternion by r.
void	scale(double r, Quaternion q1) Scales the elements of quaternion q1 by r and places the results in this quaternion.
void	scaleAdd(double r, Quaternion q1) Computes r this + q1 and places the result in this quaternion.
void	scaleAdd(double r, Quaternion q1, Quaternion q2) Computes r q1 + q2 and places the result in this quaternion.
void	set(AxisAngle axisAng) Sets this quaternion to a unit quaternion corresponding to a specified rotation.
void	set(double[] values) Sets the elements of this quaternion from an array of doubles.
void	set(double s, double ux, double uy, double uz) Sets the elements of this quaternion to the prescribed values.
void	set(int i, double value) Sets a single element of this quaternion.
void	set(Quaternion q1) Sets the values of this quaternion to those of q1.
void	set(RotationMatrix3d R) Sets this quaternion to a unit quaternion corresponding to a specified rotation.
void	setRandom() Sets the elements of this quaternion to uniformly distributed random values in the range -0.5 (inclusive) to 0.5 (exclusive).
void	setRandom(double lower, double upper) Sets the elements of this quaternion to uniformly distributed random values in a specified range.
void	setRandom(double lower, double upper, java.util.Random generator) Sets the elements of this quaternion to uniformly distributed random values in a specified range, using a supplied random number generator.
void	setRandomUnit() Sets this quaternion to a random unit value.
void	setRandomUnit(java.util.Random generator) Sets this quaternion to a random unit value, using a supplied random number generator.
void	setZero() Sets the elements of this quaternion to zero.
int	size() Returns the size of this quaternion (which is always 4)
void	sphericalInterpolate(double r, Quaternion q1) Computes a spherical (great circle) interpolation between this quaternion and q1 and places the result in this quaternion.
void	sphericalInterpolate(Quaternion q1, double r, Quaternion q2) Computes a spherical (great circle) interpolation between quaternions q1 and q2 and places the result in this quaternion.
void	sub(Quaternion q1) Subtracts q1 from this quaternion and places the result in this quaternion.
void	sub(Quaternion q1, Quaternion q2) Subtracts quaternion q1 from q2 and places the result in this quaternion.

Methods inherited from class maspack.matrix.VectorObject

dot, epsilonEquals, equals, equals, get, isFixedSize, maxElement, minElement, norm, normSquared, scan, set, setSize, toString, toString, toString

Methods inherited from class java.lang.Object

getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

s

public double s

Scalar element

u

public Vector3d u

Vector element

Constructor Detail

Quaternion

public Quaternion()

Creates a Quaternion and initializes its elements to 0.

Quaternion

public Quaternion(Quaternion q)

Creates a Quaternion by copying an existing one.

Parameters:

q - quaternion to be copied

Quaternion

public Quaternion(double s,
                  double ux,
                  double uy,
                  double uz)

Creates a Quaternion with the supplied element values.

Parameters:

s - scalar element

ux - first vector element

uy - second vector element

uz - third vector element

Method Detail

size

public int size()

Returns the size of this quaternion (which is always 4)

Specified by:

size in class VectorObject

Returns:

4

get

public double get(int i)

Gets a single element of this quaternion. Elements 0, 1, 2, and 3 correspond to s, u.x, u.y, and u.z.

Specified by:

get in class VectorObject

Parameters:

i - element index

Returns:

element value throws ArrayIndexOutOfBoundsException if i is not in the range 0 to 3.

get

public void get(double[] values)

Copies the elements of this quaternion into an array of doubles.

Overrides:

get in class VectorObject

Parameters:

values - array into which values are copied

set

public void set(int i,
                double value)

Sets a single element of this quaternion. Elements 0, 1, 2, and 3 correspond to s, u.x, u.y, and u.z.

Specified by:

set in class VectorObject

Parameters:

i - element index

value - element value

Returns:

element value throws ArrayIndexOutOfBoundsException if i is not in the range 0 to 3.

set

public void set(double[] values)

Sets the elements of this quaternion from an array of doubles.

Overrides:

set in class VectorObject

Parameters:

values - array from which values are copied

set

public void set(Quaternion q1)

Sets the values of this quaternion to those of q1.

Parameters:

q1 - quaternion whose values are copied

add

public void add(Quaternion q1,
                Quaternion q2)

Adds q1 quaternion to q2 and places the result in this quaternion.

Parameters:

q1 - left-hand quaternion

q2 - right-hand quaternion

add

public void add(Quaternion q1)

Adds this quaternion to q1 and places the result in this quaternion.

Parameters:

q1 - right-hand quaternion

sub

public void sub(Quaternion q1,
                Quaternion q2)

Subtracts quaternion q1 from q2 and places the result in this quaternion.

Parameters:

q1 - left-hand quaternion

q2 - right-hand quaternion

sub

public void sub(Quaternion q1)

Subtracts q1 from this quaternion and places the result in this quaternion.

Parameters:

q1 - right-hand quaternion

negate

public void negate(Quaternion q1)

Sets this quaternion to the negative of q1.

Parameters:

q1 - quaternion to negate

negate

public void negate()

Negates this quaternion in place.

scale

public void scale(double r)

Scales the elements of this quaternion by r.

Parameters:

r - scaling factor

scale

public void scale(double r,
                  Quaternion q1)

Scales the elements of quaternion q1 by r and places the results in this quaternion.

Parameters:

r - scaling factor

q1 - quaternion to be scaled

interpolate

public void interpolate(Quaternion q1,
                        double r,
                        Quaternion q2)

Computes the interpolation (1-r) q1 + r q2 and places the result in this quaternion.

Parameters:

q1 - left-hand quaternion

r - interpolation factor

q2 - right-hand quaternion

interpolate

public void interpolate(double r,
                        Quaternion q1)

Computes the interpolation (1-r) this + r q1 and places the result in this quaternion.

Parameters:

r - interpolation factor

q1 - right-hand quaternion

sphericalInterpolate

public void sphericalInterpolate(Quaternion q1,
                                 double r,
                                 Quaternion q2)

Computes a spherical (great circle) interpolation between quaternions q1 and q2 and places the result in this quaternion. The result is a unit quaternion. Non-unit quaternions can be used for input, but this will result in slightly slower computation.

In the literature, this operation is sometimes known as "Slerp", a name that was coined by Ken Showmake when he described the process in SIGGRAPH 1985.

Parameters:

q1 - left-hand quaternion

r - interpolation factor

q2 - right-hand quaternion

normalizedInterpolate

public void normalizedInterpolate(Quaternion q1,
                                  double r,
                                  Quaternion q2)

Computes a normalized rotational interpolation between quaternions q1 and q2 and places the result in this quaternion. The result is a unit quaternion.

This operation is sometimes known as "Nlerp", and is faster than spherical interpolation. Essentially, it involves doing a linear interpolation between q1 qnd q2 and then normalizing the result. q1 and q2 are assumed to be unit quaternions. If they are not, unit versions of them are created internally although this will slow the routine down. Also, if -q1 is closer to q2 than q1, then the interpolation is done between -q1 and q2; this ensures that the shortest rotationa; path is used.

Parameters:

q1 - left-hand quaternion

r - interpolation factor

q2 - right-hand quaternion

sphericalInterpolate

public void sphericalInterpolate(double r,
                                 Quaternion q1)

Computes a spherical (great circle) interpolation between this quaternion and q1 and places the result in this quaternion. It is assumed that both are unit quaternions; otherwise, the results are undefined.

Parameters:

r - interpolation factor

q1 - right-hand quaternion

normalizedInterpolate

public void normalizedInterpolate(double r,
                                  Quaternion q1)

Computes a normalized rotational interpolation between this quaternion and q1 and places the result in this quaternion. The result is a unit quaternion.

Parameters:

r - interpolation factor

q1 - right-hand quaternion

See Also:

normalizedInterpolate(Quaternion,double,Quaternion)

scaleAdd

public void scaleAdd(double r,
                     Quaternion q1)

Computes r this + q1 and places the result in this quaternion.

Parameters:

r - scaling factor

q1 - quaternion to be added

scaleAdd

public void scaleAdd(double r,
                     Quaternion q1,
                     Quaternion q2)

Computes r q1 + q2 and places the result in this quaternion.

Parameters:

r - scaling factor

q1 - quaternion to be scaled

q2 - quaternion to be added

combine

public void combine(double r1,
                    Quaternion q1,
                    double r2,
                    Quaternion q2)

Computes r1 q1 + r2 q2 and places the result in this quaternion.

Parameters:

r1 - left-hand scaling factor

q1 - left-hand quaternion

r2 - right-hand scaling factor

q2 - right-hand quaternion

length

public double length()

Returns the 2 norm of this quaternion. This is the square root of the sum of the squares of the elements.

Returns:

quaternion 2 norm

lengthSquared

public double lengthSquared()

Returns the square of the 2 norm of this quaternion. This is the sum of the squares of the elements.

Returns:

square of the 2 norm

conjugate

public void conjugate(Quaternion q1)

Sets this quaternion to the conjugate of q1. Conjugation entails negating the values of u.

Parameters:

q1 - quaternion to conjugate

conjugate

public void conjugate()

Conjugates this quaternion in place. Conjugation entails negating the values of u.

invert

public void invert(Quaternion q1)

Sets this quaternion to the inverse of q1.

Parameters:

q1 - quaternion to invert

invert

public void invert()

Inverts this quaternion in place.

mul

public void mul(Quaternion q1)

Multiplies this quaternion by quaternion q1 and places the result in this quaternion.

Parameters:

q1 - right-hand quaternion

mul

public void mul(Quaternion q1,
                Quaternion q2)

Multiplies quaternion q1 by quaternion q2 and places the result in this quaternion.

Parameters:

q1 - left-hand quaternion

q2 - right-hand quaternion

mulInverse

public void mulInverse(Quaternion q1)

Post-multiplies this quaternion by the inverse of quaternion q1 and places the result in this quaternion.

Parameters:

q1 - right-hand quaternion

mulInverseRight

public void mulInverseRight(Quaternion q1,
                            Quaternion q2)

Multiplies quaternion q1 by the inverse of quaternion q2 and places the result in this quaternion.

Parameters:

q1 - left-hand quaternion

q2 - right-hand quaternion

mulInverseLeft

public void mulInverseLeft(Quaternion q1,
                           Quaternion q2)

Multiplies the inverse of quaternion q1 by quaternion q2 and places the result in this quaternion.

Parameters:

q1 - left-hand quaternion

q2 - right-hand quaternion

mulInverseBoth

public void mulInverseBoth(Quaternion q1,
                           Quaternion q2)

Multiplies the inverse of quaternion q1 by the inverse of quaternion q2 and places the result in this quaternion.

Parameters:

q1 - left-hand quaternion

q2 - right-hand quaternion

distance

public double distance(Quaternion q)

Returns the Euclidean distance between this quaternion and quaternion q.

Returns:

distance between this quaternion and q

distanceSquared

public double distanceSquared(Quaternion q)

Returns the squared of the Euclidean distance between this quaternion and quaternion q.

Returns:

squared distance between this quaternion and q

infinityNorm

public double infinityNorm()

Returns the infinity norm of this quaternion. This is the maximum absolute value over all elements, treating it as a 4-vector.

Overrides:

infinityNorm in class VectorObject

Returns:

quaternion infinity norm

oneNorm

public double oneNorm()

Returns the 1 norm of this quaternion. This is the sum of the absolute values of the elements, treating it as a 4-vector.

Overrides:

oneNorm in class VectorObject

Returns:

quaternion 1 norm

dot

public double dot(Quaternion q1)

Returns the dot product of this quaternion and q1.

Parameters:

q1 - right-hand quaternion

Returns:

dot product

rotationAngle

public double rotationAngle(Quaternion q1)

Returns the angular distance between the rotations represented by this quaternion and q1. The returned value is in the range 0 to Math.PI.

Parameters:

q1 - right-hand quaternion

Returns:

angular rotational distance, in radians

normalize

public void normalize()

Normalizes this quaternion in place.

normalize

public void normalize(Quaternion q1)

Computes a unit quaternion in the direction of q1 and places the result in this quaternion.

Parameters:

q1 - quaternion to normalize

epsilonEquals

public boolean epsilonEquals(Quaternion q1,
                             double eps)

Returns true if the elements of this quaternion equal those of quaternion q1within a prescribed tolerance epsilon.

Parameters:

q1 - quaternion to compare with

eps - comparison tolerance

Returns:

false if the vectors are not equal within the specified tolerance

equals

public boolean equals(Quaternion q1)

Returns true if the elements of this quaternion exactly equal those of quaternion q1.

Parameters:

q1 - quaternion to compare with

Returns:

false if the vectors are not equal

set

public void set(AxisAngle axisAng)

Sets this quaternion to a unit quaternion corresponding to a specified rotation.

Parameters:

axisAng - gives the rotation axis and corresponding angle

set

public void set(RotationMatrix3d R)

Sets this quaternion to a unit quaternion corresponding to a specified rotation.

Parameters:

R - rotation specified as a matrix

setZero

public void setZero()

Sets the elements of this quaternion to zero.

set

public void set(double s,
                double ux,
                double uy,
                double uz)

Sets the elements of this quaternion to the prescribed values.

Parameters:

s - scalar value

ux - first vector value

uy - second vector value

uz - thirs vector value

setRandomUnit

public void setRandomUnit()

Sets this quaternion to a random unit value.

setRandomUnit

public void setRandomUnit(java.util.Random generator)

Sets this quaternion to a random unit value, using a supplied random number generator.

Parameters:

generator - random number generator

setRandom

public void setRandom()

Sets the elements of this quaternion to uniformly distributed random values in the range -0.5 (inclusive) to 0.5 (exclusive).

setRandom

public void setRandom(double lower,
                      double upper)

Sets the elements of this quaternion to uniformly distributed random values in a specified range.

Parameters:

lower - lower random value (inclusive)

upper - upper random value (exclusive)

setRandom

public void setRandom(double lower,
                      double upper,
                      java.util.Random generator)

Sets the elements of this quaternion to uniformly distributed random values in a specified range, using a supplied random number generator.

Parameters:

lower - lower random value (inclusive)

upper - upper random value (exclusive)

generator - random number generator