Transform3¶

Overview¶

Forward and inverse transforms with 3x3 matrices. Methods starting with 'transform' will apply the transform from our primary matrix, while methods starting with 'inverse' will apply the transform from the inverse of our matrix.

Generally, this means transform.inverseThing( transform.transformThing( thing ) ).equals( thing ).

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

Class Transform3¶

import { Transform3 } from 'scenerystack/dot';

Constructor¶

new Transform3( matrix )¶

Instance Methods¶

setMatrix( matrix )¶

Sets the value of the primary matrix directly from a Matrix3. Does not change the Matrix3 instance. @public

@param {Matrix3} matrix

validateMatrix( matrix )¶

Validates the matrix or matrix arguments, overrideable by subclasses to refine the validation. @param {Matrix} matrix @protected

invalidate()¶

This should be called after our internal matrix is changed. It marks the other dependent matrices as invalid, and sends out notifications of the change. @private

prepend( matrix )¶

Modifies the primary matrix such that: this.matrix = matrix * this.matrix. @public

@param {Matrix3} matrix

prependTranslation( x, y )¶

Optimized prepended translation such that: this.matrix = translation( x, y ) * this.matrix. @public

@param {number} x - x-coordinate @param {number} y - y-coordinate

append( matrix )¶

Modifies the primary matrix such that: this.matrix = this.matrix * matrix @public

@param {Matrix3} matrix

prependTransform( transform )¶

Like prepend(), but prepends the other transform's matrix. @public

@param {Transform3} transform

appendTransform( transform )¶

Like append(), but appends the other transform's matrix. @public

@param {Transform3} transform

applyToCanvasContext( context )¶

Sets the transform of a Canvas context to be equivalent to this transform. @public

@param {CanvasRenderingContext2D} context

copy()¶

Creates a copy of this transform. @public

@returns {Transform3}

getMatrix()¶

Returns the primary matrix of this transform. @public

@returns {Matrix3}

getInverse()¶

Returns the inverse of the primary matrix of this transform. @public

@returns {Matrix3}

getMatrixTransposed()¶

Returns the transpose of the primary matrix of this transform. @public

@returns {Matrix3}

getInverseTransposed()¶

Returns the inverse of the transpose of matrix of this transform. @public

@returns {Matrix3}

isIdentity()¶

Returns whether our primary matrix is known to be an identity matrix. If false is returned, it doesn't necessarily mean our matrix isn't an identity matrix, just that it is unlikely in normal usage. @public

@returns {boolean}

isFinite()¶

Returns whether any components of our primary matrix are either infinite or NaN. @public

@returns {boolean}

transformPosition2( v )¶

Transforms a 2-dimensional vector like it is a point with a position (translation is applied). @public

For an affine matrix \(M\), the result is the homogeneous multiplication \(M\begin{bmatrix} x \\ y \\ 1 \end{bmatrix}\).

@param {Vector2} v @returns {Vector2}

transformDelta2( v )¶

Transforms a 2-dimensional vector like position is irrelevant (translation is not applied). @public

For an affine matrix \(\begin{bmatrix} a & b & c \\ d & e & f \\ 0 & 0 & 1 \end{bmatrix}\), the result is \(\begin{bmatrix} a & b & 0 \\ d & e & 0 \\ 0 & 0 & 1 \end{bmatrix} \begin{bmatrix} x \\ y \\ 1 \end{bmatrix}\).

@param {Vector2} v @returns {Vector2}

transformNormal2( v )¶

Transforms a 2-dimensional vector like it is a normal to a curve (so that the curve is transformed, and the new normal to the curve at the transformed point is returned). @public

For an affine matrix \(\begin{bmatrix} a & b & c \\ d & e & f \\ 0 & 0 & 1 \end{bmatrix}\), the result is \(\begin{bmatrix} a & e & 0 \\ d & b & 0 \\ 0 & 0 & 1 \end{bmatrix}^{-1} \begin{bmatrix} x \\ y \\ 1 \end{bmatrix}\). This is essentially the transposed inverse with translation removed.

@param {Vector2} v @returns {Vector2}

transformX( x )¶

Returns the resulting x-coordinate of the transformation of all vectors with the initial input x-coordinate. If this is not well-defined (the x value depends on y), an assertion is thrown (and y is assumed to be 0). @public

@param {number} x @returns {number}

transformY( y )¶

Returns the resulting y-coordinate of the transformation of all vectors with the initial input y-coordinate. If this is not well-defined (the y value depends on x), an assertion is thrown (and x is assumed to be 0). @public

@param {number} y @returns {number}

transformDeltaX( x )¶

