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 = phet.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 phet.dot.Vector2( 10, 0 ); var rotatedVector = rotation.timesVector2( vector ); console.log( rotatedVector.x, rotatedVector.y ); // 7.0710678118654755 7.071067811865475
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/
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 phet.dot.BinPacker( new phet.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 );
}
}
Creates a BinPacker with the specified containing bounds.
| Bounds2 | bounds | - | The available bounds to pack bins inside. |
Allocates a bin with the specified width and height if possible (returning a {Bin}), otherwise returns null.
Deallocates a bin, so that its area can be reused by future allocations.
| Bin | bin | - | The bin that was returned from allocate(). |
A rectangular bin that can be used itself or split into sub-bins.
Our containing bounds
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.
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. |
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.
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.
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
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. |
The maximum X coordinate of the bounds.
The maximum Y coordinate of the bounds.
The minimum X coordinate of the bounds.
The minimum Y coordinate of the bounds.
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.
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.
Alias for maxY, when thinking in the UI-layout manner.
The point (centerX, centerY), in the center of the bounds.
The point (centerX, maxY), in the UI-coordinate lower-center
The point (centerX, minY), in the UI-coordinate upper-center.
The horizontal (X-coordinate) center of the bounds, averaging the minX and maxX.
The vertical (Y-coordinate) center of the bounds, averaging the minY and maxY.
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.
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.
Whether this bounding box completely contains the bounding box passed as a parameter. The boundary of a box is considered to be "contained".
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 |
Whether the point is contained inside the bounding box, or is on the boundary.
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. |
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.
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.
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.
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.
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.
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.
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) |
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.
Exact equality comparison between this bounds and another bounds.
Approximate equality comparison between this bounds and another bounds.
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.
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.
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.
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.
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.
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.
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) |
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.
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. |
Alias for maxX, supporting the explicit getter function style.
Alias for maxY, supporting the explicit getter function style.
Alias for minX, supporting the explicit getter function style.
Alias for minY, supporting the explicit getter function style.
Whether this bounds has a non-zero area (non-zero positive width and height).
The height of the bounds, defined as maxY - minY.
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.
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.
Whether this and another bounding box have any points of intersection (including touching boundaries).
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.
Whether our minimums and maximums are all finite numbers. This will exclude Bounds2.NOTHING and Bounds2.EVERYTHING.
Whether this bounds has a finite and non-negative width and height.
Alias for minX, when thinking in the UI-layout manner.
The point (minX, maxY), in the UI-coordinate lower-left
The point (left, centerY), in the UI-coordinate center-left.
The point (minX, minY), in the UI-coordinate upper-left.
The squared distance from the input point to the point furthest from it inside the bounding box.
The squared distance from the input point to the point closest to it inside the bounding box.
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) |
Alias for maxX, when thinking in the UI-layout manner.
The point (maxX, maxY), in the UI-coordinate lower-right
The point (maxX, centerY), in the UI-coordinate center-right
The point (right, minY), in the UI-coordinate upper-right.
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.
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.
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.
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.
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.
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.
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.
Sets each value for this bounds, and returns itself.
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.
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.
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.
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.
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.
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.
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.
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.
Debugging string for the bounds.
Alias for minY, when thinking in the UI-layout manner.
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.
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.
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.
The width of the bounds, defined as maxX - minX.
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.
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.
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.
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.
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.
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) |
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.
Alias for minX, when thinking of the bounds as an (x,y,width,height) rectangle.
Alias for minY, when thinking of the bounds as an (x,y,width,height) rectangle.
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.
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. |
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.
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.
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. |
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.
The maximum X coordinate of the bounds.
The maximum Y coordinate of the bounds.
The maximum Z coordinate of the bounds.
The minimum X coordinate of the bounds.
The minimum Y coordinate of the bounds.
The minimum Z coordinate of the bounds.
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.
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.
Alias for minZ, when thinking in the UI-layout manner.
Alias for maxY, when thinking in the UI-layout manner.
The point (centerX, centerY, centerZ), in the center of the bounds.
The horizontal (X-coordinate) center of the bounds, averaging the minX and maxX.
The vertical (Y-coordinate) center of the bounds, averaging the minY and maxY.
The depthwise (Z-coordinate) center of the bounds, averaging the minZ and maxZ.
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.
Whether this bounding box completely contains the bounding box passed as a parameter. The boundary of a box is considered to be "contained".
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 |
Whether the point is contained inside the bounding box, or is on the boundary.
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. |
The depth of the bounds, defined as maxZ - minZ.
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.
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.
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.
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.
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.
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.
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.
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) |
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.
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.
Exact equality comparison between this bounds and another bounds.
Approximate equality comparison between this bounds and another bounds.
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.
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.
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.
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.
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.
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.
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.
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) |
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.
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.
Alias for maxZ, when thinking in the UI-layout manner.
Alias for maxX, supporting the explicit getter function style.
Alias for maxY, supporting the explicit getter function style.
Alias for maxZ, supporting the explicit getter function style.
Alias for minX, supporting the explicit getter function style.
Alias for minY, supporting the explicit getter function style.
Alias for minZ, supporting the explicit getter function style.
Whether this bounds has a non-zero area (non-zero positive width, height and depth).
The height of the bounds, defined as maxY - minY.
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.
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.
Whether this and another bounding box have any points of intersection (including touching boundaries).
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.
Whether our minimums and maximums are all finite numbers. This will exclude Bounds3.NOTHING and Bounds3.EVERYTHING.
Whether this bounds has a finite and non-negative width, height and depth.
Alias for minX, when thinking in the UI-layout manner.
Alias for maxX, when thinking in the UI-layout manner.
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.
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.
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.
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.
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.
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.
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.
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.
Sets each value for this bounds, and returns itself.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Debugging string for the bounds.
Alias for minY, when thinking in the UI-layout manner.
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.
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.
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.
The width of the bounds, defined as maxX - minX.
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.
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.
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.
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.
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.
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.
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.
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.
Alias for minX, when thinking of the bounds as an (x,y,z,width,height,depth) cuboid.
Alias for minY, when thinking of the bounds as an (x,y,z,width,height,depth) cuboid.
Alias for minZ, when thinking of the bounds as an (x,y,z,width,height,depth) cuboid.
A complex number with mutable and immutable methods.
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$. |
Immutable constant $i$, the imaginary unit.
Immutable constant $1$.
Immutable constant $0$.
Constructs a complex number from the polar form. For a magnitude $r$ and phase $\varphi$, this will be $\cos\varphi+i r\sin\varphi$.
Constructs a complex number from just the imaginary part (assuming the real part is 0).
Constructs a complex number from just the real part (assuming the imaginary part is 0).
The imaginary part. For a complex number $a+bi$, this is $b$.
The real part. For a complex number $a+bi$, this is $a$.
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.
Complex conjugate. Mutable form of conjugated
Complex conjugate. Immutable form of conjugate
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. |
Cosine. Mutable form of cosOf.
Cosine. Immutable form of cos.
Mutable Complex division. The immutable form is dividedBy.
Complex division. Immutable version of divide
Exact equality comparison between this Complex and another Complex.
Approximate equality comparison between this Complex and another 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
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.
The magnitude (Euclidean/L2 Norm) of this complex number, i.e. $\sqrt{a^2+b^2}$.
The squared magnitude (square of the Euclidean/L2 Norm) of this complex, i.e. $a^2+b^2$.
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.
Mutable Complex multiplication.
The phase / argument of the complex number.
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.
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.
Sets the imaginary component of this complex, returning this
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.
| number | phase | - | In radians |
Sets the real component of this complex, returning this
Sets all of the components of this complex, returning this
Sine. Mutable form of sinOf.
Sine. Immutable form of sin.
Square root. Mutable form of sqrtOf.
Square root. Immutable form of sqrt.
Squares this complex number. This is the mutable version of squared.
Returns the square of this complex number and does not modify it. This is the immutable version of square.
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.
Complex multiplication. Immutable version of multiply
Debugging string for the complex number (provides real and imaginary parts).
Construction of 2D convex hulls from a list of points.
For example:
var points = _.range( 50 ).map( function() {
return new phet.dot.Vector2( 5 + ( 256 - 10 ) * Math.random(), 5 + ( 128 - 10 ) * Math.random() );
} );
var hullPoints = phet.dot.ConvexHull2.grahamScan( points, false );
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? |
Basic width and height, like a Bounds2 but without the location defined.
Creates a 2-dimensional size with a width and height
Height of the dimension
Width of the dimension
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. |
Exact equality comparison between this dimension and another dimension.
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.
Sets the height of the dimension, returning this.
Sets the width of the dimension, returning this.
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. |
Debugging string for the dimension.
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 ).
Creates a transform based around an initial matrix.
Modifies the primary matrix such that: this.matrix = this.matrix * matrix
Like append(), but appends the other transform's matrix.
Sets the transform of a Canvas context to be equivalent to this transform.
Creates a copy of this transform.
Returns the inverse of the primary matrix of this transform.
Returns the inverse of the transpose of matrix of this transform.
Returns the primary matrix of this transform.
Returns the transpose of the primary matrix of this transform.
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.
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.
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().
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().
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().
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().
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().
Returns an inverse-transformed ray.
This is the inverse of transformRay2()
Returns an inverse-transformed phet.kite.Shape.
This is the inverse of transformShape()
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().
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().
Returns whether any components of our primary matrix are either infinite or NaN.
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.
Modifies the primary matrix such that: this.matrix = matrix * this.matrix.
Like prepend(), but prepends the other transform's matrix.
Optimized prepended translation such that: this.matrix = translation( x, y ) * this.matrix.
| number | x | - | x-coordinate |
| number | y | - | y-coordinate |
Sets the value of the primary matrix directly from a Matrix3. Does not change the Matrix3 instance of this Transform3.
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.
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}$.
Returns the x-coordinate difference for two transformed vectors, which add the x-coordinate difference of the input x (and same y values) beforehand.
Returns the y-coordinate difference for two transformed vectors, which add the y-coordinate difference of the input y (and same x values) beforehand.
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.
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}$.
Returns a transformed ray.
Returns a transformed phet.kite.Shape.
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).
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).
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 ).
Creates a transform based around an initial matrix.
Modifies the primary matrix such that: this.matrix = this.matrix * matrix
Like append(), but appends the other transform's matrix.
Sets the transform of a Canvas context to be equivalent to the 2D affine part of this transform.
Creates a copy of this transform.
Returns the inverse of the primary matrix of this transform.
Returns the inverse of the transpose of matrix of this transform.
Returns the primary matrix of this transform.
Returns the transpose of the primary matrix of this transform.
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.
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().
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().
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().
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().
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().
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().
Returns an inverse-transformed ray.
This is the inverse of transformRay()
Returns whether any components of our primary matrix are either infinite or NaN.
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.
Modifies the primary matrix such that: this.matrix = matrix * this.matrix.
Like prepend(), but prepends the other transform's matrix.
Sets the value of the primary matrix directly from a Matrix4. Does not change the Matrix4 instance of this Transform4.
Transforms a 3-dimensional vector like position is irrelevant (translation is not applied).
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.
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.
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.
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).
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}$.
Returns a transformed ray.
Utility functions for Dot, placed into the phet.dot.X namespace.
Determines whether the three points are approximately collinear.
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 |
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.
Function that returns the hyperbolic cosine of a number
Returns the unique real cube root of x, such that $y^3=x$.
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 |
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 |
Greatest Common Denominator, using https://en.wikipedia.org/wiki/Euclidean_algorithm
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.
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.
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)$.
Log base-10, since it wasn't included in every supported browser.
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.
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.
Returns an array of integers from A to B (exclusive), e.g. rangeExclusive( 4, 7 ) maps to [ 5, 6 ].
Returns an array of integers from A to B (inclusive), e.g. rangeInclusive( 4, 7 ) maps to [ 4, 5, 6, 7 ].
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 | - | ` |
Function that returns the hyperbolic sine of a 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).
Returns an array of the real roots of the quadratic equation $ax^2 + bx + c=0$ (there will be between 0 and 2 roots).
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
}
Converts radians to degrees.
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 Utils.roundSymmetric.
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 Utils.roundSymmetric.
Converts degrees to radians.
The area inside the triangle defined by the three vertices.
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.
Basic 2-dimensional vector, represented as (x,y).
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 |
Immutable vector: $\begin{bmatrix} 1\\0 \end{bmatrix}$
Immutable vector: $\begin{bmatrix} 0\\1 \end{bmatrix}$
Immutable zero vector: $\begin{bmatrix} 0\\0 \end{bmatrix}$
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} $
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} } |
The X coordinate of the vector.
The Y coordinate of the vector.
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.
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.
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.
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]$
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).
The average (midpoint) between this vector and another vector.
A linear interpolation between this vector (ratio=0) and another vector (ratio=1).
| number | ratio | - | Not necessarily constrained in [0, 1] |
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.
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.
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. |
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 $
The Euclidean distance between this vector (treated as a point) and another point.
The squared Euclidean distance between this vector (treated as a point) and another point.
The squared Euclidean distance between this vector (treated as a point) and another point with coordinates (x,y).
The Euclidean distance between this vector (treated as a point) and another point (x,y).
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.
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.
The dot-product (Euclidean inner product) between this vector and another vector v.
The dot-product (Euclidean inner product) between this vector and another vector (x,y).
Exact equality comparison between this vector and another vector.
Approximate equality comparison between this vector and another vector.
Whether all of the components are numbers (not NaN) that are not infinity or -infinity.
The magnitude (Euclidean/L2 Norm) of this vector, i.e. $\sqrt{x^2+y^2}$.
The squared magnitude (square of the Euclidean/L2 Norm) of this vector, i.e. $x^2+y^2$.
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.
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.
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.
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.
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.
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 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.
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 (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.
Rotated by -pi/2 (perpendicular to this vector), returned as a copy.
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.
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.
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.
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.
| number | angle | - | In radians |
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.
| number | angle | - | In radians |
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.
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.
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.
| number | angle | - | In radians |
Sets the x-component of this vector, returning this.
Sets all of the components of this vector, returning this.
Sets the y-component of this vector, returning this.
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.
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.
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.
Same as timesScalar.
This is the immutable form of the function multiply(). This will return a new vector, and will not modify this vector.
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.
Returns a duck-typed object meant for use with tandem/phet-io serialization.
Debugging string for the vector.
Converts this to a 3-dimensional vector, with the z-component equal to 0.
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.
Basic 3-dimensional vector, represented as (x,y,z).
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 |
helpful immutable constants
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) |
The X coordinate of the vector.
The Y coordinate of the vector.
The Z coordinate of the vector.
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.
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.
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.
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).
The average (midpoint) between this vector and another vector.
A linear interpolation between this vector (ratio=0) and another vector (ratio=1).
| number | ratio | - | Not necessarily constrained in [0, 1] |
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.
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.
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. |
The Euclidean 3-dimensional cross-product of this vector by the passed-in vector.
The Euclidean distance between this vector (treated as a point) and another point.
The squared Euclidean distance between this vector (treated as a point) and another point.
The squared Euclidean distance between this vector (treated as a point) and another point (x,y,z).
The Euclidean distance between this vector (treated as a point) and another point (x,y,z).
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.
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.
The dot-product (Euclidean inner product) between this vector and another vector v.
The dot-product (Euclidean inner product) between this vector and another vector (x,y,z).
Exact equality comparison between this vector and another vector.
Approximate equality comparison between this vector and another vector.
Whether all of the components are numbers (not NaN) that are not infinity or -infinity.
The magnitude (Euclidean/L2 Norm) of this vector, i.e. $\sqrt{x^2+y^2+z^2}$.
T squared magnitude (square of the Euclidean/L2 Norm) of this vector, i.e. $x^2+y^2+z^2$.
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.
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.
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.
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.
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.
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 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.
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 (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.
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.
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.
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.
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.
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.
Sets the x-component of this vector, returning this.
Sets all of the components of this vector, returning this.
Sets the y-component of this vector, returning this.
Sets the z-component of this vector, returning this.
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.
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.
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.
Same as timesScalar.
This is the immutable form of the function multiply(). This will return a new vector, and will not modify this vector.
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.
Debugging string for the vector.
Converts this to a 2-dimensional vector, discarding the z-component.
Converts this to a 4-dimensional vector, with the z-component equal to 1 (useful for homogeneous coordinates).
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.
Basic 4-dimensional vector, represented as (x,y).
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) |
helpful immutable constants
The W coordinate of the vector. Default is 1, for ease with homogeneous coordinates.
The X coordinate of the vector.
The Y coordinate of the vector.
The Z coordinate of the vector.
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.
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.
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.
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).
The average (midpoint) between this vector and another vector.
A linear interpolation between this vector (ratio=0) and another vector (ratio=1).
| number | ratio | - | Not necessarily constrained in [0, 1] |
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.
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.
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. |
The Euclidean distance between this vector (treated as a point) and another point.
The squared Euclidean distance between this vector (treated as a point) and another point.
The squared Euclidean distance between this vector (treated as a point) and another point (x,y,z,w).
The Euclidean distance between this vector (treated as a point) and another point (x,y,z,w).
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.
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.
The dot-product (Euclidean inner product) between this vector and another vector v.
The dot-product (Euclidean inner product) between this vector and another vector (x,y,z,w).
Exact equality comparison between this vector and another vector.
Approximate equality comparison between this vector and another vector.
Whether all of the components are numbers (not NaN) that are not infinity or -infinity.
The magnitude (Euclidean/L2 Norm) of this vector, i.e. $\sqrt{x^2+y^2+z^2+w^2}$.
The squared magnitude (square of the Euclidean/L2 Norm) of this vector, i.e. $x^2+y^2+z^2+w^2$.
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.
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.
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.
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.
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.
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 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.
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 (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.
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.
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.
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.
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.
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.
Sets the w-component of this vector, returning this.
Sets the x-component of this vector, returning this.
Sets all of the components of this vector, returning this.
Sets the y-component of this vector, returning this.
Sets the z-component of this vector, returning this.
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.
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.
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.
Same as timesScalar.
This is the immutable form of the function multiply(). This will return a new vector, and will not modify this vector.
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.
Debugging string for the vector.
Converts this to a 3-dimensional vector, discarding the w-component.
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.