Vector math API documentation

Functions for mathematical operations on vectors, matrices and quaternions. - The vector types (`vmath.vector3` and `vmath.vector4`) supports addition and subtraction with vectors of the same type. Vectors can be negated and multiplied (scaled) or divided by numbers. - The quaternion type (`vmath.quat`) supports multiplication with other quaternions. - The matrix type (`vmath.matrix4`) can be multiplied with numbers, other matrices and `vmath.vector4` values. - All types performs equality comparison by each component value. The following components are available for the various types: vector3 : `x`, `y` and `z`. Example: `v.y` vector4 : `x`, `y`, `z`, and `w`. Example: `v.w` quaternion : `x`, `y`, `z`, and `w`. Example: `q.w` matrix4 : `m00` to `m33` where the first number is the row (starting from 0) and the second number is the column. Columns can be accessed with `c0` to `c3`, returning a `vector4`. Example: `m.m21` which is equal to `m.c1.z` vector : indexed by number 1 to the vector length. Example: `v[3]`

Version: stable

FUNCTIONS
vmath.clamp() clamp input value in range [min, max] and return clamped value
vmath.conj() calculates the conjugate of a quaternion
vmath.cross() calculates the cross-product of two vectors
vmath.dot() calculates the dot-product of two vectors
vmath.euler_to_quat() converts euler angles into a quaternion
vmath.inv() calculates the inverse matrix.
vmath.length() calculates the length of a vector or quaternion
vmath.length_sqr() calculates the squared length of a vector or quaternion
vmath.lerp() lerps between two vectors
vmath.lerp() lerps between two quaternions
vmath.lerp() lerps between two numbers
vmath.matrix4() creates a new identity matrix
vmath.matrix4() creates a new matrix from another existing matrix
vmath.matrix4_axis_angle() creates a matrix from an axis and an angle
vmath.matrix4_compose() creates a new matrix4 from translation, rotation and scale
vmath.matrix4_frustum() creates a frustum matrix
vmath.matrix4_look_at() creates a look-at view matrix
vmath.matrix4_orthographic() creates an orthographic projection matrix
vmath.matrix4_perspective() creates a perspective projection matrix
vmath.matrix4_quat() creates a matrix from a quaternion
vmath.matrix4_rotation_x() creates a matrix from rotation around x-axis
vmath.matrix4_rotation_y() creates a matrix from rotation around y-axis
vmath.matrix4_rotation_z() creates a matrix from rotation around z-axis
vmath.matrix4_scale() creates a new matrix4 from scale vector
vmath.matrix4_scale() creates a new matrix4 from uniform scale
vmath.matrix4_scale() creates a new matrix4 from three scale components
vmath.matrix4_translation() creates a translation matrix from a position vector
vmath.mul_per_elem() performs an element wise multiplication of two vectors
vmath.normalize() normalizes a vector
vmath.ortho_inv() calculates the inverse of an ortho-normal matrix.
vmath.project() projects a vector onto another vector
vmath.quat() creates a new identity quaternion
vmath.quat() creates a new quaternion from another existing quaternion
vmath.quat() creates a new quaternion from its coordinates
vmath.quat_axis_angle() creates a quaternion to rotate around a unit vector
vmath.quat_basis() creates a quaternion from three base unit vectors
vmath.quat_from_to() creates a quaternion to rotate between two unit vectors
vmath.quat_matrix4() creates a new quaternion from matrix4
vmath.quat_rotation_x() creates a quaternion from rotation around x-axis
vmath.quat_rotation_y() creates a quaternion from rotation around y-axis
vmath.quat_rotation_z() creates a quaternion from rotation around z-axis
vmath.quat_to_euler() converts a quaternion into euler angles
vmath.rotate() rotates a vector by a quaternion
vmath.slerp() slerps between two vectors
vmath.slerp() slerps between two quaternions
vmath.vector() create a new vector from a table of values
vmath.vector3() creates a new zero vector
vmath.vector3() creates a new vector from scalar value
vmath.vector3() creates a new vector from another existing vector
vmath.vector3() creates a new vector from its coordinates
vmath.vector4() creates a new zero vector
vmath.vector4() creates a new vector from scalar value
vmath.vector4() creates a new vector from another existing vector
vmath.vector4() creates a new vector from its coordinates

Functions

vmath.clamp()

vmath.clamp(value,min,max)

Clamp input value to be in range of [min, max]. In case if input value has vector3|vector4 type return new vector3|vector4 with clamped value at every vector's element. Min/max arguments can be vector3|vector4. In that case clamp excuted per every vector's element

PARAMETERS

value number
vector3
vector4
Input value or vector of values
min number
vector3
vector4
Min value(s) border
max number
vector3
vector4
Max value(s) border

RETURNS

clamped_value number
vector3
vector4
Clamped value or vector

