# Dot Documentation

## Introduction

To use Dot, first include references to Dot itself and Lodash (the only external dependency) in your HTML:

<script src="http://example.com/lodash.min.js"></script>
<script src="http://example.com/dot.min.js"></script>

Then Dot types and utilities can be accessed from the namespace:

var rotation = dot.Matrix3.rotationZ( Math.PI / 4 );

console.log( rotation.toString() );
// 0.7071067811865476 -0.7071067811865475 0
// 0.7071067811865475 0.7071067811865476 0
// 0 0 1

var vector = new dot.Vector2( 10, 0 );
var rotatedVector = rotation.timesVector2( vector );

console.log( rotatedVector.x, rotatedVector.y );
// 7.0710678118654755 7.071067811865475


## Building

Dot depends on a few other libraries, and needs to have them checked out as siblings. It is recommended to place all of these inside a containing directory. Make sure you have git installed, then run:

git clone https://github.com/phetsims/sherpa.git
git clone https://github.com/phetsims/chipper.git
git clone https://github.com/phetsims/axon.git
git clone https://github.com/phetsims/assert.git
git clone https://github.com/phetsims/phet-core.git
git clone https://github.com/phetsims/dot.git

For some examples and tests, and to build a custom version, you'll need to install node.js, and grunt-cli. Then,

cd dot
npm update
grunt

You will now have the built files under build/

## API Documentation

### BinPacker

Given a rectangular containing area, takes care of allocating and deallocating smaller rectangular "bins" that fit together inside the area and do not overlap. Optimized more for runtime CPU usage than space currently.

For example:

var binPacker = new dot.BinPacker( new dot.Bounds2( 0, 0, 256, 256 ) );
var bins = [];
for ( var i = 0; i < 100; i++ ) {
var bin = binPacker.allocate( Math.random() * 64, Math.random() * 64 );
if ( bin ) {
bins.push( bin );
}
}

#### BinPacker( Bounds2 bounds ) extends Object

Creates a BinPacker with the specified containing bounds.

 Bounds2 bounds - The available bounds to pack bins inside.
##### allocate( number width, number height ) : Bin|null

Allocates a bin with the specified width and height if possible (returning a {Bin}), otherwise returns null.

##### deallocate( Bin bin )

Deallocates a bin, so that its area can be reused by future allocations.

 Bin bin - The bin that was returned from allocate().

#### Bin( Bounds2 bounds, Bin|null parent )

A rectangular bin that can be used itself or split into sub-bins.

##### bounds Bounds2

Our containing bounds

### Bounds2

A 2D rectangle-shaped bounded area (bounding box).

There are a number of convenience functions to get locations and points on the Bounds. Currently we do not store these with the Bounds2 instance, since we want to lower the memory footprint.

minX, minY, maxX, and maxY are actually stored. We don't do x,y,width,height because this can't properly express semi-infinite bounds (like a half-plane), or easily handle what Bounds2.NOTHING and Bounds2.EVERYTHING do with the constructive solid areas.

#### Bounds2( number minX, number minY, number maxX, number maxY ) extends Object

Creates a 2-dimensional bounds (bounding box).

 number minX - The initial minimum X coordinate of the bounds. number minY - The initial minimum Y coordinate of the bounds. number maxX - The initial maximum X coordinate of the bounds. number maxY - The initial maximum Y coordinate of the bounds.
##### Bounds2.EVERYTHING Bounds2

A contant Bounds2 with minimums = $-\infty$, maximums = $\infty$, so that it represents "all bounds".

This allows us to take the intersection (intersection/constrainBounds) of this and any other Bounds2 to get the other bounds back, e.g. Bounds2.EVERYTHING.intersection( bounds ).equals( bounds ). This object naturally serves as the base case as an intersection of zero bounds objects.

Additionally, unions with EVERYTHING will always return a Bounds2 equivalent to EVERYTHING.

##### Bounds2.NOTHING Bounds2

A contant Bounds2 with minimums = $\infty$, maximums = $-\infty$, so that it represents "no bounds whatsoever".

This allows us to take the union (union/includeBounds) of this and any other Bounds2 to get the other bounds back, e.g. Bounds2.NOTHING.union( bounds ).equals( bounds ). This object naturally serves as the base case as a union of zero bounds objects.

Additionally, intersections with NOTHING will always return a Bounds2 equivalent to NOTHING.

##### Bounds2.point( number|Vector2 x, number] undefined ) : Bounds2

Returns a new Bounds2 object that only contains the specified point (x,y). Useful for being dilated to form a bounding box around a point. Note that the bounds will not be "empty" as it contains (x,y), but it will have zero area. The x and y coordinates can be specified by numbers or with at Vector2

##### Bounds2.rect( number x, number y, number width, number height ) : Bounds2

Returns a new Bounds2 object, with the familiar rectangle construction with x, y, width, and height.

 number x - The minimum value of X for the bounds. number y - The minimum value of Y for the bounds. number width - The width (maxX - minX) of the bounds. number height - The height (maxY - minY) of the bounds.
##### maxX number

The maximum X coordinate of the bounds.

##### maxY number

The maximum Y coordinate of the bounds.

##### minX number

The minimum X coordinate of the bounds.

##### minY number

The minimum Y coordinate of the bounds.

##### addCoordinates( number x, number y ) : Bounds2

Modifies this bounds so that it contains both its original bounds and the input point (x,y).

This is the mutable form of the function withCoordinates(). This will mutate (change) this bounds, in addition to returning this bounds itself.

##### addPoint( Vector2 point ) : Bounds2

Modifies this bounds so that it contains both its original bounds and the input point.

This is the mutable form of the function withPoint(). This will mutate (change) this bounds, in addition to returning this bounds itself.

##### bottom numbergetBottom() : number

Alias for maxY, when thinking in the UI-layout manner.

##### center Vector2getCenter() : Vector2

The point (centerX, centerY), in the center of the bounds.

##### centerBottom Vector2getCenterBottom() : Vector2

The point (centerX, maxY), in the UI-coordinate lower-center

##### centerTop Vector2getCenterTop() : Vector2

The point (centerX, minY), in the UI-coordinate upper-center.

##### centerX numbergetCenterX() : number

The horizontal (X-coordinate) center of the bounds, averaging the minX and maxX.

##### centerY numbergetCenterY() : number

The vertical (Y-coordinate) center of the bounds, averaging the minY and maxY.

##### closestPointTo( Vector2 location ) : Vector2

If the location is inside the bounds, the location will be returned. Otherwise, this will return a new location on the edge of the bounds that is the closest to the provided location.

##### constrainBounds( Bounds2 bounds ) : Bounds2

Modifies this bounds so that it is the largest bounds contained both in its original bounds and in the input bounds.

This is the mutable form of the function intersection(). This will mutate (change) this bounds, in addition to returning this bounds itself.

##### containsBounds( Bounds2 bounds ) : boolean

Whether this bounding box completely contains the bounding box passed as a parameter. The boundary of a box is considered to be "contained".

##### containsCoordinates( number x, number y ) : boolean

Whether the coordinates are contained inside the bounding box, or are on the boundary.

 number x - X coordinate of the point to check number y - Y coordinate of the point to check
##### containsPoint( Vector2 point ) : boolean

Whether the point is contained inside the bounding box, or is on the boundary.

##### copy( Bounds2 bounds ) : Bounds2

Creates a copy of this bounds, or if a bounds is passed in, set that bounds's values to ours.

This is the immutable form of the function set(), if a bounds is provided. This will return a new bounds, and will not modify this bounds.

 Bounds2 bounds - If not provided, creates a new Bounds2 with filled in values. Otherwise, fills in the values of the provided bounds so that it equals this bounds.
##### dilate( number d ) : Bounds2

Expands this bounds on all sides by the specified amount.

This is the mutable form of the function dilated(). This will mutate (change) this bounds, in addition to returning this bounds itself.

##### dilateX( number x ) : Bounds2

Expands this bounds horizontally (left and right) by the specified amount.

This is the mutable form of the function dilatedX(). This will mutate (change) this bounds, in addition to returning this bounds itself.

##### dilateXY( number x, number y ) : Bounds2

Expands this bounds independently in the horizontal and vertical directions. Will be equal to calling bounds.dilateX( x ).dilateY( y ).

This is the mutable form of the function dilatedXY(). This will mutate (change) this bounds, in addition to returning this bounds itself.

##### dilateY( number y ) : Bounds2

Expands this bounds vertically (top and bottom) by the specified amount.

This is the mutable form of the function dilatedY(). This will mutate (change) this bounds, in addition to returning this bounds itself.

##### dilated( number d ) : Bounds2

A bounding box that is expanded on all sides by the specified amount.)

This is the immutable form of the function dilate(). This will return a new bounds, and will not modify this bounds.

##### dilatedX( number x ) : Bounds2

A bounding box that is expanded horizontally (on the left and right) by the specified amount.

This is the immutable form of the function dilateX(). This will return a new bounds, and will not modify this bounds.

##### dilatedXY( number x, number y ) : Bounds2

A bounding box that is expanded on all sides, with different amounts of expansion horizontally and vertically. Will be identical to the bounds returned by calling bounds.dilatedX( x ).dilatedY( y ).

This is the immutable form of the function dilateXY(). This will return a new bounds, and will not modify this bounds.

 number x - Amount to dilate horizontally (for each side) number y - Amount to dilate vertically (for each side)
##### dilatedY( number y ) : Bounds2

A bounding box that is expanded vertically (on the top and bottom) by the specified amount.

This is the immutable form of the function dilateY(). This will return a new bounds, and will not modify this bounds.

##### equals( Bounds2 other ) : boolean

Exact equality comparison between this bounds and another bounds.

##### equalsEpsilon( Bounds2 other, number epsilon ) : boolean

Approximate equality comparison between this bounds and another bounds.

##### erode( number d ) : Bounds2

Contracts this bounds on all sides by the specified amount.

This is the mutable form of the function eroded(). This will mutate (change) this bounds, in addition to returning this bounds itself.

##### erodeX( number x ) : Bounds2

Contracts this bounds horizontally (left and right) by the specified amount.

This is the mutable form of the function erodedX(). This will mutate (change) this bounds, in addition to returning this bounds itself.

##### erodeXY( number x, number y ) : Bounds2

Contracts this bounds independently in the horizontal and vertical directions. Will be equal to calling bounds.erodeX( x ).erodeY( y ).

This is the mutable form of the function erodedXY(). This will mutate (change) this bounds, in addition to returning this bounds itself.

##### erodeY( number y ) : Bounds2

Contracts this bounds vertically (top and bottom) by the specified amount.

This is the mutable form of the function erodedY(). This will mutate (change) this bounds, in addition to returning this bounds itself.

##### eroded( number amount ) : Bounds2

A bounding box that is contracted on all sides by the specified amount.

This is the immutable form of the function erode(). This will return a new bounds, and will not modify this bounds.

##### erodedX( number x ) : Bounds2

A bounding box that is contracted horizontally (on the left and right) by the specified amount.

This is the immutable form of the function erodeX(). This will return a new bounds, and will not modify this bounds.

##### erodedXY( number x, number y ) : Bounds2

A bounding box that is contracted on all sides, with different amounts of contraction horizontally and vertically.

