Reference

std/linear/matrix3

std/linear/src/matrix3.trb

Matrix3, the 3x3 matrix: a linear transformation of space, and at the same time the affine transformation of the plane - rotation, scale, shear and a translation - that a 2D scene graph is built out of.

The fields are the columns, and a column is where a basis vector lands. Read as an affine transformation of the plane, the third column is the translation and the third row is (0, 0, 1).

type Matrix3

type Matrix3<Scalar: Numeric = Float> with Add, Subtract, Multiply

A linear transformation of space, held as the three vectors its basis lands on - or an affine transformation of the plane, where the third column is the translation.

Vectors are columns and a transformation is applied on the left, so composing a after b is a * b.

Examples

const move = Matrix3.affine Matrix2<Float>.identity, by: Vector2(3.0, 4.0)
print move.transformedPoint(Vector2(1.0, 1.0))

Related

  • Matrix4 - the same for affine transformations of space.
  • Quaternion - a rotation of space that interpolates without shearing.

field xAxis

xAxis: Vector3<Scalar>

Where the first basis vector lands.

field yAxis

yAxis: Vector3<Scalar>

Where the second basis vector lands.

field zAxis

zAxis: Vector3<Scalar>

Where the third basis vector lands, which for an affine transformation of the plane is the translation.

const identity

static identity: Matrix3<Scalar>

The transformation that changes nothing, over whichever scalar is asked for: Matrix3<Int>.identity.

fn scaling

static fn scaling(by: Vector3<Scalar>): Matrix3<Scalar>

A diagonal matrix: each axis scaled on its own.

fn linearPart

fn linearPart(): Matrix2<Scalar>

The two rows and columns an affine transformation of the plane keeps as its linear part.

fn translationPart

fn translationPart(): Vector2<Scalar>

The translation an affine transformation of the plane carries: the first two components of the third column.

fn transposed

fn transposed(): Matrix3<Scalar>

The rows read as columns.

fn determinant

fn determinant(): Scalar

The factor the transformation multiplies a volume by. Zero where it collapses space onto a plane or less.

fn at

fn at(row: Int, index: Int): Scalar

The cell in that row and that column. Panics outside 0..3.

fn column

fn column(index: Int): Vector3<Scalar>

The column at that index. Panics outside 0..3.

fn row

fn row(index: Int): Vector3<Scalar>

The row at that index. Panics outside 0..3.

fn add

fn add(other: Matrix3<Scalar>): Matrix3<Scalar>

Cell by cell. Adding two transformations is not composing them; multiply is.

fn subtract

fn subtract(other: Matrix3<Scalar>): Matrix3<Scalar>

Cell by cell.

fn multiply

fn multiply(other: Matrix3<Scalar>): Matrix3<Scalar>

The composition: self after other.

fn applied

fn applied(to: Vector3<Scalar>): Vector3<Scalar>

The vector transformed: the column combination x * xAxis + y * yAxis + z * zAxis.

It is a method and not matrix * vector, because a type has one namespace of members and multiply is already the composition of two matrices.

fn transformedDirection

fn transformedDirection(direction: Vector2<Scalar>): Vector2<Scalar>

A direction of the plane, turned by the affine transformation: the translation is not applied.

fn affine

static fn affine(linear: Matrix2<Scalar>, by: Vector2<Scalar>): Matrix3<Scalar>

The affine transformation of the plane that applies the linear part and then moves by by. Its bottom row ends in Scalar.one, which every number type has, so a tile grid gets one as well as a scene: Matrix3<Int>.affine.

const move = Matrix3.affine Matrix2<Float>.identity, by: Vector2(1.0, 2.0)
print move.translationPart()

fn transformedPoint

fn transformedPoint(point: Vector2<Scalar>): Vector2<Scalar>

A point of the plane, moved by the affine transformation: the translation is applied.

extend Matrix3<Scalar> with Negate

extend<Scalar: Signed> Matrix3<Scalar> with Negate

Every cell turned around.

fn negate

fn negate(): Matrix3<Scalar>

Every cell with its sign flipped.

extend Matrix3<Scalar>

extend<Scalar: Real> Matrix3<Scalar>

What an angle and a division buy: the three rotations, and the way back.

fn rotationAroundX

static fn rotationAroundX(by: Angle<Scalar>): Matrix3<Scalar>

The rotation of space around the first axis.

fn rotationAroundY

static fn rotationAroundY(by: Angle<Scalar>): Matrix3<Scalar>

The rotation of space around the second axis.

fn rotationAroundZ

static fn rotationAroundZ(by: Angle<Scalar>): Matrix3<Scalar>

The rotation of space around the third axis, which is the rotation of the plane.

fn inverse

fn inverse(): Matrix3<Scalar>?

The transformation that undoes this one, or None where the determinant is zero and there is none.

fn isCloseTo

fn isCloseTo(other: Matrix3<Scalar>, tolerance: Scalar): Bool

Whether every cell is within tolerance of the other matrix's.

extend Matrix3<Scalar> with Power<Int64>

extend<Scalar: Numeric> Matrix3<Scalar> with Power<Int64>

A whole power: the transformation applied that many times over.

fn power

fn power(exponent: Int64): Matrix3<Scalar>

turn ** 3 is turn * turn * turn, by squaring, and matrix ** 0 is the identity.

Panics

On a negative exponent, which is a power of the inverse: a matrix has one only over a Real scalar and only where its determinant is not zero, so the caller asks for inverse() and raises that.