EXAMPLES

local value1 = 56
print(vmath.clamp(value1, 89, 134)) -> 89
local v2 = vmath.vector3(190, 190, -10)
print(vmath.clamp(v2, -50, 150)) -> vmath.vector3(150, 150, -10)
local v3 = vmath.vector4(30, -30, 45, 1)
print(vmath.clamp(v3, 0, 20)) -> vmath.vector4(20, 0, 20, 1)

local min_v = vmath.vector4(0, -10, -10, 1)
print(vmath.clamp(v3, min_v, 20)) -> vmath.vector4(20, -10, 20, 1)

vmath.conj()

vmath.conj(q1)

Calculates the conjugate of a quaternion. The result is a quaternion with the same magnitudes but with the sign of the imaginary (vector) parts changed: q* = [w, -v]

PARAMETERS

q1 quaternion
quaternion of which to calculate the conjugate

RETURNS

q quaternion
the conjugate

EXAMPLES

local quat = vmath.quat(1, 2, 3, 4)
print(vmath.conj(quat)) --> vmath.quat(-1, -2, -3, 4)

vmath.cross()

vmath.cross(v1,v2)

Given two linearly independent vectors P and Q, the cross product, P × Q, is a vector that is perpendicular to both P and Q and therefore normal to the plane containing them. If the two vectors have the same direction (or have the exact opposite direction from one another, i.e. are not linearly independent) or if either one has zero length, then their cross product is zero.

PARAMETERS

v1 vector3
first vector
v2 vector3
second vector

RETURNS

v vector3
a new vector representing the cross product

EXAMPLES

local vec1 = vmath.vector3(1, 0, 0)
local vec2 = vmath.vector3(0, 1, 0)
print(vmath.cross(vec1, vec2)) --> vmath.vector3(0, 0, 1)
local vec3 = vmath.vector3(-1, 0, 0)
print(vmath.cross(vec1, vec3)) --> vmath.vector3(0, -0, 0)

vmath.dot()

vmath.dot(v1,v2)

The returned value is a scalar defined as: P ⋅ Q = |P| |Q| cos θ where θ is the angle between the vectors P and Q.

  • If the dot product is positive then the angle between the vectors is below 90 degrees.
  • If the dot product is zero the vectors are perpendicular (at right-angles to each other).
  • If the dot product is negative then the angle between the vectors is more than 90 degrees.

PARAMETERS

v1 vector3
vector4
first vector
v2 vector3
vector4
second vector

RETURNS

n number
dot product

EXAMPLES

if vmath.dot(vector1, vector2) == 0 then
    -- The two vectors are perpendicular (at right-angles to each other)
    ...
end

vmath.euler_to_quat()

vmath.euler_to_quat(x,y,z)

Converts euler angles (x, y, z) in degrees into a quaternion The error is guaranteed to be less than 0.001. If the first argument is vector3, its values are used as x, y, z angles.

PARAMETERS

x number
vector3
rotation around x-axis in degrees or vector3 with euler angles in degrees
y number
rotation around y-axis in degrees
z number
rotation around z-axis in degrees

RETURNS

q quaternion
quaternion describing an equivalent rotation (231 (YZX) rotation sequence)

EXAMPLES

local q = vmath.euler_to_quat(0, 45, 90)
print(q) --> vmath.quat(0.27059805393219, 0.27059805393219, 0.65328145027161, 0.65328145027161)

local v = vmath.vector3(0, 0, 90)
print(vmath.euler_to_quat(v)) --> vmath.quat(0, 0, 0.70710676908493, 0.70710676908493)

vmath.inv()

vmath.inv(m1)

The resulting matrix is the inverse of the supplied matrix. For ortho-normal matrices, e.g. regular object transformation, use vmath.ortho_inv() instead. The specialized inverse for ortho-normalized matrices is much faster than the general inverse.

PARAMETERS

m1 matrix4
matrix to invert

RETURNS

m matrix4
inverse of the supplied matrix

EXAMPLES

local mat1 = vmath.matrix4_rotation_z(3.141592653)
local mat2 = vmath.inv(mat1)
-- M * inv(M) = identity matrix
print(mat1 * mat2) --> vmath.matrix4(1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1)

vmath.length()

vmath.length(v)

Returns the length of the supplied vector or quaternion. If you are comparing the lengths of vectors or quaternions, you should compare the length squared instead as it is slightly more efficient to calculate (it eliminates a square root calculation).

PARAMETERS

v vector3
vector4
quat
value of which to calculate the length

RETURNS

n number
length

EXAMPLES

if vmath.length(self.velocity) < max_velocity then
    -- The speed (velocity vector) is below max.

    -- TODO: max_velocity can be expressed as squared
    -- so we can compare with length_sqr() instead.
    ...
end