This is the immutable form of the function erodeXY(). This will return a new bounds, and will not modify this bounds.

 number x - Amount to erode horizontally (for each side) number y - Amount to erode vertically (for each side)
##### erodedY( number y ) : Bounds2

A bounding box that is contracted vertically (on the top and bottom) by the specified amount.

This is the immutable form of the function erodeY(). This will return a new bounds, and will not modify this bounds.

##### getClosestPoint( number x, number y, Vector2 result ) : Vector2

Find a point in the bounds closest to the specified point.

 number x - X coordinate of the point to test. number y - Y coordinate of the point to test. Vector2 result - Vector2 that can store the return value to avoid allocations.
##### getMaxX() : number

Alias for maxX, supporting the explicit getter function style.

##### getMaxY() : number

Alias for maxY, supporting the explicit getter function style.

##### getMinX() : number

Alias for minX, supporting the explicit getter function style.

##### getMinY() : number

Alias for minY, supporting the explicit getter function style.

##### hasNonzeroArea() : boolean

Whether this bounds has a non-zero area (non-zero positive width and height).

##### height numbergetHeight() : number

The height of the bounds, defined as maxY - minY.

##### includeBounds( Bounds2 bounds ) : Bounds2

Modifies this bounds so that it contains both its original bounds and the input bounds.

This is the mutable form of the function union(). This will mutate (change) this bounds, in addition to returning this bounds itself.

##### intersection( Bounds2 bounds ) : Bounds2

The smallest bounds that is contained by both this bounds and the input bounds, returned as a copy.

This is the immutable form of the function constrainBounds(). This will return a new bounds, and will not modify this bounds.

##### intersectsBounds( Bounds2 bounds ) : boolean

Whether this and another bounding box have any points of intersection (including touching boundaries).

##### isEmpty() : boolean

Whether we have negative width or height. Bounds2.NOTHING is a prime example of an empty Bounds2. Bounds with width = height = 0 are considered not empty, since they include the single (0,0) point.

##### isFinite() : boolean

Whether our minimums and maximums are all finite numbers. This will exclude Bounds2.NOTHING and Bounds2.EVERYTHING.

##### isValid() : boolean

Whether this bounds has a finite and non-negative width and height.

##### left numbergetLeft() : number

Alias for minX, when thinking in the UI-layout manner.

##### leftBottom Vector2getLeftBottom() : Vector2

The point (minX, maxY), in the UI-coordinate lower-left

##### leftCenter Vector2getLeftCenter() : Vector2

The point (left, centerY), in the UI-coordinate center-left.

##### leftTop Vector2getLeftTop() : Vector2

The point (minX, minY), in the UI-coordinate upper-left.

##### maximumDistanceToPointSquared( Vector2 point ) : number

The squared distance from the input point to the point furthest from it inside the bounding box.

##### minimumDistanceToPointSquared( Vector2 point ) : number

The squared distance from the input point to the point closest to it inside the bounding box.

##### offset( number left, number top, number right, number bottom ) : Bounds2

Expands this bounds independently for each side (or if some offsets are negative, will contract those sides).

This is the mutable form of the function withOffsets(). This will mutate (change) this bounds, in addition to returning this bounds itself.

 number left - Amount to expand to the left (subtracts from minX) number top - Amount to expand to the top (subtracts from minY) number right - Amount to expand to the right (adds to maxX) number bottom - Amount to expand to the bottom (adds to maxY)
##### right numbergetRight() : number

Alias for maxX, when thinking in the UI-layout manner.

##### rightBottom Vector2getRightBottom() : Vector2

The point (maxX, maxY), in the UI-coordinate lower-right

##### rightCenter Vector2getRightCenter() : Vector2

The point (maxX, centerY), in the UI-coordinate center-right

##### rightTop Vector2getRightTop() : Vector2

The point (right, minY), in the UI-coordinate upper-right.

##### roundIn() : Bounds2

Modifies this bounds so that its boundaries are integer-aligned, rounding the minimum boundaries up and the maximum boundaries down (contracting as necessary).

This is the mutable form of the function roundedIn(). This will mutate (change) this bounds, in addition to returning this bounds itself.

##### roundOut() : Bounds2

Modifies this bounds so that its boundaries are integer-aligned, rounding the minimum boundaries down and the maximum boundaries up (expanding as necessary).

This is the mutable form of the function roundedOut(). This will mutate (change) this bounds, in addition to returning this bounds itself.

##### roundedIn() : Bounds2

A copy of this bounds, with the minimum values rounded up to the nearest integer, and the maximum values rounded down to the nearest integer. This causes the bounds to contract as necessary so that its boundaries are integer-aligned.

This is the immutable form of the function roundIn(). This will return a new bounds, and will not modify this bounds.

##### roundedOut() : Bounds2

A copy of this bounds, with the minimum values rounded down to the nearest integer, and the maximum values rounded up to the nearest integer. This causes the bounds to expand as necessary so that its boundaries are integer-aligned.

This is the immutable form of the function roundOut(). This will return a new bounds, and will not modify this bounds.

##### set( Bounds2 bounds ) : Bounds2

Sets the values of this bounds to be equal to the input bounds.

This is the mutable form of the function copy(). This will mutate (change) this bounds, in addition to returning this bounds itself.

##### setMaxX( number maxX ) : Bounds2

Sets the value of maxX.

This is the mutable form of the function withMaxX(). This will mutate (change) this bounds, in addition to returning this bounds itself.

##### setMaxY( number maxY ) : Bounds2

Sets the value of maxY.

This is the mutable form of the function withMaxY(). This will mutate (change) this bounds, in addition to returning this bounds itself.

##### setMinMax( number minX, number minY, number maxX, number maxY ) : Bounds2

Sets each value for this bounds, and returns itself.

##### setMinX( number minX ) : Bounds2

Sets the value of minX.

This is the mutable form of the function withMinX(). This will mutate (change) this bounds, in addition to returning this bounds itself.

##### setMinY( number minY ) : Bounds2

Sets the value of minY.

This is the mutable form of the function withMinY(). This will mutate (change) this bounds, in addition to returning this bounds itself.

##### shift( number x, number y ) : Bounds2

Translates our bounds by (x,y).

This is the mutable form of the function shifted(). This will mutate (change) this bounds, in addition to returning this bounds itself.

##### shiftX( number x ) : Bounds2

Translates our bounds horizontally by x.

This is the mutable form of the function shiftedX(). This will mutate (change) this bounds, in addition to returning this bounds itself.

##### shiftY( number y ) : Bounds2

Translates our bounds vertically by y.

This is the mutable form of the function shiftedY(). This will mutate (change) this bounds, in addition to returning this bounds itself.

##### shifted( number x, number y ) : Bounds2

Our bounds, translated by (x,y), returned as a copy.

This is the immutable form of the function shift(). This will return a new bounds, and will not modify this bounds.

##### shiftedX( number x ) : Bounds2

Our bounds, translated horizontally by x, returned as a copy.

This is the immutable form of the function shiftX(). This will return a new bounds, and will not modify this bounds.

##### shiftedY( number y ) : Bounds2

Our bounds, translated vertically by y, returned as a copy.

This is the immutable form of the function shiftY(). This will return a new bounds, and will not modify this bounds.

##### toString() : string

Debugging string for the bounds.

##### top numbergetTop() : number

Alias for minY, when thinking in the UI-layout manner.

##### transform( Matrix3 matrix ) : Bounds2

Modifies this bounds so that it would fully contain a transformed version if its previous value, applying the matrix as an affine transformation.

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

This is the mutable form of the function transformed(). This will mutate (change) this bounds, in addition to returning this bounds itself.

##### transformed( Matrix3 matrix ) : Bounds2

A bounding box (still axis-aligned) that contains the transformed shape of this bounds, applying the matrix as an affine transformation.

NOTE: bounds.transformed( matrix ).transformed( inverse ) 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.

This is the immutable form of the function transform(). This will return a new bounds, and will not modify this bounds.

##### union( Bounds2 bounds ) : Bounds2

The smallest bounds that contains both this bounds and the input bounds, returned as a copy.

This is the immutable form of the function includeBounds(). This will return a new bounds, and will not modify this bounds.

##### width numbergetWidth() : number

The width of the bounds, defined as maxX - minX.

##### withCoordinates( number x, number y ) : Bounds2

The smallest bounds that contains this bounds and the point (x,y), returned as a copy.

This is the immutable form of the function addCoordinates(). This will return a new bounds, and will not modify this bounds.

##### withMaxX( number maxX ) : Bounds2

A copy of this bounds, with maxX replaced with the input.

This is the immutable form of the function setMaxX(). This will return a new bounds, and will not modify this bounds.

##### withMaxY( number maxY ) : Bounds2

A copy of this bounds, with maxY replaced with the input.

This is the immutable form of the function setMaxY(). This will return a new bounds, and will not modify this bounds.

##### withMinX( number minX ) : Bounds2

A copy of this bounds, with minX replaced with the input.

This is the immutable form of the function setMinX(). This will return a new bounds, and will not modify this bounds.

##### withMinY( number minY ) : Bounds2

A copy of this bounds, with minY replaced with the input.

This is the immutable form of the function setMinY(). This will return a new bounds, and will not modify this bounds.

##### withOffsets( number left, number top, number right, number bottom ) : Bounds2

A bounding box that is expanded by a specific amount on all sides (or if some offsets are negative, will contract those sides).

This is the immutable form of the function offset(). This will return a new bounds, and will not modify this bounds.

 number left - Amount to expand to the left (subtracts from minX) number top - Amount to expand to the top (subtracts from minY) number right - Amount to expand to the right (adds to maxX) number bottom - Amount to expand to the bottom (adds to maxY)
##### withPoint( Vector2 point ) : Bounds2

The smallest bounds that contains this bounds and the input point, returned as a copy.

This is the immutable form of the function addPoint(). This will return a new bounds, and will not modify this bounds.

##### x numbergetX() : number

Alias for minX, when thinking of the bounds as an (x,y,width,height) rectangle.

##### y numbergetY() : number

Alias for minY, when thinking of the bounds as an (x,y,width,height) rectangle.

### Bounds3

A 3D cuboid-shaped bounded area (bounding box).

There are a number of convenience functions to get locations and points on the Bounds. Currently we do not store these with the Bounds3 instance, since we want to lower the memory footprint.

minX, minY, minZ, maxX, maxY, and maxZ are actually stored. We don't do x,y,z,width,height,depth because this can't properly express semi-infinite bounds (like a half-plane), or easily handle what Bounds3.NOTHING and Bounds3.EVERYTHING do with the constructive solid areas.

#### Bounds3( number minX, number minY, number minZ, number maxX, number maxY, number maxZ ) extends Object

Creates a 3-dimensional bounds (bounding box).

 number minX - The initial minimum X coordinate of the bounds. number minY - The initial minimum Y coordinate of the bounds. number minZ - The initial minimum Z coordinate of the bounds. number maxX - The initial maximum X coordinate of the bounds. number maxY - The initial maximum Y coordinate of the bounds. number maxZ - The initial maximum Z coordinate of the bounds.
##### Bounds3.EVERYTHING Bounds3

A contant Bounds3 with minimums = $-\infty$, maximums = $\infty$, so that it represents "all bounds".

