Matrix3¶

Overview¶

3-dimensional Matrix

@author Jonathan Olson <jonathan.olson@colorado.edu>

Class Matrix3¶

import { Matrix3 } from 'scenerystack/dot';

Constructor¶

new Matrix3()¶

Instance Methods¶

initialize() : this¶

m00() : number¶

Convenience getter for the individual 0,0 entry of the matrix.

m01() : number¶

Convenience getter for the individual 0,1 entry of the matrix.

m02() : number¶

Convenience getter for the individual 0,2 entry of the matrix.

m10() : number¶

Convenience getter for the individual 1,0 entry of the matrix.

m11() : number¶

Convenience getter for the individual 1,1 entry of the matrix.

m12() : number¶

Convenience getter for the individual 1,2 entry of the matrix.

m20() : number¶

Convenience getter for the individual 2,0 entry of the matrix.

m21() : number¶

Convenience getter for the individual 2,1 entry of the matrix.

m22() : number¶

Convenience getter for the individual 2,2 entry of the matrix.

isIdentity() : boolean¶

Returns whether this matrix is an identity matrix.

isFastIdentity() : boolean¶

Returns whether this matrix is likely to be an identity matrix (returning false means "inconclusive, may be identity or not"), but true is guaranteed to be an identity matrix.

isTranslation() : boolean¶

Returns whether this matrix is a translation matrix. By this we mean it has no shear, rotation, or scaling It may be a translation of zero.

isAffine() : boolean¶

Returns whether this matrix is an affine matrix (e.g. no shear).

isAligned() : boolean¶

Returns whether it's an affine matrix where the components of transforms are independent, i.e. constructed from arbitrary component scaling and translation.

isAxisAligned() : boolean¶

Returns if it's an affine matrix where the components of transforms are independent, but may be switched (unlike isAligned)

i.e. the 2x2 rotational sub-matrix is of one of the two forms: A 0 or 0 A 0 B B 0 This means that moving a transformed point by (x,0) or (0,y) will result in a motion along one of the axes.

isFinite() : boolean¶

Returns whether every single entry in this matrix is a finite number (non-NaN, non-infinite).

getDeterminant() : number¶

Returns the determinant of this matrix.

getTranslation() : Vector2¶

Returns the 2D translation, assuming multiplication with a homogeneous vector

getScaleVector() : Vector2¶

Returns a vector that is equivalent to ( T(1,0).magnitude(), T(0,1).magnitude() ) where T is a relative transform

getSignedScale() : number¶

Returns the total "amount" of scaled area in this matrix (which will be negative if it flips the coordinate system). For instance, Matrix3.scaling( 2 ) will return 4, since it scales the area by 4.

getRotation() : number¶

Returns the angle in radians for the 2d rotation from this matrix, between pi, -pi

toMatrix4() : Matrix4¶

Returns an identity-padded copy of this matrix with an increased dimension.

toAffineMatrix4() : Matrix4¶

Returns an identity-padded copy of this matrix with an increased dimension, treating this matrix's affine components only.

toString() : string¶

Returns a string form of this object

toSVGMatrix() : SVGMatrix¶

Creates an SVG form of this matrix, for high-performance processing in SVG output.

getCSSTransform() : string¶

Returns the CSS form (simplified if possible) for this transformation matrix.

getSVGTransform() : string¶

Returns the CSS-like SVG matrix form for this transformation matrix.

getCSSTransformStyles() : Record<string, string>¶

Returns a parameter object suitable for use with jQuery's .css()

equals( matrix : Matrix3 ) : boolean¶

Returns exact equality with another matrix

equalsEpsilon( matrix : Matrix3, epsilon : number ) : boolean¶

Returns equality within a margin of error with another matrix

copy() : Matrix3¶

Returns a copy of this matrix

plus( matrix : Matrix3 ) : Matrix3¶

Returns a new matrix, defined by this matrix plus the provided matrix

minus( matrix : Matrix3 ) : Matrix3¶

Returns a new matrix, defined by this matrix plus the provided matrix

transposed() : Matrix3¶

Returns a transposed copy of this matrix

negated() : Matrix3¶

Returns a negated copy of this matrix

inverted() : Matrix3¶

Returns an inverted copy of this matrix

timesMatrix( matrix : Matrix3 ) : Matrix3¶

Returns a matrix, defined by the multiplication of this * matrix.

@param matrix @returns - NOTE: this may be the same matrix!

timesVector2( vector2 : Vector2 ) : Vector2¶

Returns the multiplication of this matrix times the provided vector (treating this matrix as homogeneous, so that it is the technical multiplication of (x,y,1)).

timesVector3( vector3 : Vector3 ) : Vector3¶

Returns the multiplication of this matrix times the provided vector

timesTransposeVector2( vector2 : Vector2 ) : Vector2¶

Returns the multiplication of the transpose of this matrix times the provided vector (assuming the 2x2 quadrant)

timesRelativeVector2( vector2 : Vector2 ) : Vector2¶