vmath.length_sqr()

vmath.length_sqr(v)

Returns the squared length of the supplied vector or quaternion.

PARAMETERS

v vector3
vector4
quat
value of which to calculate the squared length

RETURNS

n number
squared length

EXAMPLES

if vmath.length_sqr(vector1) < vmath.length_sqr(vector2) then
    -- Vector 1 has less magnitude than vector 2
    ...
end

vmath.lerp()

vmath.lerp(t,v1,v2)

Linearly interpolate between two vectors. The function treats the vectors as positions and interpolates between the positions in a straight line. Lerp is useful to describe transitions from one place to another over time. The function does not clamp t between 0 and 1.

PARAMETERS

t number
interpolation parameter, 0-1
v1 vector3
vector4
vector to lerp from
v2 vector3
vector4
vector to lerp to

RETURNS

v vector3
vector4
the lerped vector

EXAMPLES

function init(self)
    self.t = 0
end

function update(self, dt)
    self.t = self.t + dt
    if self.t <= 1 then
        local startpos = vmath.vector3(0, 600, 0)
        local endpos = vmath.vector3(600, 0, 0)
        local pos = vmath.lerp(self.t, startpos, endpos)
        go.set_position(pos, "go")
    end
end

vmath.lerp()

vmath.lerp(t,q1,q2)

Linearly interpolate between two quaternions. Linear interpolation of rotations are only useful for small rotations. For interpolations of arbitrary rotations, vmath.slerp yields much better results. The function does not clamp t between 0 and 1.

PARAMETERS

t number
interpolation parameter, 0-1
q1 quaternion
quaternion to lerp from
q2 quaternion
quaternion to lerp to

RETURNS

q quaternion
the lerped quaternion

EXAMPLES

function init(self)
    self.t = 0
end

function update(self, dt)
    self.t = self.t + dt
    if self.t <= 1 then
        local startrot = vmath.quat_rotation_z(0)
        local endrot = vmath.quat_rotation_z(3.141592653)
        local rot = vmath.lerp(self.t, startrot, endrot)
        go.set_rotation(rot, "go")
    end
end

vmath.lerp()

vmath.lerp(t,n1,n2)

Linearly interpolate between two values. Lerp is useful to describe transitions from one value to another over time. The function does not clamp t between 0 and 1.

PARAMETERS

t number
interpolation parameter, 0-1
n1 number
number to lerp from
n2 number
number to lerp to

RETURNS

n number
the lerped number

EXAMPLES

function init(self)
    self.t = 0
end

function update(self, dt)
    self.t = self.t + dt
    if self.t <= 1 then
        local startx = 0
        local endx = 600
        local x = vmath.lerp(self.t, startx, endx)
        go.set_position(vmath.vector3(x, 100, 0), "go")
    end
end

vmath.matrix4()

vmath.matrix4()

The resulting identity matrix describes a transform with no translation or rotation.

PARAMETERS

None

RETURNS

m matrix4
identity matrix

EXAMPLES

local mat = vmath.matrix4()
print(mat) --> vmath.matrix4(1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1)
-- get column 0:
print(mat.c0) --> vmath.vector4(1, 0, 0, 0)
-- get the value in row 3 and column 2:
print(mat.m32) --> 0

vmath.matrix4()

vmath.matrix4(m1)

Creates a new matrix with all components set to the corresponding values from the supplied matrix. I.e. the function creates a copy of the given matrix.

PARAMETERS

m1 matrix4
existing matrix

RETURNS

m matrix4
matrix which is a copy of the specified matrix

EXAMPLES

local mat1 = vmath.matrix4_rotation_x(3.141592653)
local mat2 = vmath.matrix4(mat1)
if mat1 == mat2 then
    -- yes, they are equal
    print(mat2) --> vmath.matrix4(1, 0, 0, 0, 0, -1, 8.7422776573476e-08, 0, 0, -8.7422776573476e-08, -1, 0, 0, 0, 0, 1)
end

vmath.matrix4_axis_angle()

vmath.matrix4_axis_angle(v,angle)

The resulting matrix describes a rotation around the axis by the specified angle.

PARAMETERS

v vector3
axis
angle number
angle in radians

RETURNS

m matrix4
matrix represented by axis and angle

EXAMPLES

local vec = vmath.vector4(1, 1, 0, 0)
local axis = vmath.vector3(0, 0, 1) -- z-axis
local mat = vmath.matrix4_axis_angle(axis, 3.141592653)
print(mat * vec) --> vmath.vector4(-0.99999994039536, -1.0000001192093, 0, 0)

vmath.matrix4_compose()

vmath.matrix4_compose(translation,rotation,scale)

Creates a new matrix constructed from separate translation vector, roation quaternion and scale vector

PARAMETERS