This allows us to take the intersection (intersection/constrainBounds) of this and any other Bounds3 to get the other bounds back, e.g. Bounds3.EVERYTHING.intersection( bounds ).equals( bounds ). This object naturally serves as the base case as an intersection of zero bounds objects.

Additionally, unions with EVERYTHING will always return a Bounds3 equivalent to EVERYTHING.

##### Bounds3.NOTHING Bounds3

A contant Bounds3 with minimums = $\infty$, maximums = $-\infty$, so that it represents "no bounds whatsoever".

This allows us to take the union (union/includeBounds) of this and any other Bounds3 to get the other bounds back, e.g. Bounds3.NOTHING.union( bounds ).equals( bounds ). This object naturally serves as the base case as a union of zero bounds objects.

Additionally, intersections with NOTHING will always return a Bounds3 equivalent to NOTHING.

##### Bounds3.cuboid( number x, number y, number z, number width, number height, number depth ) : Bounds3

Returns a new Bounds3 object, with the cuboid (3d rectangle) construction with x, y, z, width, height and depth.

 number x - The minimum value of X for the bounds. number y - The minimum value of Y for the bounds. number z - The minimum value of Z for the bounds. number width - The width (maxX - minX) of the bounds. number height - The height (maxY - minY) of the bounds. number depth - The depth (maxZ - minZ) of the bounds.
##### Bounds3.point( number x, number y, number z ) : Bounds3

Returns a new Bounds3 object that only contains the specified point (x,y,z). Useful for being dilated to form a bounding box around a point. Note that the bounds will not be "empty" as it contains (x,y,z), but it will have zero area.

##### maxX number

The maximum X coordinate of the bounds.

##### maxY number

The maximum Y coordinate of the bounds.

##### maxZ number

The maximum Z coordinate of the bounds.

##### minX number

The minimum X coordinate of the bounds.

##### minY number

The minimum Y coordinate of the bounds.

##### minZ number

The minimum Z coordinate of the bounds.

##### addCoordinates( number x, number y, number z ) : Bounds3

Modifies this bounds so that it contains both its original bounds and the input point (x,y,z).

This is the mutable form of the function withCoordinates(). This will mutate (change) this bounds, in addition to returning this bounds itself.

##### addPoint( Vector3 point ) : Bounds3

Modifies this bounds so that it contains both its original bounds and the input point.

This is the mutable form of the function withPoint(). This will mutate (change) this bounds, in addition to returning this bounds itself.

##### back numbergetBack() : number

Alias for minZ, when thinking in the UI-layout manner.

##### bottom numbergetBottom() : number

Alias for maxY, when thinking in the UI-layout manner.

##### center Vector3getCenter() : Vector3

The point (centerX, centerY, centerZ), in the center of the bounds.

##### centerX numbergetCenterX() : number

The horizontal (X-coordinate) center of the bounds, averaging the minX and maxX.

##### centerY numbergetCenterY() : number

The vertical (Y-coordinate) center of the bounds, averaging the minY and maxY.

##### centerZ numbergetCenterZ() : number

The depthwise (Z-coordinate) center of the bounds, averaging the minZ and maxZ.

##### constrainBounds( Bounds3 bounds ) : Bounds3

Modifies this bounds so that it is the largest bounds contained both in its original bounds and in the input bounds.

This is the mutable form of the function intersection(). This will mutate (change) this bounds, in addition to returning this bounds itself.

##### containsBounds( Bounds3 bounds ) : boolean

Whether this bounding box completely contains the bounding box passed as a parameter. The boundary of a box is considered to be "contained".

##### containsCoordinates( number x, number y, number z ) : boolean

Whether the coordinates are contained inside the bounding box, or are on the boundary.

 number x - X coordinate of the point to check number y - Y coordinate of the point to check number z - Z coordinate of the point to check
##### containsPoint( Vector3 point ) : boolean

Whether the point is contained inside the bounding box, or is on the boundary.

##### copy( Bounds3 bounds ) : Bounds3

Creates a copy of this bounds, or if a bounds is passed in, set that bounds's values to ours.

This is the immutable form of the function set(), if a bounds is provided. This will return a new bounds, and will not modify this bounds.

 Bounds3 bounds - If not provided, creates a new Bounds3 with filled in values. Otherwise, fills in the values of the provided bounds so that it equals this bounds.
##### depth numbergetDepth() : number

The depth of the bounds, defined as maxZ - minZ.

##### dilate( number d ) : Bounds3

Expands this bounds on all sides by the specified amount.

This is the mutable form of the function dilated(). This will mutate (change) this bounds, in addition to returning this bounds itself.

##### dilateX( number x ) : Bounds3

Expands this bounds horizontally (left and right) by the specified amount.

This is the mutable form of the function dilatedX(). This will mutate (change) this bounds, in addition to returning this bounds itself.

##### dilateXYZ( number x, number y, number z ) : Bounds3

Expands this bounds independently along each axis. Will be equal to calling bounds.dilateX( x ).dilateY( y ).dilateZ( z ).

This is the mutable form of the function dilatedXYZ(). This will mutate (change) this bounds, in addition to returning this bounds itself.

##### dilateY( number y ) : Bounds3

Expands this bounds vertically (top and bottom) by the specified amount.

This is the mutable form of the function dilatedY(). This will mutate (change) this bounds, in addition to returning this bounds itself.

##### dilateZ( number z ) : Bounds3

Expands this bounds depth-wise (front and back) by the specified amount.

This is the mutable form of the function dilatedZ(). This will mutate (change) this bounds, in addition to returning this bounds itself.

##### dilated( number d ) : Bounds3

A bounding box that is expanded on all sides by the specified amount.)

This is the immutable form of the function dilate(). This will return a new bounds, and will not modify this bounds.

##### dilatedX( number x ) : Bounds3

A bounding box that is expanded horizontally (on the left and right) by the specified amount.

This is the immutable form of the function dilateX(). This will return a new bounds, and will not modify this bounds.

##### dilatedXYZ( number x, number y, number z ) : Bounds3

A bounding box that is expanded on all sides, with different amounts of expansion along each axis. Will be identical to the bounds returned by calling bounds.dilatedX( x ).dilatedY( y ).dilatedZ( z ).

This is the immutable form of the function dilateXYZ(). This will return a new bounds, and will not modify this bounds.

 number x - Amount to dilate horizontally (for each side) number y - Amount to dilate vertically (for each side) number z - Amount to dilate depth-wise (for each side)
##### dilatedY( number y ) : Bounds3

A bounding box that is expanded vertically (on the top and bottom) by the specified amount.

This is the immutable form of the function dilateY(). This will return a new bounds, and will not modify this bounds.

##### dilatedZ( number z ) : Bounds3

A bounding box that is expanded depth-wise (on the front and back) by the specified amount.

This is the immutable form of the function dilateZ(). This will return a new bounds, and will not modify this bounds.

##### equals( Bounds3 other ) : boolean

Exact equality comparison between this bounds and another bounds.

##### equalsEpsilon( Bounds3 other, number epsilon ) : boolean

Approximate equality comparison between this bounds and another bounds.

##### erode( number d ) : Bounds3

Contracts this bounds on all sides by the specified amount.

This is the mutable form of the function eroded(). This will mutate (change) this bounds, in addition to returning this bounds itself.

##### erodeX( number x ) : Bounds3

Contracts this bounds horizontally (left and right) by the specified amount.

This is the mutable form of the function erodedX(). This will mutate (change) this bounds, in addition to returning this bounds itself.

##### erodeXYZ( number x, number y, number z ) : Bounds3

Contracts this bounds independently along each axis. Will be equal to calling bounds.erodeX( x ).erodeY( y ).erodeZ( z ).

This is the mutable form of the function erodedXYZ(). This will mutate (change) this bounds, in addition to returning this bounds itself.

##### erodeY( number y ) : Bounds3

Contracts this bounds vertically (top and bottom) by the specified amount.

This is the mutable form of the function erodedY(). This will mutate (change) this bounds, in addition to returning this bounds itself.

##### erodeZ( number z ) : Bounds3

Contracts this bounds depth-wise (front and back) by the specified amount.

This is the mutable form of the function erodedZ(). This will mutate (change) this bounds, in addition to returning this bounds itself.

##### eroded( number amount ) : Bounds3

A bounding box that is contracted on all sides by the specified amount.

This is the immutable form of the function erode(). This will return a new bounds, and will not modify this bounds.

##### erodedX( number x ) : Bounds3

A bounding box that is contracted horizontally (on the left and right) by the specified amount.

This is the immutable form of the function erodeX(). This will return a new bounds, and will not modify this bounds.

##### erodedXYZ( number x, number y, number z ) : Bounds3

A bounding box that is contracted on all sides, with different amounts of contraction along each axis.

This is the immutable form of the function erodeXYZ(). This will return a new bounds, and will not modify this bounds.

 number x - Amount to erode horizontally (for each side) number y - Amount to erode vertically (for each side) number z - Amount to erode depth-wise (for each side)
##### erodedY( number y ) : Bounds3

A bounding box that is contracted vertically (on the top and bottom) by the specified amount.

This is the immutable form of the function erodeY(). This will return a new bounds, and will not modify this bounds.

##### erodedZ( number z ) : Bounds3

A bounding box that is contracted depth-wise (on the front and back) by the specified amount.

This is the immutable form of the function erodeZ(). This will return a new bounds, and will not modify this bounds.

##### front numbergetFront() : number

Alias for maxZ, when thinking in the UI-layout manner.

##### getMaxX() : number

Alias for maxX, supporting the explicit getter function style.

##### getMaxY() : number

Alias for maxY, supporting the explicit getter function style.

##### getMaxZ() : number

Alias for maxZ, supporting the explicit getter function style.

##### getMinX() : number

Alias for minX, supporting the explicit getter function style.

##### getMinY() : number

Alias for minY, supporting the explicit getter function style.

##### getMinZ() : number

Alias for minZ, supporting the explicit getter function style.

##### hasNonzeroArea() : boolean

Whether this bounds has a non-zero area (non-zero positive width, height and depth).

##### height numbergetHeight() : number

The height of the bounds, defined as maxY - minY.

##### includeBounds( Bounds3 bounds ) : Bounds3

Modifies this bounds so that it contains both its original bounds and the input bounds.

This is the mutable form of the function union(). This will mutate (change) this bounds, in addition to returning this bounds itself.

##### intersection( Bounds3 bounds ) : Bounds3

The smallest bounds that is contained by both this bounds and the input bounds, returned as a copy.

This is the immutable form of the function constrainBounds(). This will return a new bounds, and will not modify this bounds.

##### intersectsBounds( Bounds3 bounds ) : boolean

Whether this and another bounding box have any points of intersection (including touching boundaries).

##### isEmpty() : boolean

Whether we have negative width, height or depth. Bounds3.NOTHING is a prime example of an empty Bounds3. Bounds with width = height = depth = 0 are considered not empty, since they include the single (0,0,0) point.

##### isFinite() : boolean

Whether our minimums and maximums are all finite numbers. This will exclude Bounds3.NOTHING and Bounds3.EVERYTHING.

##### isValid() : boolean

Whether this bounds has a finite and non-negative width, height and depth.

##### left numbergetLeft() : number

