Pylinalg API reference

pylinalg

Linear algebra utilities for Python.

pylinalg.aabb_to_sphere(aabb, /, *, out=None, dtype=None)

A sphere that envelops an Axis-Aligned Bounding Box.

Parameters:

aabb (ndarray, [2, 3]) – The axis-aligned bounding box.
out (ndarray, optional) – A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple must have length equal to the number of outputs.
dtype (data-type, optional) – Overrides the data type of the result.

Returns:

sphere – A sphere (x, y, z, radius).

Return type:

ndarray, [4]

pylinalg.aabb_transform(aabb, matrix, /, *, out=None, dtype=None)

Apply an affine transformation to an axis-aligned bounding box.

Parameters:

aabb (ndarray, [2, 3]) – The axis-aligned bounding box.
homogeneous_matrix ([4, 4]) – The homogeneous transformation to apply.
out (ndarray, optional) – A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple must have length equal to the number of outputs.
dtype (data-type, optional) – Overrides the data type of the result.

Returns:

aabb – The transformed axis-aligned bounding box.

Return type:

ndarray, [2, 3]

Notes

This function preserves the alignment axes of the bounding box. This means the returned bounding box has the same alignment axes as the input bounding box, but contains the transformed object. In other words, the box will grow or shrink depending on how the contained object is transformed, but its alignment axis stay the same.

pylinalg.mat_combine(matrices, /, *, out=None, dtype=None)

Combine a list of affine matrices by multiplying them.

Note that by matrix multiplication rules, the output matrix will applied the given transformations in reverse order. For example, passing a scaling, rotation and translation matrix (in that order), will lead to a combined transformation matrix that applies translation first, then rotation and finally scaling.

Parameters:

matrices (list of ndarray, [4, 4]) – List of affine matrices to combine.
out (ndarray, optional) – A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple must have length equal to the number of outputs.
dtype (data-type, optional) – Overrides the data type of the result.

Returns:

Combined transformation matrix.

Return type:

ndarray, [4, 4]

pylinalg.mat_compose(translation, rotation, scaling, /, *, out=None, dtype=None)

Compose a transformation matrix given a translation vector, a quaternion and a scaling vector.

Parameters:

translation (number or ndarray, [3]) – translation vector
rotation (ndarray, [4]) – quaternion
scaling (number or ndarray, [3]) – scaling factor(s)
out (ndarray, optional) – A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple must have length equal to the number of outputs.
dtype (data-type, optional) – Overrides the data type of the result.

Returns:

Transformation matrix

Return type:

ndarray, [4, 4]

pylinalg.mat_decompose(matrix, /, *, scaling_signs=None, dtype=None, out=None)

Decompose a transformation matrix into a translation vector, a quaternion and a scaling vector.

Parameters:

matrix (ndarray, [4, 4]) – transformation matrix
scaling_signs (ndarray, [3], optional) – scaling factor signs. If you wish to preserve the original scaling factors through a compose-decompose roundtrip, you should provide the original scaling factors here, or alternatively just the signs.
out (ndarray, optional) – A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple must have length equal to the number of outputs.
dtype (data-type, optional) – Overrides the data type of the result.

Returns:

translation (ndarray, [3]) – translation vector
rotation (ndarray, [4]) – quaternion
scaling (ndarray, [3]) – scaling factors

pylinalg.mat_decompose_translation(homogeneous_matrix, /, *, out=None, dtype=None)

Position component of a homogeneous matrix.

Parameters:

homogeneous_matrix (ndarray, [4, 4]) – The matrix of which the position/translation component will be extracted.
out (ndarray, optional) – A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple must have length equal to the number of outputs.
dtype (data-type, optional) – Overrides the data type of the result.

Returns:

position – The position/translation component.

Return type:

ndarray, [3]

pylinalg.mat_from_axis_angle(axis, angle, /, *, out=None, dtype=None)

Make a rotation matrix given a rotation axis and an angle (in radians).

Parameters:

