pymath

The pymath library contains mathematical helper functions

Matrices and Vectors

Vectors are represented as arrays (Lua tables) of numbers, e.g. {1, 2, 3}. The pymath functions do not make a difference between row and column vectors.

A matrix is represented as an array of row-vectors, e.g.

local mat = {
    {1, 2}, 
    {3, 4}
}

with its layout as printed.

Even higher tensors may be formed as arrays of lower tensors (with the lower indices to the right)

Basic Vector and Matrix Functions

• pymath.dot
• pymath.transpose
• pymath.inverse
• pymath.solve_linear
• pymath.least_squares
• pymath.least_squares_box_constrained
• pymath.determinant
• pymath.identity
• pymath.trace

Inplace variants

For matrices or arrays-of-vectors, the Lua representation required a large number of tables. For enhanced performance, *_inplace variants are provided where applicable, that write the result back into the first parameter.

• pymath.dot_inplace
• pymath.transpose_inplace

Sparse Matrices

Some functions are specifically designed and documented to take advantage of sparse matrices. Sparse matrices are represented in a similar way, but have to declare their size up-font. The entries are defined (sparsely) for all rows, taking advantage of Lua's table implementation:

local sparse_mat = {
    size={1000,1000},
    {[17]=1, [202]=2, [998]=2}, 
    {[5]=3, [368]=4},
    ...
}

Rotation matrices

pymath.rotation_matrix is a convenience constructor for rotation matrices, with the form selected by its arguments:

• pymath.rotation_matrix(axis, angle) — 3×3 matrix for a rotation about axis (a vector or an axis keyword) by angle degrees
• pymath.rotation_matrix(angle) — 2×2 matrix for a planar rotation by angle degrees

Quaternions

Unit quaternions are widely used in 3D CAD because of their tight correspondence with 3D rotation matrices. A quaternion is represented in Lua an array of four numbers {x, y, z, w}.

Functions that require a unit quaternion (e.g. pymath.matrix_from_quat) normalize their input internally, so you rarely need to normalize by hand. See the individual pages for the exact behaviour.

Conversions

• pymath.quat_from_rotation — from an axis and angle
• pymath.quat_from_matrix — from a 3×3 rotation matrix
• pymath.rotation_from_quat — to an axis and angle
• pymath.matrix_from_quat — to a 3×3 rotation matrix

Operations

• pymath.multiply_quat — compose two rotations
• pymath.invert_quat — invert a rotation
• pymath.interpolate_quat — spherical linear interpolation (SLERP)
• pymath.rotate_by_quat — rotate a 3-vector with the rotation given by a quaternion

Euler angles

A rotation can also be described by three Euler angles. pymath uses the ZXZ convention

mat = rot(z, alpha) · rot(x, beta) · rot(z, gamma)

• pymath.matrix_from_euler_angles — 3×3 rotation matrix from alpha, beta, gamma
• pymath.euler_angles_from_matrix — alpha, beta, gamma from a 3×3 rotation matrix

with all angles in degrees (like every PYTHA Lua API function)

Bézier curves

The pymath namespace evaluates Bézier curves from their control points (scalars or points of any dimension):

• pymath.eval_bezier — the curve point at a parameter t
• pymath.eval_bezier_deriv — the curve derivative (tangent) at t
• pymath.interpolate_cubic — a smooth cubic curve through a list of points, as Bézier segments

See also:

Math functions