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.
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.
Constructor
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
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.
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. |
|---|
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. |
|---|
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. |
|---|
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.
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. |
|---|
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 matrixIf the main 2x2 block of matrix is 'not' orthogonal, then the transpose will not be equal to the inverse.
Returns:
The transposed matrix.