axis (ndarray, [3]) – The rotation axis.
angle (number) – The angle (in radians) to rotate about the axis.
out (ndarray, optional) – A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple must have length equal to the number of outputs.
dtype (data-type, optional) – Overrides the data type of the result.

Returns:

Rotation matrix.

Return type:

ndarray, [4, 4]

pylinalg.mat_from_euler(angles, /, *, order='xyz', out=None, dtype=None)

Make a matrix given euler angles (in radians) per axis.

Parameters:

angles (ndarray, [3]) – The euler angles.
order (string, optional) – The order in which the rotations should be applied. Default is “xyz”.
out (ndarray, optional) – A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple must have length equal to the number of outputs.
dtype (data-type, optional) – Overrides the data type of the result.

Returns:

Rotation matrix.

Return type:

ndarray, [4, 4]

Notes

If you are familiar with TreeJS note that this function uses order to denote both the order in which rotations are applied and the order in which angles are provided in angles. I.e., mat_from_euler([np.pi, np.pi, 0], order="zyx") will first rotate 180° ccw (counter-clockwise) around the z-axis, then 180° ccw around the y-axis, and finally 0° around the x axis.

pylinalg.mat_from_quat(quaternion, /, *, out=None, dtype=None)

Make a rotation matrix given a quaternion.

Parameters:

quaternion (ndarray, [4]) – Quaternion.
out (ndarray, optional) – A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple must have length equal to the number of outputs.
dtype (data-type, optional) – Overrides the data type of the result.

Returns:

rotation matrix.

Return type:

ndarray, [4, 4]

pylinalg.mat_from_scale(factors, /, *, out=None, dtype=None)

Make a scaling matrix given scaling factors per axis, or a single uniform scaling factor.

Parameters:

factor (number or ndarray, [3]) – scaling factor(s)
out (ndarray, optional) – A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple must have length equal to the number of outputs.
dtype (data-type, optional) – Overrides the data type of the result.

Returns:

Scaling matrix.

Return type:

ndarray, [4, 4]

pylinalg.mat_from_translation(vector, /, *, out=None, dtype=None)

Make a translationmatrix given a translation vector.

Parameters:

vector (number or ndarray, [3]) – translation vector
out (ndarray, optional) – A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple must have length equal to the number of outputs.
dtype (data-type, optional) – Overrides the data type of the result.

Returns:

Translation matrix.

Return type:

ndarray, [4, 4]

pylinalg.mat_look_at(eye, target, up_reference, /, *, out=None, dtype=None)

Rotation that aligns two vectors.

Given an entity at position eye looking at position target, this function computes a rotation matrix that makes the local frame “look at” the same direction, i.e., the matrix will rotate the local frame’s z-axes (forward) to point in direction target - eye.

This rotation matrix is not unique (yet), as the above doesn’t specify the desired rotation around the new z-axis. The rotation around this axis is controlled by up_reference, which indicates the direction of the y-axis (up) of a reference frame of choice expressed in local coordinates. The rotation around the new z-axis will then align up_reference, the new y-axis, and the new z-axis in the same plane.

In many cases, a natural choice for up_reference is the world frame’s y-axis, i.e., up_reference would be the world’s y-axis expressed in local coordinates. This can be thought of as “gravity pulling on the rotation” (opposite direction of world frame’s up) and will create a result with a level attitude.

Parameters:

eye (ndarray, [3]) – A vector indicating the direction that should be aligned.
target (ndarray, [3]) – A vector indicating the direction to align on.
up (ndarray, [3]) – The direction of the camera’s up axis.
out (ndarray, optional) – A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple must have length equal to the number of outputs.
dtype (data-type, optional) – Overrides the data type of the result.

Returns:

rotation_matrix – A homogeneous matrix describing the rotation.

Return type:

ndarray, [4, 4]

Notes

If the new z-axis (target - eye) aligns with the chosen up_reference then we can’t compute the angle of rotation around the new z-axis. In this case, we will default to a rotation of 0, which may result in surprising behavior for some use-cases. It is the user’s responsibility to ensure that these two directions don’t align.

pylinalg.mat_orthographic(left, right, top, bottom, near, far, /, *, depth_range=(-1, 1), out=None, dtype=None)

