three-dimensional vector

Collaboration diagram for three-dimensional vector:

Data Structures
struct	a_vector3
	instance structure for three-dimensional vector More...

Macros
#define	A_VECTOR3_C(x, y, z)
#define	a_vector3_c(x)
#define	a_vector3_(_, x)

Typedefs
typedef struct a_vector3	a_vector3

Functions
a_real	a_vector3_set_dir (a_vector3 *ctx, a_real x, a_real y, a_real z)
	set the components of a 3D vector and normalize it in place.
void	a_vector3_val (a_vector3 const *ctx, a_real *x, a_real *y, a_real *z)
	get the cartesian coordinates of a 3D vector.
void	a_vector3_set_val (a_vector3 *ctx, a_real x, a_real y, a_real z)
	set the cartesian coordinates of a 3D vector.
void	a_vector3_cyl (a_vector3 const *ctx, a_real *rho, a_real *theta, a_real *z)
	get the cylindrical coordinates of a 3D vector.
void	a_vector3_set_cyl (a_vector3 *ctx, a_real rho, a_real theta, a_real z)
	set the cylindrical coordinates of a 3D vector.
void	a_vector3_sph (a_vector3 const *ctx, a_real *rho, a_real *theta, a_real *alpha)
	get the spherical coordinates of a 3D vector.
void	a_vector3_set_sph (a_vector3 *ctx, a_real rho, a_real theta, a_real alpha)
	set the spherical coordinates of a 3D vector.
void	a_vector3_add (a_vector3 const *lhs, a_vector3 const *rhs, a_vector3 *res)
	add a 3D vector to a 3D vector.
void	a_vector3_sub (a_vector3 const *lhs, a_vector3 const *rhs, a_vector3 *res)
	subtract a 3D vector from a 3D vector.
void	a_vector3_mul (a_vector3 const *lhs, a_real rhs, a_vector3 *res)
	multiplie a 3D vector by a scalar.
void	a_vector3_div (a_vector3 const *lhs, a_real rhs, a_vector3 *res)
	divide a 3D vector by a scalar.
void	a_vector3_neg (a_vector3 const *ctx, a_vector3 *res)
	negate a 3D vector.
a_real	a_vector3_unit (a_vector3 *ctx)
	normalize a 3D vector in-place to unit length.
a_real	a_vector3_norm (a_vector3 const *ctx)
	compute the magnitude of a 3D vector.
a_real	a_vector3_norm2 (a_vector3 const *ctx)
	compute the squared magnitude of a 3D vector.
a_real	a_vector3_dot (a_vector3 const *lhs, a_vector3 const *rhs)
	compute the dot product (scalar product) of two 3D vectors.
a_real	a_vector3_dist (a_vector3 const *lhs, a_vector3 const *rhs)
	compute the distance between two 3D vectors.
a_real	a_vector3_dist2 (a_vector3 const *lhs, a_vector3 const *rhs)
	compute the squared distance between two 3D vectors.
a_real	a_vector3_angle (a_vector3 const *lhs, a_vector3 const *rhs)
	compute the angle between two 3D vectors in radians.
a_bool	a_vector3_isver (a_vector3 const *lhs, a_vector3 const *rhs)
	check if two 3D vectors are orthogonal.
a_bool	a_vector3_ispar (a_vector3 const *lhs, a_vector3 const *rhs)
	check if two 3D vectors are parallel or anti-parallel.
void	a_vector3_cross (a_vector3 const *lhs, a_vector3 const *rhs, a_vector3 *res)
	compute the cross product (vector product) of two 3D vectors
void	a_vector3_outer (a_vector3 const *lhs, a_vector3 const *rhs, a_real res[9])
	compute the outer product (tensor product) of two 3D vectors.
int	a_vector3_ortho (a_vector3 const *ctx, a_vector3 *u, a_vector3 *v)
	construct an orthonormal basis from a given 3D direction vector.
int	a_vector3_proj (a_vector3 const *ctx, a_vector3 const *dir, a_vector3 *res)
	project vector onto the direction of vector.
int	a_vector3_perp (a_vector3 const *ctx, a_vector3 const *dir, a_vector3 *res)
	project vector onto the plane perpendicular to normal vector.
