vectors3d.h - Three dimensional geometry, vectors and matrices More...

Data Structures
struct	V3D_Matrix
	3x3 matrix. More...

struct	V3D_Vector
	3x1 vector. More...

Enumerations
enum	V3D_AxisNames { Xaxis, Yaxis, Zaxis }
	Enumeration to be used by the v3d_createRotationMatrix() function.

Functions
V3D_Vector *	v3d_addV (V3D_Vector destV, const V3D_Vector srcV1, const V3D_Vector *srcV2)
	Add two vectors: [destV] = [srcV1] + [srcV2]. More...

V3D_Vector *	v3d_addToV (V3D_Vector modV1, const V3D_Vector srcV2)
	Modify first vector by adding a second one: [modV1] += [srcV2]. More...

V3D_Vector *	v3d_subtractV (V3D_Vector destV, const V3D_Vector srcV1, const V3D_Vector *srcV2)
	Vector subtraction: [destV] = [srcV1] - [srcV2]. More...

V3D_Vector *	v3d_subFromV (V3D_Vector modV1, const V3D_Vector srcV2)
	Modify first vector by subtracting a second one: [modV1] -= [srcV2]. More...

double	v3d_dotProductV (const V3D_Vector srcV1, const V3D_Vector srcV2)
	Return the dot product of the two vectors: res = [srcV1] · [srcV2] or res = \|\|srcV1\|\| * \|\|srcV2\|\| * cos(θ) More...

V3D_Vector *	v3d_crossProductV (V3D_Vector destV, const V3D_Vector srcV1, const V3D_Vector *srcV2)
	Return the cross product of the two vectors: [destV] = [srcV1] x [srcV2]. More...

V3D_Vector *	v3d_addToUV (V3D_Vector modV1, const V3D_Vector srcV2)
	Modify a unit length rectangular position vector modV1 by adding a correction vector srcV2 to it and re-normalizing to unit length. More...

V3D_Vector *	v3d_addToUVfast (V3D_Vector modV1, const V3D_Vector srcV2)
	Modify a unit length rectangular position vector modV1 by adding a small correction vector srcV2 to it and re-normalizing to unit length. More...

double	v3d_magVSq (const V3D_Vector *srcV)
	Return the square of the magnitude of the specified vector. More...

double	v3d_magV (const V3D_Vector *srcV)
	Return the magnitude of the specified vector. More...

V3D_Vector *	v3d_polarToRect (V3D_Vector *destV, double alpha_rad, double delta_rad)
	Converts polar (curvilinear) coordinates to equivalent rectangular (Cartesian) coordinates. More...

void	v3d_rectToPolar (double alpha_rad, double delta_rad, const V3D_Vector *srcV)
	Converts rectangular (Cartesian) coordinates to the equivalent polar (curvilinear) ones. More...

V3D_Matrix *	v3d_createRotationMatrix (V3D_Matrix *destM, V3D_AxisNames axis, double angle_rad)
	Creates a matrix to rotate a coordinate system about an axis. More...

V3D_Vector *	v3d_multMxV (V3D_Vector destV, const V3D_Matrix srcM, const V3D_Vector *srcV)
	Multiply 3x3 matrix by 3x1 vector to give a new 3x1 vector, as per equation [destV] = [srcM] * [srcV]. More...

V3D_Vector *	v3d_multMtransxV (V3D_Vector destV, const V3D_Matrix srcM, const V3D_Vector *srcV)
	Multiply 3x1 vector by the transpose of the 3x3 matrix to give a new 3x1 vector, as per equation [destV] = TRANSPOSE([srcM]) * [srcV]. More...

V3D_Matrix *	v3d_multMxM (V3D_Matrix destM, const V3D_Matrix srcM1, const V3D_Matrix *srcM2)
	Multiply 3x3 matrix by 3x3 matrix to give a new 3x3 matrix, as per [destM] = [srcM1]*[srcM2]. More...

Detailed Description

vectors3d.h - Three dimensional geometry, vectors and matrices

Author: David Hoadley

Data types and operations for handling three-dimensional positions and performing operations upon them, such as adding or subtracting vectors, coordinate rotation, conversion to and from polar coords.

Definition in file vectors3d.h.

Function Documentation

◆ v3d_addV()

V3D_Vector* v3d_addV	(	V3D_Vector *	destV,
		const V3D_Vector *	srcV1,
		const V3D_Vector *	srcV2
	)

Add two vectors: [destV] = [srcV1] + [srcV2].

Returns: pointer to destV

Parameters

[out]	destV	vector which will contain the result
[in]	srcV1	first vector
[in]	srcV2	second vector

Definition at line 64 of file vectors3d.c.

◆ v3d_addToV()

V3D_Vector* v3d_addToV	(	V3D_Vector *	modV1,
		const V3D_Vector *	srcV2
	)

Modify first vector by adding a second one: [modV1] += [srcV2].

Returns: pointer to modV1

Parameters