Create an orthographic projection matrix.

The result projects points from local space into NDC (normalized device coordinates). Elements inside the viewing frustum defind by left, right, top, bottom, near, far, are projected into the unit cube centered at the origin (default) or a cuboid (custom depth_range). The frustum is centered around the local frame’s origin.

Parameters:

left (ndarray, [1]) – Distance between the left frustum plane and the origin
right (ndarray, [1]) – Distance between the right frustum plane and the origin
top (ndarray, [1]) – Distance between the top frustum plane and the origin
bottom (ndarray, [1]) – Distance between the bottom frustum plane and the origin
near (ndarray, [1]) – Distance between the near frustum plane and the origin
far (ndarray, [1]) – Distance between the far frustum plane and the origin
depth_range (ndarray, [2]) – The interval along the z-axis in NDC that shall correspond to the region inside the viewing frustum.
out (ndarray, optional) – A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple must have length equal to the number of outputs.
dtype (data-type, optional) – Overrides the data type of the result.

Returns:

matrix – orthographic projection matrix

Return type:

ndarray, [4, 4]

Notes

The parameters to this function are given in a left-handed frame that is obtained by mirroring source’s Z-axis at the origin. In other words, if the returned matrix represents a camera’s projection matrix then this function’s parameters are given in a frame that is like the camera’s local frame except that it’s Z-axis is inverted. This means that positive values for near and far refer to a negative Z values in camera local.

pylinalg.mat_perspective(left, right, top, bottom, near, far, /, *, depth_range=(-1, 1), out=None, dtype=None)

Create a perspective projection matrix.

Parameters:

left (number) – distance between the left frustum plane and the origin
right (number) – distance between the right frustum plane and the origin
top (number) – distance between the top frustum plane and the origin
bottom (number) – distance between the bottom frustum plane and the origin
near (number) – distance between the near frustum plane and the origin
far (number) – distance between the far frustum plane and the origin
depth_range (Tuple[float, float]) – The interval along the z-axis in NDC that shall correspond to the region inside the viewing frustum.
out (ndarray, optional) – A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple must have length equal to the number of outputs.
dtype (data-type, optional) – Overrides the data type of the result.

Returns:

matrix – perspective projection matrix

Return type:

ndarray, [4, 4]

pylinalg.quat_from_axis_angle(axis, angle, /, *, out=None, dtype=None)

Quaternion from axis-angle pair.

Create a quaternion representing the rotation of an given angle about a given unit vector

Parameters:

axis (ndarray, [3]) – Unit vector
angle (number) – The angle (in radians) to rotate about axis
out (ndarray, optional) – A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple must have length equal to the number of outputs.
dtype (data-type, optional) – Overrides the data type of the result.

Returns:

Quaternion.

Return type:

ndarray, [4]

pylinalg.quat_from_euler(angles, /, *, order='XYZ', out=None, dtype=None)

Create a quaternion from euler angles.

Parameters:

angles (ndarray, [3]) – A set of XYZ euler angles.
order (string, optional) – The order in which the rotations should be applied. Default is “xyz”.
out (ndarray, optional) – A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple must have length equal to the number of outputs.
dtype (data-type, optional) – Overrides the data type of the result.

Returns:

quaternion – The rotation expressed as a quaternion.

Return type:

ndarray, [4]

pylinalg.quat_from_mat(matrix, /, *, out=None, dtype=None)

Make a quaternion given a rotation matrix.

Parameters:

matrix (ndarray, [3]) – The rotation matrix.
out (ndarray, optional) – A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple must have length equal to the number of outputs.
dtype (data-type, optional) – Overrides the data type of the result.

Returns:

Quaternion.

Return type:

ndarray, [4]

pylinalg.quat_from_vecs(source, target, /, *, out=None, dtype=None)

Rotate one vector onto another.

Create a quaternion that rotates source onto target.

Parameters:

source (ndarray, [3]) – The vector that should be rotated.
target (ndarray, [3]) – The vector that will be rotated onto.
out (ndarray, optional) – A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple must have length equal to the number of outputs.
dtype (data-type, optional) – Overrides the data type of the result.