int	a_vector3_refl (a_vector3 const *ctx, a_vector3 const *dir, a_vector3 *res)
	reflect vector across the plane perpendicular to normal vector.
int	a_vector3_sym1 (a_vector3 const *ctx, a_vector3 const *dir, a_vector3 *res)
	reflect vector across the line with direction vector.
void	a_vector3_rot_ (a_vector3 const *ctx, a_vector3 const *dir, a_real sin, a_real cos, a_vector3 *res)
	rotate a 3D vector around an arbitrary unit axis using Rodrigues' rotation formula.
void	a_vector3_rot (a_vector3 const *ctx, a_vector3 const *dir, a_real angle, a_vector3 *res)
	rotate a 3D vector around an arbitrary unit axis using Rodrigues' rotation formula.
void	a_vector3_rot2d (a_vector3 const *iu, a_vector3 const *iv, a_real angle, a_vector3 *ou, a_vector3 *ov)
	rotate a 2D basis in the plane spanned by two orthogonal vectors.

Detailed Description

Macro Definition Documentation

a_vector3_

#define a_vector3_	(		_,
			x )

Value:

a_cast_s(a_vector3 _, x)

A_VECTOR3_C

#define A_VECTOR3_C	(		x,
			y,
			z )

Value:

{a_real_c(x), a_real_c(y), a_real_c(z)}

constructs a three-dimensional vector from cartesian coordinate

a_vector3_c

#define a_vector3_c

(

x

)

Value:

a_cast_s(a_vector3, x)

static cast to three-dimensional vector

Function Documentation

a_vector3_angle()

a_real a_vector3_angle	(	a_vector3 const *	lhs,
		a_vector3 const *	rhs )

compute the angle between two 3D vectors in radians.

In three-dimensional space, let vector \(\vec{a}\) have coordinates \((a_x,a_y,a_z)\) and let vector \(\vec{b}\) have coordinates \((b_x,b_y,b_z)\). Then the angle between \(\vec{a}\) and \(\vec{b}\) is given by:

\[ \theta=\arccos\left(\frac{\vec{a}\cdot\vec{b}}{\|\vec{a}\|\|\vec{b}\|}\right) =\arccos\left(\frac{\vec{a}\cdot\vec{b}}{\sqrt{\|\vec{a}\|^2\|\vec{b}\|^2}}\right) \]

Parameters

[in]	lhs	is left-hand side 3D vector
[in]	rhs	is right-hand side 3D vector

Returns

the angle between two 3D vectors in radians, in the range \([0,\pi]\)

Return values

0	if the vector is null

a_vector3_cross()

void a_vector3_cross	(	a_vector3 const *	lhs,
		a_vector3 const *	rhs,
		a_vector3 *	res )

compute the cross product (vector product) of two 3D vectors

In three-dimensional space, let vector \(\vec{a}\) have coordinates \((a_x,a_y,a_z)\) and let vector \(\vec{b}\) have coordinates \((b_x,b_y,b_z)\). Then the cross product of vectors \(\vec{a}\) and \(\vec{b}\) is defined as:

\[ \vec{a} \times \vec{b} = \begin{pmatrix} a_y b_z - a_z b_y \\ a_z b_x - a_x b_z \\ a_x b_y - a_y b_x \end{pmatrix} \]

https://en.wikipedia.org/wiki/Cross_product

Parameters

[in]	lhs	is left-hand side 3D vector
[in]	rhs	is right-hand side 3D vector
[out]	res	stores the result vector

a_vector3_dist()

a_real a_vector3_dist	(	a_vector3 const *	lhs,
		a_vector3 const *	rhs )

compute the distance between two 3D vectors.

In three-dimensional space, let vector \(\vec{a}\) have coordinates \((a_x,a_y,a_z)\) and let vector \(\vec{b}\) have coordinates \((b_x,b_y,b_z)\). Then the distance between \(\vec{a}\) and \(\vec{b}\) is given by:

\[ d(\vec{a},\vec{b})=\sqrt{(a_x-b_x)^2+(a_y-b_y)^2+(a_z-b_z)^2} \]

Parameters

[in]	lhs	is left-hand side 3D vector
[in]	rhs	is right-hand side 3D vector

Returns

the distance between two 3D vectors

a_vector3_dist2()

