You are here: Start » PyAVL » Working with Matrices

Working with Matrices

The Matrix type stores a two-dimensional array of single-precision floating-point values. Many functions of Aurora Vision Library read and write matrices, for example the functions for affine transforms, calibration and principal component analysis. In PyAVL a matrix can be created from Python data, its elements can be read and modified, and matrices can be combined with the Python operators.

Creating a Matrix

Expression	Result
`AVL.Matrix()`	An empty matrix with zero rows and columns.
`AVL.Matrix(rows, cols)`	A matrix of the given size filled with zeros.
`AVL.Matrix(rows, cols, fill)`	A matrix of the given size filled with the value `fill`.
`AVL.Matrix([[1, 2], [3, 4]])`	A matrix created from a sequence of rows. All rows must have the same, non-zero length.
`AVL.Matrix.eye(n)`	The identity matrix of size `n` × `n`, where `n` is at least 1.

A matrix of size zero in either dimension is an empty matrix. Rows of different lengths, empty rows and values that are not numbers raise an exception: ValueError for the invalid structure and TypeError for the invalid type.

The size of a matrix is available in the RowCount and ColCount properties.

Reading and Writing Elements

An element is addressed with the row and the column index in square brackets. The indices start from zero. Negative indices count from the end of the row or the column.

import AVL

m = AVL.Matrix([[1, 2, 3], [4, 5, 6]])

print(m[0, 2])      # 3.0
print(m[-1, -1])    # 6.0, the last element

m[1, 0] = 40
print(m.tolist())   # [[1.0, 2.0, 3.0], [40.0, 5.0, 6.0]]

An index outside the matrix raises IndexError. A key that is not a pair of integers raises TypeError. The elements of a matrix cannot be deleted.

The method tolist() returns the elements as a list of rows, each row being a list of Python floats.

Methods

Method	Result	Function used
`m.transpose()`	A new matrix with the rows and columns swapped.	TransposeMatrix
`m.inverse()`	A new matrix, the inverse of the square matrix.	InvertMatrix

Neither method modifies the original matrix. An empty matrix or a matrix that is not square cannot be inverted and raises AVL.DomainError. As in InvertMatrix, inverting a singular matrix does not raise an error; the result is a matrix of zeros.

Operators

Expression	Result	Function used
`a + b`	Matrix, element-wise sum.	AddMatrices
`a - b`	Matrix, element-wise difference.	SubtractMatrices
`a * number`, `number * a`	Matrix, all elements multiplied by the number.	MultiplyMatrixByReal
`-a`	Matrix, all elements negated.	MultiplyMatrixByReal
`a * b`	Matrix, element-wise product.	—
`a @ b`	Matrix, the matrix product.	MultiplyMatrices
`a @ vector`	Vector3D, the vector transformed by a 3×3 matrix.	—
`a @ point`	Point3D, the point transformed by a 3×3 or a 4×4 matrix.	The same transformation as `TransformPoint3D`.

Operations on two matrices require matching sizes: +, - and the element-wise * require matrices of the same size, and @ requires that the number of columns of the left matrix equals the number of rows of the right matrix. Otherwise AVL.DomainError is raised. The operator * between two matrices is the element-wise product; use @ for the matrix product.

When a matrix is applied to a point, a 3×3 matrix performs a linear transformation, such as a rotation or a scaling. A 4×4 matrix additionally contains a translation in its last column; the last row of a 4×4 matrix is not used. When a matrix is applied to a vector, only the 3×3 form is accepted.

import AVL

# Rotation by 90 degrees around the Z axis
rotation = AVL.Matrix([[0, -1, 0],
                       [1,  0, 0],
                       [0,  0, 1]])

print(rotation @ AVL.Vector3D(1, 0, 0))       # Vector3D (0, 1, 0)

# Translation by (10, 20, 30) expressed as a 4x4 matrix
transform = AVL.Matrix([[1, 0, 0, 10],
                        [0, 1, 0, 20],
                        [0, 0, 1, 30],
                        [0, 0, 0, 1]])

print(transform @ AVL.Point3D(1, 2, 3))       # Point3D (11, 22, 33)

# Inverse and product
m = AVL.Matrix([[2, 0], [0, 4]])
print(m.inverse().tolist())                   # [[0.5, 0.0], [0.0, 0.25]]
print((m @ m.inverse()).tolist())             # [[1.0, 0.0], [0.0, 1.0]]

Printing a Matrix

print and repr show the elements of a matrix with six decimal places, in the same way as the other PyAVL types:

>>> AVL.Matrix([[1, 2.5], [-3, 4]])
Matrix([[1.000000, 2.500000], [-3.000000, 4.000000]])