ON_Quaternion Class Reference

#include <opennurbs_quaternion.h>

Public Member Functions
	ON_Quaternion ()
	ON_Quaternion (const ON_3dVector &v)
	(a,b,c,d) = (0,v.x,v.y,v.z) More...
	ON_Quaternion (double qa, double qb, double qc, double qd)
ON_Quaternion	Conjugate () const
double	DistanceTo (const ON_Quaternion &q) const
bool	GetEulerZYZ (double &alpha, double &beta, double &gamma) const
bool	GetRotation (double &angle, ON_3dVector &axis) const
bool	GetRotation (ON_Plane &plane) const
bool	GetRotation (ON_Xform &xform) const
bool	GetYawPitchRoll (double &yaw, double &pitch, double &roll) const
ON_Quaternion	Inverse () const
bool	Invert ()
bool	IsNotZero () const
bool	IsScalar () const
bool	IsValid () const
bool	IsVector () const
bool	IsZero () const
double	Length () const
double	LengthSquared () const
ON_Xform	MatrixForm () const
ON_Quaternion	operator* (const ON_Quaternion &) const
	quaternion multiplication is not commutative More...
ON_Quaternion	operator* (double) const
ON_Quaternion	operator* (float) const
ON_Quaternion	operator* (int) const
	arithmetic operators More...
ON_Quaternion	operator+ (const ON_Quaternion &) const
ON_Quaternion	operator- (const ON_Quaternion &) const
ON_Quaternion	operator/ (double) const
ON_Quaternion	operator/ (float) const
ON_Quaternion	operator/ (int) const
ON_Quaternion &	operator= (const ON_3dVector &v)
	(a,b,c,d) = (0,v.x,v.y,v.z) More...
ON_3dVector	Rotate (ON_3dVector v) const
double	Scalar () const
void	Set (double qa, double qb, double qc, double qd)
void	SetRotation (const ON_Plane &plane0, const ON_Plane &plane1)
void	SetRotation (double angle, const ON_3dVector &axis)
bool	Unitize ()
ON_3dVector	Vector () const

Static Public Member Functions
static double	Distance (const ON_Quaternion &p, const ON_Quaternion &q)
static ON_Quaternion	Exp (ON_Quaternion q)
static ON_Quaternion	Log (ON_Quaternion q)
static ON_Quaternion	Pow (ON_Quaternion q, double t)
static ON_Quaternion	RotateTowards (ON_Quaternion q0, ON_Quaternion q1, double MaxRadians)
static ON_Quaternion	Rotation (const ON_Plane &plane0, const ON_Plane &plane1)
static ON_Quaternion	Rotation (double angle, const ON_3dVector &axis)
static ON_Quaternion	RotationZYX (double yaw, double pitch, double roll)
static ON_Quaternion	RotationZYZ (double alpha, double beta, double gamma)
static ON_Quaternion	Slerp (ON_Quaternion q0, ON_Quaternion q1, double t)

Public Attributes
double	a
	quaternion = a + bi + cj + dk More...
double	b
double	c
double	d

Static Public Attributes
static const ON_Quaternion	I
	"i" = (0,1,0,0) More...
static const ON_Quaternion	Identity
	1 = (1,0,0,0) More...
static const ON_Quaternion	J
	"j" = (0,0,1,0) More...
static const ON_Quaternion	K
	"k" = (0,0,0,1) More...