translation vector3
vecto4
translation
rotation quaternion
rotation
scale vector3
scale

RETURNS

matrix matrix4
new matrix4

EXAMPLES

local translation = vmath.vector3(103, -95, 14)
local quat = vmath.quat(1, 2, 3, 4)
local scale = vmath.vector3(1, 0.5, 0.5)
local result = vmath.matrix4_compose(translation, quat, scale)
print(result) --> vmath.matrix4(-25, -10, 11, 103, 28, -9.5, 2, -95, -10, 10, -4.5, 14, 0, 0, 0, 1)

vmath.matrix4_frustum()

vmath.matrix4_frustum(left,right,bottom,top,near,far)

Constructs a frustum matrix from the given values. The left, right, top and bottom coordinates of the view cone are expressed as distances from the center of the near clipping plane. The near and far coordinates are expressed as distances from the tip of the view frustum cone.

PARAMETERS

left number
coordinate for left clipping plane
right number
coordinate for right clipping plane
bottom number
coordinate for bottom clipping plane
top number
coordinate for top clipping plane
near number
coordinate for near clipping plane
far number
coordinate for far clipping plane

RETURNS

m matrix4
matrix representing the frustum

EXAMPLES

-- Construct a projection frustum with a vertical and horizontal
-- FOV of 45 degrees. Useful for rendering a square view.
local proj = vmath.matrix4_frustum(-1, 1, -1, 1, 1, 1000)
render.set_projection(proj)

vmath.matrix4_look_at()

vmath.matrix4_look_at(eye,look_at,up)

The resulting matrix is created from the supplied look-at parameters. This is useful for constructing a view matrix for a camera or rendering in general.

PARAMETERS

eye vector3
eye position
look_at vector3
look-at position
up vector3
up vector

RETURNS

m matrix4
look-at matrix

EXAMPLES

-- Set up a perspective camera at z 100 with 45 degrees (pi/2) FOV
-- Aspect ratio 4:3
local eye = vmath.vector3(0, 0, 100)
local look_at = vmath.vector3(0, 0, 0)
local up = vmath.vector3(0, 1, 0)
local view = vmath.matrix4_look_at(eye, look_at, up)
render.set_view(view)
local proj = vmath.matrix4_perspective(3.141592/2, 4/3, 1, 1000)
render.set_projection(proj)

vmath.matrix4_orthographic()

vmath.matrix4_orthographic(left,right,bottom,top,near,far)

Creates an orthographic projection matrix. This is useful to construct a projection matrix for a camera or rendering in general.

PARAMETERS

left number
coordinate for left clipping plane
right number
coordinate for right clipping plane
bottom number
coordinate for bottom clipping plane
top number
coordinate for top clipping plane
near number
coordinate for near clipping plane
far number
coordinate for far clipping plane

RETURNS

m matrix4
orthographic projection matrix

EXAMPLES

-- Set up an orthographic projection based on the width and height
-- of the game window.
local w = render.get_width()
local h = render.get_height()
local proj = vmath.matrix4_orthographic(- w / 2, w / 2, -h / 2, h / 2, -1000, 1000)
render.set_projection(proj)

vmath.matrix4_perspective()

vmath.matrix4_perspective(fov,aspect,near,far)

Creates a perspective projection matrix. This is useful to construct a projection matrix for a camera or rendering in general.

PARAMETERS

fov number
angle of the full vertical field of view in radians
aspect number
aspect ratio
near number
coordinate for near clipping plane
far number
coordinate for far clipping plane

RETURNS

m matrix4
perspective projection matrix

EXAMPLES

-- Set up a perspective camera at z 100 with 45 degrees (pi/2) FOV
-- Aspect ratio 4:3
local eye = vmath.vector3(0, 0, 100)
local look_at = vmath.vector3(0, 0, 0)
local up = vmath.vector3(0, 1, 0)
local view = vmath.matrix4_look_at(eye, look_at, up)
render.set_view(view)
local proj = vmath.matrix4_perspective(3.141592/2, 4/3, 1, 1000)
render.set_projection(proj)

vmath.matrix4_quat()

vmath.matrix4_quat(q)

The resulting matrix describes the same rotation as the quaternion, but does not have any translation (also like the quaternion).

PARAMETERS

q quaternion
quaternion to create matrix from

RETURNS

m matrix4
matrix represented by quaternion

EXAMPLES

local vec = vmath.vector4(1, 1, 0, 0)
local quat = vmath.quat_rotation_z(3.141592653)
local mat = vmath.matrix4_quat(quat)
print(mat * vec) --> vmath.matrix4_frustum(-1, 1, -1, 1, 1, 1000)

vmath.matrix4_rotation_x()

vmath.matrix4_rotation_x(angle)

The resulting matrix describes a rotation around the x-axis by the specified angle.

PARAMETERS