a_real a_vector3_dist2	(	a_vector3 const *	lhs,
		a_vector3 const *	rhs )

compute the squared distance between two 3D vectors.

In three-dimensional space, let vector \(\vec{a}\) have coordinates \((a_x,a_y,a_z)\) and let vector \(\vec{b}\) have coordinates \((b_x,b_y,b_z)\). Then the squared distance between \(\vec{a}\) and \(\vec{b}\) is given by:

\[ d(\vec{a},\vec{b})^2=(a_x-b_x)^2+(a_y-b_y)^2+(a_z-b_z)^2 \]

Parameters

[in]	lhs	is left-hand side 3D vector
[in]	rhs	is right-hand side 3D vector

Returns

the squared distance between two 3D vectors

a_vector3_dot()

a_real a_vector3_dot	(	a_vector3 const *	lhs,
		a_vector3 const *	rhs )

compute the dot product (scalar product) of two 3D vectors.

In three-dimensional space, let vector \(\vec{a}\) have coordinates \((a_x,a_y,a_z)\) and let vector \(\vec{b}\) have coordinates \((b_x,b_y,b_z)\). Then the dot product of vectors \(\vec{a}\) and \(\vec{b}\) is defined as:

\[ \vec{a} \cdot \vec{b} = a_x b_x + a_y b_y + a_z b_z \]

Parameters

[in]	lhs	is left-hand side 3D vector
[in]	rhs	is right-hand side 3D vector

Returns

the dot product of two 3D vectors

a_vector3_ispar()

a_bool a_vector3_ispar	(	a_vector3 const *	lhs,
		a_vector3 const *	rhs )

check if two 3D vectors are parallel or anti-parallel.

Parameters

[in]	lhs	is left-hand side 3D vector
[in]	rhs	is right-hand side 3D vector

Returns

whether the vectors are nearly parallel or anti-parallel

Return values

true	if the vector is null

a_vector3_isver()

a_bool a_vector3_isver	(	a_vector3 const *	lhs,
		a_vector3 const *	rhs )

check if two 3D vectors are orthogonal.

Parameters

[in]	lhs	is left-hand side 3D vector
[in]	rhs	is right-hand side 3D vector

Returns

whether the vectors are nearly orthogonal

Return values

true	if the vector is null

a_vector3_norm()

a_real a_vector3_norm

(

a_vector3 const *

ctx

)

compute the magnitude of a 3D vector.

In three-dimensional space, a vector \(\vec{v}\) with coordinates \((x,y,z)\) has a magnitude defined as:

\[ \|\vec{v}\|=\sqrt{x^2+y^2+z^2} \]

Parameters

[in]

ctx

points to the input vector

Returns

the magnitude of the vector

a_vector3_norm2()

a_real a_vector3_norm2

(

a_vector3 const *

ctx

)

compute the squared magnitude of a 3D vector.

In three-dimensional space, a vector \(\vec{v}\) with coordinates \((x,y,z)\) has a squared magnitude defined as:

\[ \|\vec{v}\|^2=x^2+y^2+z^2 \]

Parameters

[in]

ctx

points to the input vector

Returns

the squared magnitude of the vector

a_vector3_ortho()

int a_vector3_ortho	(	a_vector3 const *	ctx,
		a_vector3 *	u,
		a_vector3 *	v )

construct an orthonormal basis from a given 3D direction vector.

Let \(\vec{n}\) be a non-zero 3D vector. The orthonormal vectors \(\vec{u}\) and \(\vec{v}\) such that \(\{\vec{u},\vec{v},\vec{n}\}\) forms a right-handed orthogonal basis are given by:

If \(|c_x| \ge |c_y|\):

\[ \vec{u} = \frac{\mathbf{j}\times\vec{n}}{\|\mathbf{j}\times\vec{n}\|} \quad \vec{v} = \frac{\vec{n}\times\vec{u}}{\|\vec{n}\times\vec{u}\|} \]

Otherwise:

\[ \vec{v} = \frac{\vec{n}\times\mathbf{i}}{\|\vec{n}\times\mathbf{i}\|} \quad \vec{u} = \frac{\vec{v}\times\vec{n}}{\|\vec{v}\times\vec{n}\|} \]

Parameters

[in]	ctx	points to the input direction vector
[out]	u	stores first orthogonal unit vector
[out]	v	stores second orthogonal unit vector