Alias for minX, when thinking in the UI-layout manner.

##### right numbergetRight() : number

Alias for maxX, when thinking in the UI-layout manner.

##### roundIn() : Bounds3

Modifies this bounds so that its boundaries are integer-aligned, rounding the minimum boundaries up and the maximum boundaries down (contracting as necessary).

This is the mutable form of the function roundedIn(). This will mutate (change) this bounds, in addition to returning this bounds itself.

##### roundOut() : Bounds3

Modifies this bounds so that its boundaries are integer-aligned, rounding the minimum boundaries down and the maximum boundaries up (expanding as necessary).

This is the mutable form of the function roundedOut(). This will mutate (change) this bounds, in addition to returning this bounds itself.

##### roundedIn() : Bounds3

A copy of this bounds, with the minimum values rounded up to the nearest integer, and the maximum values rounded down to the nearest integer. This causes the bounds to contract as necessary so that its boundaries are integer-aligned.

This is the immutable form of the function roundIn(). This will return a new bounds, and will not modify this bounds.

##### roundedOut() : Bounds3

A copy of this bounds, with the minimum values rounded down to the nearest integer, and the maximum values rounded up to the nearest integer. This causes the bounds to expand as necessary so that its boundaries are integer-aligned.

This is the immutable form of the function roundOut(). This will return a new bounds, and will not modify this bounds.

##### set( Bounds3 bounds ) : Bounds3

Sets the values of this bounds to be equal to the input bounds.

This is the mutable form of the function copy(). This will mutate (change) this bounds, in addition to returning this bounds itself.

##### setMaxX( number maxX ) : Bounds3

Sets the value of maxX.

This is the mutable form of the function withMaxX(). This will mutate (change) this bounds, in addition to returning this bounds itself.

##### setMaxY( number maxY ) : Bounds3

Sets the value of maxY.

This is the mutable form of the function withMaxY(). This will mutate (change) this bounds, in addition to returning this bounds itself.

##### setMaxZ( number maxZ ) : Bounds3

Sets the value of maxZ.

This is the mutable form of the function withMaxZ(). This will mutate (change) this bounds, in addition to returning this bounds itself.

##### setMinMax( number minX, number minY, number minZ, number maxX, number maxY, number maxZ ) : Bounds3

Sets each value for this bounds, and returns itself.

##### setMinX( number minX ) : Bounds3

Sets the value of minX.

This is the mutable form of the function withMinX(). This will mutate (change) this bounds, in addition to returning this bounds itself.

##### setMinY( number minY ) : Bounds3

Sets the value of minY.

This is the mutable form of the function withMinY(). This will mutate (change) this bounds, in addition to returning this bounds itself.

##### setMinZ( number minZ ) : Bounds3

Sets the value of minZ.

This is the mutable form of the function withMinZ(). This will mutate (change) this bounds, in addition to returning this bounds itself.

##### shift( number x, number y, number z ) : Bounds3

Translates our bounds by (x,y,z).

This is the mutable form of the function shifted(). This will mutate (change) this bounds, in addition to returning this bounds itself.

##### shiftX( number x ) : Bounds3

Translates our bounds horizontally by x.

This is the mutable form of the function shiftedX(). This will mutate (change) this bounds, in addition to returning this bounds itself.

##### shiftY( number y ) : Bounds3

Translates our bounds vertically by y.

This is the mutable form of the function shiftedY(). This will mutate (change) this bounds, in addition to returning this bounds itself.

##### shiftZ( number z ) : Bounds3

Translates our bounds depth-wise by z.

This is the mutable form of the function shiftedZ(). This will mutate (change) this bounds, in addition to returning this bounds itself.

##### shifted( number x, number y, number z ) : Bounds3

Our bounds, translated by (x,y,z), returned as a copy.

This is the immutable form of the function shift(). This will return a new bounds, and will not modify this bounds.

##### shiftedX( number x ) : Bounds3

Our bounds, translated horizontally by x, returned as a copy.

This is the immutable form of the function shiftX(). This will return a new bounds, and will not modify this bounds.

##### shiftedY( number y ) : Bounds3

Our bounds, translated vertically by y, returned as a copy.

This is the immutable form of the function shiftY(). This will return a new bounds, and will not modify this bounds.

##### shiftedZ( number z ) : Bounds3

Our bounds, translated depth-wise by z, returned as a copy.

This is the immutable form of the function shiftZ(). This will return a new bounds, and will not modify this bounds.

##### toString() : string

Debugging string for the bounds.

##### top numbergetTop() : number

Alias for minY, when thinking in the UI-layout manner.

##### transform( Matrix4 matrix ) : Bounds3

Modifies this bounds so that it would fully contain a transformed version if its previous value, applying the matrix as an affine transformation.

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

This is the mutable form of the function transformed(). This will mutate (change) this bounds, in addition to returning this bounds itself.

##### transformed( Matrix4 matrix ) : Bounds3

A bounding box (still axis-aligned) that contains the transformed shape of this bounds, applying the matrix as an affine transformation.

NOTE: bounds.transformed( matrix ).transformed( inverse ) 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.

This is the immutable form of the function transform(). This will return a new bounds, and will not modify this bounds.

##### union( Bounds3 bounds ) : Bounds3

The smallest bounds that contains both this bounds and the input bounds, returned as a copy.

This is the immutable form of the function includeBounds(). This will return a new bounds, and will not modify this bounds.

##### width numbergetWidth() : number

The width of the bounds, defined as maxX - minX.

##### withCoordinates( number x, number y, number z ) : Bounds3

The smallest bounds that contains this bounds and the point (x,y,z), returned as a copy.

This is the immutable form of the function addCoordinates(). This will return a new bounds, and will not modify this bounds.

##### withMaxX( number maxX ) : Bounds3

A copy of this bounds, with maxX replaced with the input.

This is the immutable form of the function setMaxX(). This will return a new bounds, and will not modify this bounds.

##### withMaxY( number maxY ) : Bounds3

A copy of this bounds, with maxY replaced with the input.

This is the immutable form of the function setMaxY(). This will return a new bounds, and will not modify this bounds.

##### withMaxZ( number maxZ ) : Bounds3

A copy of this bounds, with maxZ replaced with the input.

This is the immutable form of the function setMaxZ(). This will return a new bounds, and will not modify this bounds.

##### withMinX( number minX ) : Bounds3

A copy of this bounds, with minX replaced with the input.

This is the immutable form of the function setMinX(). This will return a new bounds, and will not modify this bounds.

##### withMinY( number minY ) : Bounds3

A copy of this bounds, with minY replaced with the input.

This is the immutable form of the function setMinY(). This will return a new bounds, and will not modify this bounds.

##### withMinZ( number minZ ) : Bounds3

A copy of this bounds, with minZ replaced with the input.

This is the immutable form of the function setMinZ(). This will return a new bounds, and will not modify this bounds.

##### withPoint( Vector3 point ) : Bounds3

The smallest bounds that contains this bounds and the input point, returned as a copy.

This is the immutable form of the function addPoint(). This will return a new bounds, and will not modify this bounds.

##### x numbergetX() : number

Alias for minX, when thinking of the bounds as an (x,y,z,width,height,depth) cuboid.

##### y numbergetY() : number

Alias for minY, when thinking of the bounds as an (x,y,z,width,height,depth) cuboid.

##### z numbergetZ() : number

Alias for minZ, when thinking of the bounds as an (x,y,z,width,height,depth) cuboid.

### Complex

A complex number with mutable and immutable methods.

#### Complex( number real, number imaginary ) extends Object

Creates a complex number, that has both a real and imaginary part.

 number real - The real part. For a complex number $a+bi$, this should be $a$. number imaginary - The imaginary part. For a complex number $a+bi$, this should be $b$.
##### Complex.I Complex

Immutable constant $i$, the imaginary unit.

##### Complex.ONE Complex

Immutable constant $1$.

##### Complex.ZERO Complex

Immutable constant $0$.

##### Complex.createPolar( number magnitude, number phase ) : Complex

Constructs a complex number from the polar form. For a magnitude $r$ and phase $\varphi$, this will be $\cos\varphi+i r\sin\varphi$.

##### Complex.imaginary( number imaginary ) : Complex

Constructs a complex number from just the imaginary part (assuming the real part is 0).

##### Complex.real( number real ) : Complex

Constructs a complex number from just the real part (assuming the imaginary part is 0).

##### imaginary number

The imaginary part. For a complex number $a+bi$, this is $b$.

##### real number

The real part. For a complex number $a+bi$, this is $a$.

##### add( Complex c ) : Complex

Addition of this Complex and another Complex, returning a copy.

This is the mutable form of the function plus(). This will modify and return this.

##### conjugate() : Complex

Complex conjugate. Mutable form of conjugated

##### conjugated() : Complex

Complex conjugate. Immutable form of conjugate

##### copy( Complex complex ) : Complex

Creates a copy of this complex, or if a complex is passed in, set that complex's values to ours.

This is the immutable form of the function set(), if a complex is provided. This will return a new complex, and will not modify this complex.

 Complex complex - If not provided, creates a new Complex with filled in values. Otherwise, fills in the values of the provided complex so that it equals this complex.
##### cos() : Complex

Cosine. Mutable form of cosOf.

##### cosOf() : Complex

Cosine. Immutable form of cos.

##### divide( Complex c ) : Complex

Mutable Complex division. The immutable form is dividedBy.

##### dividedBy( Complex c ) : Complex

Complex division. Immutable version of divide

##### equals( Complex other ) : boolean

Exact equality comparison between this Complex and another Complex.

##### equalsEpsilon( Complex other, number epsilon ) : boolean

Approximate equality comparison between this Complex and another Complex.

##### exponentiate() : Complex

Sets this Complex to e to the power of this complex number. $e^{a+bi}=e^a\cos b + i\sin b$. This is the mutable version of exponentiated

##### exponentiated() : Complex

Takes e to the power of this complex number. $e^{a+bi}=e^a\cos b + i\sin b$. This is the immutable form of exponentiate.

##### magnitude() : number

The magnitude (Euclidean/L2 Norm) of this complex number, i.e. $\sqrt{a^2+b^2}$.

##### magnitudeSquared() : number

The squared magnitude (square of the Euclidean/L2 Norm) of this complex, i.e. $a^2+b^2$.

##### minus( Complex c ) : Complex

Subtraction of this Complex by another Complex c, returning a copy.

This is the immutable form of the function subtract(). This will return a new Complex, and will not modify this Complex.

##### multiply( Complex c ) : Complex

Mutable Complex multiplication.

##### phase() : number

The phase / argument of the complex number.

##### plus( Complex c ) : Complex

Addition of this Complex and another Complex, returning a copy.

This is the immutable form of the function add(). This will return a new Complex, and will not modify this Complex.

##### set( Complex c ) : Complex

Sets the components of this complex to be a copy of the parameter

This is the mutable form of the function copy(). This will mutate (change) this complex, in addition to returning this complex itself.

##### setImaginary( number imaginary ) : Complex

Sets the imaginary component of this complex, returning this

##### setPolar( number magnitude, number phase ) : Complex

Sets this Complex's value to be the a,b values matching the given magnitude and phase (in radians), changing this Complex, and returning itself.