angle number
angle in radians around x-axis

RETURNS

m matrix4
matrix from rotation around x-axis

EXAMPLES

local vec = vmath.vector4(1, 1, 0, 0)
local mat = vmath.matrix4_rotation_x(3.141592653)
print(mat * vec) --> vmath.vector4(1, -1, -8.7422776573476e-08, 0)

vmath.matrix4_rotation_y()

vmath.matrix4_rotation_y(angle)

The resulting matrix describes a rotation around the y-axis by the specified angle.

PARAMETERS

angle number
angle in radians around y-axis

RETURNS

m matrix4
matrix from rotation around y-axis

EXAMPLES

local vec = vmath.vector4(1, 1, 0, 0)
local mat = vmath.matrix4_rotation_y(3.141592653)
print(mat * vec) --> vmath.vector4(-1, 1, 8.7422776573476e-08, 0)

vmath.matrix4_rotation_z()

vmath.matrix4_rotation_z(angle)

The resulting matrix describes a rotation around the z-axis by the specified angle.

PARAMETERS

angle number
angle in radians around z-axis

RETURNS

m matrix4
matrix from rotation around z-axis

EXAMPLES

local vec = vmath.vector4(1, 1, 0, 0)
local mat = vmath.matrix4_rotation_z(3.141592653)
print(mat * vec) --> vmath.vector4(-0.99999994039536, -1.0000001192093, 0, 0)

vmath.matrix4_scale()

vmath.matrix4_scale(scale)

Creates a new matrix constructed from scale vector

PARAMETERS

scale vector3
scale

RETURNS

matrix matrix4
new matrix4

EXAMPLES

local scale = vmath.vector3(1, 0.5, 0.5)
local result = vmath.matrix4_scale(scale)
print(result) --> vmath.matrix4(1, 0, 0, 0, 0, 0.5, 0, 0, 0, 0, 0.5, 0, 0, 0, 0, 1)

vmath.matrix4_scale()

vmath.matrix4_scale(scale)

creates a new matrix4 from uniform scale

PARAMETERS

scale number
scale

RETURNS

matrix matrix4
new matrix4

EXAMPLES

local result = vmath.matrix4_scale(0.5)
print(result) --> vmath.matrix4(0.5, 0, 0, 0, 0, 0.5, 0, 0, 0, 0, 0.5, 0, 0, 0, 0, 1)

vmath.matrix4_scale()

vmath.matrix4_scale(scale_x,scale_y,scale_z)

Creates a new matrix4 from three scale components

PARAMETERS

scale_x number
scale along X axis
scale_y number
sclae along Y axis
scale_z number
scale along Z asis

RETURNS

matrix matrix4
new matrix4

EXAMPLES

local result = vmath.matrix4_scale(1, 0.5, 0.5)
print(result) --> vmath.matrix4(1, 0, 0, 0, 0, 0.5, 0, 0, 0, 0, 0.5, 0, 0, 0, 0, 1)

vmath.matrix4_translation()

vmath.matrix4_translation(position)

The resulting matrix describes a translation of a point in euclidean space.

PARAMETERS

position vector3
vector4
position vector to create matrix from

RETURNS

m matrix4
matrix from the supplied position vector

EXAMPLES

-- Set camera view from custom view and translation matrices
local mat_trans = vmath.matrix4_translation(vmath.vector3(0, 10, 100))
local mat_view  = vmath.matrix4_rotation_y(-3.141592/4)
render.set_view(mat_view * mat_trans)

vmath.mul_per_elem()

vmath.mul_per_elem(v1,v2)

Performs an element wise multiplication between two vectors of the same type The returned value is a vector defined as (e.g. for a vector3): v = vmath.mul_per_elem(a, b) = vmath.vector3(a.x * b.x, a.y * b.y, a.z * b.z)

PARAMETERS

v1 vector3
vector4
first vector
v2 vector3
vector4
second vector

RETURNS

v vector3
vector4
multiplied vector

EXAMPLES

local blend_color = vmath.mul_per_elem(color1, color2)

vmath.normalize()

vmath.normalize(v1)

Normalizes a vector, i.e. returns a new vector with the same direction as the input vector, but with length 1. The length of the vector must be above 0, otherwise a division-by-zero will occur.

PARAMETERS

v1 vector3
vector4
quat
vector to normalize

RETURNS

v vector3
vector4
quat
new normalized vector

EXAMPLES

local vec = vmath.vector3(1, 2, 3)
local norm_vec = vmath.normalize(vec)
print(norm_vec) --> vmath.vector3(0.26726123690605, 0.5345224738121, 0.80178368091583)
print(vmath.length(norm_vec)) --> 0.99999994039536

vmath.ortho_inv()

vmath.ortho_inv(m1)

