Directional Vectors and Points

This module provides the following directional vector and point classes:

• Dir2d: Two-dimensional directional vectors.
• Dir3d: Three-dimensional directional vectors.
• Normal2d: Two-dimensional normal vectors.
• Normal3d: Three-dimensional normal vectors.
  • Point2d: Two-dimensional points.
  • Point3d: Three-dimensional points.
  • VectorPair3d: A three-dimensional pairing of an origin point with a directional vector.

The Normal2d and Normal3d classes are provided for clarity when the intent is to store a unit vector functioning as a surface normal. Otherwise they are identical to the Dir2d and Dir3d classes, and actually implemented by the same.

Single precision variants of these classes are also available. Simply prefix these class names with "Float" to use them.

Module Data

x_axis -> An object of Dir3d initialized with (1, 0, 0)

y_axis -> An object of Dir3d initialized with (0, 1, 0)

z_axis -> An object of Dir3d initialized with (0, 0, 1)

The Dir2d Class

Objects of this class represent directional vectors which are typically kept a unit length.

This class has the following constant data members:

Dir2d.kNumElements -> constant integer value of 2

Dir2d.kElementSize -> constant integer value of 4

This class has the following construction methods:

Dir2d ()

Constructs a new 2D vector with uninitialized values.

Returns the new vector.

Dir2d (dir)

dir -> Dir2d

Constructs a new 2D vector by copying the given 2D vector.

Returns the new vector.

Dir2d (x, y)

x -> double

y -> double

Constructs a new 2D vector with the given values.

Returns the new vector.

Dir2d (t)

t -> table of two double values, either numerically indexed

or indexed by the keys 'x' and 'y'

Constructs a new 2D vector with the values from the given table.

Returns the new vector.

Every instance of this class has the following member values, accessible both by numeric indices and the following keys:

1 | "x" -> the x coordinate value

2 | "y" -> the y coordinate value

Every instance of this class has the following member methods:

Dir2d:GetAngleBetween (other)

other -> Dir2d

Returns the 2D angle between one vector and the other in radians.

Dir2d:Normalize ()

Normalizes the vector to a length of one.

The original vector is modified in place. Returns the newly normalized vector.

Dir2d:NormalTransform (richMatrix, useInverse)

richMatrix -> FloatRichMatrix3x3 | RichMatrix3x3

useInverse -> boolean

Transforms the vector by the supplied rich matrix, treating the vector as a normal and preserving the normal properties.

This means it will remain perpendicular to any surface also transformed.

Rich matrices contain both a transformation and its inverse.

The original vector is modified in place.

Returns the newly transformed vector.

Dir2d:Set (value [ , value2 ] )

value [ , value2 ]-> double

Sets the vector with a single value in all positions, or using two new values.

The original vector is modified in place.

Returns the newly modified vector.

Dir2d:Transform (matrix)

matrix -> FloatMatrix3x3 | Matrix3x3

Transforms the vector by the supplied matrix.

The original vector is modified in place.

Returns the newly transformed vector.

... plus all of the member methods documented in the Common Vector Methods section.

The Normal2d Class

The Normal3d Class

The Point2d Class

Objects of this class represent positional vectors (points), and their component values may range over all real numbers.

This class has the following constant data members:

Point2d.kNumElements -> constant integer value of 2

Point2d.kElementSize -> constant integer value of 4

This class has the following construction methods:

Point2d ()

Constructs a new 2D point with uninitialized values.

Returns the new point.

Point2d (point)

point -> Point2d

Constructs a new 2D point by copying the given 2D point.

Returns the new point.

Point2d (x, y)

x -> double

y -> double

Constructs a new 2D point with the given values.

Returns the new point.

Point2d (t)

t -> table of two double values, either numerically indexed or indexed by the keys 'x' and 'y'

Constructs a new 2D point with the values from the given table.

Returns the new point.

Every instance of this class has the following member values, accessible both by numeric indices and the following keys:

1 | "x" -> the x coordinate value

2 | "y" -> the y coordinate value

Every instance of this class has the following member methods:

Point2d:GetDistanceBetween (other)

other -> Point2d

Returns the 2D distance between one point and the other.

Point2d:GetDistanceBetweenSquared (other)

other -> Point2d

Returns the square of the 2D distance between one point and the other.

Point2d:Set (value [ , value2 ] )

value [ , value2 ] -> double

Sets the point with a single value in all positions, or using two new values.

The original point is modified in place.

Returns the newly modified point.

Point2d:Transform (matrix)

matrix -> FloatMatrix3x3 | Matrix3x3

Transforms the point by the supplied matrix.

The original point is modified in place.

Returns the newly transformed point.

... plus all of the member methods documented in the Common Vector Methods section.

The Point3d Class

Objects of this class represent positional vectors (points), and their component values may range over all real numbers.

This class has the following constant data members:

Point3d.kNumElements -> constant integer value of 3

Point3d.kElementSize -> constant integer value of 4

This class has the following construction methods:

Point3d ()

Constructs a new 3D point with uninitialized values.

Returns the new point.

Point3d (point)

point -> Point3d

Constructs a new 3D point by copying the given 3D point.

Returns the new point.

Point3d (x, y, z)

x -> double

y -> double

z -> double

Constructs a new 3D point with the given values.

Returns the new point.

Point3d (t)

