Description

Functions for quaternion manipulation.

All functions have two versions, one that acts on an rc_vector_t of length 4 and another that acts on normal C arrays, also of length 4. They are functionally identical and just give the user options depending on how they represent quaternions in their code.

Author: James Strawson

Date: 2016

Functions
double	rc_quaternion_norm (rc_vector_t q)
	Returns the length of a quaternion vector by finding its 2-norm. More...

double	rc_quaternion_norm_array (double q[4])
	Returns the length of a quaternion vector by finding its 2-norm. More...

int	rc_normalize_quaternion (rc_vector_t *q)
	Normalizes a quaternion in-place to have length 1.0. More...

int	rc_normalize_quaternion_array (double q[4])
	Normalizes a quaternion in-place to have length 1.0. More...

int	rc_quaternion_to_tb (rc_vector_t q, rc_vector_t *tb)
	Calculates 321 Tait Bryan angles in array order XYZ with operation order 321(yaw-Z, pitch-Y, roll-x). More...

int	rc_quaternion_to_tb_array (double q[4], double tb[3])
	Calculates 321 Tait Bryan angles in array order XYZ with operation order 321(yaw-Z, pitch-Y, roll-x). More...

int	rc_quaternion_from_tb (rc_vector_t tb, rc_vector_t *q)
	Calculates quaternion vector q from tait-bryan angles tb. More...

int	rc_quaternion_from_tb_array (double tb[3], double q[4])
	Calculates quaternion vector q from tait-bryan angles tb. More...

int	rc_quaternion_conjugate (rc_vector_t q, rc_vector_t *c)
	Calculates conjugate of quaternion q. More...

int	rc_quaternion_conjugate_inplace (rc_vector_t *q)
	Calculates conjugate of quaternion q and overwrites the old q. More...

int	rc_quaternion_conjugate_array (double q[4], double c[4])
	Calculates conjugate of quaternion q. More...

int	rc_quaternion_conjugate_array_inplace (double q[4])
	Calculates conjugate of quaternion q and overwrites the old q. More...

int	rc_quaternion_imaginary_part (rc_vector_t q, rc_vector_t *img)
	Populates vector i with the imaginary components ijk of of quaternion vector q. More...

int	rc_quaternion_multiply (rc_vector_t a, rc_vector_t b, rc_vector_t *c)
	Calculates the quaternion Hamilton product ab=c. More...

int	rc_quaternion_multiply_array (double a[4], double b[4], double c[4])
	Calculates the quaternion Hamilton product ab=c. More...

int	rc_quaternion_rotate (rc_vector_t *p, rc_vector_t q)
	Rotates the quaternion p by quaternion q with the operation p'=qpq*. More...

int	rc_quaternion_rotate_array (double p[4], double q[4])
	Rotates the quaternion p by quaternion q with the operation p'=qpq*. More...

int	rc_quaternion_rotate_vector (rc_vector_t *v, rc_vector_t q)
	Rotate a 3D vector v in-place about the origin by quaternion q by converting v to a quaternion and performing the operation p'=qpq*. More...

int	rc_quaternion_rotate_vector_array (double v[3], double q[4])
	Rotate a 3D vector v in-place about the origin by quaternion q by converting v to a quaternion and performing the operation p'=qpq*. More...

int	rc_quaternion_to_rotation_matrix (rc_vector_t q, rc_matrix_t *m)
	Converts a normalized quaternion to a 3x3 orthogonal rotation matrix. More...

Function Documentation

◆ rc_quaternion_norm()

double rc_quaternion_norm ( rc_vector_t q )

Returns the length of a quaternion vector by finding its 2-norm.

Parameters

[in] q The quarternion in form of a vector of length 4

Returns: Returns the norm, or prints an error message and returns -1.0f on error.

◆ rc_quaternion_norm_array()

double rc_quaternion_norm_array ( double q[4] )

Returns the length of a quaternion vector by finding its 2-norm.

Parameters

[in] q The quarternion in form of an array of length 4

Returns: Returns the norm, or prints an error message and returns -1.0f on error.