The resulting matrix is the inverse of the supplied matrix. The supplied matrix has to be an ortho-normal matrix, e.g. describe a regular object transformation. For matrices that are not ortho-normal use the general inverse vmath.inv() instead.

PARAMETERS

m1 matrix4
ortho-normalized matrix to invert

RETURNS

m matrix4
inverse of the supplied matrix

EXAMPLES

local mat1 = vmath.matrix4_rotation_z(3.141592653)
local mat2 = vmath.ortho_inv(mat1)
-- M * inv(M) = identity matrix
print(mat1 * mat2) --> vmath.matrix4(1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1)

vmath.project()

vmath.project(v1,v2)

Calculates the extent the projection of the first vector onto the second. The returned value is a scalar p defined as: p = |P| cos θ / |Q| where θ is the angle between the vectors P and Q.

PARAMETERS

v1 vector3
vector to be projected on the second
v2 vector3
vector onto which the first will be projected, must not have zero length

RETURNS

n number
the projected extent of the first vector onto the second

EXAMPLES

local v1 = vmath.vector3(1, 1, 0)
local v2 = vmath.vector3(2, 0, 0)
print(vmath.project(v1, v2)) --> 0.5

vmath.quat()

vmath.quat()

Creates a new identity quaternion. The identity quaternion is equal to: vmath.quat(0, 0, 0, 1)

PARAMETERS

None

RETURNS

q quaternion
new identity quaternion

EXAMPLES

local quat = vmath.quat()
print(quat) --> vmath.quat(0, 0, 0, 1)
print(quat.w) --> 1

vmath.quat()

vmath.quat(q1)

Creates a new quaternion with all components set to the corresponding values from the supplied quaternion. I.e. This function creates a copy of the given quaternion.

PARAMETERS

q1 quaternion
existing quaternion

RETURNS

q quaternion
new quaternion

EXAMPLES

local quat1 = vmath.quat(1, 2, 3, 4)
local quat2 = vmath.quat(quat1)
if quat1 == quat2 then
    -- yes, they are equal
    print(quat2) --> vmath.quat(1, 2, 3, 4)
end

vmath.quat()

vmath.quat(x,y,z,w)

Creates a new quaternion with the components set according to the supplied parameter values.

PARAMETERS

x number
x coordinate
y number
y coordinate
z number
z coordinate
w number
w coordinate

RETURNS

q quaternion
new quaternion

EXAMPLES

local quat = vmath.quat(1, 2, 3, 4)
print(quat) --> vmath.quat(1, 2, 3, 4)

vmath.quat_axis_angle()

vmath.quat_axis_angle(v,angle)

The resulting quaternion describes a rotation of angle radians around the axis described by the unit vector v.

PARAMETERS

v vector3
axis
angle number
angle

RETURNS

q quaternion
quaternion representing the axis-angle rotation

EXAMPLES

local axis = vmath.vector3(1, 0, 0)
local rot = vmath.quat_axis_angle(axis, 3.141592653)
local vec = vmath.vector3(1, 1, 0)
print(vmath.rotate(rot, vec)) --> vmath.vector3(1, -1, -8.7422776573476e-08)

vmath.quat_basis()

vmath.quat_basis(x,y,z)

The resulting quaternion describes the rotation from the identity quaternion (no rotation) to the coordinate system as described by the given x, y and z base unit vectors.

PARAMETERS

x vector3
x base vector
y vector3
y base vector
z vector3
z base vector

RETURNS

q quaternion
quaternion representing the rotation of the specified base vectors

EXAMPLES

-- Axis rotated 90 degrees around z.
local rot_x = vmath.vector3(0, -1, 0)
local rot_y = vmath.vector3(1, 0, 0)
local z = vmath.vector3(0, 0, 1)
local rot1 = vmath.quat_basis(rot_x, rot_y, z)
local rot2 = vmath.quat_from_to(vmath.vector3(0, 1, 0), vmath.vector3(1, 0, 0))
if rot1 == rot2 then
    -- These quaternions are equal!
    print(rot2) --> vmath.quat(0, 0, -0.70710676908493, 0.70710676908493)
end

vmath.quat_from_to()

vmath.quat_from_to(v1,v2)

The resulting quaternion describes the rotation that, if applied to the first vector, would rotate the first vector to the second. The two vectors must be unit vectors (of length 1). The result is undefined if the two vectors point in opposite directions

PARAMETERS

v1 vector3
first unit vector, before rotation
v2 vector3
second unit vector, after rotation

RETURNS

q quaternion
quaternion representing the rotation from first to second vector

EXAMPLES

local v1 = vmath.vector3(1, 0, 0)
local v2 = vmath.vector3(0, 1, 0)
local rot = vmath.quat_from_to(v1, v2)
print(vmath.rotate(rot, v1)) --> vmath.vector3(0, 0.99999994039536, 0)

