2D Matrix class representing affine transformations:

[ a  b  tx ]
[ c  d  ty ]
[ 0  0  1  ]

Note that in AS3, flash.geom.Matrix has 'b' and 'c' swapped! so if you are converting between flash.geom.Matrix and nape.geom.Mat23 you should use the methods provided to avoid any mistakes with this.

Constructor

@:value({ ty : 0.0, tx : 0.0, d : 1.0, c : 0.0, b : 0.0, a : 1.0 })new(a:Float = 1.0, b:Float = 0.0, c:Float = 0.0, d:Float = 1.0, tx:Float = 0.0, ty:Float = 0.0)

Construct new Mat23.

[ a  b  tx ]
[ c  d  ty ]

Parameters:

a

The (1,1) entry in matrix (default 1)

b

The (1,2) entry in matrix (default 0)

c

The (2,1) entry in matrix (default 0)

d

The (2,2) entry in matrix (default 1)

tx

The (1,3) entry in matrix (default 0)

ty

The (2,3) entry in matrix (default 0)

Returns:

The newly constructed Mat23.

Variables

a:Float

The (1,1) entry in Mat23:

[ a  .  . ]
[ .  .  . ]

b:Float

The (1,2) entry in Mat23:

[ .  b  . ]
[ .  .  . ]

c:Float

The (2,1) entry in Mat23:

[ .  .  . ]
[ c  .  . ]

d:Float

The (2,2) entry in Mat23:

[ .  .  . ]
[ .  d  . ]

read onlydeterminant:Float

(readonly) The determinant of this matrix.

This represents the factor of change in area for a region of the plane after transformation by matrix.

A determinant of 0 signifies that the matrix is not invertible.

A negative determinant signifies that for example, a clockwise wound polygon would be transformed into a counter-clockwise polygon.

tx:Float

The (1,3) entry in Mat23 which represents x translation

[ .  .  tx ]
[ .  .  .  ]

ty:Float

The (2,3) entry in Mat23 which represents y translation

[ .  .  .  ]
[ .  .  ty ]

@:value(null)zpp_inner:ZPP_Mat23 = null

@private

Methods

concat(matrix:Mat23):Mat23

Concatenate matrices (left-multiplication), returning new Mat23.

mat1.concat(mat2) is the transformation that first performs transformation represented by mat1, followed by transformation represented by mat2.

Parameters:

matrix

Matrix to concatenate with.

Returns:

The result of the concatenation.

Throws:

#

If matrix argument is null.

copy():Mat23

Produce copy of this Mat23

Returns:

The new Mat23 representing copy of this.

equiorthogonal():Bool

Determine if matrix is equiorthogonal

This is a term I invented after failing to find an existing name. It describes that this matrix maps circles into other circles (of not necessarigly the same radius). In otherwords the matrix can be decomposed into a rotation, translation and scaling of equal x/y factors.

This property is required for any Mat23 that is used to transform a Circle, or any Body containing a Circle, or to transform a Debug view.

This is a weaker property than orthogonality which describes a mapping to a circle of equal radius.

Mathematically speaking a matrix is equiorthogonal iff. transpose(M) * M = kI for some non-zero scalar k.

Returns:

True if matrix is equiorthogonal.

equiorthogonalise():Mat23

Equiorthogonalise matrix.

We do this by finding the 'nearest' orthogonal matrix; scaling the basis vectors of matrix to their mean length and applying an equal and opposite rotation to each basis vector to make them perpendicular.

Returns:

A reference to this Mat23.

Throws:

#

If matrix is singular.

inverse():Mat23

Compute the inverse of this matrix, returning the inverse in a new Mat23 object.

The inverse is such that mat.concat(mat.inverse()) is the identity matrix, as well as mat.inverse().concat(mat)

Returns:

The inverse matrix.

Throws:

#

If matrix is singular.

@:value({ weak : false, noTranslation : false })inverseTransform(point:Vec2, noTranslation:Bool = false, weak:Bool = false):Vec2

Perform inverse transformation with Vec2, returning new Vec2.

The matrix inverse will be performed implicitly and should this method be called many times for the same Mat23, it would be better to instead compute the matrix inverse only once.

The new Vec2 will be allocated from the global object pool.

Parameters:

point

The Vec2 to transform.

noTranslation

If true then the input Vec2 will be treat as a vector instead of a point, treating the tx/ty values of this Mat23 as though they were 0. (default false)

weak

If true, then the allocated Vec2 will be automatically released to global object pool when used as an argument to a Nape function.

Returns:

The result of the transformation as a newly allocated (possibly weak) Vec2. (default false)

Throws:

#

If matrix is singular.

#

If point argument is null.

orthogonal():Bool

Determine if matrix is orthogonal

This property describes a matrix which maps circles into other circles of equal radius. In otherwords the matrix can be decomposed into a rotation and a translation.