##### setReal( number real ) : Complex

Sets the real component of this complex, returning this

##### setRealImaginary( number real, number imaginary ) : Complex

Sets all of the components of this complex, returning this

##### sin() : Complex

Sine. Mutable form of sinOf.

##### sinOf() : Complex

Sine. Immutable form of sin.

##### sqrt() : Complex

Square root. Mutable form of sqrtOf.

##### sqrtOf() : Complex

Square root. Immutable form of sqrt.

##### square() : Complex

Squares this complex number. This is the mutable version of squared.

##### squared() : Complex

Returns the square of this complex number and does not modify it. This is the immutable version of square.

##### subtract( Complex c ) : Complex

Subtraction of another Complex from this Complex, returning a copy.

This is the mutable form of the function minus(). This will modify and return this.

##### times( Complex c ) : Complex

Complex multiplication. Immutable version of multiply

##### toString() : string

Debugging string for the complex number (provides real and imaginary parts).

### ConvexHull2

Construction of 2D convex hulls from a list of points.

For example:

var points = _.range( 50 ).map( function() {
return new dot.Vector2( 5 + ( 256 - 10 ) * Math.random(), 5 + ( 128 - 10 ) * Math.random() );
} );
var hullPoints = dot.ConvexHull2.grahamScan( points, false );
##### ConvexHull2.grahamScan( Array.<Vector2> points, boolean includeCollinear ) : Array.<Vector2>

Given multiple points, this performs a Graham Scan (http://en.wikipedia.org/wiki/Graham_scan) to identify an ordered list of points which define the minimal polygon that contains all of the points.

 boolean includeCollinear - If a point is along an edge of the convex hull (not at one of its vertices), should it be included?

### Dimension2

Basic width and height, like a Bounds2 but without the location defined.

#### Dimension2( number width, number height ) extends Object

Creates a 2-dimensional size with a width and height

##### height number

Height of the dimension

##### width number

Width of the dimension

##### copy( Dimension2 dimension ) : Dimension2

Creates a copy of this dimension, or if a dimension is passed in, set that dimension's values to ours.

This is the immutable form of the function set(), if a dimension is provided. This will return a new dimension, and will not modify this dimension.

 Dimension2 dimension - If not provided, creates a new Vector2 with filled in values. Otherwise, fills in the values of the provided dimension so that it equals this dimension.
##### equals( Dimension2 other ) : boolean

Exact equality comparison between this dimension and another dimension.

##### set( Dimension2 dimension ) : Dimension2

Sets this dimension to be a copy of another dimension.

This is the mutable form of the function copy(). This will mutate (change) this dimension, in addition to returning this dimension itself.

##### setHeight( number height ) : Dimension2

Sets the height of the dimension, returning this.

##### setWidth( number width ) : Dimension2

Sets the width of the dimension, returning this.

##### toBounds( number x, number y ) : Bounds2

Creates a Bounds2 from this dimension based on passing in the minimum (top-left) corner as (x,y).

 number x - Minimum x coordinate of the bounds, or 0 if not provided. number y - Minimum y coordinate of the bounds, or 0 if not provided.
##### toString() : string

Debugging string for the dimension.

### Transform3

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 ).

#### Transform3( Matrix3 matrix ) extends Events

Creates a transform based around an initial matrix.

##### append( Matrix3 matrix )

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

##### appendTransform( Transform3 transform )

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

##### applyToCanvasContext( CanvasRenderingContext2D context )

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

##### copy() : Transform3

Creates a copy of this transform.

##### getInverse() : Matrix3

Returns the inverse of the primary matrix of this transform.

##### getInverseTransposed() : Matrix3

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

##### getMatrix() : Matrix3

Returns the primary matrix of this transform.

##### getMatrixTransposed() : Matrix3

Returns the transpose of the primary matrix of this transform.

##### 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.

##### inverseBounds2( Bounds2 bounds ) : Bounds2

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

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.

##### inverseDelta2( Vector2 v ) : Vector2

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

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().

##### inverseDeltaX( number x ) : number

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.

This is the inverse of transformDeltaX().

##### inverseDeltaY( number y ) : number

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.

This is the inverse of transformDeltaY().

##### inverseNormal2( Vector2 v ) : Vector2

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).

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().

##### inversePosition2( Vector2 v ) : Vector2

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

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().

##### inverseRay2( Ray2 ray ) : Ray2

Returns an inverse-transformed ray.

This is the inverse of transformRay2()

##### inverseShape( Shape shape ) : Shape

Returns an inverse-transformed kite.Shape.

This is the inverse of transformShape()

##### inverseX( number x ) : number

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).

This is the inverse of transformX().

##### inverseY( number y ) : number

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).

This is the inverse of transformY().

##### isFinite() : boolean

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

##### isIdentity() : boolean

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.

##### prepend( Matrix3 matrix )

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

##### prependTransform( Transform3 transform )

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

##### prependTranslation( number x, number y )

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

 number x - x-coordinate number y - y-coordinate
##### setMatrix( Matrix3 matrix )

Sets the value of the primary matrix directly from a Matrix3. Does not change the Matrix3 instance of this Transform3.

##### transformBounds2( Bounds2 bounds ) : Bounds2

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

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.

##### transformDelta2( Vector2 v ) : Vector2

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

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}$.

##### transformDeltaX( number x ) : number

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

##### transformDeltaY( number y ) : number

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

##### transformNormal2( Vector2 v ) : Vector2

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).

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.

##### transformPosition2( Vector2 v ) : Vector2

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

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

##### transformRay2( Ray2 ray ) : Ray2

Returns a transformed ray.

##### transformShape( Shape shape ) : Shape

Returns a transformed kite.Shape.

##### transformX( number x ) : number

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).

##### transformY( number y ) : number

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).

### Transform4

Forward and inverse transforms with 4x4 matrices, allowing flexibility including affine and perspective transformations.

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 ).

#### Transform4( Matrix4 matrix ) extends Events

Creates a transform based around an initial matrix.

##### append( Matrix4 matrix )

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

##### appendTransform( Transform4 transform )

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

##### applyToCanvasContext( CanvasRenderingContext2D context )

Sets the transform of a Canvas context to be equivalent to the 2D affine part of this transform.

##### copy() : Transform4

Creates a copy of this transform.

##### getInverse() : Matrix4

Returns the inverse of the primary matrix of this transform.

##### getInverseTransposed() : Matrix4

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

##### getMatrix() : Matrix4

Returns the primary matrix of this transform.

##### getMatrixTransposed() : Matrix4

Returns the transpose of the primary matrix of this transform.

##### 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.

##### inverseDelta3( Vector3 v ) : Vector3

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

This is the inverse of transformDelta3().

##### inverseDeltaX( number x ) : number

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

This is the inverse of transformDeltaX().

##### inverseDeltaY( number y ) : number

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

This is the inverse of transformDeltaY().

##### inverseDeltaZ( number z ) : number

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

This is the inverse of transformDeltaZ().

##### inverseNormal3( Vector3 v ) : Vector3

Transforms a 3-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).

This is the inverse of transformNormal3().

##### inversePosition3( Vector3 v ) : Vector3

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

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

This is the inverse of transformPosition3().

##### inverseRay( Ray3 ray ) : Ray3

Returns an inverse-transformed ray.

This is the inverse of transformRay()

##### isFinite() : boolean

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

##### isIdentity() : boolean

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.

##### prepend( Matrix4 matrix )

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

##### prependTransform( Transform4 transform )

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

##### setMatrix( Matrix4 matrix )

Sets the value of the primary matrix directly from a Matrix4. Does not change the Matrix4 instance of this Transform4.

##### transformDelta3( Vector3 v ) : Vector3

Transforms a 3-dimensional vector like position is irrelevant (translation is not applied).

##### transformDeltaX( number x ) : number

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

##### transformDeltaY( number y ) : number

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

##### transformDeltaZ( number z ) : number

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

##### transformNormal3( Vector3 v ) : Vector3

Transforms a 3-dimensional vector like it is a normal to a surface (so that the surface is transformed, and the new normal to the surface at the transformed point is returned).

##### transformPosition3( Vector3 v ) : Vector3

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

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

##### transformRay( Ray3 ray ) : Ray3

Returns a transformed ray.

### Util

Utility functions for Dot, placed into the dot.X namespace.

##### Util.arePointsCollinear( Vector2 a, Vector2 b, Vector2 c, number epsilon ) : boolean

Determines whether the three points are approximately collinear.

##### Util.boxMullerTransform( number mu, number sigma, Random random ) : number

Generates a random Gaussian sample with the given mean and standard deviation. This method relies on the "static" variables generate, z0, and z1 defined above. Random.js is the primary client of this function, but it is defined here so it can be used other places more easily if need be. Code inspired by example here: https://en.wikipedia.org/wiki/Box%E2%80%93Muller_transform.

 number mu - The mean of the Gaussian number sigma - The standard deviation of the Gaussian Random random - the source of randomness
##### Util.clamp( number value, number min, number max ) : number

Returns the original value if it is inclusively within the [max,min] range. If it's below the range, min is returned, and if it's above the range, max is returned.

##### Util.cosh( number value ) : number

Function that returns the hyperbolic cosine of a number

##### Util.cubeRoot( number x ) : number

Returns the unique real cube root of x, such that $y^3=x$.

##### Util.distToSegment( Vector2 point, Vector2 a, Vector2 b ) : number

distance from a point to a line segment squared.

 Vector2 point - The point Vector2 a - Starting point of the line segment Vector2 b - Ending point of the line segment
##### Util.distToSegmentSquared( Vector2 point, Vector2 a, Vector2 b ) : number

Squared distance from a point to a line segment squared. See http://stackoverflow.com/questions/849211/shortest-distance-between-a-point-and-a-line-segment

 Vector2 point - The point Vector2 a - Starting point of the line segment Vector2 b - Ending point of the line segment
##### Util.gcd( number a, number b )

Greatest Common Denominator, using https://en.wikipedia.org/wiki/Euclidean_algorithm

##### Util.isInteger( number n ) : boolean

Returns whether the input is a number that is an integer (no fractional part).

##### Util.lineLineIntersection( Vector2 p1, Vector2 p2, Vector2 p3, Vector2 p4 ) : Vector2|null

Intersection point between the lines defined by the line segments p1-2 and p3-p4. If the lines are not properly defined, null is returned. If there are no intersections or infinitely many, e.g. parallel lines, null is returned.

##### Util.lineSegmentIntersection( number x1, number y1, number x2, number y2, number x3, number y3, number x4, number y4 ) : Vector2|null

Computes the intersection of the two line segments $(x_1,y_1)(x_2,y_2)$ and $(x_3,y_3)(x_4,y_4)$. If there is no intersection, null is returned.

##### Util.linear( number a1, number a2, number b1, number b2, number a3 ) : number

Defines and evaluates a linear mapping. The mapping is defined so that $f(a_1)=b_1$ and $f(a_2)=b_2$, and other values are interpolated along the linear equation. The returned value is $f(a_3)$.

##### Util.log10( number val ) : number

Log base-10, since it wasn't included in every supported browser.

##### Util.moduloBetweenDown( number value, number min, number max ) : number