vmath.quat_matrix4()

vmath.quat_matrix4(matrix)

Creates a new quaternion with the components set according to the supplied parameter values.

PARAMETERS

matrix matrix4
source matrix4

RETURNS

q quaternion
new quaternion

vmath.quat_rotation_x()

vmath.quat_rotation_x(angle)

The resulting quaternion describes a rotation of angle radians around the x-axis.

PARAMETERS

angle number
angle in radians around x-axis

RETURNS

q quaternion
quaternion representing the rotation around the x-axis

EXAMPLES

local rot = vmath.quat_rotation_x(3.141592653)
local vec = vmath.vector3(1, 1, 0)
print(vmath.rotate(rot, vec)) --> vmath.vector3(1, -1, -8.7422776573476e-08)

vmath.quat_rotation_y()

vmath.quat_rotation_y(angle)

The resulting quaternion describes a rotation of angle radians around the y-axis.

PARAMETERS

angle number
angle in radians around y-axis

RETURNS

q quaternion
quaternion representing the rotation around the y-axis

EXAMPLES

local rot = vmath.quat_rotation_y(3.141592653)
local vec = vmath.vector3(1, 1, 0)
print(vmath.rotate(rot, vec)) --> vmath.vector3(-1, 1, 8.7422776573476e-08)

vmath.quat_rotation_z()

vmath.quat_rotation_z(angle)

The resulting quaternion describes a rotation of angle radians around the z-axis.

PARAMETERS

angle number
angle in radians around z-axis

RETURNS

q quaternion
quaternion representing the rotation around the z-axis

EXAMPLES

local rot = vmath.quat_rotation_z(3.141592653)
local vec = vmath.vector3(1, 1, 0)
print(vmath.rotate(rot, vec)) --> vmath.vector3(-0.99999988079071, -1, 0)

vmath.quat_to_euler()

vmath.quat_to_euler(q)

Converts a quaternion into euler angles (r0, r1, r2), based on YZX rotation order. To handle gimbal lock (singularity at r1 ~ +/- 90 degrees), the cut off is at r0 = +/- 88.85 degrees, which snaps to +/- 90. The provided quaternion is expected to be normalized. The error is guaranteed to be less than +/- 0.02 degrees

PARAMETERS

q quaternion
source quaternion

RETURNS

x number
euler angle x in degrees
y number
euler angle y in degrees
z number
euler angle z in degrees

EXAMPLES

local q = vmath.quat_rotation_z(math.rad(90))
print(vmath.quat_to_euler(q)) --> 0 0 90

local q2 = vmath.quat_rotation_y(math.rad(45)) * vmath.quat_rotation_z(math.rad(90))
local v = vmath.vector3(vmath.quat_to_euler(q2))
print(v) --> vmath.vector3(0, 45, 90)

vmath.rotate()

vmath.rotate(q,v1)

Returns a new vector from the supplied vector that is rotated by the rotation described by the supplied quaternion.

PARAMETERS

q quaternion
quaternion
v1 vector3
vector to rotate

RETURNS

v vector3
the rotated vector

EXAMPLES

local vec = vmath.vector3(1, 1, 0)
local rot = vmath.quat_rotation_z(3.141592563)
print(vmath.rotate(rot, vec)) --> vmath.vector3(-1.0000002384186, -0.99999988079071, 0)

vmath.slerp()

vmath.slerp(t,v1,v2)

Spherically interpolates between two vectors. The difference to lerp is that slerp treats the vectors as directions instead of positions in space. The direction of the returned vector is interpolated by the angle and the magnitude is interpolated between the magnitudes of the from and to vectors. Slerp is computationally more expensive than lerp. The function does not clamp t between 0 and 1.

PARAMETERS

t number
interpolation parameter, 0-1
v1 vector3
vector4
vector to slerp from
v2 vector3
vector4
vector to slerp to

RETURNS

v vector3
vector4
the slerped vector

EXAMPLES

function init(self)
    self.t = 0
end

function update(self, dt)
    self.t = self.t + dt
    if self.t <= 1 then
        local startpos = vmath.vector3(0, 600, 0)
        local endpos = vmath.vector3(600, 0, 0)
        local pos = vmath.slerp(self.t, startpos, endpos)
        go.set_position(pos, "go")
    end
end

vmath.slerp()

vmath.slerp(t,q1,q2)

Slerp travels the torque-minimal path maintaining constant velocity, which means it travels along the straightest path along the rounded surface of a sphere. Slerp is useful for interpolation of rotations. Slerp travels the torque-minimal path, which means it travels along the straightest path the rounded surface of a sphere. The function does not clamp t between 0 and 1.

PARAMETERS

t number
interpolation parameter, 0-1
q1 quaternion
quaternion to slerp from
q2 quaternion
quaternion to slerp to

