Math

class Matrix44(**kwds)

4x4 orthonormal matrix for transformations.

This matrix class derives from list and is designed for 3D transformations and orientations. It provides methods to initialize the matrix from various properties like angles, origin, scale, etc.

small_zero

Small threshold for zero value.

Type

float

big_zero

Large threshold for zero value.

Type

float

identity

4x4 identity matrix.

Type

list

property angles

The Euler angles (Body313) in radians.

copy()

Create a copy of the matrix.

Returns

A copy of the current matrix.

Return type

Matrix44

divide(other)

Divide the current matrix by another matrix.

Parameters

other (Matrix44) – The matrix to divide by.

Returns

The result of the division.

Return type

Matrix44

getDeterminant()

Compute the determinant of the current matrix.

Returns

The determinant value.

Return type

float

getEulerAngles(degrees=False)

Retrieve the Z-X-Z Euler angles representing the matrix’s orientation.

Parameters

degrees (bool, optional) – If True, returns angles in degrees. Defaults to False.

Returns

List of three Euler angles.

Return type

list[float]

getTranslation()

Retrieve the translation part of the matrix.

Returns

The translation part of the matrix.

Return type

Point

invert()

Return the inverse of the current matrix.

Returns

Inverted matrix.

Return type

Matrix44

isIdentity()

Check if the matrix is an identity matrix.

Returns

True if the matrix is an identity matrix, False otherwise.

Return type

bool

property location

Get or set the location (translation) part of the matrix.

Returns

The translation part of the matrix.

Return type

Point

multiply(other)

Multiply the current matrix with another matrix, point, vector, or scalar.

Parameters

other (Matrix44, Point, Vector, int, float) – The object to multiply with.

Returns

The result of the multiplication.

Return type

Matrix44

multiplyPoint(x, y=None, z=None)

Multiply a point by the current matrix.

Parameters

• x (float or list[float]) – x-coordinate or a list/tuple containing x, y, and z coordinates.

• y (float, optional) – y-coordinate. Defaults to None.

• z (float, optional) – z-coordinate. Defaults to None.

Returns

Transformed point.

Return type

Point

multiplyVector(x, y=None, z=None)

Multiply a vector by the current matrix.

Parameters

• x (float or list[float]) – x-coordinate or a list/tuple containing x, y, and z coordinates.

• y (float, optional) – y-coordinate. Defaults to None.

• z (float, optional) – z-coordinate. Defaults to None.

Returns

Transformed vector.

Return type

Vector

orientFromAxes(axes, dir1, dir2=(1, 0, 0))

Align the specified axes of the matrix to the given vectors.

Parameters

• axes (str) – Specifies which axes to align. One of: ‘x’, ‘y’, ‘z’, ‘xy’, ‘xz’, ‘yx’, ‘yz’, ‘zx’, ‘zy’.

• dir1 (list[float] or Vector) – Direction for the first axis.

• dir2 (list[float] or Vector, optional) – Direction for the second axis. Defaults to [1,0,0].

Returns

Updated matrix instance.

Return type

Matrix44

orientFromEulerAngles(e1, e2=None, e3=None, degrees=False)

Update the matrix orientation using the provided Euler angles.

Parameters

• e1 (float or list[float]) – First Euler angle or a list of all three Euler angles.

• e2 (float, optional) – Second Euler angle. Defaults to None.

• e3 (float, optional) – Third Euler angle. Defaults to None.

• degrees (bool, optional) – If True, angles are in degrees. Defaults to False.

Returns

Updated matrix instance.

Return type

Matrix44

orientFromEulerParameters(e0, e1=None, e2=None, e3=None)

Update the matrix orientation using the provided Euler parameters.

Parameters

• e0 (float or list[float]) – First Euler parameter or a list of all four parameters.

• e1 (float, optional) – Second Euler parameter. Defaults to None.

• e2 (float, optional) – Third Euler parameter. Defaults to None.