Returns

error code value

Return values

<0	failure
0	success

a_vector3_outer()

void a_vector3_outer	(	a_vector3 const *	lhs,
		a_vector3 const *	rhs,
		a_real	res[9] )

compute the outer product (tensor product) of two 3D vectors.

In three-dimensional space, let vector \(\vec{a}\) have coordinates \((a_x,a_y,a_z)\) and let vector \(\vec{b}\) have coordinates \((b_x,b_y,b_z)\). Then the outer product of vectors \(\vec{a}\) and \(\vec{b}\) is defined as:

\[ \vec{a} \otimes \vec{b} = \begin{bmatrix} a_x b_x & a_x b_y & a_x b_z \\ a_y b_x & a_y b_y & a_y b_z \\ a_z b_x & a_z b_y & a_z b_z \end{bmatrix} \]

https://en.wikipedia.org/wiki/Outer_product

Parameters

[in]	lhs	is left-hand side 3D vector
[in]	rhs	is right-hand side 3D vector
[out]	res	stores the 3×3 matrix in row-major order

a_vector3_perp()

int a_vector3_perp	(	a_vector3 const *	ctx,
		a_vector3 const *	dir,
		a_vector3 *	res )

project vector onto the plane perpendicular to normal vector.

In three-dimensional space, let \(\vec{v}\) be the vector to be projected, and let \(\vec{n}\) be the normal vector of the plane. Then the perpendicular projection of \(\vec{v}\) about the plane normal \(\vec{n}\) is defined as:

