C++ documentation  C documentation

Vector3D.h

Support for three dimensional (3D) vectors.
For an elementary explanation of vectors see Vector2D.h only it is extended into three dimensions rather than two - so ideal for an airborne vehicle.
A C++ implementation is available via the Vector3D class.

Function

VECTOR3D MAKE_VECTOR3D(x,y,z)

Construct a new vector with the given x,y,z values.
For example to create a vector with the values (10,5,7) then:-
VECTOR3D myVector = MAKE_VECTOR3D(10,5,7);

double vector3d_GetX(const VECTOR3D* vector)

Returns the X value of the vector.
Example:
VECTOR3D myVector = MAKE_VECTOR3D(10,5,7); // Create vector
double x = vector3d_GetX(&myVector); // Get x value ie 10 in this case

double vector3d_GetY(const VECTOR3D* vector)

Returns the Y value of the vector.
Example:
VECTOR3D myVector = MAKE_VECTOR3D(10,5,7); // Create vector
double y = vector3d_GetY(&myVector); // Get y value ie 5 in this case

double vector3d_GetZ(const VECTOR3D* vector)

Returns the Z value of the vector.
Example:
VECTOR3D myVector = MAKE_VECTOR3D(10,5,7); // Create vector
double y = vector3d_GetZ(&myVector); // Get z value ie 7 in this case

vector3d_SetX(VECTOR3D* vector, double x)

Set the X value of an exiting vector.
Example:
VECTOR3D myVector = MAKE_VECTOR3D(10,5,7);
vector3d_SetX(&myVector, 12); // Change to (12,5,7)

vector3d_SetY(VECTOR3D* vector, double y)

Set the Y value of an exiting vector.
Example:
VECTOR3D myVector = MAKE_VECTOR3D(10,5,7);
vector3d_SetY(&myVector, 6); // Change to (10,6,7)

vector3d_SetZ(VECTOR3D* vector, double y)

Set the Z value of an exiting vector.
Example:
VECTOR3D myVector = MAKE_VECTOR3D(10,5,7);
vector3d_SetZ(&myVector, 6); // Change to (10,5,6)

vector3d_Set(VECTOR3D* vector, double x, double y, double z)

Overwrite the vector with new values.
Example:
VECTOR3D myVector; // Create vector with undefined values
vector3d_Set(&myVector, 10, 5, 7);// Vector is now (10,5,7)

double vector3d_Length(const VECTOR3D* vector)

Get the length of the vector.
Mathematically this is SQRT(x*x + y*y + z*z)

double vector3d_LengthSquared(const VECTOR3D* vector)

Return the length squared of the vector.
Mathematically this is: x*x + y*y + z*z
Sometimes you may only be comparing relative lengths of different vectors - in which case you can use this function instead of the real length and thus avoid the overhead of the additional square root function to convert to the real length.

vector3d_Normalise(VECTOR3D* dst,const VECTOR3D* src)

Normalise the vector so that it has a length of 1.0
The first parameter specifies the vector to store the result, and the second parameter specifies the vector to be normalised. Both parameters can refer to the same vector if you are happy to loose the details of the original vector.

Add two vectors ie dst = dst + src

vector3d_Subtract(VECTOR3D* dst, const VECTOR3D* src)

Subtract two vectors. dst = dst - src;

vector3d_Copy(VECTOR3D* dst, const VECTOR3D* src)

Set a vector to be a copy of another vector. dst = src.
Example:
VECTOR3D vec1 = MAKE_VECTOR2D(10,5,7); // Init vec1
VECTOR3D vec2; // Create vec2 with unknown values
vector3d_Copy(&vec2, &vec1); // Set vec2 to vec1 ie (10,5,7)

vector3d_Scale(VECTOR3D* v,double scale)

Multiply the X, Y and Z values of the vector by the given scale factor.
Example:
Assuming we know that
VECTOR3D robotPosition = MAKE_VECTOR2D(10,5,7); // current location
double speed = 7; // The speed of the robot in, say, cm/second
We can estimate what the robot position will be in 5 seconds using:
VECTOR3D newPosition; // Create a new vector
VECTOR3D movement; // Create a new vector
vector3d_Copy(&newPosition, &robotPosition); // new = current
vector3d_Scale(&movement, speed * 5); // Heading = Heading * speed * 5 seconds
vector3d_Add(&newPosition, &movement); // Estimated position after 5 seconds

double vector3d_DotProduct(const VECTOR3D* v1, const VECTOR3D* v2)

Return the dot product of the two vectors 'v1' and 'v2'.
The dot product is: Length(v1) * Length(v2) * cos(angle between them)
If 'v1' and 'v2' have been normalised then their lengths are 1.0 and so the above simplifies to: cos(angle between them)

vector3d_CrossProduct(VECTOR3D*result, const VECTOR3D* v1, const VECTOR3D* v2)

Calculate the vector cross product.
The first parameter is the address of an existing Vector3D to store the result and the remaining parameters are the two vectors to calculate the cross product from.
The resultant vector is at 90° to the two vectors.
This is very handy in a 3 dimensional world as it allows you to determine the complete orientation of a body given only two vectors - ie it can be used to calculate the missing third vector.

double vector3d_AngleRadians(const VECTOR3D* v1, const VECTOR3D* v2)

Return the angle, in radians, between two vectors.
The returned value will be in the range 0 to PI.
To convert the radians value into degrees then multiply it by (180.0 / PI)