◆ rc_normalize_quaternion()

int rc_normalize_quaternion ( rc_vector_t * q )

Normalizes a quaternion in-place to have length 1.0.

Parameters

q	The quarternion in form of a vector of lenth 4

Returns: Returns 0 on success or -1 on failure

◆ rc_normalize_quaternion_array()

int rc_normalize_quaternion_array ( double q[4] )

Normalizes a quaternion in-place to have length 1.0.

Parameters

q	The quarternion in form of an array of length 4

Returns: Returns 0 on success or -1 on failure

◆ rc_quaternion_to_tb()

int rc_quaternion_to_tb	(	rc_vector_t	q,
		rc_vector_t *	tb
	)

Calculates 321 Tait Bryan angles in array order XYZ with operation order 321(yaw-Z, pitch-Y, roll-x).

If tb is already allocated and of length 3 then the new values are written in place, otherwise any existing memory is freed and a new vector of length 3 is allocated for tb.

Parameters

[in]	q	The quarternion in form of a vector of lenth 4
	tb	Output tait-bryan angles

Returns: Returns 0 on success or -1 on failure

◆ rc_quaternion_to_tb_array()

int rc_quaternion_to_tb_array	(	double	q[4],
		double	tb[3]
	)

Calculates 321 Tait Bryan angles in array order XYZ with operation order 321(yaw-Z, pitch-Y, roll-x).

Parameters

[in]	q	The quarternion in form of an array of lenth 4
[out]	tb	Output tait-bryan angles

Returns: Returns 0 on success or -1 on failure

◆ rc_quaternion_from_tb()

int rc_quaternion_from_tb	(	rc_vector_t	tb,
		rc_vector_t *	q
	)

Calculates quaternion vector q from tait-bryan angles tb.

If q is already of length 4 then old contents are simply overwritten. Otherwise q'd existing memory is freed and new memory is allocated to aint memory leaks. tb angles are 321 Tait Bryan angles in array order XYZ with operation order 321(yaw-Z, pitch-Y, roll-x).

Parameters

[in]	tb	input tait-bryan angles
[out]	q	output quaternion

Returns: Returns 0 on success or -1 on failure

◆ rc_quaternion_from_tb_array()

int rc_quaternion_from_tb_array	(	double	tb[3],
		double	q[4]
	)

Calculates quaternion vector q from tait-bryan angles tb.

tb angles are 321 Tait Bryan angles in array order XYZ with operation order 321(yaw-Z, pitch-Y, roll-x).

Parameters

[in]	tb	input tait-bryan angles
[out]	q	output quaternion

Returns: Returns 0 on success or -1 on failure

◆ rc_quaternion_conjugate()

int rc_quaternion_conjugate	(	rc_vector_t	q,
		rc_vector_t *	c
	)

Calculates conjugate of quaternion q.

Populates quaternion vector c with the conjugate of quaternion q where the 3 imaginary parts ijk are multiplied by -1. If c is already of length 4 then the old values are overwritten. Otherwise the old memory in c is freed and new memory is allocated to help prevent memory leaks.

Parameters

[in]	q	The quarter
[out]	c	output conjugate

Returns: Returns 0 on success or -1 on failure.

◆ rc_quaternion_conjugate_inplace()

int rc_quaternion_conjugate_inplace ( rc_vector_t * q )

Calculates conjugate of quaternion q and overwrites the old q.

Populates quaternion vector q with its conjugate where the 3 imaginary parts ijk are multiplied by -1.

Parameters

[in] q The quarternion

Returns: Returns 0 on success or -1 on failure.

◆ rc_quaternion_conjugate_array()

int rc_quaternion_conjugate_array	(	double	q[4],
		double	c[4]
	)

Calculates conjugate of quaternion q.

Populates quaternion vector c with the conjugate of quaternion q where the 3 imaginary parts ijk are multiplied by -1.

Parameters

[in]	q	The quarter
[out]	c	output conjugate

Returns: Returns 0 on success or -1 on failure.

◆ rc_quaternion_conjugate_array_inplace()