• e3 (float, optional) – Fourth Euler parameter. Defaults to None.

Returns

Updated matrix instance.

Return type

Matrix44

property origin

Get or set the location (translation) part of the matrix.

Returns

The translation part of the matrix.

Return type

Point

orthogonalize()

Orthogonalize the matrix to ensure orthogonality of its axes.

This method ensures that the matrix axes are orthogonal and normal.

Returns

Orthogonalized matrix.

Return type

Matrix44

Raises

RuntimeError – If the matrix cannot be orthogonalized.

pt(x, y=None, z=None)

Multiply a point by the current matrix.

Parameters

• x (float or list[float]) – x-coordinate or a list/tuple containing x, y, and z coordinates.

• y (float, optional) – y-coordinate. Defaults to None.

• z (float, optional) – z-coordinate. Defaults to None.

Returns

Transformed point.

Return type

Point

pts(pts)

Multiply a list of points by the current matrix.

Parameters

pts (list[Point or list[float]]) – List of points or list of coordinates.

Returns

List of transformed points.

Return type

list[Point]

rotate(axis, angle, degrees=True)

Return a matrix that rotates the current matrix around the specified axis by the given angle.

Parameters

• axis (str) – Axis to rotate around (‘x’, ‘y’, or ‘z’).

• angle (float) – Angle of rotation.

• degrees (bool, optional) – If True, the angle is in degrees. Defaults to True.

Returns

Rotated matrix.

Return type

Matrix44

rotx(angle, degrees=True)

Return a matrix that rotates the current matrix around the X axis by the given angle.

Parameters

• angle (float) – Angle of rotation.

• degrees (bool, optional) – If True, the angle is in degrees. Defaults to True.

Returns

Rotated matrix.

Return type

Matrix44

roty(angle, degrees=True)

Return a matrix that rotates the current matrix around the Y axis by the given angle.

Parameters

• angle (float) – Angle of rotation.

• degrees (bool, optional) – If True, the angle is in degrees. Defaults to True.

Returns

Rotated matrix.

Return type

Matrix44

rotz(angle, degrees=True)

Return a matrix that rotates the current matrix around the Z axis by the given angle.

Parameters

• angle (float) – Angle of rotation.

• degrees (bool, optional) – If True, the angle is in degrees. Defaults to True.

Returns

Rotated matrix.

Return type

Matrix44

scale(x, y=None, z=None)

Return a matrix that scales the current matrix by the specified amount.

Parameters

• x (float) – Scale factor for x-axis or for all axes if y and z are not provided.

• y (float, optional) – Scale factor for y-axis. Defaults to None.

• z (float, optional) – Scale factor for z-axis. Defaults to None.

Returns

Scaled matrix.

Return type

Matrix44

setTranslation(x, y=None, z=None)

Set the translation part of the matrix.

Parameters

• x (float or list[float]) – Translation for the x-axis or a list of translations for all three axes.

• y (float, optional) – Translation for the y-axis. Defaults to None.

• z (float, optional) – Translation for the z-axis. Defaults to None.

Returns

Updated matrix instance.

Return type

Matrix44

translate(x=0, y=None, z=None)

Translate the matrix by the given distance along each axis.

Parameters

• x (float or list[float]) – Translation along the x-axis or a list of translations for all three axes.

• y (float, optional) – Translation along the y-axis. Defaults to None.

• z (float, optional) – Translation along the z-axis. Defaults to None.

Returns

Updated matrix instance.

Return type

Matrix44

transpose()

Return the transpose of the current matrix.

Returns

Transposed matrix.

Return type

Matrix44

update(other)

Update this matrix with another matrix.

This method is designed to update the current 4x4 matrix with values from another matrix. The input matrix can be either a 3x3 or a 4x4 matrix.

• If a 3x3 matrix is provided, only the top-left 3x3 portion of the current matrix is updated.

• If a 4x4 matrix is provided, the entire matrix is updated.

Parameters