static const ON_Quaternion	Zero
	0 = (0,0,0,0 More...

Detailed Description

Copyright (c) 1993-2022 Robert McNeel & Associates. All rights reserved. OpenNURBS, Rhinoceros, and Rhino3D are registered trademarks of Robert McNeel & Associates.

THIS SOFTWARE IS PROVIDED "AS IS" WITHOUT EXPRESS OR IMPLIED WARRANTY. ALL IMPLIED WARRANTIES OF FITNESS FOR ANY PARTICULAR PURPOSE AND OF MERCHANTABILITY ARE HEREBY DISCLAIMED.

For complete openNURBS copyright information see http://www.opennurbs.org.

Constructor & Destructor Documentation

ON_Quaternion() [1/3]

ON_Quaternion::ON_Quaternion ( )

inline

ON_Quaternion() [2/3]

ON_Quaternion::ON_Quaternion	(	double	qa,
		double	qb,
		double	qc,
		double	qd
	)

ON_Quaternion() [3/3]

ON_Quaternion::ON_Quaternion

(

const ON_3dVector &

v

)

(a,b,c,d) = (0,v.x,v.y,v.z)

Member Function Documentation

Conjugate()

ON_Quaternion ON_Quaternion::Conjugate

(

)

const

Description: Returns the conjugate of the quaternion = (a,-b,-c,-d).

Distance()

static double ON_Quaternion::Distance ( const ON_Quaternion &  p, const ON_Quaternion &  q  )

static

Returns: The distance or norm of the difference between the two quaternions. = (p - q).Length().

DistanceTo()

double ON_Quaternion::DistanceTo

(

const ON_Quaternion &

q

)

const

Returns: The distance or norm of the difference between the two quaternions. = ("this" - q).Length().

Exp()

static ON_Quaternion ON_Quaternion::Exp ( ON_Quaternion  q )

static

Returns: exp(q) = e^a*( cos(|V|) + V/|V|*sin(|V|) ), where V = b*i + c*j + d*k.

GetEulerZYZ()

bool ON_Quaternion::GetEulerZYZ	(	double &	alpha,
		double &	beta,
		double &	gamma
	)		const

Description: Find the Euler angles for a rotation transformation. Parameters: alpha - angle (in radians) to rotate about the Z axis beta - angle (in radians) to rotate about the Y axis gamma - angle (in radians) to rotate about the Z axis Details: When true is returned. this = RotationZYZ(alpha, beta, gamma) = R_z( alpha) * R_y(beta) * R_z(gamma) where R_*(angle) is rotation of angle radians about the corresponding *-world coordinate axis. Returns false if this is not a rotation. Notes: alpha and gamma are in the range (-pi, pi] while beta in in the range [0, pi]

GetRotation() [1/3]

bool ON_Quaternion::GetRotation	(	double &	angle,
		ON_3dVector &	axis
	)		const

Parameters: angle - [out] in radians axis - [out] unit axis of rotation of 0 if (b,c,d) is the zero vector. Returns: The rotation defined by the quaternion. Remarks: If the quaternion is not unitized, the rotation of its unitized form is returned.

GetRotation() [2/3]

bool ON_Quaternion::GetRotation

(

ON_Plane &

plane

)

const

Parameters: plane - [out] Returns: The frame created by applying the quaternion's rotation to the canonical world frame (1,0,0),(0,1,0),(0,0,1).

GetRotation() [3/3]

bool ON_Quaternion::GetRotation

(

ON_Xform &

xform

)

const

Description: The transformation returned by this function has the property that xform*V = q.Rotate(V). Parameters: xform - [out] Returns: A transformation matrix that performs the rotation defined by the quaternion. Remarks: If the quaternion is not unitized, the rotation of its unitized form is returned. Do not confuse the result of this function the matrix returned by ON_Quaternion::MatrixForm(). The transformation returned by this function has the property that xform*V = q.Rotate(V).

GetYawPitchRoll()

bool ON_Quaternion::GetYawPitchRoll	(	double &	yaw,
		double &	pitch,
		double &	roll
	)		const

Description: Find the Tait-Byran angles (also loosely called Euler angles) for this quaternion. Parameters: yaw - angle (in radians) to rotate about the Z axis pitch - angle (in radians) to rotate about the Y axis roll - angle (in radians) to rotate about the X axis Details: When true is returned. this = RotationZYX(yaw, pitch, roll) = R_z( yaw) * R_y(pitch) * R_x(roll) where R_*(angle) is rotation of angle radians about the corresponding world coordinate axis. Returns false if this is not a rotation. Notes: roll and yaw are in the range (-pi, pi] and pitch is in [-pi/2, pi/2]

Inverse()

ON_Quaternion ON_Quaternion::Inverse

(

)

const

Returns: Sets the quaternion to a/L2, -b/L2, -c/L2, -d/L2, where L2 = length squared = (a*a + b*b + c*c + d*d). This is the multiplicative inverse, i.e., (a,b,c,d)*(a/L2, -b/L2, -c/L2, -d/L2) = (1,0,0,0). If "this" is the zero quaternion, then the zero quaternion is returned.

Invert()

bool ON_Quaternion::Invert

(

)

Description: Sets the quaternion to a/L2, -b/L2, -c/L2, -d/L2, where L2 = length squared = (a*a + b*b + c*c + d*d). This is the multiplicative inverse, i.e., (a,b,c,d)*(a/L2, -b/L2, -c/L2, -d/L2) = (1,0,0,0). Returns: True if successful. False if the quaternion is zero and cannot be inverted.

IsNotZero()

bool ON_Quaternion::IsNotZero

(

)

const

Returns: True if a, b, c, and d are all valid, finite and at least one is non-zero.

IsScalar()

bool ON_Quaternion::IsScalar

(

)

const

Returns: True if b, c, and d are all zero.

IsValid()

bool ON_Quaternion::IsValid

(

)

const

Returns: True if a, b, c, and d are valid finite IEEE doubles.

IsVector()

bool ON_Quaternion::IsVector

(

)

const

Returns: True if a = 0 and at least one of b, c, or d is not zero.

IsZero()

bool ON_Quaternion::IsZero

(

)

const

Returns: True if a, b, c, and d are all zero.

Length()

double ON_Quaternion::Length

(

)

const

Returns: Returns the length or norm of the quaternion sqrt(a*a + b*b + c*c + d*d).

LengthSquared()

double ON_Quaternion::LengthSquared

(

)

const

Returns: Returns a*a + b*b + c*c + d*d.

Log()

static ON_Quaternion ON_Quaternion::Log ( ON_Quaternion  q )

static

Returns: log(q) = log(|q|) + V/|V|*acos(a/|q|), where V = b*i + c*j + d*k.

MatrixForm()

ON_Xform ON_Quaternion::MatrixForm

(

)

const

Returns: 4x4 real valued matrix form of the quaternion

    a  b  c  d
   -b  a -d  c
   -c  d  a -b
   -d -c  b  a

which has the same arithmetic properties in as the quaternion. Remarks: Do not confuse this with the rotation defined by the quaternion. This function will only be interesting to math nerds and is not useful in rendering or animation applications.

operator*() [1/4]

ON_Quaternion ON_Quaternion::operator*

(

const ON_Quaternion &

)

const

quaternion multiplication is not commutative

operator*() [2/4]

ON_Quaternion ON_Quaternion::operator*

(

double

)

const

operator*() [3/4]

ON_Quaternion ON_Quaternion::operator*

(

float

)

const

operator*() [4/4]

ON_Quaternion ON_Quaternion::operator*

(

int

)

const

arithmetic operators

operator+()

ON_Quaternion ON_Quaternion::operator+

(

const ON_Quaternion &

)

const

operator-()

ON_Quaternion ON_Quaternion::operator-

(

const ON_Quaternion &

)

const

operator/() [1/3]

ON_Quaternion ON_Quaternion::operator/

(

double

)

const

operator/() [2/3]

ON_Quaternion ON_Quaternion::operator/

(

float

)

const

operator/() [3/3]

ON_Quaternion ON_Quaternion::operator/

(

int

)

const

operator=()

ON_Quaternion& ON_Quaternion::operator=

(

const ON_3dVector &

v

)

(a,b,c,d) = (0,v.x,v.y,v.z)

Pow()

static ON_Quaternion ON_Quaternion::Pow ( ON_Quaternion  q, double  t  )

static

Returns: q^t = Exp(t*Log(q))

Rotate()

ON_3dVector ON_Quaternion::Rotate

(

ON_3dVector

v

)

const

Description Rotate a 3d vector. This operation is also called conjugation, because the result is the same as

(q.Conjugate()*(0,x,y,x)*q/q.LengthSquared()).Vector()

Parameters: v - [in] Returns: R*v, where R is the rotation defined by the unit quaternion. This is mathematically the same as the values (Inverse(q)*(0,x,y,z)*q).Vector() and (q.Conjugate()*(0,x,y,x)*q/q.LengthSquared()).Vector() Remarks: If you need to rotate more than a dozen or so vectors, it will be more efficient to call GetRotation(ON_Xform& xform) and multiply the vectors by xform.

RotateTowards()

static ON_Quaternion ON_Quaternion::RotateTowards ( ON_Quaternion  q0, ON_Quaternion  q1, double  MaxRadians  )

static

Returns the quaternion obtained by rotating q0 towards q1 limiting the rotation by MaxRadians.

Rotation() [1/2]

static ON_Quaternion ON_Quaternion::Rotation ( const ON_Plane &  plane0, const ON_Plane &  plane1  )

static

Parameters: plane0 - [in] plane1 - [in] Returns: The unit quaternion that represents the the rotation that maps plane0.xaxis to plane1.xaxis, plane0.yaxis to plane1.yaxis, and plane0.zaxis to plane1.zaxis. Remarks: The plane origins are ignored.

Rotation() [2/2]

static ON_Quaternion ON_Quaternion::Rotation ( double  angle, const ON_3dVector &  axis  )

static

Parameters: angle - [in] in radians axis - [in] axis of rotation Returns: The unit quaternion

cos(angle/2), sin(angle/2)*x, sin(angle/2)*y, sin(angle/2)*z

where (x,y,z) is the unit vector parallel to axis. This is the unit quaternion that represents the rotation of angle about axis.

RotationZYX()

static ON_Quaternion ON_Quaternion::RotationZYX ( double  yaw, double  pitch, double  roll  )

static

Description: Returns a Quaternion defined by Tait-Byran angles (also loosely known as Euler angles). Parameters: yaw - angle (in radians) to rotate about the Z axis pitch - angle (in radians) to rotate about the Y axis roll - angle (in radians) to rotate about the X axis Details: RotationZYX(yaw, pitch, roll) = R_z( yaw) * R_y(pitch) * R_x(roll) where R_*(angle) is rotation of angle radians about the corresponding world coordinate axis. See Also: GetYawPitchRoll, RotationZYZ

RotationZYZ()

static ON_Quaternion ON_Quaternion::RotationZYZ ( double  alpha, double  beta, double  gamma  )

static

Description: Returns a Quaternion defined by Euler angles. Parameters: alpha - angle (in radians) to rotate about the Z axis beta - angle (in radians) to rotate about the Y axis gamma - angle (in radians) to rotate about the Z axis Details: RotationZYZ(alpha, beta, gamma) = R_z( alpha) * R_y(beta) * R_z(gamma) where R_*(angle) is rotation of angle radians about the corresponding *-world coordinate axis. See Also: GetEulerZYZ, RotationZYX

Scalar()

double ON_Quaternion::Scalar

(

)

const

Returns: The "real" or "scalar" part of the quaternion = a.

Set()

void ON_Quaternion::Set	(	double	qa,
		double	qb,
		double	qc,
		double	qd
	)

SetRotation() [1/2]

void ON_Quaternion::SetRotation	(	const ON_Plane &	plane0,
		const ON_Plane &	plane1
	)

Descriptin: Sets the quaternion to the unit quaternion which rotates plane0.xaxis to plane1.xaxis, plane0.yaxis to plane1.yaxis, and plane0.zaxis to plane1.zaxis. Parameters: plane0 - [in] plane1 - [in] Remarks: The plane origins are ignored.

SetRotation() [2/2]

void ON_Quaternion::SetRotation	(	double	angle,
		const ON_3dVector &	axis
	)

Description: Sets the quaternion to

cos(angle/2), sin(angle/2)*x, sin(angle/2)*y, sin(angle/2)*z

where (x,y,z) is the unit vector parallel to axis. This is the unit quaternion that represents the rotation of angle about axis. Parameters: angle - [in] in radians axis - [in] axis of rotation Returns:

Slerp()

static ON_Quaternion ON_Quaternion::Slerp ( ON_Quaternion  q0, ON_Quaternion  q1, double  t  )

static

Unitize()

bool ON_Quaternion::Unitize

(

)

Description: Scales the quaternion's coordinates so that a*a + b*b + c*c + d*d = 1. Returns: True if successful. False if the quaternion is zero and cannot be unitized.

Vector()

ON_3dVector ON_Quaternion::Vector

(

)

const

Returns: The "vector" or "imaginary" part of the quaternion = (b,c,d)

Member Data Documentation

a

double ON_Quaternion::a

quaternion = a + bi + cj + dk

b

double ON_Quaternion::b

c

double ON_Quaternion::c

d

double ON_Quaternion::d

I

const ON_Quaternion ON_Quaternion::I

static

"i" = (0,1,0,0)

Identity

const ON_Quaternion ON_Quaternion::Identity

static

1 = (1,0,0,0)

J

const ON_Quaternion ON_Quaternion::J

static

"j" = (0,0,1,0)

K

const ON_Quaternion ON_Quaternion::K

static

"k" = (0,0,0,1)

Zero

const ON_Quaternion ON_Quaternion::Zero

static

0 = (0,0,0,0