TODO: this operation seems to not work for transformDelta2, should be vetted https://github.com/phetsims/dot/issues/96

rowMajor( v00 : number, v01 : number, v02 : number, v10 : number, v11 : number, v12 : number, v20 : number, v21 : number, v22 : number, type? : Matrix3Type ) : this¶

Sets the entire state of the matrix, in row-major order.

NOTE: Every mutable method goes through rowMajor

set( matrix : Matrix3 ) : this¶

Sets this matrix to be a copy of another matrix.

setArray( array : number[] | Float32Array | Float64Array ) : this¶

Sets this matrix to be a copy of the column-major data stored in an array (e.g. WebGL).

set00( value : number ) : this¶

Sets the individual 0,0 component of this matrix.

set01( value : number ) : this¶

Sets the individual 0,1 component of this matrix.

set02( value : number ) : this¶

Sets the individual 0,2 component of this matrix.

set10( value : number ) : this¶

Sets the individual 1,0 component of this matrix.

set11( value : number ) : this¶

Sets the individual 1,1 component of this matrix.

set12( value : number ) : this¶

Sets the individual 1,2 component of this matrix.

set20( value : number ) : this¶

Sets the individual 2,0 component of this matrix.

set21( value : number ) : this¶

Sets the individual 2,1 component of this matrix.

set22( value : number ) : this¶

Sets the individual 2,2 component of this matrix.

makeImmutable() : this¶

Makes this matrix effectively immutable to the normal methods (except direct setters?)

columnMajor( v00 : number, v10 : number, v20 : number, v01 : number, v11 : number, v21 : number, v02 : number, v12 : number, v22 : number, type : Matrix3Type ) : this¶

Sets the entire state of the matrix, in column-major order.

add( matrix : Matrix3 ) : this¶

Sets this matrix to itself plus the given matrix.

subtract( m : Matrix3 ) : this¶

Sets this matrix to itself minus the given matrix.

transpose() : this¶

Sets this matrix to its own transpose.

negate() : this¶

Sets this matrix to its own negation.

invert() : this¶

Sets this matrix to its own inverse.

multiplyMatrix( matrix : Matrix3 ) : this¶

Sets this matrix to the value of itself times the provided matrix

prependTranslation( x : number, y : number ) : this¶

Mutates this matrix, equivalent to (translation * this).

setToIdentity() : this¶

Sets this matrix to the 3x3 identity matrix.

setToTranslation( x : number, y : number ) : this¶

Sets this matrix to the affine translation matrix.

setToScale( x : number, y? : number ) : this¶

Sets this matrix to the affine scaling matrix.

setToAffine( m00 : number, m01 : number, m02 : number, m10 : number, m11 : number, m12 : number ) : this¶

Sets this matrix to an affine matrix with the specified row-major values.

setToRotationAxisAngle( axis : Vector3, angle : number ) : this¶

Sets the matrix to a rotation defined by a rotation of the specified angle around the given unit axis.

@param axis - normalized @param angle - in radians

setToRotationX( angle : number ) : this¶

Sets this matrix to a rotation around the x axis (in the yz plane).

@param angle - in radians

setToRotationY( angle : number ) : this¶

Sets this matrix to a rotation around the y axis (in the xz plane).

@param angle - in radians

setToRotationZ( angle : number ) : this¶

Sets this matrix to a rotation around the z axis (in the xy plane).

@param angle - in radians

setToTranslationRotation( x : number, y : number, angle : number ) : this¶

Sets this matrix to the combined translation+rotation (where the rotation logically would happen first, THEN it would be translated).

@param x @param y @param angle - in radians

setToTranslationRotationPoint( translation : Vector2, angle : number ) : this¶

Sets this matrix to the combined translation+rotation (where the rotation logically would happen first, THEN it would be translated).

@param translation @param angle - in radians

setToScaleTranslationRotation( scale : number, x : number, y : number, angle : number ) : this¶

Sets this matrix to the combined scale+translation+rotation.

The order of operations is scale, then rotate, then translate.

@param x @param y @param angle - in radians

setToScaleTranslationRotationPoint( scale : number, translation : Vector2, angle : number ) : this¶

Sets this matrix to the combined translation+rotation (where the rotation logically would happen first, THEN it would be translated).

@param translation @param angle - in radians

setToSVGMatrix( svgMatrix : SVGMatrix ) : this¶

Sets this matrix to the values contained in an SVGMatrix.

setRotationAToB( a : Vector3, b : Vector3 ) : this¶

Sets this matrix to a rotation matrix that rotates A to B (Vector3 instances), by rotating about the axis A.cross( B ) -- Shortest path. ideally should be unit vectors.

multiplyVector2( vector2 : Vector2 ) : Vector2¶

Sets the vector to the result of (matrix * vector), as a homogeneous multiplication.

@returns - The vector that was mutated

multiplyVector3( vector3 : Vector3 ) : Vector3¶