[in,out]	modV1	first vector, to which the second will be added
[in]	srcV2	second vector

Definition at line 87 of file vectors3d.c.

◆ v3d_subtractV()

V3D_Vector* v3d_subtractV	(	V3D_Vector *	destV,
		const V3D_Vector *	srcV1,
		const V3D_Vector *	srcV2
	)

Vector subtraction: [destV] = [srcV1] - [srcV2].

Returns: pointer to destV

Parameters

[out]	destV	vector which will contain the result
[in]	srcV1	first vector
[in]	srcV2	second vector

Definition at line 106 of file vectors3d.c.

◆ v3d_subFromV()

V3D_Vector* v3d_subFromV	(	V3D_Vector *	modV1,
		const V3D_Vector *	srcV2
	)

Modify first vector by subtracting a second one: [modV1] -= [srcV2].

Returns: pointer to modV1

Parameters

[in,out]	modV1	first vector, from which the second will be subtracted
[in]	srcV2	second vector

Definition at line 129 of file vectors3d.c.

◆ v3d_dotProductV()

double v3d_dotProductV	(	const V3D_Vector *	srcV1,
		const V3D_Vector *	srcV2
	)

Return the dot product of the two vectors: res = [srcV1] · [srcV2] or res = ||srcV1|| * ||srcV2|| * cos(θ)

Returns: scalar result of the dot product

Parameters

[in]	srcV1	first vector
[in]	srcV2	second vector

Definition at line 148 of file vectors3d.c.

◆ v3d_crossProductV()

V3D_Vector* v3d_crossProductV	(	V3D_Vector *	destV,
		const V3D_Vector *	srcV1,
		const V3D_Vector *	srcV2
	)

Return the cross product of the two vectors: [destV] = [srcV1] x [srcV2].

Returns: pointer to vector result of the cross product (destV)

Parameters

[out]	destV	vector which will contain the result
[in]	srcV1	first vector
[in]	srcV2	second vector

Definition at line 167 of file vectors3d.c.

◆ v3d_addToUV()

V3D_Vector* v3d_addToUV	(	V3D_Vector *	modV1,
		const V3D_Vector *	srcV2
	)

Modify a unit length rectangular position vector modV1 by adding a correction vector srcV2 to it and re-normalizing to unit length.

Returns: Pointer to modV1

Parameters

[in,out]	modV1	First vector, to which srcV2 will be added, and then re-normalized to unit length.
[in]	srcV2	vector to be added to modV1

When to call this function: If your vector modV1 is a unit vector, and you want it to be a unit vector after the addition of srcV2, then you can use this function. But if srcV2 is very small, you will be better off calling v3d_addToUVfast() instead.

Definition at line 193 of file vectors3d.c.

◆ v3d_addToUVfast()

V3D_Vector* v3d_addToUVfast	(	V3D_Vector *	modV1,
		const V3D_Vector *	srcV2
	)

Modify a unit length rectangular position vector modV1 by adding a small correction vector srcV2 to it and re-normalizing to unit length.

The scaling factor for the length is approximated by the expression 1 - [modV1] · [srcV2], where the dot indicates the Dot Product. The correction vector srcV2 must be very small.

Returns: Pointer to modV1

Parameters

[in,out]	modV1	First vector, to which srcV2 will be added, and then re-normalized to unit length. Valid range: \|modV1\| == 1
[in]	srcV2	vector to be added to modV1. Valid range: \|srcV2\| << 1

When to call this function: This routine performs the same function as v3d_addToUV(), but without calling sqrt(), or performing divisions. This can make it quicker than v3d_addToUV(), depending on what kind of floating point processor you have, if any. It is only valid if srcV2 is very small.

Definition at line 223 of file vectors3d.c.

◆ v3d_magVSq()

double v3d_magVSq ( const V3D_Vector * srcV )

Return the square of the magnitude of the specified vector.

Definition at line 258 of file vectors3d.c.

◆ v3d_magV()

double v3d_magV ( const V3D_Vector * srcV )

Return the magnitude of the specified vector.

Definition at line 271 of file vectors3d.c.

◆ v3d_polarToRect()

V3D_Vector* v3d_polarToRect	(	V3D_Vector *	destV,
		double	alpha_rad,
		double	delta_rad
	)

Converts polar (curvilinear) coordinates to equivalent rectangular (Cartesian) coordinates.

The vector returned is of unit length and in a right or left-handed system according to the convention for measuring the angle alpha_rad: for example left-handed for Hour Angle/Declination or Azimuth/Elevation, and right-handed for Right Ascension/Declination.

Returns: Pointer to destV, the resultant vector

Parameters

[out]	destV	Resultant 3D unit vector in rectangular coordinates
[in]	alpha_rad	Secondary angle coordinate, e.g. RA or Azimuth (radians)
[in]	delta_rad	Primary angle coordinate, e.g. declination or elevation (radians)

Definition at line 280 of file vectors3d.c.

◆ v3d_rectToPolar()