\[ \vec{v}' = \vec{v}-\frac{\vec{n}\cdot\vec{v}}{\|\vec{n}\|^2}\vec{n} \]

Parameters

[in]	ctx	points to the vector to be projected
[in]	dir	points to the normal vector of the plane
[out]	res	stores the perpendicular projection vector about the plane normal

Returns

error code value

Return values

<0	failure
0	success

a_vector3_proj()

int a_vector3_proj	(	a_vector3 const *	ctx,
		a_vector3 const *	dir,
		a_vector3 *	res )

project vector onto the direction of vector.

In three-dimensional space, let \(\vec{v}\) be the vector to be projected, and let \(\vec{d}\) be the direction vector for projection. Then the projection of \(\vec{v}\) onto the direction of \(\vec{d}\) is defined as:

\[ \vec{v}' = \frac{\vec{d}\cdot\vec{v}}{\|\vec{d}\|^2}\vec{d} \]

Parameters

[in]	ctx	points to the vector to be projected
[in]	dir	points to the direction vector for projection
[out]	res	stores the projection vector onto the direction of vector

Returns

error code value

Return values

<0	failure
0	success

a_vector3_refl()

int a_vector3_refl	(	a_vector3 const *	ctx,
		a_vector3 const *	dir,
		a_vector3 *	res )

reflect vector across the plane perpendicular to normal vector.

In three-dimensional space, let \(\vec{v}\) be the vector to be reflected, and let \(\vec{n}\) be the normal vector of the reflection plane. Then the reflection of \(\vec{v}\) about the plane with normal \(\vec{n}\) is defined as:

\[ \vec{v}' = \vec{v}-2\frac{\vec{n}\cdot\vec{v}}{\|\vec{n}\|^2}\vec{n} \]

Parameters

[in]	ctx	points to the vector to be reflected
[in]	dir	points to the normal vector of the reflection plane
[out]	res	stores the reflection vector about the plane with normal

Returns

error code value

Return values

<0	failure
0	success

a_vector3_rot()

void a_vector3_rot	(	a_vector3 const *	ctx,
		a_vector3 const *	dir,
		a_real	angle,
		a_vector3 *	res )

rotate a 3D vector around an arbitrary unit axis using Rodrigues' rotation formula.

In three-dimensional space, let \(u\) be a unit vector defining a rotation axis and let \(v\) be any vector to rotate about \(u\) by angle \(\theta\) (right hand rule, anticlockwise). Then the rotated vector \(\vec{v}'\) is given by:

\[ \vec{v}' = \vec{v}\cos\theta + (\vec{u}\times\vec{v})\sin\theta + \vec{u}(\vec{u}\cdot\vec{v})(1-\cos\theta) \]

https://en.wikipedia.org/wiki/Rodrigues%27_rotation_formula

Parameters

[in]	ctx	points to the input vector to rotate
[in]	dir	points to the normalized rotation axis
[in]	angle	is rotation angle in radians
[out]	res	stores the result vector

a_vector3_rot2d()

void a_vector3_rot2d	(	a_vector3 const *	iu,
		a_vector3 const *	iv,
		a_real	angle,
		a_vector3 *	ou,
		a_vector3 *	ov )

rotate a 2D basis in the plane spanned by two orthogonal vectors.

In three-dimensional space, let \(\vec{u}\) and \(\vec{v}\) be an orthonormal basis in the plane, and let \(\theta\) be the counterclockwise rotation angle about the origin. The new basis vectors \(\vec{u}'\) and \(\vec{v}'\) after rotation are given by:

\begin{aligned} \vec{u}'=\left(\begin{bmatrix} \cos\theta & -\sin\theta \\ \sin\theta & \cos\theta \end{bmatrix} \begin{bmatrix} 1 \\ 0 \end{bmatrix}\right) \cdot \begin{bmatrix} \vec{u} \\ \vec{v} \end{bmatrix} =\cos\theta\vec{u}+\sin\theta\vec{v} \\ \vec{v}'=\left(\begin{bmatrix} \cos\theta & -\sin\theta \\ \sin\theta & \cos\theta \end{bmatrix} \begin{bmatrix} 0 \\ 1 \end{bmatrix}\right) \cdot \begin{bmatrix} \vec{u} \\ \vec{v} \end{bmatrix} =\cos\theta\vec{v}-\sin\theta\vec{u} \end{aligned}

Parameters

[in]	iu	points to first axis vector
[in]	iv	points to second axis vector
[in]	angle	is rotation angle in radians
[out]	ou	stores rotated first axis vector
[out]	ov	stores rotated second axis vector

a_vector3_rot_()

void a_vector3_rot_	(	a_vector3 const *	ctx,
		a_vector3 const *	dir,
		a_real	sin,
		a_real	cos,
		a_vector3 *	res )

rotate a 3D vector around an arbitrary unit axis using Rodrigues' rotation formula.

In three-dimensional space, let \(u\) be a unit vector defining a rotation axis and let \(v\) be any vector to rotate about \(u\) by angle \(\theta\) (right hand rule, anticlockwise). Then the rotated vector \(\vec{v}'\) is given by:

\[ \vec{v}' = \vec{v}\cos\theta + (\vec{u}\times\vec{v})\sin\theta + \vec{u}(\vec{u}\cdot\vec{v})(1-\cos\theta) \]

https://en.wikipedia.org/wiki/Rodrigues%27_rotation_formula

Parameters

[in]	ctx	points to the input vector to rotate
[in]	dir	points to the normalized rotation axis
[in]	sin	is precomputed \(\sin(\theta)\)
[in]	cos	is precomputed \(\cos(\theta)\)
[out]	res	stores the result vector

a_vector3_set_dir()

a_real a_vector3_set_dir	(	a_vector3 *	ctx,
		a_real	x,
		a_real	y,
		a_real	z )

set the components of a 3D vector and normalize it in place.

Returns

the original length of the vector

a_vector3_sym1()

int a_vector3_sym1	(	a_vector3 const *	ctx,
		a_vector3 const *	dir,
		a_vector3 *	res )

reflect vector across the line with direction vector.

In three-dimensional space, let \(\vec{v}\) be the vector to be reflected, and let \(\vec{d}\) be the direction vector defining the reflection line. Then the reflection of \(\vec{v}\) about the line with direction \(\vec{d}\) is defined as:

\[ \vec{v}' = 2\frac{\vec{d}\cdot\vec{v}}{\|\vec{d}\|^2}\vec{d}-\vec{v} \]

Parameters

[in]	ctx	points to the vector to be reflected
[in]	dir	points to the direction vector defining the reflection line
[out]	res	stores the reflection vector about the line with direction

Returns

error code value

Return values

<0	failure
0	success

a_vector3_unit()

a_real a_vector3_unit

(

a_vector3 *

ctx

)

normalize a 3D vector in-place to unit length.

Parameters

[in]

ctx

points to the input vector

Returns

the original length of the vector