other (list of list) – Another matrix, either 3x3 or 4x4.

Returns

Updated matrix.

Return type

Matrix44

vec(x, y=None, z=None)

Multiply a vector by the current matrix.

Parameters

• x (float or list[float]) – x-coordinate or a list/tuple containing x, y, and z coordinates.

• y (float, optional) – y-coordinate. Defaults to None.

• z (float, optional) – z-coordinate. Defaults to None.

Returns

Transformed vector.

Return type

Vector

property xaxis

Retrieve the x-axis direction vector of the matrix.

Returns

x-axis direction vector.

Return type

Vector

property yaxis

Retrieve the y-axis direction vector of the matrix.

Returns

y-axis direction vector.

Return type

Vector

property zaxis

Retrieve the z-axis direction vector of the matrix.

Returns

z-axis direction vector.

Return type

Vector

zeroSmallValues(zero=1e-10)

Return a copy of the current matrix with values less than a threshold set to 0.

Parameters

zero (float, optional) – The threshold value below which matrix elements are set to 0. Defaults to 1e-10.

Returns

Matrix with small values zeroed out.

Return type

Matrix44

class Point(**kwds)

3D point representing a location in space.

This class derives from Vector and represents a 3D point. It provides additional methods for operations like calculating midpoints, distances, and points along lines.

x

X coordinate of the point.

Type

float or ExprValue

y

Y coordinate of the point.

Type

float or ExprValue

z

Z coordinate of the point.

Type

float or ExprValue

along(towards, distance)

Find a point along the line from the current point towards another point.

Parameters

• towards (Point or tuple) – Point towards which to move.

• distance (float) – Distance to move along the line.

Returns

Resultant point after moving the specified distance.

Return type

Point

distance(x, y=None, z=None)

Calculate the distance to another point.

Parameters

• x (float or ExprValue or tuple) – X coordinate or tuple containing all coordinates.

• y (float or ExprValue, optional) – Y coordinate. Defaults to None.

• z (float or ExprValue, optional) – Z coordinate. Defaults to None.

Returns

Distance between the two points.

Return type

float

distanceTo(x, y=None, z=None)

Calculate the distance to another point.

Parameters

• x (float or ExprValue or tuple) – X coordinate or tuple containing all coordinates.

• y (float or ExprValue, optional) – Y coordinate. Defaults to None.

• z (float or ExprValue, optional) – Z coordinate. Defaults to None.

Returns

Distance between the two points.

Return type

float

distanceToPlane(a, b=None, c=None, d=None)

Calculate the distance from the point to a parametric plane.

Parameters

• a (float or tuple) – A coefficient or tuple containing all coefficients (a, b, c, d) of the plane.

• b (float, optional) – B coefficient. Defaults to None.

• c (float, optional) – C coefficient. Defaults to None.

• d (float, optional) – D coefficient. Defaults to None.

Returns

Distance from the point to the plane.

Return type

float

midpt(x, y=None, z=None)

Calculate the midpoint between the current point and another point.

Parameters

• x (float or ExprValue or tuple) – X coordinate or tuple containing all coordinates.

• y (float or ExprValue, optional) – Y coordinate. Defaults to None.

• z (float or ExprValue, optional) – Z coordinate. Defaults to None.

Returns

Midpoint between the two points.

Return type

Point

static planeFromPoints(pt1, pt2, pt3)

Determine the coefficients of a plane defined by three points.

Parameters

• pt1 (Point or tuple) – First point.

• pt2 (Point or tuple) – Second point.

• pt3 (Point or tuple) – Third point.

Returns

Coefficients (a, b, c, d) of the plane equation ax + by + cz + d = 0.

Return type

tuple

class Vector(**kwds)

3D vector that supports various mathematical operations.

This class derives from list and represents a 3D vector and provides methods for operations like dot product, cross product, scaling, and normalization. The class is designed to handle both regular floats and symbolic expressions (ExprValue).