Returns a number in the range $n\in[\mathrm{min},\mathrm{max})$ with the same equivalence class as the input value mod (max-min), i.e. for a value $m$, $m\equiv n\ (\mathrm{mod}\ \mathrm{max}-\mathrm{min})$.

The 'down' indicates that if the value is equal to min or max, the max is returned.

##### Util.moduloBetweenUp( number value, number min, number max ) : number

Returns a number in the range $n\in(\mathrm{min},\mathrm{max}]$ with the same equivalence class as the input value mod (max-min), i.e. for a value $m$, $m\equiv n\ (\mathrm{mod}\ \mathrm{max}-\mathrm{min})$.

The 'up' indicates that if the value is equal to min or max, the min is returned.

##### Util.rangeExclusive( number a, number b ) : Array.<number>

Returns an array of integers from A to B (exclusive), e.g. rangeExclusive( 4, 7 ) maps to [ 5, 6 ].

##### Util.rangeInclusive( number a, number b ) : Array.<number>

Returns an array of integers from A to B (inclusive), e.g. rangeInclusive( 4, 7 ) maps to [ 4, 5, 6, 7 ].

##### Util.roundSymmetric( number value ) : number

Rounds using "Round half away from zero" algorithm. See dot#35.

JavaScript's Math.round is not symmetric for positive and negative numbers, it uses IEEE 754 "Round half up". See https://en.wikipedia.org/wiki/Rounding#Round_half_up. For sims, we want to treat positive and negative values symmetrically, which is IEEE 754 "Round half away from zero", See https://en.wikipedia.org/wiki/Rounding#Round_half_away_from_zero

Note that -0 is rounded to 0, since we typically do not want to display -0 in sims.

 number value - 
##### Util.sinh( number value ) : number

Function that returns the hyperbolic sine of a number

##### Util.solveCubicRootsReal( number a, number b, number c, number d ) : Array.<number>

Returns an array of the real roots of the quadratic equation $ax^3 + bx^2 + cx + d=0$ (there will be between 0 and 3 roots).

##### Util.solveQuadraticRootsReal( number a, number b, number c ) : Array.<number>

Returns an array of the real roots of the quadratic equation $ax^2 + bx + c=0$ (there will be between 0 and 2 roots).

##### Util.sphereRayIntersection( number radius, Ray3 ray, number epsilon ) : Object

Ray-sphere intersection, returning information about the closest intersection. Assumes the sphere is centered at the origin (for ease of computation), transform the ray to compensate if needed.

If there is no intersection, null is returned. Otherwise an object will be returned like:

{
distance: {number}, // distance from the ray position to the intersection
hitPoint: {Vector3}, // location of the intersection
normal: {Vector3}, // the normal of the sphere's surface at the intersection
fromOutside: {boolean}, // whether the ray intersected the sphere from outside the sphere first
}
`

##### Util.toFixed( number value, number decimalPlaces ) : string

A predictable implementation of toFixed.

JavaScript's toFixed is notoriously buggy, behavior differs depending on browser, because the spec doesn't specify whether to round or floor. Rounding is symmetric for positive and negative values, see Util.roundSymmetric.

##### Util.toFixedNumber( number value, number decimalPlaces ) : number

A predictable implementation of toFixed, where the result is returned as a number instead of a string.

JavaScript's toFixed is notoriously buggy, behavior differs depending on browser, because the spec doesn't specify whether to round or floor. Rounding is symmetric for positive and negative values, see Util.roundSymmetric.

##### Util.triangleArea( Vector2 a, Vector2 b, Vector2 c ) : number

The area inside the triangle defined by the three vertices.

##### Util.triangleAreaSigned( Vector2 a, Vector2 b, Vector2 c ) : number

The area inside the triangle defined by the three vertices, but with the sign determined by whether the vertices provided are clockwise or counter-clockwise.

### Vector2

Basic 2-dimensional vector, represented as (x,y).

#### Vector2( number x, number y ) extends Object

Creates a 2-dimensional vector with the specified X and Y values.

 number x - X coordinate, defaults to 0 if not provided number y - Y coordinate, defaults to 0 if not provided
##### Vector2.X_UNIT Vector2

Immutable vector: $\begin{bmatrix} 1\\0 \end{bmatrix}$

##### Vector2.Y_UNIT Vector2

Immutable vector: $\begin{bmatrix} 0\\1 \end{bmatrix}$

##### Vector2.ZERO Vector2

Immutable zero vector: $\begin{bmatrix} 0\\0 \end{bmatrix}$

##### Vector2.createPolar( number magnitude, number angle ) : Vector2

Returns a Vector2 with the specified magnitude $r$ and angle $\theta$ (in radians), with the formula: $f( r, \theta ) = \begin{bmatrix} r\cos\theta \\ r\sin\theta \end{bmatrix}$

##### Vector2.fromStateObject( Object stateObject ) : Vector2

Constructs a Vector2 from a duck-typed { x: {number}, y: {number} } object, meant for use with tandem/phet-io deserialization.

 Object stateObject - Like { x: {number}, y: {number} }
##### x number

The X coordinate of the vector.

##### y number

The Y coordinate of the vector.

##### add( Vector2 v ) : Vector2

Adds another vector to this vector, changing this vector.

This is the mutable form of the function plus(). This will mutate (change) this vector, in addition to returning this vector itself.

##### addScalar( number scalar ) : Vector2

Adds a scalar to this vector (added to every component), changing this vector.

This is the mutable form of the function plusScalar(). This will mutate (change) this vector, in addition to returning this vector itself.

##### addXY( number x, number y ) : Vector2

Adds another vector (x,y) to this vector, changing this vector.

This is the mutable form of the function plusXY(). This will mutate (change) this vector, in addition to returning this vector itself.

##### angle() : number

The angle $\theta$ of this vector, such that this vector is equal to $u = \begin{bmatrix} r\cos\theta \\ r\sin\theta \end{bmatrix}$ for the magnitude $r \ge 0$ of the vector, with $\theta\in(-\pi,\pi]$

##### angleBetween( Vector2 v ) : number

The angle between this vector and another vector, in the range $\theta\in[0, \pi]$.

Equal to $\theta = \cos^{-1}( \hat{u} \cdot \hat{v} )$ where $\hat{u}$ is this vector (normalized) and $\hat{v}$ is the input vector (normalized).

##### average( Vector2 vector ) : Vector2

The average (midpoint) between this vector and another vector.

##### blend( Vector2 vector, number ratio ) : Vector2

A linear interpolation between this vector (ratio=0) and another vector (ratio=1).

 number ratio - Not necessarily constrained in [0, 1]
##### componentMultiply( Vector2 v ) : Vector2

Multiplies this vector by another vector component-wise, changing this vector.

This is the mutable form of the function componentTimes(). This will mutate (change) this vector, in addition to returning this vector itself.

##### componentTimes( Vector2 v ) : Vector2

Copy of this vector, multiplied component-wise by the passed-in vector v.

This is the immutable form of the function componentMultiply(). This will return a new vector, and will not modify this vector.

##### copy( Vector2 vector ) : Vector2

Creates a copy of this vector, or if a vector is passed in, set that vector's values to ours.

This is the immutable form of the function set(), if a vector is provided. This will return a new vector, and will not modify this vector.

 Vector2 vector - If not provided, creates a new Vector2 with filled in values. Otherwise, fills in the values of the provided vector so that it equals this vector.
##### crossScalar( Vector2 v ) : number

The scalar value of the z-component of the equivalent 3-dimensional cross product: $f( u, v ) = \left( \begin{bmatrix} u_x \\ u_y \\ 0 \end{bmatrix} \times \begin{bmatrix} v_x \\ v_y \\ 0 \end{bmatrix} \right)_z = u_x v_y - u_y v_x$

##### distance( Vector2 point ) : number

The Euclidean distance between this vector (treated as a point) and another point.

##### distanceSquared( Vector2 point ) : number

The squared Euclidean distance between this vector (treated as a point) and another point.

##### distanceSquaredXY( number x, number y ) : number

The squared Euclidean distance between this vector (treated as a point) and another point with coordinates (x,y).

##### distanceXY( number x, number y ) : number

The Euclidean distance between this vector (treated as a point) and another point (x,y).

##### divideScalar( number scalar ) : Vector2

Divides this vector by a scalar (divides each component by the scalar), changing this vector.

This is the mutable form of the function dividedScalar(). This will mutate (change) this vector, in addition to returning this vector itself.

##### dividedScalar( number scalar ) : Vector2

Division of this vector by a scalar (divides every component by the scalar), returning a copy.

This is the immutable form of the function divideScalar(). This will return a new vector, and will not modify this vector.

##### dot( Vector2 v ) : number

The dot-product (Euclidean inner product) between this vector and another vector v.

##### dotXY( number x, number y ) : number

The dot-product (Euclidean inner product) between this vector and another vector (x,y).

##### equals( Vector2 other ) : boolean

Exact equality comparison between this vector and another vector.

##### equalsEpsilon( Vector2 other, number epsilon ) : boolean

Approximate equality comparison between this vector and another vector.

##### isFinite() : boolean

Whether all of the components are numbers (not NaN) that are not infinity or -infinity.

##### magnitude() : number

The magnitude (Euclidean/L2 Norm) of this vector, i.e. $\sqrt{x^2+y^2}$.

##### magnitudeSquared() : number

The squared magnitude (square of the Euclidean/L2 Norm) of this vector, i.e. $x^2+y^2$.

##### minus( Vector2 v ) : Vector2

Subtraction of this vector by another vector v, returning a copy.

This is the immutable form of the function subtract(). This will return a new vector, and will not modify this vector.

##### minusScalar( number scalar ) : Vector2

Subtraction of this vector by a scalar (subtracts the scalar from every component), returning a copy.

This is the immutable form of the function subtractScalar(). This will return a new vector, and will not modify this vector.

##### minusXY( number x, number y ) : Vector2

Subtraction of this vector by another vector (x,y), returning a copy.

This is the immutable form of the function subtractXY(). This will return a new vector, and will not modify this vector.

##### multiply( number scalar ) : Vector2

Multiplies this vector by a scalar (multiplies each component by the scalar), changing this vector. Same as multiplyScalar.

This is the mutable form of the function times(). This will mutate (change) this vector, in addition to returning this vector itself.

##### multiplyScalar( number scalar ) : Vector2

Multiplies this vector by a scalar (multiplies each component by the scalar), changing this vector.

This is the mutable form of the function timesScalar(). This will mutate (change) this vector, in addition to returning this vector itself.

##### negate() : Vector2

Negates this vector (multiplies each component by -1), changing this vector.

This is the mutable form of the function negated(). This will mutate (change) this vector, in addition to returning this vector itself.

##### negated() : Vector2

Negated copy of this vector (multiplies every component by -1).

This is the immutable form of the function negate(). This will return a new vector, and will not modify this vector.

##### normalize() : Vector2

Normalizes this vector (rescales to where the magnitude is 1), changing this vector.

This is the mutable form of the function normalized(). This will mutate (change) this vector, in addition to returning this vector itself.

##### normalized() : Vector2

Normalized (re-scaled) copy of this vector such that its magnitude is 1. If its initial magnitude is zero, an error is thrown.

This is the immutable form of the function normalize(). This will return a new vector, and will not modify this vector.

##### perpendicular() : Vector2

Rotated by -pi/2 (perpendicular to this vector), returned as a copy.

##### plus( Vector2 v ) : Vector2

Addition of this vector and another vector, returning a copy.

This is the immutable form of the function add(). This will return a new vector, and will not modify this vector.

##### plusScalar( number scalar ) : Vector2

Addition of this vector with a scalar (adds the scalar to every component), returning a copy.

This is the immutable form of the function addScalar(). This will return a new vector, and will not modify this vector.

##### plusXY( number x, number y ) : Vector2

Addition of this vector and another vector (x,y), returning a copy.

This is the immutable form of the function addXY(). This will return a new vector, and will not modify this vector.

##### rotate( number angle ) : Vector2

Rotates this vector by the angle (in radians), changing this vector.

This is the mutable form of the function rotated(). This will mutate (change) this vector, in addition to returning this vector itself.

##### rotated( number angle ) : Vector2

Rotated by an arbitrary angle, in radians. Returned as a copy.

This is the immutable form of the function rotate(). This will return a new vector, and will not modify this vector.

##### set( Vector2 v ) : Vector2

Sets this vector to be a copy of another vector.

This is the mutable form of the function copy(). This will mutate (change) this vector, in addition to returning this vector itself.

##### setMagnitude( number magnitude ) : Vector2

Sets the magnitude of this vector. If the passed-in magnitude is negative, this flips the vector and sets its magnitude to abs( magnitude ).

This is the mutable form of the function withMagnitude(). This will mutate (change) this vector, in addition to returning this vector itself.

##### setPolar( number magnitude, number angle ) : Vector2

Sets this vector's value to be the x,y values matching the given magnitude and angle (in radians), changing this vector, and returning itself.

##### setX( number x ) : Vector2

Sets the x-component of this vector, returning this.

##### setXY( number x, number y ) : Vector2

Sets all of the components of this vector, returning this.

##### setY( number y ) : Vector2

Sets the y-component of this vector, returning this.

##### subtract( Vector2 v ) : Vector2

Subtracts this vector by another vector, changing this vector.

This is the mutable form of the function minus(). This will mutate (change) this vector, in addition to returning this vector itself.

##### subtractScalar( number scalar ) : Vector2

Subtracts this vector by a scalar (subtracts each component by the scalar), changing this vector.

This is the mutable form of the function minusScalar(). This will mutate (change) this vector, in addition to returning this vector itself.

##### subtractXY( number x, number y ) : Vector2

Subtracts this vector by another vector (x,y), changing this vector.

This is the mutable form of the function minusXY(). This will mutate (change) this vector, in addition to returning this vector itself.

##### times( number scalar ) : Vector2

Same as timesScalar.

This is the immutable form of the function multiply(). This will return a new vector, and will not modify this vector.

##### timesScalar( number scalar ) : Vector2

Copy of this vector, scaled by the desired scalar value.

This is the immutable form of the function multiplyScalar(). This will return a new vector, and will not modify this vector.

##### toStateObject() : Object

Returns a duck-typed object meant for use with tandem/phet-io serialization.

##### toString() : string

Debugging string for the vector.

##### toVector3() : Vector3

Converts this to a 3-dimensional vector, with the z-component equal to 0.

##### withMagnitude( number magnitude ) : Vector2

Re-scaled copy of this vector such that it has the desired magnitude. If its initial magnitude is zero, an error is thrown. If the passed-in magnitude is negative, the direction of the resulting vector will be reversed.

This is the immutable form of the function setMagnitude(). This will return a new vector, and will not modify this vector.

### Vector3

Basic 3-dimensional vector, represented as (x,y,z).

#### Vector3( number x, number y, number z ) extends Object

Creates a 3-dimensional vector with the specified X, Y and Z values.

 number x - X coordinate, defaults to 0 if not provided number y - Y coordinate, defaults to 0 if not provided number z - Z coordinate, defaults to 0 if not provided

##### Vector3.slerp( Vector3 start, Vector3 end, number ratio )

Spherical linear interpolation between two unit vectors.

 Vector3 start - Start unit vector Vector3 end - End unit vector number ratio - Between 0 (at start vector) and 1 (at end vector)
##### x number

The X coordinate of the vector.

##### y number

The Y coordinate of the vector.

##### z number

The Z coordinate of the vector.

##### add( Vector2 v ) : Vector2

Adds another vector to this vector, changing this vector.

This is the mutable form of the function plus(). This will mutate (change) this vector, in addition to returning this vector itself.

##### addScalar( number scalar ) : Vector3

Adds a scalar to this vector (added to every component), changing this vector.

This is the mutable form of the function plusScalar(). This will mutate (change) this vector, in addition to returning this vector itself.

##### addXYZ( number x, number y, number z ) : Vector3

Adds another vector (x,y,z) to this vector, changing this vector.

This is the mutable form of the function plusXYZ(). This will mutate (change) this vector, in addition to returning this vector itself.

##### angleBetween( Vector3 v ) : number

The angle between this vector and another vector, in the range $\theta\in[0, \pi]$.

Equal to $\theta = \cos^{-1}( \hat{u} \cdot \hat{v} )$ where $\hat{u}$ is this vector (normalized) and $\hat{v}$ is the input vector (normalized).

##### average( Vector3 vector ) : Vector3

The average (midpoint) between this vector and another vector.

##### blend( Vector3 vector, number ratio ) : Vector3

A linear interpolation between this vector (ratio=0) and another vector (ratio=1).

 number ratio - Not necessarily constrained in [0, 1]
##### componentMultiply( Vector3 v ) : Vector3

Multiplies this vector by another vector component-wise, changing this vector.

This is the mutable form of the function componentTimes(). This will mutate (change) this vector, in addition to returning this vector itself.

##### componentTimes( Vector3 v ) : Vector3

Copy of this vector, multiplied component-wise by the passed-in vector v.

This is the immutable form of the function componentMultiply(). This will return a new vector, and will not modify this vector.

##### copy( Vector3 vector ) : Vector3

Creates a copy of this vector, or if a vector is passed in, set that vector's values to ours.

This is the immutable form of the function set(), if a vector is provided. This will return a new vector, and will not modify this vector.

 Vector3 vector - If not provided, creates a new Vector3 with filled in values. Otherwise, fills in the values of the provided vector so that it equals this vector.
##### cross( Vector3 v ) : Vector3

The Euclidean 3-dimensional cross-product of this vector by the passed-in vector.

##### distance( Vector3 point ) : number

The Euclidean distance between this vector (treated as a point) and another point.

##### distanceSquared( Vector3 point ) : number

The squared Euclidean distance between this vector (treated as a point) and another point.

##### distanceSquaredXYZ( number x, number y, number z ) : number

The squared Euclidean distance between this vector (treated as a point) and another point (x,y,z).

##### distanceXYZ( number x, number y, number z ) : number

The Euclidean distance between this vector (treated as a point) and another point (x,y,z).

##### divideScalar( number scalar ) : Vector3

Divides this vector by a scalar (divides each component by the scalar), changing this vector.

This is the mutable form of the function dividedScalar(). This will mutate (change) this vector, in addition to returning this vector itself.

##### dividedScalar( number scalar ) : Vector3

Division of this vector by a scalar (divides every component by the scalar), returning a copy.

This is the immutable form of the function divideScalar(). This will return a new vector, and will not modify this vector.

##### dot( Vector3 v ) : number

The dot-product (Euclidean inner product) between this vector and another vector v.

##### dotXYZ( number x, number y, number z ) : number

The dot-product (Euclidean inner product) between this vector and another vector (x,y,z).

##### equals( Vector3 other ) : boolean

Exact equality comparison between this vector and another vector.

##### equalsEpsilon( Vector3 other, number epsilon ) : boolean

Approximate equality comparison between this vector and another vector.

##### isFinite() : boolean

Whether all of the components are numbers (not NaN) that are not infinity or -infinity.

##### magnitude() : number

The magnitude (Euclidean/L2 Norm) of this vector, i.e. $\sqrt{x^2+y^2+z^2}$.

##### magnitudeSquared() : number

T squared magnitude (square of the Euclidean/L2 Norm) of this vector, i.e. $x^2+y^2+z^2$.

##### minus( Vector3 v ) : Vector3

Subtraction of this vector by another vector v, returning a copy.

This is the immutable form of the function subtract(). This will return a new vector, and will not modify this vector.

##### minusScalar( number scalar ) : Vector3

Subtraction of this vector by a scalar (subtracts the scalar from every component), returning a copy.

This is the immutable form of the function subtractScalar(). This will return a new vector, and will not modify this vector.

##### minusXYZ( number x, number y, number z ) : Vector3

Subtraction of this vector by another vector (x,y,z), returning a copy.

This is the immutable form of the function subtractXYZ(). This will return a new vector, and will not modify this vector.

##### multiply( number scalar ) : Vector3

Multiplies this vector by a scalar (multiplies each component by the scalar), changing this vector. Same as multiplyScalar.

This is the mutable form of the function times(). This will mutate (change) this vector, in addition to returning this vector itself.

##### multiplyScalar( number scalar ) : Vector3

Multiplies this vector by a scalar (multiplies each component by the scalar), changing this vector.

This is the mutable form of the function timesScalar(). This will mutate (change) this vector, in addition to returning this vector itself.

##### negate() : Vector3

Negates this vector (multiplies each component by -1), changing this vector.

This is the mutable form of the function negated(). This will mutate (change) this vector, in addition to returning this vector itself.

##### negated() : Vector3

Negated copy of this vector (multiplies every component by -1).

This is the immutable form of the function negate(). This will return a new vector, and will not modify this vector.

##### normalize() : Vector3

Normalizes this vector (rescales to where the magnitude is 1), changing this vector.

This is the mutable form of the function normalized(). This will mutate (change) this vector, in addition to returning this vector itself.

##### normalized() : Vector3

Normalized (re-scaled) copy of this vector such that its magnitude is 1. If its initial magnitude is zero, an error is thrown.

This is the immutable form of the function normalize(). This will return a new vector, and will not modify this vector.

##### plus( Vector3 v ) : Vector3

Addition of this vector and another vector, returning a copy.

This is the immutable form of the function add(). This will return a new vector, and will not modify this vector.

##### plusScalar( number scalar ) : Vector3

Addition of this vector with a scalar (adds the scalar to every component), returning a copy.

This is the immutable form of the function addScalar(). This will return a new vector, and will not modify this vector.

##### plusXYZ( number x, number y, number z ) : Vector3

Addition of this vector and another vector (x,y,z), returning a copy.

This is the immutable form of the function addXYZ(). This will return a new vector, and will not modify this vector.

##### set( Vector3 v ) : Vector3

Sets this vector to be a copy of another vector.

This is the mutable form of the function copy(). This will mutate (change) this vector, in addition to returning this vector itself.

##### setMagnitude( number magnitude ) : Vector3

Sets the magnitude of this vector. If the passed-in magnitude is negative, this flips the vector and sets its magnitude to abs( magnitude ).

This is the mutable form of the function withMagnitude(). This will mutate (change) this vector, in addition to returning this vector itself.

##### setX( number x ) : Vector3

Sets the x-component of this vector, returning this.

##### setXYZ( number x, number y, number z ) : Vector3

Sets all of the components of this vector, returning this.

##### setY( number y ) : Vector3

Sets the y-component of this vector, returning this.

##### setZ( number z ) : Vector3

Sets the z-component of this vector, returning this.

##### subtract( Vector3 v ) : Vector3

Subtracts this vector by another vector, changing this vector.

This is the mutable form of the function minus(). This will mutate (change) this vector, in addition to returning this vector itself.

##### subtractScalar( number scalar ) : Vector3

Subtracts this vector by a scalar (subtracts each component by the scalar), changing this vector.

This is the mutable form of the function minusScalar(). This will mutate (change) this vector, in addition to returning this vector itself.

##### subtractXYZ( number x, number y, number z ) : Vector3

Subtracts this vector by another vector (x,y,z), changing this vector.

This is the mutable form of the function minusXYZ(). This will mutate (change) this vector, in addition to returning this vector itself.

##### times( number scalar ) : Vector3

Same as timesScalar.

This is the immutable form of the function multiply(). This will return a new vector, and will not modify this vector.

##### timesScalar( number scalar ) : Vector3

Copy of this vector, scaled by the desired scalar value.

This is the immutable form of the function multiplyScalar(). This will return a new vector, and will not modify this vector.

##### toString() : string

Debugging string for the vector.

##### toVector2() : Vector2

Converts this to a 2-dimensional vector, discarding the z-component.

##### toVector4() : Vector4

Converts this to a 4-dimensional vector, with the z-component equal to 1 (useful for homogeneous coordinates).

##### withMagnitude( number magnitude ) : Vector3

Re-scaled copy of this vector such that it has the desired magnitude. If its initial magnitude is zero, an error is thrown. If the passed-in magnitude is negative, the direction of the resulting vector will be reversed.

This is the immutable form of the function setMagnitude(). This will return a new vector, and will not modify this vector.

### Vector4

Basic 4-dimensional vector, represented as (x,y).

#### Vector4( number x, number y, number z, number w ) extends Object

Creates a 4-dimensional vector with the specified X, Y, Z and W values.

 number x - X coordinate, defaults to 0 if not provided number y - Y coordinate, defaults to 0 if not provided number z - Z coordinate, defaults to 0 if not provided number w - W coordinate, defaults to 1 if not provided (convenience for homogeneous coordinates)

##### w number

The W coordinate of the vector. Default is 1, for ease with homogeneous coordinates.

##### x number

The X coordinate of the vector.

##### y number

The Y coordinate of the vector.

##### z number

The Z coordinate of the vector.

##### add( Vector4 v ) : Vector4

Adds another vector to this vector, changing this vector.

This is the mutable form of the function plus(). This will mutate (change) this vector, in addition to returning this vector itself.

##### addScalar( number scalar ) : Vector4

Adds a scalar to this vector (added to every component), changing this vector.

This is the mutable form of the function plusScalar(). This will mutate (change) this vector, in addition to returning this vector itself.

##### addXYZW( number x, number y, number z, number w ) : Vector4

Adds another vector (x,y,z,w) to this vector, changing this vector.

This is the mutable form of the function plusXYZW(). This will mutate (change) this vector, in addition to returning this vector itself.

##### angleBetween( Vector4 v ) : number

The angle between this vector and another vector, in the range $\theta\in[0, \pi]$.

Equal to $\theta = \cos^{-1}( \hat{u} \cdot \hat{v} )$ where $\hat{u}$ is this vector (normalized) and $\hat{v}$ is the input vector (normalized).

##### average( Vector4 vector ) : Vector4

The average (midpoint) between this vector and another vector.

##### blend( Vector4 vector, number ratio ) : Vector4

A linear interpolation between this vector (ratio=0) and another vector (ratio=1).

 number ratio - Not necessarily constrained in [0, 1]
##### componentMultiply( Vector4 v ) : Vector4

Multiplies this vector by another vector component-wise, changing this vector.

This is the mutable form of the function componentTimes(). This will mutate (change) this vector, in addition to returning this vector itself.

##### componentTimes( Vector4 v ) : Vector4

Copy of this vector, multiplied component-wise by the passed-in vector v.

This is the immutable form of the function componentMultiply(). This will return a new vector, and will not modify this vector.

##### copy( Vector4 vector ) : Vector4

Creates a copy of this vector, or if a vector is passed in, set that vector's values to ours.

This is the immutable form of the function set(), if a vector is provided. This will return a new vector, and will not modify this vector.

 Vector4 vector - If not provided, creates a new Vector4 with filled in values. Otherwise, fills in the values of the provided vector so that it equals this vector.
##### distance( Vector4 point ) : number

The Euclidean distance between this vector (treated as a point) and another point.

##### distanceSquared( Vector4 point ) : number

The squared Euclidean distance between this vector (treated as a point) and another point.

##### distanceSquaredXYZW( number x, number y, number z, number w ) : number

The squared Euclidean distance between this vector (treated as a point) and another point (x,y,z,w).

##### distanceXYZW( number x, number y, number z, number w ) : number

The Euclidean distance between this vector (treated as a point) and another point (x,y,z,w).

##### divideScalar( number scalar ) : Vector4

Divides this vector by a scalar (divides each component by the scalar), changing this vector.

This is the mutable form of the function dividedScalar(). This will mutate (change) this vector, in addition to returning this vector itself.

##### dividedScalar( number scalar ) : Vector4

Division of this vector by a scalar (divides every component by the scalar), returning a copy.

This is the immutable form of the function divideScalar(). This will return a new vector, and will not modify this vector.

##### dot( Vector4 v ) : number

The dot-product (Euclidean inner product) between this vector and another vector v.

##### dotXYZW( number x, number y, number z, number w ) : number

The dot-product (Euclidean inner product) between this vector and another vector (x,y,z,w).

##### equals( Vector4 other ) : boolean

Exact equality comparison between this vector and another vector.

##### equalsEpsilon( Vector4 other, number epsilon ) : boolean

Approximate equality comparison between this vector and another vector.

##### isFinite() : boolean

Whether all of the components are numbers (not NaN) that are not infinity or -infinity.

##### magnitude() : number

The magnitude (Euclidean/L2 Norm) of this vector, i.e. $\sqrt{x^2+y^2+z^2+w^2}$.

##### magnitudeSquared() : number

The squared magnitude (square of the Euclidean/L2 Norm) of this vector, i.e. $x^2+y^2+z^2+w^2$.

##### minus( Vector4 v ) : Vector4

Subtraction of this vector by another vector v, returning a copy.

This is the immutable form of the function subtract(). This will return a new vector, and will not modify this vector.

##### minusScalar( number scalar ) : Vector4

Subtraction of this vector by a scalar (subtracts the scalar from every component), returning a copy.

This is the immutable form of the function subtractScalar(). This will return a new vector, and will not modify this vector.

##### minusXYZW( number x, number y, number z, number w ) : Vector4

Subtraction of this vector by another vector (x,y,z,w), returning a copy.

This is the immutable form of the function subtractXYZW(). This will return a new vector, and will not modify this vector.

##### multiply( number scalar ) : Vector4

Multiplies this vector by a scalar (multiplies each component by the scalar), changing this vector. Same as multiplyScalar.

This is the mutable form of the function times(). This will mutate (change) this vector, in addition to returning this vector itself.

##### multiplyScalar( number scalar ) : Vector4

Multiplies this vector by a scalar (multiplies each component by the scalar), changing this vector.

This is the mutable form of the function timesScalar(). This will mutate (change) this vector, in addition to returning this vector itself.

##### negate() : Vector4

Negates this vector (multiplies each component by -1), changing this vector.

This is the mutable form of the function negated(). This will mutate (change) this vector, in addition to returning this vector itself.

##### negated() : Vector4

Negated copy of this vector (multiplies every component by -1).

This is the immutable form of the function negate(). This will return a new vector, and will not modify this vector.

##### normalize() : Vector4

Normalizes this vector (rescales to where the magnitude is 1), changing this vector.

This is the mutable form of the function normalized(). This will mutate (change) this vector, in addition to returning this vector itself.

##### normalized() : Vector4

Normalized (re-scaled) copy of this vector such that its magnitude is 1. If its initial magnitude is zero, an error is thrown.

This is the immutable form of the function normalize(). This will return a new vector, and will not modify this vector.

##### plus( Vector4 v ) : Vector4

Addition of this vector and another vector, returning a copy.

This is the immutable form of the function add(). This will return a new vector, and will not modify this vector.

##### plusScalar( number scalar ) : Vector4

Addition of this vector with a scalar (adds the scalar to every component), returning a copy.

This is the immutable form of the function addScalar(). This will return a new vector, and will not modify this vector.

##### plusXYZW( number x, number y, number z, number w ) : Vector4

Addition of this vector and another vector (x,y,z,w), returning a copy.

This is the immutable form of the function addXYZW(). This will return a new vector, and will not modify this vector.

##### set( Vector4 v ) : Vector4

Sets this vector to be a copy of another vector.

This is the mutable form of the function copy(). This will mutate (change) this vector, in addition to returning this vector itself.

##### setMagnitude( number magnitude ) : Vector4

Sets the magnitude of this vector. If the passed-in magnitude is negative, this flips the vector and sets its magnitude to abs( magnitude ).

This is the mutable form of the function withMagnitude(). This will mutate (change) this vector, in addition to returning this vector itself.

##### setW( number w ) : Vector4

Sets the w-component of this vector, returning this.

##### setX( number x ) : Vector4

Sets the x-component of this vector, returning this.

##### setXYZW( number x, number y, number z, number w ) : Vector4

Sets all of the components of this vector, returning this.

##### setY( number y ) : Vector4

Sets the y-component of this vector, returning this.

##### setZ( number z ) : Vector4

Sets the z-component of this vector, returning this.

##### subtract( Vector4 v ) : Vector4

Subtracts this vector by another vector, changing this vector.

This is the mutable form of the function minus(). This will mutate (change) this vector, in addition to returning this vector itself.

##### subtractScalar( number scalar ) : Vector4

Subtracts this vector by a scalar (subtracts each component by the scalar), changing this vector.

This is the mutable form of the function minusScalar(). This will mutate (change) this vector, in addition to returning this vector itself.

##### subtractXYZW( number x, number y, number z, number w ) : Vector4

Subtracts this vector by another vector (x,y,z,w), changing this vector.

This is the mutable form of the function minusXYZW(). This will mutate (change) this vector, in addition to returning this vector itself.

##### times( number scalar ) : Vector4

Same as timesScalar.

This is the immutable form of the function multiply(). This will return a new vector, and will not modify this vector.

##### timesScalar( number scalar ) : Vector4

Copy of this vector, scaled by the desired scalar value.

This is the immutable form of the function multiplyScalar(). This will return a new vector, and will not modify this vector.

##### toString() : string

Debugging string for the vector.

##### toVector3() : Vector3

Converts this to a 3-dimensional vector, discarding the w-component.

##### withMagnitude( number magnitude ) : Vector4

Re-scaled copy of this vector such that it has the desired magnitude. If its initial magnitude is zero, an error is thrown. If the passed-in magnitude is negative, the direction of the resulting vector will be reversed.

This is the immutable form of the function setMagnitude(). This will return a new vector, and will not modify this vector.