Returns:

Quaternion.

Return type:

ndarray, [4]

Notes

Among all the possible rotations that send source onto target this function always chooses the right-hand rotation around the origin. In cases where more than one right-hand rotation around the origin exists (source and target are parallel), an arbitrary one is returned.

While this function is intended to be used with unit vectors, it also works on non-unit vectors in which case the returned rotation will point source in the direction of target.

pylinalg.quat_inv(quaternion, /, *, out=None, dtype=None)

Inverse of a given quaternion

Parameters:

a (ndarray, [3]) – First unit vector
out (ndarray, optional) – A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple must have length equal to the number of outputs.
dtype (data-type, optional) – Overrides the data type of the result.

Returns:

Quaternion.

Return type:

ndarray, [4]

pylinalg.quat_mul(a, b, /, *, out=None, dtype=None)

Multiply two quaternions

Parameters:

a (ndarray, [4]) – Left-hand quaternion
b (ndarray, [4]) – Right-hand quaternion
out (ndarray, optional) – A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple must have length equal to the number of outputs.
dtype (data-type, optional) – Overrides the data type of the result.

Returns:

Quaternion.

Return type:

ndarray, [4]

pylinalg.quat_to_axis_angle(quaternion, /, *, out=None, dtype=None)

Convert a quaternion to axis-angle representation.

Parameters:

quaternion (ndarray, [4]) – A quaternion describing the rotation.
out (Tuple[ndarray, ...], optional) – A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple must have length equal to the number of outputs.
dtype (data-type, optional) – Overrides the data type of the result.

Returns:

axis (ndarray, [3]) – The axis around which the quaternion rotates in euclidean coordinates.
angle (ndarray, [1]) – The angle (in rad) by which the quaternion rotates.

Notes

To use out with a single quaternion you need to provide a ndarray of shape (1,) for angle.

pylinalg.quat_to_euler(quaternion, /, *, out=None, dtype=None)

Convert quaternions to XYZ Euler angles.

Parameters:

quaternion (ndarray, [4]) – The quaternion to convert (in xyzw format).
out (ndarray, optional) – A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple must have length equal to the number of outputs.
dtype (data-type, optional) – Overrides the data type of the result.

Returns:

out – The XYZ Euler angles.

Return type:

ndarray, [3]

pylinalg.vec_angle(vector_a, vector_b, /, *, out=None, dtype=None)

The angle between two vectors

Parameters:

vector_a (ndarray, [3]) – The first vector.
vector_b (ndarray, [3]) – The second vector.
out (ndarray, optional) – A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple must have length equal to the number of outputs.
dtype (data-type, optional) – Overrides the data type of the result.

Returns:

angle – The angle between both vectors.

Return type:

float

pylinalg.vec_dist(vector_a, vector_b, /, *, out=None, dtype=None)

The distance between two vectors

Parameters:

vector_a (ndarray, [3]) – The first vector.
vector_b (ndarray, [3]) – The second vector.
out (ndarray, optional) – A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple must have length equal to the number of outputs.
dtype (data-type, optional) – Overrides the data type of the result.

Returns:

distance – The distance between both vectors.

Return type:

ndarray

pylinalg.vec_euclidean_to_spherical(euclidean, /, *, out=None, dtype=None)

Convert euclidean -> spherical coordinates

Parameters:

euclidean (ndarray, [3]) – A vector in euclidean coordinates.
out (ndarray, optional) – A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple must have length equal to the number of outputs.
dtype (data-type, optional) – Overrides the data type of the result.

Returns:

spherical – A vector in spherical coordinates (r, phi, theta).

Return type:

ndarray, [3]

pylinalg.vec_homogeneous(vectors, /, *, w=1, out=None, dtype=None)

Append homogeneous coordinates to vectors.

Parameters:

vectors (array_like, [..., 3]) – array of vectors
w (number, optional, default is 1) – the value for the homogeneous dimensionality. this affects the result of translation transforms. use 0 (vectors) if the translation component should not be applied, 1 (positions) otherwise.
out (ndarray, optional) – A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple must have length equal to the number of outputs.
dtype (data-type, optional) – Overrides the data type of the result.

Returns:

The list of vectors with appended homogeneous value.

Return type:

ndarray, […, 4]

pylinalg.vec_normalize(vectors, /, *, out=None, dtype=None)

Normalize an array of vectors.

Parameters:

vectors (array_like, [..., 3]) – array of vectors
out (ndarray, optional) – A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple must have length equal to the number of outputs.
dtype (data-type, optional) – Overrides the data type of the result.

Returns:

array of normalized vectors.

Return type:

ndarray, […, 3]

pylinalg.vec_spherical_safe(vector, /, *, out=None, dtype=None)

Normalize sperhical coordinates.

Normalizes a vector of spherical coordinates to restrict phi to [0, pi) and theta to [0, 2pi).

Parameters:

vector (ndarray, [3]) – A vector in spherical coordinates.
out (ndarray, optional) – A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple must have length equal to the number of outputs.
dtype (data-type, optional) – Overrides the data type of the result.

Returns:

normalized_vector – A vector in spherical coordinates with restricted angle values.

Return type:

ndarray, [3]

pylinalg.vec_spherical_to_euclidean(spherical, /, *, out=None, dtype=None)

Convert spherical -> euclidean coordinates.

Parameters:

spherical (ndarray, [3]) – A vector in spherical coordinates (r, phi, theta). Phi and theta are measured in radians.
out (ndarray, optional) – A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple must have length equal to the number of outputs.
dtype (data-type, optional) – Overrides the data type of the result.

Returns:

euclidean – A vector in euclidean coordinates.

Return type:

ndarray, [3]

Notes

This implementation follows pygfx’s coordinate conventions. This means that the positive y-axis is the zenith reference and the positive z-axis is the azimuth reference. Angles are measured counter-clockwise.

pylinalg.vec_transform(vectors, matrix, /, *, w=1, out=None, dtype=None)

Apply a transformation matrix to a vector.

Parameters:

vectors (ndarray, [3]) – Array of vectors
matrix (ndarray, [4, 4]) – Transformation matrix
w (ndarray, [1], optional) – The value of the scale component of the homogeneous coordinate. This affects the result of translation transforms. use 0 (vectors) if the translation component should not be applied, 1 (positions) otherwise.
out (ndarray, optional) – A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple must have length equal to the number of outputs.
dtype (data-type, optional) – Overrides the data type of the result.

Returns:

transformed vectors

Return type:

ndarray, [3]

pylinalg.vec_transform_quat(vector, quaternion, /, *, out=None, dtype=None)

Rotate a vector using a quaternion.

Parameters:

vector (ndarray, [3]) – The vector to be rotated.
quaternion (ndarray, [4]) – The quaternion to apply (in xyzw format).
out (ndarray, optional) – A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple must have length equal to the number of outputs.
dtype (data-type, optional) – Overrides the data type of the result.

Returns:

rotated_vector – The rotated vector.

Return type:

ndarray, [3]

pylinalg.vec_unproject(vector, matrix, /, *, depth=0, out=None, dtype=None)

Un-project a vector from 2D space to 3D space.

Find a vectorB in 3D euclidean space such that the projection matrix @ vectorB yields the provided vector (in 2D euclidean space). Since the solution to the above is a 1D subspace of 3D space (a line), depth is used to select a single vector within.

Parameters:

vector (ndarray, [2]) – The vector to be un-projected.
matrix (ndarray, [4, 4]) – The camera’s intrinsic matrix.
depth (number, optional) – The distance of the unprojected vector from the camera.
out (ndarray, optional) – A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple must have length equal to the number of outputs.
dtype (data-type, optional) – Overrides the data type of the result.

Returns:

projected_vector – The unprojected vector in 3D space

Return type:

ndarray, [3]

Notes

The source frame of this operation is the XY-plane of the camera’s NDC frame and the target frame is the camera’s local frame.