void v3d_rectToPolar	(	double *	alpha_rad,
		double *	delta_rad,
		const V3D_Vector *	srcV
	)

Converts rectangular (Cartesian) coordinates to the equivalent polar (curvilinear) ones.

Parameters

[out]	alpha_rad	Secondary angle coordinate (radians), range [-Pi, +Pi]
[out]	delta_rad	Primary angle coordinate (radians), range [-Pi/2, +Pi/2]
[in]	srcV	3D unit vector in rectangular coordinates (direction cosines)

Definition at line 311 of file vectors3d.c.

◆ v3d_createRotationMatrix()

V3D_Matrix* v3d_createRotationMatrix	(	V3D_Matrix *	destM,
		V3D_AxisNames	axis,
		double	angle_rad
	)

Creates a matrix to rotate a coordinate system about an axis.

This matrix can then be used to convert a rectangular position vector from one coordinate system to another

Returns: pointer to destM, the resultant matrix

Parameters

[out]	destM	3x3 rotation matrix
[in]	axis	axis of rotation. Xaxis (=0), Yaxis (=1), Zaxis (=2) No other values allowed.
[in]	angle_rad	angle to rotate around the axis of rotation (radian). When looking down the axis of rotation toward the origin, positive angles of rotation are: clockwise for left-handed systems (like Azimuth/Elevation) anticlockwise for right-handed systems (like Right Ascension/Declination)

                                               ┌  1     0     0  ┐
  createRotationMatrix(M, Xaxis, θ) is R1(θ) = │  0    cosθ  sinθ│
                                               └  0   -sinθ  cosθ┘

                                               ┌ cosθ   0   -sinθ┐
  createRotationMatrix(M, Yaxis, θ) is R2(θ) = │  0     1     0  │
                                               └ sinθ   0    cosθ┘

                                               ┌ cosθ  sinθ   0  ┐
  createRotationMatrix(M, Zaxis, θ) is R3(θ) = │-sinθ  cosθ   0  │
                                               └  0     0     1  ┘

Definition at line 377 of file vectors3d.c.

◆ v3d_multMxV()

V3D_Vector* v3d_multMxV	(	V3D_Vector *	destV,
		const V3D_Matrix *	srcM,
		const V3D_Vector *	srcV
	)

Multiply 3x3 matrix by 3x1 vector to give a new 3x1 vector, as per equation [destV] = [srcM] * [srcV].

Returns: pointer to destV

Parameters

[out]	destV	vector which will contain the result
[in]	srcM	the matrix
[in]	srcV	vector which will be multiplied by the matrix

Note: The same vector may be passed to destV and srcV, in which case the contents of srcV will be replaced.

Definition at line 439 of file vectors3d.c.

◆ v3d_multMtransxV()

V3D_Vector* v3d_multMtransxV	(	V3D_Vector *	destV,
		const V3D_Matrix *	srcM,
		const V3D_Vector *	srcV
	)

Multiply 3x1 vector by the transpose of the 3x3 matrix to give a new 3x1 vector, as per equation [destV] = TRANSPOSE([srcM]) * [srcV].

Returns: pointer to destV

Parameters

[out]	destV	vector which will contain the result
[in]	srcM	the matrix
[in]	srcV	vector which will be multiplied by the matrix

Note that for an orthogonal matrix which represents a rotation about axis j by angle θ, i.e. Matrix = Rj(θ), the following identity holds: TRANSPOSE(Matrix) = INVERSE(Matrix) = Rj(-θ). This is why this is a useful routine

Note: The same vector may be passed to destV and srcV, in which case the contents of srcV will be replaced.

Definition at line 475 of file vectors3d.c.

◆ v3d_multMxM()

V3D_Matrix* v3d_multMxM	(	V3D_Matrix *	destM,
		const V3D_Matrix *	srcM1,
		const V3D_Matrix *	srcM2
	)

Multiply 3x3 matrix by 3x3 matrix to give a new 3x3 matrix, as per [destM] = [srcM1]*[srcM2].

Returns: pointer to destM

Parameters

[out]	destM	matrix which will contain the result
[in]	srcM1	first matrix
[in]	srcM2	second matrix

Note: The same matrix may be passed to destM and either of the source matrices, in which case the contents of that source matrix will be replaced.

Definition at line 517 of file vectors3d.c.

Data Structures

Enumerations

Functions

Detailed Description

Function Documentation

◆ v3d_addV()

◆ v3d_addToV()

◆ v3d_subtractV()

◆ v3d_subFromV()

◆ v3d_dotProductV()

◆ v3d_crossProductV()

◆ v3d_addToUV()

◆ v3d_addToUVfast()

◆ v3d_magVSq()

◆ v3d_magV()

◆ v3d_polarToRect()

◆ v3d_rectToPolar()

◆ v3d_createRotationMatrix()

◆ v3d_multMxV()

◆ v3d_multMtransxV()

◆ v3d_multMxM()