Mathematically speaking a matrix is orthogonal iff. transpose(M) * M = I.

Returns:

True if matrix is orthogonal.

orthogonalise():Mat23

Orthogonalise matrix.

We do this by finding the 'nearest' orthogonal matrix; normalising the basis vectors of matrix and applying an equal and opposite rotation to each basis vector to make them perpendicular.

Returns:

A reference to this Mat23.

Throws:

#

If matrix is singular.

inlinereset():Mat23

Reset matrix to identity.

Equivalent to calling setAs with default argument values.

Returns:

A reference to this Mat23.

set(matrix:Mat23):Mat23

Set values of matrix from another.

Parameters:

matrix

The matrix to copy values from.

Returns:

A reference to this Mat23.

Throws:

#

if matrix argument is null.

@:value({ ty : 0.0, tx : 0.0, d : 1.0, c : 0.0, b : 0.0, a : 1.0 })setAs(a:Float = 1.0, b:Float = 0.0, c:Float = 0.0, d:Float = 1.0, tx:Float = 0.0, ty:Float = 0.0):Mat23

Set values of matrix from numbers.

So that: mat.setAs(...) is semantically equivalent to: mat.set(new Mat23(...))

Parameters:

a

The value to which the (1,1) entry will be set (default 1)

b

The value to which the (1,2) entry will be set (default 0)

c

The value to which the (2,1) entry will be set (default 0)

d

The value to which the (2,2) entry will be set (default 1)

tx

The value to which the (1,3) entry will be set (default 0)

ty

The value to which the (2,3) entry will be set (default 0)

Returns:

A reference to this Mat23.

singular():Bool

Determine if the matrix is singular. This check is based on computing the condition number of the matrix by the Frobenius norm, and comparing against 2 / epsilon.

If matrix is singular, then inversion of the matrix cannot be performed

Returns:

True, if matrix is singular.

@:value({ output : null })toMatrix(?output:Matrix):Matrix

Create an AS3 flash.geom.Matrix from this Mat23.

This method should be used in preference to doing so manually as the allocation of matrix entries to name is different and it is easy to make this mistake!

@preturn The constructed AS3 Matrix.

Parameters:

output

If supplied, this Matrix will have its properties populated insteaad of creating a new Matrix.

@:keeptoString():String

@private

@:value({ weak : false, noTranslation : false })transform(point:Vec2, noTranslation:Bool = false, weak:Bool = false):Vec2

Transform a Vec2 by this matrix in new Vec2.

The Vec2 object will be allocated form the global object pool.

Parameters:

point

The Vec2 to transform by this matrix.

noTranslation

If true, then the input Vec2 will be treat as a vector, rather than a point with the tx/ty values treat as 0. (default false)

weak

If true, then the allocated Vec2 will be automatically released to global object pool when used as an argument to a Nape function.

Returns:

The result of the transformation as a newly allocated (possibly weak) Vec2. (default false)

Throws:

#

If point argument is null.

transpose():Mat23

Compute the transpose of this matrix, returning the transpose in a new Mat23 object.

Technically speaking, we cannot transpose a matrix if the tx/ty values are non-zero as the implicit bottom row of matrix must be (0, 0, 1) so the tx/ty values of output matrix are set so that should the main 2x2 block of the matrix be orthogonal (Representing a rotation), then the transpose will be able to act as the matrix inverse.

var mat = Mat23.rotation(..).concat(Mat23.translation(...));
trace(mat.concat(mat.transpose())); // Identity matrix
trace(mat.concat(mat.inverse())); // Identity matrix
If the main 2x2 block of matrix is 'not' orthogonal, then the transpose will not be equal to the inverse.

Returns:

The transposed matrix.

Static methods

staticfromMatrix(matrix:Matrix):Mat23

Create a Mat23 matrix from a given AS3 flash.geom.Matrix.

This method should be used in preference to doing so manually as the allocation of matrix entries to name is different and it is easy to make this mistake!

This method is only available on flash and openfl||nme targets.

Parameters:

matrix

The AS3 Matrix to create Mat23 from. This value must not be null.

Returns:

The constructed Mat23 matching AS3 Matrix.

staticrotation(angle:Float):Mat23

Construct a Mat23 representing a clockwise rotation.

[ cos angle  -sin angle  0 ]
[ sin angle   cos angle  0 ]

Parameters:

angle

The clockwise rotation in radians

Returns:

The rotation matrix.

staticscale(sx:Float, sy:Float):Mat23

Construct a Mat23 representing a scaling

[ sx  0  0 ]
[ 0  sy  0 ]

Parameters:

sx

The x factor of scaling.

sy

The y factor of scaling.

Returns:

The scaling matrix.

statictranslation(tx:Float, ty:Float):Mat23

Construct a Mat23 representing a translation

[ 1  0  tx ]
[ 0  1  ty ]

Parameters:

tx

The x translation.

ty

The y translation.

Returns:

The translation matrix.