class nape.geom.Mat23
Available on all platforms
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.
Class Fields
static function fromMatrix(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.
*
*
matrix | The AS3 Matrix to create Mat23 from. This value must * not be null. * |
returns | The constructed Mat23 matching AS3 Matrix. |
static function rotation(angle:Float):Mat23
Construct a Mat23 representing a clockwise rotation.
*
* [ cos angle -sin angle 0 ]
* [ sin angle cos angle 0 ]
*
*
angle | The clockwise rotation in radians * |
returns | The rotation matrix. |
static function scale(sx:Float, sy:Float):Mat23
Construct a Mat23 representing a scaling
*
* [ sx 0 0 ]
* [ 0 sy 0 ]
*
*
sx | The x factor of scaling. * |
sy | The y factor of scaling. * |
returns | The scaling matrix. |
static function translation(tx:Float, ty:Float):Mat23
Construct a Mat23 representing a translation
*
* [ 1 0 tx ]
* [ 0 1 ty ]
*
*
tx | The x translation. * |
ty | The y translation. * |
returns | The translation matrix. |
Instance Fields
var determinant: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.
*
* @default 1
The (1,3) entry in Mat23 which represents x translation
*
*
* [ . . tx ] * [ . . . ] ** * @default 0
The (2,3) entry in Mat23 which represents y translation
*
*
* [ . . . ] * [ . . ty ] ** * @default 0
function new(?a:Float = 1.0f, ?b:Float = 0.0f, ?c:Float = 0.0f, ?d:Float = 1.0f, ?tx:Float = 0.0f, ?ty:Float = 0.0f):Void
Construct new Mat23.
*
*
* [ a b tx ] * [ c d ty ] ** *
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. |
function 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.
*
*
*
matrix | Matrix to concatenate with. * |
returns | The result of the concatenation. * |
function 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. |
function 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. * |
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. * |
function 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.
*
*
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) |
function 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. |
function 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. * |
Reset matrix to identity.
*
* Equivalent to calling setAs with default argument values.
*
*
returns | A reference to this Mat23. |
function set(matrix:Mat23):Mat23
Set values of matrix from another. * *
matrix | The matrix to copy values from. * |
returns | A reference to this Mat23. * |
function setAs(?a:Float = 1.0f, ?b:Float = 0.0f, ?c:Float = 0.0f, ?d:Float = 1.0f, ?tx:Float = 0.0f, ?ty:Float = 0.0f):Mat23
Set values of matrix from numbers.
*
* So that: mat.setAs(...)
is
* semantically equivalent to: mat.set(new Mat23(...))
*
*
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. |
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. |
function toMatrix(?output:Matrix = null):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.
output | If supplied, this Matrix will have its properties * populated insteaad of creating a new Matrix. * |
function 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.
*
*
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) |
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. |