RETURNS

q quaternion
the slerped quaternion

EXAMPLES

function init(self)
    self.t = 0
end

function update(self, dt)
    self.t = self.t + dt
    if self.t <= 1 then
        local startrot = vmath.quat_rotation_z(0)
        local endrot = vmath.quat_rotation_z(3.141592653)
        local rot = vmath.slerp(self.t, startrot, endrot)
        go.set_rotation(rot, "go")
    end
end

vmath.vector()

vmath.vector(t)

Creates a vector of arbitrary size. The vector is initialized with numeric values from a table. The table values are converted to floating point values. If a value cannot be converted, a 0 is stored in that value position in the vector.

PARAMETERS

t table
table of numbers

RETURNS

v vector
new vector

EXAMPLES

How to create a vector with custom data to be used for animation easing:
local values = { 0, 0.5, 0 }
local vec = vmath.vector(values)
print(vec) --> vmath.vector (size: 3)
print(vec[2]) --> 0.5

vmath.vector3()

vmath.vector3()

Creates a new zero vector with all components set to 0.

PARAMETERS

None

RETURNS

v vector3
new zero vector

EXAMPLES

local vec = vmath.vector3()
pprint(vec) --> vmath.vector3(0, 0, 0)
print(vec.x) --> 0

vmath.vector3()

vmath.vector3(n)

Creates a new vector with all components set to the supplied scalar value.

PARAMETERS

n number
scalar value to splat

RETURNS

v vector3
new vector

EXAMPLES

local vec = vmath.vector3(1.0)
print(vec) --> vmath.vector3(1, 1, 1)
print(vec.x) --> 1

vmath.vector3()

vmath.vector3(v1)

Creates a new vector with all components set to the corresponding values from the supplied vector. I.e. This function creates a copy of the given vector.

PARAMETERS

v1 vector3
existing vector

RETURNS

v vector3
new vector

EXAMPLES

local vec1 = vmath.vector3(1.0)
local vec2 = vmath.vector3(vec1)
if vec1 == vec2 then
    -- yes, they are equal
    print(vec2) --> vmath.vector3(1, 1, 1)
end

vmath.vector3()

vmath.vector3(x,y,z)

Creates a new vector with the components set to the supplied values.

PARAMETERS

x number
x coordinate
y number
y coordinate
z number
z coordinate

RETURNS

v vector3
new vector

EXAMPLES

local vec = vmath.vector3(1.0, 2.0, 3.0)
print(vec) --> vmath.vector3(1, 2, 3)
print(-vec) --> vmath.vector3(-1, -2, -3)
print(vec * 2) --> vmath.vector3(2, 4, 6)
print(vec + vmath.vector3(2.0)) --> vmath.vector3(3, 4, 5)
print(vec - vmath.vector3(2.0)) --> vmath.vector3(-1, 0, 1)

vmath.vector4()

vmath.vector4()

Creates a new zero vector with all components set to 0.

PARAMETERS

None

RETURNS

v vector4
new zero vector

EXAMPLES

local vec = vmath.vector4()
print(vec) --> vmath.vector4(0, 0, 0, 0)
print(vec.w) --> 0

vmath.vector4()

vmath.vector4(n)

Creates a new vector with all components set to the supplied scalar value.

PARAMETERS

n number
scalar value to splat

RETURNS

v vector4
new vector

EXAMPLES

local vec = vmath.vector4(1.0)
print(vec) --> vmath.vector4(1, 1, 1, 1)
print(vec.w) --> 1

vmath.vector4()

vmath.vector4(v1)

Creates a new vector with all components set to the corresponding values from the supplied vector. I.e. This function creates a copy of the given vector.

PARAMETERS

v1 vector4
existing vector

RETURNS

v vector4
new vector

EXAMPLES

local vect1 = vmath.vector4(1.0)
local vect2 = vmath.vector4(vec1)
if vec1 == vec2 then
    -- yes, they are equal
    print(vec2) --> vmath.vector4(1, 1, 1, 1)
end

vmath.vector4()

vmath.vector4(x,y,z,w)

Creates a new vector with the components set to the supplied values.

PARAMETERS

x number
x coordinate
y number
y coordinate
z number
z coordinate
w number
w coordinate

RETURNS

v vector4
new vector

EXAMPLES

local vec = vmath.vector4(1.0, 2.0, 3.0, 4.0)
print(vec) --> vmath.vector4(1, 2, 3, 4)
print(-vec) --> vmath.vector4(-1, -2, -3, -4)
print(vec * 2) --> vmath.vector4(2, 4, 6, 8)
print(vec + vmath.vector4(2.0)) --> vmath.vector4(3, 4, 5, 6)
print(vec - vmath.vector4(2.0)) --> vmath.vector4(-1, 0, 1, 2)