x

X component of the vector.

Type

float or ExprValue

y

Y component of the vector.

Type

float or ExprValue

z

Z component of the vector.

Type

float or ExprValue

angle(x, y=None, z=None, degrees=False)

Calculate the angle between the vector and another vector.

Parameters

• x (float or ExprValue or tuple) – X component or tuple containing all components.

• y (float or ExprValue, optional) – Y component. Defaults to None.

• z (float or ExprValue, optional) – Z component. Defaults to None.

• degrees (bool, optional) – If True, returns the angle in degrees. Defaults to False.

Returns

Angle between the vectors in radians or degrees.

Return type

float

asfloats()

Convert the vector components to float values.

This method was added as a speed optimization when evaluating an entity position during simulations.

Returns

A new vector with components converted to floats.

Return type

Vector

close(x, y=None, z=None, tol=1e-07)

Compare the vector with another one within a tolerance.

Parameters

• x (float or ExprValue or tuple) – X component or tuple containing all components.

• y (float or ExprValue, optional) – Y component. Defaults to None.

• z (float or ExprValue, optional) – Z component. Defaults to None.

• tol (float, optional) – Tolerance value for comparison. Defaults to 1e-7.

Returns

True if vectors are close, False otherwise.

Return type

bool

copy()

Create a copy of the current Vector instance.

Returns

A copy of the current instance.

Return type

Vector

cross(x, y=None, z=None)

Calculate the cross product with another vector.

Parameters

• x (float or ExprValue or tuple) – X component or tuple containing all components.

• y (float or ExprValue, optional) – Y component. Defaults to None.

• z (float or ExprValue, optional) – Z component. Defaults to None.

Returns

Resultant vector after cross product.

Return type

Vector

dot(x, y=None, z=None)

Calculate the dot product with another vector.

Parameters

• x (float or ExprValue or tuple) – X component or tuple containing all components.

• y (float or ExprValue, optional) – Y component. Defaults to None.

• z (float or ExprValue, optional) – Z component. Defaults to None.

Returns

Dot product result.

Return type

float or ExprValue

classmethod findAngle(pt1, pt2, pt3, degrees=False)

Calculate the angle subtended between vectors (pt2-pt1) and (pt3-pt1).

Parameters

• pt1 (Vector or tuple) – First point.

• pt2 (Vector or tuple) – Second point.

• pt3 (Vector or tuple) – Third point.

• degrees (bool, optional) – If True, returns the angle in degrees. Defaults to False.

Returns

Angle between the vectors in radians or degrees.

Return type

float

isAlignedWith(x, y=None, z=None, tolerance=1e-05, normalize=True)

Check if the vector is parallel to another vector.

Parameters

• x (float or ExprValue or tuple) – X component or tuple containing all components.

• y (float or ExprValue, optional) – Y component. Defaults to None.

• z (float or ExprValue, optional) – Z component. Defaults to None.

• tolerance (float, optional) – Tolerance value for alignment check. Defaults to 1e-5.

• normalize (bool, optional) – If True, normalizes the vectors before checking. Defaults to True.

Returns

True if vectors are aligned, False otherwise.

Return type

bool

iszero()

Check if the vector is null. Returns True if x, y and z are all zero.

magnitude()

Calculate the magnitude (length) of the vector.

Returns

Magnitude of the vector.

Return type

float or ExprValue

normalize()

Normalize the vector to have a magnitude of 1.

Returns

Normalized vector.

Return type

Vector

perpendicularize()

Create a vector perpendicular to the current one.

Returns

Perpendicular vector.

Return type

Vector

scale(x, y=None, z=None)

Scale the vector.

Parameters

• x (float or ExprValue) – Scale value for X component or for all if y and z are None.

• y (float or ExprValue, optional) – Scale value for Y component. Defaults to x.

• z (float or ExprValue, optional) – Scale value for Z component. Defaults to x.

Returns

Scaled vector.

Return type

Vector