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