Sets the vector to the result of (matrix * vector).

@returns - The vector that was mutated

multiplyTransposeVector2( v : Vector2 ) : Vector2¶

Sets the vector to the result of (transpose(matrix) * vector), ignoring the translation parameters.

@returns - The vector that was mutated

multiplyRelativeVector2( v : Vector2 ) : Vector2¶

Sets the vector to the result of (matrix * vector - matrix * zero). Since this is a homogeneous operation, it is equivalent to the multiplication of (x,y,0).

@returns - The vector that was mutated

canvasSetTransform( context : CanvasRenderingContext2D )¶

Sets the transform of a Canvas 2D rendering context to the affine part of this matrix

canvasAppendTransform( context : CanvasRenderingContext2D )¶

Appends to the affine part of this matrix to the Canvas 2D rendering context

copyToArray( array : number[] | Float32Array | Float64Array ) : number[] | Float32Array | Float64Array¶

Copies the entries of this matrix over to an arbitrary array (typed or normal).

freeToPool()¶

Instance Properties¶

entries : NineNumbers¶

Entries stored in column-major format

type : Matrix3Type¶

Static Methods¶

identity() : Matrix3¶

Returns an identity matrix.

translation( x : number, y : number ) : Matrix3¶

Returns a translation matrix.

translationFromVector( vector : Vector2 | Vector3 ) : Matrix3¶

Returns a translation matrix computed from a vector.

scaling( x : number, y? : number ) : Matrix3¶

Returns a matrix that scales things in each dimension.

scale( x : number, y? : number ) : Matrix3¶

Returns a matrix that scales things in each dimension.

affine( m00 : number, m01 : number, m02 : number, m10 : number, m11 : number, m12 : number ) : Matrix3¶

Returns an affine matrix with the given parameters.

rowMajor( v00 : number, v01 : number, v02 : number, v10 : number, v11 : number, v12 : number, v20 : number, v21 : number, v22 : number, type? : Matrix3Type ) : Matrix3¶

Creates a new matrix with all entries determined in row-major order.

rotationAxisAngle( axis : Vector3, angle : number ) : Matrix3¶

Returns a matrix rotation defined by a rotation of the specified angle around the given unit axis.

@param axis - normalized @param angle - in radians

rotationX( angle : number ) : Matrix3¶

Returns a matrix that rotates around the x axis (in the yz plane).

@param angle - in radians

rotationY( angle : number ) : Matrix3¶

Returns a matrix that rotates around the y axis (in the xz plane).

@param angle - in radians

rotationZ( angle : number ) : Matrix3¶

Returns a matrix that rotates around the z axis (in the xy plane).

@param angle - in radians

translationRotation( x : number, y : number, angle : number ) : Matrix3¶

Returns a combined 2d translation + rotation (with the rotation effectively applied first).

@param angle - in radians

rotation2( angle : number ) : Matrix3¶

Standard 2d rotation matrix for a given angle.

@param angle - in radians

rotationAround( angle : number, x : number, y : number ) : Matrix3¶

Returns a matrix which will be a 2d rotation around a given x,y point.

@param angle - in radians @param x @param y

rotationAroundPoint( angle : number, point : Vector2 ) : Matrix3¶

Returns a matrix which will be a 2d rotation around a given 2d point.

@param angle - in radians @param point

fromSVGMatrix( svgMatrix : SVGMatrix ) : Matrix3¶

Returns a matrix equivalent to a given SVGMatrix.

rotateAToB( a : Vector3, b : Vector3 ) : Matrix3¶

Returns a rotation matrix that rotates A to B, by rotating about the axis A.cross( B ) -- Shortest path. ideally should be unit vectors.

translationTimesMatrix( x : number, y : number, matrix : Matrix3 ) : Matrix3¶

Shortcut for translation times a matrix (without allocating a translation matrix), see scenery#119

toStateObject( matrix3 : Matrix3 ) : Matrix3StateObject¶

Serialize to an Object that can be handled by PhET-iO

fromStateObject( stateObject : Matrix3StateObject ) : Matrix3¶

Convert back from a serialized Object to a Matrix3

Static Properties¶

pool : Pool¶

(readonly)

IDENTITY : Matrix3¶

X_REFLECTION : Matrix3¶

Y_REFLECTION : Matrix3¶

Matrix3IO : IOType¶

Type Matrix3StateObject¶

import type { Matrix3StateObject } from 'scenerystack/dot';

• entries: NineNumbers
• type: string

Class Matrix3Type¶

import { Matrix3Type } from 'scenerystack/dot';

Static Properties¶

OTHER : Matrix3Type¶

(readonly)

IDENTITY : Matrix3Type¶

(readonly)

TRANSLATION_2D : Matrix3Type¶

(readonly)

SCALING : Matrix3Type¶

(readonly)

AFFINE : Matrix3Type¶

(readonly)

enumeration : Enumeration¶

(readonly)

Source Code¶

See the source for Matrix3.ts in the dot repository.