int rc_quaternion_conjugate_array_inplace ( double q[4] )

Calculates conjugate of quaternion q and overwrites the old q.

Populates quaternion vector q with its conjugate where the 3 imaginary parts ijk are multiplied by -1.

Parameters

[in] q The quarternion

Returns: Returns 0 on success or -1 on failure.

◆ rc_quaternion_imaginary_part()

int rc_quaternion_imaginary_part	(	rc_vector_t	q,
		rc_vector_t *	img
	)

Populates vector i with the imaginary components ijk of of quaternion vector q.

If img is already of length 3 then its original contents are overwritten. Otherwise the original allocated memory is freed and new memory is allocated.

Parameters

[in]	q	The quarternion
[out]	img	imaginary part

Returns: Returns 0 on success or -1 on failure.

◆ rc_quaternion_multiply()

int rc_quaternion_multiply	(	rc_vector_t	a,
		rc_vector_t	b,
		rc_vector_t *	c
	)

Calculates the quaternion Hamilton product ab=c.

Places the result in vector argument c. If c is already of length 4 then the old values are overwritten. Otherwise the old memory in c is freed and new memory is allocated to help prevent memory leaks.

Parameters

[in]	a	First input
[in]	b	second input
[out]	c	output

Returns: Returns 0 on success or -1 on failure.

◆ rc_quaternion_multiply_array()

int rc_quaternion_multiply_array	(	double	a[4],
		double	b[4],
		double	c[4]
	)

Calculates the quaternion Hamilton product ab=c.

Places the result in vector argument c.

Parameters

[in]	a	First input
[in]	b	second input
[out]	c	output

Returns: Returns 0 on success or -1 on failure.

◆ rc_quaternion_rotate()

int rc_quaternion_rotate	(	rc_vector_t *	p,
		rc_vector_t	q
	)

Rotates the quaternion p by quaternion q with the operation p'=qpq*.

p is modified in place, q is unmodified.

Parameters

	p	quaternion to be rotated
[in]	q	rotation quarternion

Returns: Returns 0 on success or -1 on failure.

◆ rc_quaternion_rotate_array()

int rc_quaternion_rotate_array	(	double	p[4],
		double	q[4]
	)

Rotates the quaternion p by quaternion q with the operation p'=qpq*.

p is modified in place, q is unmodified.

Parameters

	p	quaternion to be rotated
[in]	q	rotation quarternion

Returns: Returns 0 on success or -1 on failure.

◆ rc_quaternion_rotate_vector()

int rc_quaternion_rotate_vector	(	rc_vector_t *	v,
		rc_vector_t	q
	)

Rotate a 3D vector v in-place about the origin by quaternion q by converting v to a quaternion and performing the operation p'=qpq*.

v is modified in place, q is unmodified.

Parameters

	v	vectpr to be rotated
[in]	q	rotation quarternion

Returns: Returns 0 on success or -1 on failure.

◆ rc_quaternion_rotate_vector_array()

int rc_quaternion_rotate_vector_array	(	double	v[3],
		double	q[4]
	)

Rotate a 3D vector v in-place about the origin by quaternion q by converting v to a quaternion and performing the operation p'=qpq*.

v is modified in place, q is unmodified.

Parameters

	v	vectpr to be rotated
[in]	q	rotation quarternion

Returns: Returns 0 on success or -1 on failure.

Examples:: rc_altitude.c.

◆ rc_quaternion_to_rotation_matrix()

int rc_quaternion_to_rotation_matrix	(	rc_vector_t	q,
		rc_matrix_t *	m
	)

Converts a normalized quaternion to a 3x3 orthogonal rotation matrix.

q must be normalized before calling this! The orthogonal matrix corresponds to a rotation by the unit quaternion q when post-multiplied with a column vector as such: v_rotated=mv.

If m is already 3x3 then its contents are overwritten, otherwise its existing memory is freed and new memory is allocated.

Parameters

[in]	q	The quarter
	m	output 3x3 rotation matrix

Returns: Returns 0 on success or -1 on failure.