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)

Vector Geometry

• pymath.cross — cross product of two 3-vectors
• pymath.length — length of a vector, or the distance between two points
• pymath.normalize — scale a vector to unit length

Basic Linear Algebra

• pymath.dot
• pymath.transpose
• pymath.determinant
• pymath.identity
• pymath.trace
• pymath.inverse

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
• pymath.normalize_inplace

Linear systems

• pymath.solve_linear

Overdetermined systems

• pymath.least_squares
• pymath.least_squares_box_constrained

Root finding

Polynomial coefficients are given in descending power order, the order in which the polynomial is written down: {1, -3, 2} is x² - 3x + 2.

• pymath.solve_quadratic — the two real roots of a x² + b x + c, as separate return values
• pymath.solve_polynomial — the real roots of a polynomial of arbitrary degree, as an array

Both handle degenerate input (vanishing leading coefficients) gracefully and take an optional tolerance controlling whether a barely-touching or barely-complex root pair still counts as real.

Rotations

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 as 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.

• 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

and Quaternion 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

Bezier curves are a versatile tool to represent spatial splines and for interpolation:

• 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

Interpolation and Clamping

• pymath.interpolate_linear — linear interpolation v + (w - v) * t between two numbers or vectors
• pymath.clamp — clamp a number or vector into an interval (default [0, 1])
• pymath.smooth_step — smooth 0-to-1 ramp over an interval (numbers only)

See also:

Math functions