vector3
3D Vector library with meta functions
License: GPLv3
Usage
- Make your mod depends on
vector3; - Create vectors with
vector3(x, y, z); - See available methods below
All functions create new vectors so that the original vector is not modified. All the functions return the new vector so that operations can be chained easily.
Example:
u = vector3(1, 2, 3)
v = vector3(4, 5, 6)
w = (5 * u + u:dot(v) * u:cross(v:scale(5))):norm()
Constructors
vector3(x, y, z)
Creates a new vector with components x, y and z. Components defaults to zero.
v0 = vector3() -- (0,0,0)
v1 = vector3(1,2,3) -- (1,2,3)
vector3.fromSpherical(r, theta, phi)
Creates a new vector from spherical coordinates. theta is the polar angle (from the upwards y axis), phi the azimut (counting clockwise around y, starting from x), and r the radius. Default values are r=1, theta=pi/2, phi=0.
v2 = vector3.fromSpherical(10, math.pi / 2, math.pi) -- (10, 0, 0)
vector3.fromCylindrical(r, phi, y)
Creates a new vector from cylindrical coordinates. r is the radius, phi is the azimut angle (counting clockwise around y, starting from x) and y the height. Default values are r=1, phi=0 and y=1.
v21 = vector3.fromCylindrical(10, math.pi / 2, 5) -- (0, 5, 10)
vector3.fromPolar(r, phi)
Creates a new vector from polar coordinates. r is the radius and phi the angle (counting clockwise around y, starting from x), and . Default values are r=1 and phi=0.
v22 = vector3.fromPolar(6, - math.pi / 2) -- (0, 0, -6)
vector3.srandom(a, b)
Creates a vector with random spherical coordinates and with the radius drawn at random between a and b
v3 = vector3.srandom()
vector3.crandom(a, b, c, d)
Creates a vector with random cylindrical coordinates. The radius is drawn at random between a and b and the height between c and d
v31 = vector3.crandom(0, 10, 5, 15)
vector3.prandom(a, b)
Creates a vector with random polar coordinates and with the radius drawn at random between a and b
v32 = vector3.prandom()
Constants
vector3.zero = vector3(0, 0, 0)
vector3.one = vector3(1, 1, 1)
vector3.none = -vector3(1, 1, 1)
vector3.x = vector3(1, 0, 0)
vector3.y = vector3(0, 1, 0)
vector3.z = vector3(0, 0, 1)
vector3.xy = vector3(1, 1, 0)
vector3.yz = vector3(0, 1, 1)
vector3.xz = vector3(1, 0, 1)
vector3.nx = -vector3(1, 0, 0)
vector3.ny = -vector3(0, 1, 0)
vector3.nz = -vector3(0, 0, 1)
vector3.nxy = -vector3(1, 1, 0)
vector3.nyz = -vector3(0, 1, 1)
vector3.nxz = -vector3(1, 0, 1)
Meta functions
Allows to print a vector.
print(v1)
concatenation
Allows to create strings from vector concatenation.
print(v1 .. v2 .. v3)
negative
Returns the opposite vector.
v5 = -v1
equality
Return true if two vectors have their components equals
v1 == v2
addition
Return the sum of two vectors component wise. If one argument is a number then this number is added to each component of the vector.
v1 + v2
v1 + 10
subtraction
Return the difference of two vectors component wise. If one argument is a number then this number is subtracted to each component of the vector.
v1 - v2
v1 - 1
multiplication
Return the product of two vectors component wise. If one argument is a number then each component of the vector is multiplied by this number.
v1 * v2
v1 * 10
division
Return the division of two vectors component wise. If one argument is a number then each component of the vector is divided by this number.
v1 / v3
v1 / 10
Functions
clone()
Return a new vector which is a copy of the initial vector.
v4 = v1:clone()
length()
Returns the magnitude of the vector.
v3:length()
norm()
Return the corresponding normalized vector (with magnitude one).
v3:norm()
scale(mag)
Return a new vector which is scaled to magnitude mag
v1:scale(10)
limit(max)
Returns a new vector which is scaled to magnitude max if its magnitude if greater than max.
vector3(10, 20, 30):limit(5)
vector3(1, 2, 3):limit(5)
floor()
Return a new vector with the components floored.
v3:floor()
round()
Return a new vector with the components rounded to the closest integer.
v3:round()
set(x, y, z)
Return a new vector with components x,y and z. If a parameter is nil then the corresponding component is unchanged.
v1:set(4, nil, 7)
offset(a, b, c)
Return a new vector with components x, y, z offset by a, b and c. If a parameter is nil the corresponding component is unchanged.
v2:offset(-1, 3, 2)
apply(f)
Return a new vector with the function f applied to its components.
v2:apply(function(x) return x * x end)
dist(b)
Returns the distance between the current vector and b (as if they were representing points).
v1:dist(v2)
dot(b)
Returns the dot product of the current vector and b.
v1:dot(v2)
cross(b)
Returns a vector which is the cross product of the current vector and b.
v1:cross(v2)
rotate_around(axis, angle)
Returns a new vector which is the current vector rotated around axis with angle.
axis = vector3(0, 1, 0)
v2:rotate_around(axis, math.pi)
unpack()
Returns the unpacked components of the current vector.
x, y, z = v1:unpack()
print(x)
print(y)
print(z)