Returns the x-coordinate difference for two transformed vectors, which add the x-coordinate difference of the input x (and same y values) beforehand. @public

@param {number} x @returns {number}

transformDeltaY( y )¶

Returns the y-coordinate difference for two transformed vectors, which add the y-coordinate difference of the input y (and same x values) beforehand. @public

@param {number} y @returns {number}

transformBounds2( bounds )¶

Returns bounds (axis-aligned) that contains the transformed bounds rectangle. @public

NOTE: transform.inverseBounds2( transform.transformBounds2( bounds ) ) may be larger than the original box, if it includes a rotation that isn't a multiple of \(\pi/2\). This is because the returned bounds may expand in area to cover ALL of the corners of the transformed bounding box.

@param {Bounds2} bounds @returns {Bounds2}

transformShape( shape )¶

Returns a transformed phet.kite.Shape. @public

@param {Shape} shape @returns {Shape}

transformRay2( ray )¶

Returns a transformed ray. @public

@param {Ray2} ray @returns {Ray2}

inversePosition2( v )¶

Transforms a 2-dimensional vector by the inverse of our transform like it is a point with a position (translation is applied). @public

For an affine matrix \(M\), the result is the homogeneous multiplication \(M^{-1}\begin{bmatrix} x \\ y \\ 1 \end{bmatrix}\).

This is the inverse of transformPosition2().

@param {Vector2} v @returns {Vector2}

inverseDelta2( v )¶

Transforms a 2-dimensional vector by the inverse of our transform like position is irrelevant (translation is not applied). @public

For an affine matrix \(\begin{bmatrix} a & b & c \\ d & e & f \\ 0 & 0 & 1 \end{bmatrix}\), the result is \(\begin{bmatrix} a & b & 0 \\ d & e & 0 \\ 0 & 0 & 1 \end{bmatrix}^{-1} \begin{bmatrix} x \\ y \\ 1 \end{bmatrix}\).

This is the inverse of transformDelta2().

@param {Vector2} v @returns {Vector2}

inverseNormal2( v )¶

Transforms a 2-dimensional vector by the inverse of our transform like it is a normal to a curve (so that the curve is transformed, and the new normal to the curve at the transformed point is returned). @public

For an affine matrix \(\begin{bmatrix} a & b & c \\ d & e & f \\ 0 & 0 & 1 \end{bmatrix}\), the result is \(\begin{bmatrix} a & e & 0 \\ d & b & 0 \\ 0 & 0 & 1 \end{bmatrix} \begin{bmatrix} x \\ y \\ 1 \end{bmatrix}\). This is essentially the transposed transform with translation removed.

This is the inverse of transformNormal2().

@param {Vector2} v @returns {Vector2}

inverseX( x )¶

Returns the resulting x-coordinate of the inverse transformation of all vectors with the initial input x-coordinate. If this is not well-defined (the x value depends on y), an assertion is thrown (and y is assumed to be 0). @public

This is the inverse of transformX().

@param {number} x @returns {number}

inverseY( y )¶

Returns the resulting y-coordinate of the inverse transformation of all vectors with the initial input y-coordinate. If this is not well-defined (the y value depends on x), an assertion is thrown (and x is assumed to be 0). @public

This is the inverse of transformY().

@param {number} y @returns {number}

inverseDeltaX( x )¶

Returns the x-coordinate difference for two inverse-transformed vectors, which add the x-coordinate difference of the input x (and same y values) beforehand. @public

This is the inverse of transformDeltaX().

@param {number} x @returns {number}

inverseDeltaY( y )¶

Returns the y-coordinate difference for two inverse-transformed vectors, which add the y-coordinate difference of the input y (and same x values) beforehand. @public

This is the inverse of transformDeltaY().

@param {number} y @returns {number}

inverseBounds2( bounds )¶

Returns bounds (axis-aligned) that contains the inverse-transformed bounds rectangle. @public

NOTE: transform.inverseBounds2( transform.transformBounds2( bounds ) ) may be larger than the original box, if it includes a rotation that isn't a multiple of \(\pi/2\). This is because the returned bounds may expand in area to cover ALL of the corners of the transformed bounding box.

@param {Bounds2} bounds @returns {Bounds2}

inverseShape( shape )¶

Returns an inverse-transformed phet.kite.Shape. @public

This is the inverse of transformShape()

@param {Shape} shape @returns {Shape}

inverseRay2( ray )¶

Returns an inverse-transformed ray. @public

This is the inverse of transformRay2()

@param {Ray2} ray @returns {Ray2}

Source Code¶

See the source for Transform3.js in the dot repository.