t -> table of three double values, either numerically indexed or indexed by the keys 'x', 'y' and 'z'

Constructs a new 3D point with the values from the given table.

Returns the new point.

Every instance of this class has the following member values, accessible both by numeric indices and the following keys:

1 | "x" -> the x coordinate value

2 | "y" -> the y coordinate value

3 | "z" -> the z coordinate value

Every instance of this class has the following member methods:

Point3d: GetDistanceBetween (other)

other -> Point3d

Returns the 3D distance between one point and the other.

Point3d:GetDistanceBetweenSquared (other)

other -> Point3d

Returns the square of the 3D distance between one point and the other.

Point3d:Set (value [ , value2, value3 ] )

value [ , value2, value3 ] -> double

Sets the point with a single value in all positions, or using three new values.

The original point is modified in place.

Returns the newly modified point.

Point3d:SetCrossProduct (other)

other -> Point3d

Sets the point to the cross product of this point with another point.

The original point is modified in place.

Returns the newly modified point.

Point3d:Transform (matrixOrQuaternion)

matrixOrQuaternion -> FloatMatrix3x3 | FloatMatrix4x3 | FloatMatrix4x4 | Matrix3x3 |

Matrix4x3 | Matrix4x4 | Quaternion | DoubleQuaternion

Transforms the point by the supplied matrix or quaternion.

The original point is modified in place.

Returns the newly transformed point.

... plus all of the member methods documented in the Common Vector Methods section.

Common Vector Methods

All instances of the vector and point classes also support the following member methods, where the vector or point class is referenced as "this_object_type":

object: Add (obj)

obj -> this_object_type (the same type as this object)

Adds the given object to this object in memberwise fashion, value by value.

The original object is modified in place.

Returns the newly added to object.

object:Clone ()

Returns a newly allocated copy of this object.

object:DotProduct (obj)

obj -> this_object_type (the same type as this object)

Returns the dot product of this object with the given object.

object:GetLength ()

Returns the scalar length of this object.

object:GetLengthSquared ()

Returns the square of the scalar length of this object.

object:IndexedElement (index)

index -> integer (from 1 to this_object_type.kNumElements)

Returns the indexed value.

This seems a bit redundant now that I think of it, but it's potentially faster than the normal numerical Lua index operation.

object:IsEqual (obj)

obj -> this_object_type (the same type as this object)

Returns true if this object is exactly equal to the given object, compared value by value.

Returns false otherwise.

object:IsFinite ()

Returns true this object defines a finite value, otherwise false.

object:IsNearEqual (obj)

tolerance -> double

obj -> this_object_type (the same type as this object)

Returns true if the elements of this object are equal to the elements of the given object within a tolerance determined by the precision of the elements.

Returns false otherwise.

object:IsNearEqual (obj, tolerance)

tolerance -> double

obj -> this_object_type (the same type as this object)

Returns true if the elements of this object are equal to the elements of the given object within the given tolerance.

Returns false otherwise.

object:IsNearZero ()

tolerance -> double

Returns true if every value in this object is nearly zero using a tolerance determined by the precision of the elements.

Returns false otherwise.

object:IsNearZero (tolerance)

tolerance -> double

Returns true if every value in this object is nearly zero using the given tolerance.

Returns false otherwise.

object:IsZero ()

Returns true if this object is filled with zeros.

Returns false otherwise.

object:Multiply (scalar) Multiplies the given object by a scalar, value by value.

scalar -> double

The original object is modified in place.

Returns the newly scaled object.

object:Negate ()

Sets every value in this object to the negative value of the existing value.

The original object is modified in place.

Returns the newly negated object.

object:SetAbs ()

Sets every value in this object to the absolute value of the existing value.

The original object is modified in place.

Returns the newly changed object.

object:SetZero ()

Sets every value in this object to zero.

The original object is modified in place.

Returns the newly zeroed object.

object:Subtract (obj)

obj -> this_object_type (the same type as this object)

subtracts the given object from this object in memberwise fashion, value by value.

The original object is modified in place.

Returns the newly subtracted from object.

All instances of the vector and point classes also support the following operators:

object:__eq (obj)

Available as the infix notation "=="

Returns the result of calling object:IsEqual(obj).

object:__tostring ()

Available via the tostring() global Lua function, and called from many other places.

Returns a textual representation of this object.

The VectorPair3d Class

Objects of this class consist of a three-dimensional origin point and direction vector, useful for tasks such as ray casting.

This class has the following constant data members:

VectorPair3d.kOriginClass -> The class of the origin of this pair, in this case Point3d.

VectorPair3d.kDirectionClass -> The class of the origin of this pair, in this case Dir3d.

This class has the following construction methods:

VectorPair3d ()

Constructs a new vector pair with uninitialized values.

Returns the new object.

VectorPair3d (vector)

vector -> VectorPair3d

Constructs a new vector pair by copying the given vector pair.

Returns the new object.

VectorPair3d (origin, direction)

origin -> Point3d

direction -> Dir3d

Constructs a new vector pair with the given values.

Returns the new object.

Every instance of this class has the following member values, accessible both by numeric indices and the following keys:

1 | "origin" -> the origin as a Point3d

2 | "direction" -> the direction as a Dir3d

Every instance of this class has the following member methods:

VectorPair3d:Clone ()

Returns a newly allocated copy of this object.