From 8a8ed845d3f0c1e1518cefb0860562e6fe0a7897 Mon Sep 17 00:00:00 2001 From: Michael Kauzmann Date: Mon, 4 Mar 2024 12:04:01 -0700 Subject: [PATCH] convert to typescript, https://github.com/phetsims/dot/issues/125 Signed-off-by: Michael Kauzmann --- js/Bounds3.ts | 775 ++++++++++++++------------------------------------ 1 file changed, 213 insertions(+), 562 deletions(-) diff --git a/js/Bounds3.ts b/js/Bounds3.ts index 3f5b822..48aafa3 100644 --- a/js/Bounds3.ts +++ b/js/Bounds3.ts @@ -18,39 +18,28 @@ import IOType from '../../tandem/js/types/IOType.js'; import NumberIO from '../../tandem/js/types/NumberIO.js'; import dot from './dot.js'; import Vector3 from './Vector3.js'; +import Matrix3 from './Matrix3.js'; class Bounds3 { + /** * Creates a 3-dimensional bounds (bounding box). - * @public * - * @param {number} minX - The initial minimum X coordinate of the bounds. - * @param {number} minY - The initial minimum Y coordinate of the bounds. - * @param {number} minZ - The initial minimum Z coordinate of the bounds. - * @param {number} maxX - The initial maximum X coordinate of the bounds. - * @param {number} maxY - The initial maximum Y coordinate of the bounds. - * @param {number} maxZ - The initial maximum Z coordinate of the bounds. - */ - constructor( minX, minY, minZ, maxX, maxY, maxZ ) { + * @param minX - The initial minimum X coordinate of the bounds. + * @param minY - The initial minimum Y coordinate of the bounds. + * @param minZ - The initial minimum Z coordinate of the bounds. + * @param maxX - The initial maximum X coordinate of the bounds. + * @param maxY - The initial maximum Y coordinate of the bounds. + * @param maxZ - The initial maximum Z coordinate of the bounds. + */ + public constructor( + public minX: number, + public minY: number, + public minZ: number, + public maxX: number, + public maxY: number, + public maxZ: number ) { assert && assert( maxY !== undefined, 'Bounds3 requires 4 parameters' ); - - // @public {number} - The minimum X coordinate of the bounds. - this.minX = minX; - - // @public {number} - The minimum Y coordinate of the bounds. - this.minY = minY; - - // @public {number} - The minimum Z coordinate of the bounds. - this.minZ = minZ; - - // @public {number} - The maximum X coordinate of the bounds. - this.maxX = maxX; - - // @public {number} - The maximum Y coordinate of the bounds. - this.maxY = maxY; - - // @public {number} - The maximum Z coordinate of the bounds. - this.maxZ = maxZ; } @@ -60,33 +49,24 @@ class Bounds3 { /** * The width of the bounds, defined as maxX - minX. - * @public - * - * @returns {number} */ - getWidth() { return this.maxX - this.minX; } + public getWidth(): number { return this.maxX - this.minX; } - get width() { return this.getWidth(); } + public get width(): number { return this.getWidth(); } /** * The height of the bounds, defined as maxY - minY. - * @public - * - * @returns {number} */ - getHeight() { return this.maxY - this.minY; } + public getHeight(): number { return this.maxY - this.minY; } - get height() { return this.getHeight(); } + public get height(): number { return this.getHeight(); } /** * The depth of the bounds, defined as maxZ - minZ. - * @public - * - * @returns {number} */ - getDepth() { return this.maxZ - this.minZ; } + public getDepth(): number { return this.maxZ - this.minZ; } - get depth() { return this.getDepth(); } + public get depth(): number { return this.getDepth(); } /* * Convenience locations @@ -101,287 +81,197 @@ class Bounds3 { /** * Alias for minX, when thinking of the bounds as an (x,y,z,width,height,depth) cuboid. - * @public - * - * @returns {number} */ - getX() { return this.minX; } + public getX(): number { return this.minX; } - get x() { return this.getX(); } + public get x(): number { return this.getX(); } /** * Alias for minY, when thinking of the bounds as an (x,y,z,width,height,depth) cuboid. - * @public - * - * @returns {number} */ - getY() { return this.minY; } + public getY(): number { return this.minY; } - get y() { return this.getY(); } + public get y(): number { return this.getY(); } /** * Alias for minZ, when thinking of the bounds as an (x,y,z,width,height,depth) cuboid. - * @public - * - * @returns {number} */ - getZ() { return this.minZ; } + public getZ(): number { return this.minZ; } - get z() { return this.getZ(); } + public get z(): number { return this.getZ(); } /** * Alias for minX, supporting the explicit getter function style. - * @public - * - * @returns {number} */ - getMinX() { return this.minX; } + public getMinX(): number { return this.minX; } /** * Alias for minY, supporting the explicit getter function style. - * @public - * - * @returns {number} */ - getMinY() { return this.minY; } + public getMinY(): number { return this.minY; } /** * Alias for minZ, supporting the explicit getter function style. - * @public - * - * @returns {number} */ - getMinZ() { return this.minZ; } + public getMinZ(): number { return this.minZ; } /** * Alias for maxX, supporting the explicit getter function style. - * @public - * - * @returns {number} */ - getMaxX() { return this.maxX; } + public getMaxX(): number { return this.maxX; } /** * Alias for maxY, supporting the explicit getter function style. - * @public - * - * @returns {number} */ - getMaxY() { return this.maxY; } + public getMaxY(): number { return this.maxY; } /** * Alias for maxZ, supporting the explicit getter function style. - * @public - * - * @returns {number} */ - getMaxZ() { return this.maxZ; } + public getMaxZ(): number { return this.maxZ; } /** * Alias for minX, when thinking in the UI-layout manner. - * @public - * - * @returns {number} */ - getLeft() { return this.minX; } + public getLeft(): number { return this.minX; } - get left() { return this.minX; } + public get left(): number { return this.minX; } /** * Alias for minY, when thinking in the UI-layout manner. - * @public - * - * @returns {number} */ - getTop() { return this.minY; } + public getTop(): number { return this.minY; } - get top() { return this.minY; } + public get top(): number { return this.minY; } /** * Alias for minZ, when thinking in the UI-layout manner. - * @public - * - * @returns {number} */ - getBack() { return this.minZ; } + public getBack(): number { return this.minZ; } - get back() { return this.minZ; } + public get back(): number { return this.minZ; } /** * Alias for maxX, when thinking in the UI-layout manner. - * @public - * - * @returns {number} */ - getRight() { return this.maxX; } + public getRight(): number { return this.maxX; } - get right() { return this.maxX; } + public get right(): number { return this.maxX; } /** * Alias for maxY, when thinking in the UI-layout manner. - * @public - * - * @returns {number} */ - getBottom() { return this.maxY; } + public getBottom(): number { return this.maxY; } - get bottom() { return this.maxY; } + public get bottom(): number { return this.maxY; } /** * Alias for maxZ, when thinking in the UI-layout manner. - * @public - * - * @returns {number} */ - getFront() { return this.maxZ; } + public getFront(): number { return this.maxZ; } - get front() { return this.maxZ; } + public get front(): number { return this.maxZ; } /** * The horizontal (X-coordinate) center of the bounds, averaging the minX and maxX. - * @public - * - * @returns {number} */ - getCenterX() { return ( this.maxX + this.minX ) / 2; } + public getCenterX(): number { return ( this.maxX + this.minX ) / 2; } - get centerX() { return this.getCenterX(); } + public get centerX(): number { return this.getCenterX(); } /** * The vertical (Y-coordinate) center of the bounds, averaging the minY and maxY. - * @public - * - * @returns {number} */ - getCenterY() { return ( this.maxY + this.minY ) / 2; } + public getCenterY(): number { return ( this.maxY + this.minY ) / 2; } - get centerY() { return this.getCenterY(); } + public get centerY(): number { return this.getCenterY(); } /** * The depthwise (Z-coordinate) center of the bounds, averaging the minZ and maxZ. - * @public - * - * @returns {number} */ - getCenterZ() { return ( this.maxZ + this.minZ ) / 2; } + public getCenterZ(): number { return ( this.maxZ + this.minZ ) / 2; } - get centerZ() { return this.getCenterZ(); } + public get centerZ(): number { return this.getCenterZ(); } /** * The point (centerX, centerY, centerZ), in the center of the bounds. - * @public - * - * @returns {Vector3} */ - getCenter() { return new Vector3( this.getCenterX(), this.getCenterY(), this.getCenterZ() ); } + public getCenter(): Vector3 { return new Vector3( this.getCenterX(), this.getCenterY(), this.getCenterZ() ); } - get center() { return this.getCenter(); } + public get center(): Vector3 { return this.getCenter(); } /** * 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. - * @public - * - * @returns {boolean} */ - isEmpty() { return this.getWidth() < 0 || this.getHeight() < 0 || this.getDepth() < 0; } + public isEmpty(): boolean { return this.getWidth() < 0 || this.getHeight() < 0 || this.getDepth() < 0; } /** * Whether our minimums and maximums are all finite numbers. This will exclude Bounds3.NOTHING and Bounds3.EVERYTHING. - * @public - * - * @returns {boolean} */ - isFinite() { + public isFinite(): boolean { return isFinite( this.minX ) && isFinite( this.minY ) && isFinite( this.minZ ) && isFinite( this.maxX ) && isFinite( this.maxY ) && isFinite( this.maxZ ); } /** * Whether this bounds has a non-zero area (non-zero positive width, height and depth). - * @public - * - * @returns {boolean} */ - hasNonzeroArea() { + public hasNonzeroArea(): boolean { return this.getWidth() > 0 && this.getHeight() > 0 && this.getDepth() > 0; } /** * Whether this bounds has a finite and non-negative width, height and depth. - * @public - * - * @returns {boolean} */ - isValid() { + public isValid(): boolean { return !this.isEmpty() && this.isFinite(); } /** * Whether the coordinates are contained inside the bounding box, or are on the boundary. - * @public * - * @param {number} x - X coordinate of the point to check - * @param {number} y - Y coordinate of the point to check - * @param {number} z - Z coordinate of the point to check - * @returns {boolean} + * @param x - X coordinate of the point to check + * @param y - Y coordinate of the point to check + * @param z - Z coordinate of the point to check */ - containsCoordinates( x, y, z ) { + public containsCoordinates( x: number, y: number, z: number ): boolean { return this.minX <= x && x <= this.maxX && this.minY <= y && y <= this.maxY && this.minZ <= z && z <= this.maxZ; } /** * Whether the point is contained inside the bounding box, or is on the boundary. - * @public - * - * @param {Vector3} point - * @returns {boolean} */ - containsPoint( point ) { + public containsPoint( point: Vector3 ): boolean { return this.containsCoordinates( point.x, point.y, point.z ); } /** * Whether this bounding box completely contains the bounding box passed as a parameter. The boundary of a box is * considered to be "contained". - * @public - * - * @param {Bounds3} bounds - * @returns {boolean} */ - containsBounds( bounds ) { + public containsBounds( bounds: Bounds3 ): boolean { return this.minX <= bounds.minX && this.maxX >= bounds.maxX && this.minY <= bounds.minY && this.maxY >= bounds.maxY && this.minZ <= bounds.minZ && this.maxZ >= bounds.maxZ; } /** * Whether this and another bounding box have any points of intersection (including touching boundaries). - * @public - * - * @param {Bounds3} bounds - * @returns {boolean} */ - intersectsBounds( bounds ) { + public intersectsBounds( bounds: Bounds3 ): boolean { // TODO: more efficient way of doing this? https://github.com/phetsims/dot/issues/96 return !this.intersection( bounds ).isEmpty(); } /** * Debugging string for the bounds. - * @public - * - * @returns {string} */ - toString() { + public toString(): string { return `[x:(${this.minX},${this.maxX}),y:(${this.minY},${this.maxY}),z:(${this.minZ},${this.maxZ})]`; } /** * Exact equality comparison between this bounds and another bounds. - * @public - * - * @param {Bounds3} other - * @returns {boolean} - Whether the two bounds are equal */ - equals( other ) { + public equals( other: Bounds3 ): boolean { return this.minX === other.minX && this.minY === other.minY && this.minZ === other.minZ && @@ -392,14 +282,9 @@ class Bounds3 { /** * Approximate equality comparison between this bounds and another bounds. - * @public - * - * @param {Bounds3} other - * @param {number} epsilon - * @returns {boolean} - Whether difference between the two bounds has no min/max with an absolute value greater - * than epsilon. + * @returns - Whether difference between the two bounds has no min/max with an absolute value greater than epsilon. */ - equalsEpsilon( other, epsilon ) { + public equalsEpsilon( other: Bounds3, epsilon: number ): boolean { epsilon = epsilon !== undefined ? epsilon : 0; const thisFinite = this.isFinite(); const otherFinite = other.isFinite(); @@ -435,16 +320,13 @@ class Bounds3 { /** * Creates a copy of this bounds, or if a bounds is passed in, set that bounds's values to ours. - * @public * * 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. - * - * @param {Bounds3} [bounds] - If not provided, creates a new Bounds3 with filled in values. Otherwise, fills in the + * @param 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. - * @returns {Bounds3} */ - copy( bounds ) { + public copy( bounds?: Bounds3 ): Bounds3 { if ( bounds ) { return bounds.set( this ); } @@ -455,15 +337,11 @@ class Bounds3 { /** * The smallest bounds that contains both this bounds and the input bounds, returned as a copy. - * @public * * This is the immutable form of the function includeBounds(). This will return a new bounds, and will not modify * this bounds. - * - * @param {Bounds3} bounds - * @returns {Bounds3} */ - union( bounds ) { + public union( bounds: Bounds3 ): Bounds3 { return new Bounds3( Math.min( this.minX, bounds.minX ), Math.min( this.minY, bounds.minY ), @@ -476,15 +354,11 @@ class Bounds3 { /** * The smallest bounds that is contained by both this bounds and the input bounds, returned as a copy. - * @public * * This is the immutable form of the function constrainBounds(). This will return a new bounds, and will not modify * this bounds. - * - * @param {Bounds3} bounds - * @returns {Bounds3} */ - intersection( bounds ) { + public intersection( bounds: Bounds3 ): Bounds3 { return new Bounds3( Math.max( this.minX, bounds.minX ), Math.max( this.minY, bounds.minY ), @@ -499,17 +373,11 @@ class Bounds3 { /** * The smallest bounds that contains this bounds and the point (x,y,z), returned as a copy. - * @public * * This is the immutable form of the function addCoordinates(). This will return a new bounds, and will not modify * this bounds. - * - * @param {number} x - * @param {number} y - * @param {number} z - * @returns {Bounds3} */ - withCoordinates( x, y, z ) { + public withCoordinates( x: number, y: number, z: number ): Bounds3 { return new Bounds3( Math.min( this.minX, x ), Math.min( this.minY, y ), @@ -522,99 +390,71 @@ class Bounds3 { /** * The smallest bounds that contains this bounds and the input point, returned as a copy. - * @public * * This is the immutable form of the function addPoint(). This will return a new bounds, and will not modify * this bounds. - * - * @param {Vector3} point - * @returns {Bounds3} */ - withPoint( point ) { + public withPoint( point: Vector3 ): Bounds3 { return this.withCoordinates( point.x, point.y, point.z ); } /** * A copy of this bounds, with minX replaced with the input. - * @public * * This is the immutable form of the function setMinX(). This will return a new bounds, and will not modify * this bounds. - * - * @param {number} minX - * @returns {Bounds3} */ - withMinX( minX ) { + public withMinX( minX: number ): Bounds3 { return new Bounds3( minX, this.minY, this.minZ, this.maxX, this.maxY, this.maxZ ); } /** * A copy of this bounds, with minY replaced with the input. - * @public * * This is the immutable form of the function setMinY(). This will return a new bounds, and will not modify * this bounds. - * - * @param {number} minY - * @returns {Bounds3} */ - withMinY( minY ) { + public withMinY( minY: number ): Bounds3 { return new Bounds3( this.minX, minY, this.minZ, this.maxX, this.maxY, this.maxZ ); } /** * A copy of this bounds, with minZ replaced with the input. - * @public * * This is the immutable form of the function setMinZ(). This will return a new bounds, and will not modify * this bounds. - * - * @param {number} minZ - * @returns {Bounds3} */ - withMinZ( minZ ) { + public withMinZ( minZ: number ): Bounds3 { return new Bounds3( this.minX, this.minY, minZ, this.maxX, this.maxY, this.maxZ ); } /** * A copy of this bounds, with maxX replaced with the input. - * @public * * This is the immutable form of the function setMaxX(). This will return a new bounds, and will not modify * this bounds. - * - * @param {number} maxX - * @returns {Bounds3} */ - withMaxX( maxX ) { + public withMaxX( maxX: number ): Bounds3 { return new Bounds3( this.minX, this.minY, this.minZ, maxX, this.maxY, this.maxZ ); } /** * A copy of this bounds, with maxY replaced with the input. - * @public * * This is the immutable form of the function setMaxY(). This will return a new bounds, and will not modify * this bounds. - * - * @param {number} maxY - * @returns {Bounds3} */ - withMaxY( maxY ) { + public withMaxY( maxY: number ): Bounds3 { return new Bounds3( this.minX, this.minY, this.minZ, this.maxX, maxY, this.maxZ ); } /** * A copy of this bounds, with maxZ replaced with the input. - * @public * * This is the immutable form of the function setMaxZ(). This will return a new bounds, and will not modify * this bounds. - * - * @param {number} maxZ - * @returns {Bounds3} */ - withMaxZ( maxZ ) { + public withMaxZ( maxZ: number ): Bounds3 { return new Bounds3( this.minX, this.minY, this.minZ, this.maxX, this.maxY, maxZ ); } @@ -622,14 +462,11 @@ class 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. - * @public * * This is the immutable form of the function roundOut(). This will return a new bounds, and will not modify * this bounds. - * - * @returns {Bounds3} */ - roundedOut() { + public roundedOut(): Bounds3 { return new Bounds3( Math.floor( this.minX ), Math.floor( this.minY ), @@ -644,14 +481,11 @@ class 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. - * @public * * This is the immutable form of the function roundIn(). This will return a new bounds, and will not modify * this bounds. - * - * @returns {Bounds3} */ - roundedIn() { + public roundedIn(): Bounds3 { return new Bounds3( Math.ceil( this.minX ), Math.ceil( this.minY ), @@ -665,7 +499,6 @@ class Bounds3 { /** * A bounding box (still axis-aligned) that contains the transformed shape of this bounds, applying the matrix as * an affine transformation. - * @public * * 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 @@ -673,215 +506,163 @@ class Bounds3 { * * This is the immutable form of the function transform(). This will return a new bounds, and will not modify * this bounds. - * - * @param {Matrix4} matrix - * @returns {Bounds3} + * // TODO: Should be Matrix4 type, https://github.com/phetsims/dot/issues/125 */ - transformed( matrix ) { + public transformed( matrix: Matrix3 ): Bounds3 { return this.copy().transform( matrix ); } /** * A bounding box that is expanded on all sides by the specified amount.) - * @public * * This is the immutable form of the function dilate(). This will return a new bounds, and will not modify * this bounds. - * - * @param {number} d - * @returns {Bounds3} */ - dilated( d ) { + public dilated( d: number ): Bounds3 { return this.dilatedXYZ( d, d, d ); } /** * A bounding box that is expanded horizontally (on the left and right) by the specified amount. - * @public * * This is the immutable form of the function dilateX(). This will return a new bounds, and will not modify * this bounds. - * - * @param {number} x - * @returns {Bounds3} */ - dilatedX( x ) { + public dilatedX( x: number ): Bounds3 { return new Bounds3( this.minX - x, this.minY, this.minZ, this.maxX + x, this.maxY, this.maxZ ); } /** * A bounding box that is expanded vertically (on the top and bottom) by the specified amount. - * @public * * This is the immutable form of the function dilateY(). This will return a new bounds, and will not modify * this bounds. - * - * @param {number} y - * @returns {Bounds3} */ - dilatedY( y ) { + public dilatedY( y: number ): Bounds3 { return new Bounds3( this.minX, this.minY - y, this.minZ, this.maxX, this.maxY + y, this.maxZ ); } /** * A bounding box that is expanded depth-wise (on the front and back) by the specified amount. - * @public * * This is the immutable form of the function dilateZ(). This will return a new bounds, and will not modify * this bounds. - * - * @param {number} z - * @returns {Bounds3} */ - dilatedZ( z ) { + public dilatedZ( z: number ): Bounds3 { return new Bounds3( this.minX, this.minY, this.minZ - z, this.maxX, this.maxY, this.maxZ + z ); } /** * 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 ). - * @public * * This is the immutable form of the function dilateXYZ(). This will return a new bounds, and will not modify * this bounds. - * - * @param {number} x - Amount to dilate horizontally (for each side) - * @param {number} y - Amount to dilate vertically (for each side) - * @param {number} z - Amount to dilate depth-wise (for each side) - * @returns {Bounds3} + * @param x - Amount to dilate horizontally (for each side) + * @param y - Amount to dilate vertically (for each side) + * @param z - Amount to dilate depth-wise (for each side) */ - dilatedXYZ( x, y, z ) { + public dilatedXYZ( x: number, y: number, z: number ): Bounds3 { return new Bounds3( this.minX - x, this.minY - y, this.minZ - z, this.maxX + x, this.maxY + y, this.maxZ + z ); } /** * A bounding box that is contracted on all sides by the specified amount. - * @public * * This is the immutable form of the function erode(). This will return a new bounds, and will not modify * this bounds. - * - * @param {number} amount - * @returns {Bounds3} */ - eroded( amount ) { return this.dilated( -amount ); } + public eroded( amount: number ): Bounds3 { + return this.dilated( -amount ); + } /** * A bounding box that is contracted horizontally (on the left and right) by the specified amount. - * @public * * This is the immutable form of the function erodeX(). This will return a new bounds, and will not modify * this bounds. - * - * @param {number} x - * @returns {Bounds3} */ - erodedX( x ) { return this.dilatedX( -x ); } + public erodedX( x: number ): Bounds3 { + return this.dilatedX( -x ); + } /** * A bounding box that is contracted vertically (on the top and bottom) by the specified amount. - * @public * * This is the immutable form of the function erodeY(). This will return a new bounds, and will not modify * this bounds. - * - * @param {number} y - * @returns {Bounds3} */ - erodedY( y ) { return this.dilatedY( -y ); } + public erodedY( y: number ): Bounds3 { + return this.dilatedY( -y ); + } /** * A bounding box that is contracted depth-wise (on the front and back) by the specified amount. - * @public * * This is the immutable form of the function erodeZ(). This will return a new bounds, and will not modify * this bounds. - * - * @param {number} z - * @returns {Bounds3} */ - erodedZ( z ) { return this.dilatedZ( -z ); } + public erodedZ( z: number ): Bounds3 { + return this.dilatedZ( -z ); + } /** * A bounding box that is contracted on all sides, with different amounts of contraction along each axis. - * @public * * This is the immutable form of the function erodeXYZ(). This will return a new bounds, and will not modify * this bounds. - * - * @param {number} x - Amount to erode horizontally (for each side) - * @param {number} y - Amount to erode vertically (for each side) - * @param {number} z - Amount to erode depth-wise (for each side) - * @returns {Bounds3} + * @param x - Amount to erode horizontally (for each side) + * @param y - Amount to erode vertically (for each side) + * @param z - Amount to erode depth-wise (for each side) */ - erodedXYZ( x, y, z ) { return this.dilatedXYZ( -x, -y, -z ); } + public erodedXYZ( x: number, y: number, z: number ): Bounds3 { + return this.dilatedXYZ( -x, -y, -z ); + } /** * Our bounds, translated horizontally by x, returned as a copy. - * @public * * This is the immutable form of the function shiftX(). This will return a new bounds, and will not modify * this bounds. - * - * @param {number} x - * @returns {Bounds3} */ - shiftedX( x ) { + public shiftedX( x: number ): Bounds3 { return new Bounds3( this.minX + x, this.minY, this.minZ, this.maxX + x, this.maxY, this.maxZ ); } /** * Our bounds, translated vertically by y, returned as a copy. - * @public * * This is the immutable form of the function shiftY(). This will return a new bounds, and will not modify * this bounds. - * - * @param {number} y - * @returns {Bounds3} */ - shiftedY( y ) { + public shiftedY( y: number ): Bounds3 { return new Bounds3( this.minX, this.minY + y, this.minZ, this.maxX, this.maxY + y, this.maxZ ); } /** * Our bounds, translated depth-wise by z, returned as a copy. - * @public * * This is the immutable form of the function shiftZ(). This will return a new bounds, and will not modify * this bounds. - * - * @param {number} z - * @returns {Bounds3} */ - shiftedZ( z ) { + public shiftedZ( z: number ): Bounds3 { return new Bounds3( this.minX, this.minY, this.minZ + z, this.maxX, this.maxY, this.maxZ + z ); } /** * Our bounds, translated by (x,y,z), returned as a copy. - * @public * * This is the immutable form of the function shift(). This will return a new bounds, and will not modify * this bounds. - * - * @param {number} x - * @param {number} y - * @param {number} z - * @returns {Bounds3} */ - shiftedXYZ( x, y, z ) { + public shiftedXYZ( x: number, y: number, z: number ): Bounds3 { return new Bounds3( this.minX + x, this.minY + y, this.minZ + z, this.maxX + x, this.maxY + y, this.maxZ + z ); } /** * Returns our bounds, translated by a vector, returned as a copy. - * @public - * - * @param {Vector3} v - * @returns {Bounds3} */ - shifted( v ) { + public shifted( v: Vector3 ): Bounds3 { return this.shiftedXYZ( v.x, v.y, v.z ); } @@ -894,17 +675,8 @@ class Bounds3 { /** * Sets each value for this bounds, and returns itself. - * @public - * - * @param {number} minX - * @param {number} minY - * @param {number} minZ - * @param {number} maxX - * @param {number} maxY - * @param {number} maxZ - * @returns {Bounds3} */ - setMinMax( minX, minY, minZ, maxX, maxY, maxZ ) { + public setMinMax( minX: number, minY: number, minZ: number, maxX: number, maxY: number, maxZ: number ): Bounds3 { this.minX = minX; this.minY = minY; this.minZ = minZ; @@ -916,119 +688,87 @@ class Bounds3 { /** * Sets the value of minX. - * @public * * This is the mutable form of the function withMinX(). This will mutate (change) this bounds, in addition to returning * this bounds itself. - * - * @param {number} minX - * @returns {Bounds3} */ - setMinX( minX ) { + public setMinX( minX: number ): Bounds3 { this.minX = minX; return this; } /** * Sets the value of minY. - * @public * * This is the mutable form of the function withMinY(). This will mutate (change) this bounds, in addition to returning * this bounds itself. - * - * @param {number} minY - * @returns {Bounds3} */ - setMinY( minY ) { + public setMinY( minY: number ): Bounds3 { this.minY = minY; return this; } /** * Sets the value of minZ. - * @public * * This is the mutable form of the function withMinZ(). This will mutate (change) this bounds, in addition to returning * this bounds itself. - * - * @param {number} minZ - * @returns {Bounds3} */ - setMinZ( minZ ) { + public setMinZ( minZ: number ): Bounds3 { this.minZ = minZ; return this; } /** * Sets the value of maxX. - * @public * * This is the mutable form of the function withMaxX(). This will mutate (change) this bounds, in addition to returning * this bounds itself. - * - * @param {number} maxX - * @returns {Bounds3} */ - setMaxX( maxX ) { + public setMaxX( maxX: number ): Bounds3 { this.maxX = maxX; return this; } /** * Sets the value of maxY. - * @public * * This is the mutable form of the function withMaxY(). This will mutate (change) this bounds, in addition to returning * this bounds itself. - * - * @param {number} maxY - * @returns {Bounds3} */ - setMaxY( maxY ) { + public setMaxY( maxY: number ): Bounds3 { this.maxY = maxY; return this; } /** * Sets the value of maxZ. - * @public * * This is the mutable form of the function withMaxZ(). This will mutate (change) this bounds, in addition to returning * this bounds itself. - * - * @param {number} maxZ - * @returns {Bounds3} */ - setMaxZ( maxZ ) { + public setMaxZ( maxZ: number ): Bounds3 { this.maxZ = maxZ; return this; } /** * Sets the values of this bounds to be equal to the input bounds. - * @public * * This is the mutable form of the function copy(). This will mutate (change) this bounds, in addition to returning * this bounds itself. - * - * @param {Bounds3} bounds - * @returns {Bounds3} */ - set( bounds ) { + public set( bounds: Bounds3 ): Bounds3 { return this.setMinMax( bounds.minX, bounds.minY, bounds.minZ, bounds.maxX, bounds.maxY, bounds.maxZ ); } /** * Modifies this bounds so that it contains both its original bounds and the input bounds. - * @public * * This is the mutable form of the function union(). This will mutate (change) this bounds, in addition to returning * this bounds itself. - * - * @param {Bounds3} bounds - * @returns {Bounds3} */ - includeBounds( bounds ) { + public includeBounds( bounds: Bounds3 ): Bounds3 { return this.setMinMax( Math.min( this.minX, bounds.minX ), Math.min( this.minY, bounds.minY ), @@ -1041,15 +781,11 @@ class Bounds3 { /** * Modifies this bounds so that it is the largest bounds contained both in its original bounds and in the input bounds. - * @public * * This is the mutable form of the function intersection(). This will mutate (change) this bounds, in addition to returning * this bounds itself. - * - * @param {Bounds3} bounds - * @returns {Bounds3} */ - constrainBounds( bounds ) { + public constrainBounds( bounds: Bounds3 ): Bounds3 { return this.setMinMax( Math.max( this.minX, bounds.minX ), Math.max( this.minY, bounds.minY ), @@ -1062,17 +798,11 @@ class Bounds3 { /** * Modifies this bounds so that it contains both its original bounds and the input point (x,y,z). - * @public * * This is the mutable form of the function withCoordinates(). This will mutate (change) this bounds, in addition to returning * this bounds itself. - * - * @param {number} x - * @param {number} y - * @param {number} z - * @returns {Bounds3} */ - addCoordinates( x, y, z ) { + public addCoordinates( x: number, y: number, z: number ): Bounds3 { return this.setMinMax( Math.min( this.minX, x ), Math.min( this.minY, y ), @@ -1085,29 +815,22 @@ class Bounds3 { /** * Modifies this bounds so that it contains both its original bounds and the input point. - * @public * * This is the mutable form of the function withPoint(). This will mutate (change) this bounds, in addition to returning * this bounds itself. - * - * @param {Vector3} point - * @returns {Bounds3} */ - addPoint( point ) { + public addPoint( point: Vector3 ): Bounds3 { return this.addCoordinates( point.x, point.y, point.z ); } /** * Modifies this bounds so that its boundaries are integer-aligned, rounding the minimum boundaries down and the * maximum boundaries up (expanding as necessary). - * @public * * This is the mutable form of the function roundedOut(). This will mutate (change) this bounds, in addition to returning * this bounds itself. - * - * @returns {Bounds3} */ - roundOut() { + public roundOut(): Bounds3 { return this.setMinMax( Math.floor( this.minX ), Math.floor( this.minY ), @@ -1121,14 +844,11 @@ class Bounds3 { /** * Modifies this bounds so that its boundaries are integer-aligned, rounding the minimum boundaries up and the * maximum boundaries down (contracting as necessary). - * @public * * This is the mutable form of the function roundedIn(). This will mutate (change) this bounds, in addition to returning * this bounds itself. - * - * @returns {Bounds3} */ - roundIn() { + public roundIn(): Bounds3 { return this.setMinMax( Math.ceil( this.minX ), Math.ceil( this.minY ), @@ -1142,7 +862,6 @@ class Bounds3 { /** * Modifies this bounds so that it would fully contain a transformed version if its previous value, applying the * matrix as an affine transformation. - * @public * * 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 @@ -1150,11 +869,9 @@ class Bounds3 { * * This is the mutable form of the function transformed(). This will mutate (change) this bounds, in addition to returning * this bounds itself. - * - * @param {Matrix4} matrix - * @returns {Bounds3} + * // TODO: should be Matrix4 type, https://github.com/phetsims/dot/issues/125 */ - transform( matrix ) { + public transform( matrix: Matrix3 ): Bounds3 { // do nothing if ( this.isEmpty() ) { return this; @@ -1176,7 +893,7 @@ class Bounds3 { // make sure all 4 corners are inside this transformed bounding box const vector = new Vector3( 0, 0, 0 ); - function withIt( vector ) { + function withIt( vector: Vector3 ): void { minX = Math.min( minX, vector.x ); minY = Math.min( minY, vector.y ); minZ = Math.min( minZ, vector.z ); @@ -1198,222 +915,164 @@ class Bounds3 { /** * Expands this bounds on all sides by the specified amount. - * @public * * This is the mutable form of the function dilated(). This will mutate (change) this bounds, in addition to returning * this bounds itself. - * - * @param {number} d - * @returns {Bounds3} */ - dilate( d ) { + public dilate( d: number ): Bounds3 { return this.dilateXYZ( d, d, d ); } /** * Expands this bounds horizontally (left and right) by the specified amount. - * @public * * This is the mutable form of the function dilatedX(). This will mutate (change) this bounds, in addition to returning * this bounds itself. - * - * @param {number} x - * @returns {Bounds3} */ - dilateX( x ) { + public dilateX( x: number ): Bounds3 { return this.setMinMax( this.minX - x, this.minY, this.minZ, this.maxX + x, this.maxY, this.maxZ ); } /** * Expands this bounds vertically (top and bottom) by the specified amount. - * @public * * This is the mutable form of the function dilatedY(). This will mutate (change) this bounds, in addition to returning * this bounds itself. - * - * @param {number} y - * @returns {Bounds3} */ - dilateY( y ) { + public dilateY( y: number ): Bounds3 { return this.setMinMax( this.minX, this.minY - y, this.minZ, this.maxX, this.maxY + y, this.maxZ ); } /** * Expands this bounds depth-wise (front and back) by the specified amount. - * @public * * This is the mutable form of the function dilatedZ(). This will mutate (change) this bounds, in addition to returning * this bounds itself. - * - * @param {number} z - * @returns {Bounds3} */ - dilateZ( z ) { + public dilateZ( z: number ): Bounds3 { return this.setMinMax( this.minX, this.minY, this.minZ - z, this.maxX, this.maxY, this.maxZ + z ); } /** * Expands this bounds independently along each axis. Will be equal to calling * bounds.dilateX( x ).dilateY( y ).dilateZ( z ). - * @public * * This is the mutable form of the function dilatedXYZ(). This will mutate (change) this bounds, in addition to returning * this bounds itself. - * - * @param {number} x - * @param {number} y - * @param {number} z - * @returns {Bounds3} */ - dilateXYZ( x, y, z ) { + public dilateXYZ( x: number, y: number, z: number ): Bounds3 { return this.setMinMax( this.minX - x, this.minY - y, this.minZ - z, this.maxX + x, this.maxY + y, this.maxZ + z ); } /** * Contracts this bounds on all sides by the specified amount. - * @public * * This is the mutable form of the function eroded(). This will mutate (change) this bounds, in addition to returning * this bounds itself. - * - * @param {number} d - * @returns {Bounds3} */ - erode( d ) { return this.dilate( -d ); } + public erode( d: number ): Bounds3 { + return this.dilate( -d ); + } /** * Contracts this bounds horizontally (left and right) by the specified amount. - * @public * * This is the mutable form of the function erodedX(). This will mutate (change) this bounds, in addition to returning * this bounds itself. - * - * @param {number} x - * @returns {Bounds3} */ - erodeX( x ) { return this.dilateX( -x ); } + public erodeX( x: number ): Bounds3 { + return this.dilateX( -x ); + } /** * Contracts this bounds vertically (top and bottom) by the specified amount. - * @public * * This is the mutable form of the function erodedY(). This will mutate (change) this bounds, in addition to returning * this bounds itself. - * - * @param {number} y - * @returns {Bounds3} */ - erodeY( y ) { return this.dilateY( -y ); } + public erodeY( y: number ): Bounds3 { + return this.dilateY( -y ); + } /** * Contracts this bounds depth-wise (front and back) by the specified amount. - * @public * * This is the mutable form of the function erodedZ(). This will mutate (change) this bounds, in addition to returning * this bounds itself. - * - * @param {number} z - * @returns {Bounds3} */ - erodeZ( z ) { return this.dilateZ( -z ); } + public erodeZ( z: number ): Bounds3 { + return this.dilateZ( -z ); + } /** * Contracts this bounds independently along each axis. Will be equal to calling * bounds.erodeX( x ).erodeY( y ).erodeZ( z ). - * @public * * This is the mutable form of the function erodedXYZ(). This will mutate (change) this bounds, in addition to returning * this bounds itself. - * - * @param {number} x - * @param {number} y - * @param {number} z - * @returns {Bounds3} */ - erodeXYZ( x, y, z ) { return this.dilateXYZ( -x, -y, -z ); } + public erodeXYZ( x: number, y: number, z: number ): Bounds3 { + return this.dilateXYZ( -x, -y, -z ); + } /** * Translates our bounds horizontally by x. - * @public * * This is the mutable form of the function shiftedX(). This will mutate (change) this bounds, in addition to returning * this bounds itself. - * - * @param {number} x - * @returns {Bounds3} */ - shiftX( x ) { + public shiftX( x: number ): Bounds3 { return this.setMinMax( this.minX + x, this.minY, this.minZ, this.maxX + x, this.maxY, this.maxZ ); } /** * Translates our bounds vertically by y. - * @public * * This is the mutable form of the function shiftedY(). This will mutate (change) this bounds, in addition to returning * this bounds itself. - * - * @param {number} y - * @returns {Bounds3} */ - shiftY( y ) { + public shiftY( y: number ): Bounds3 { return this.setMinMax( this.minX, this.minY + y, this.minZ, this.maxX, this.maxY + y, this.maxZ ); } /** * Translates our bounds depth-wise by z. - * @public * * This is the mutable form of the function shiftedZ(). This will mutate (change) this bounds, in addition to returning * this bounds itself. - * - * @param {number} z - * @returns {Bounds3} */ - shiftZ( z ) { + public shiftZ( z: number ): Bounds3 { return this.setMinMax( this.minX, this.minY, this.minZ + z, this.maxX, this.maxY, this.maxZ + z ); } /** * Translates our bounds by (x,y,z). - * @public * * This is the mutable form of the function shifted(). This will mutate (change) this bounds, in addition to returning * this bounds itself. - * - * @param {number} x - * @param {number} y - * @param {number} z - * @returns {Bounds3} */ - shiftXYZ( x, y, z ) { + public shiftXYZ( x: number, y: number, z: number ): Bounds3 { return this.setMinMax( this.minX + x, this.minY + y, this.minZ + z, this.maxX + x, this.maxY + y, this.maxZ + z ); } /** * Translates our bounds by the given vector. - * @public - * - * @param {Vector3} v - * @returns {Bounds3} */ - shift( v ) { + public shift( v: Vector3 ): Bounds3 { return this.shiftXYZ( v.x, v.y, v.z ); } /** * Returns a new Bounds3 object, with the cuboid (3d rectangle) construction with x, y, z, width, height and depth. - * @public * - * @param {number} x - The minimum value of X for the bounds. - * @param {number} y - The minimum value of Y for the bounds. - * @param {number} z - The minimum value of Z for the bounds. - * @param {number} width - The width (maxX - minX) of the bounds. - * @param {number} height - The height (maxY - minY) of the bounds. - * @param {number} depth - The depth (maxZ - minZ) of the bounds. - * @returns {Bounds3} + * @param x - The minimum value of X for the bounds. + * @param y - The minimum value of Y for the bounds. + * @param z - The minimum value of Z for the bounds. + * @param width - The width (maxX - minX) of the bounds.` + * @param height - The height (maxY - minY) of the bounds. + * @param depth - The depth (maxZ - minZ) of the bounds. */ - static cuboid( x, y, z, width, height, depth ) { + public static cuboid( x: number, y: number, z: number, width: number, height: number, depth: number ): Bounds3 { return new Bounds3( x, y, z, x + width, y + height, z + depth ); } @@ -1421,21 +1080,58 @@ class 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. - * @public - * - * @param {number} x - * @param {number} y - * @param {number} z - * @returns {Bounds3} */ - static point( x, y, z ) { + public static point( x: number, y: number, z: number ): Bounds3 { return new Bounds3( x, y, z, x, y, z ); } -} -// @public (read-only) - Helps to identify the dimension of the bounds -Bounds3.prototype.isBounds = true; -Bounds3.prototype.dimension = 3; + // Helps to identify the dimension of the bounds + public readonly isBounds = true; + public readonly dimension = 3; + + /** + * A constant 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. + * + * @constant {Bounds3} NOTHING + */ + public static readonly NOTHING = new Bounds3( Number.POSITIVE_INFINITY, Number.POSITIVE_INFINITY, Number.POSITIVE_INFINITY, Number.NEGATIVE_INFINITY, Number.NEGATIVE_INFINITY, Number.NEGATIVE_INFINITY ); + + /** + * A constant 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. + * + * @constant {Bounds3} EVERYTHING + */ + public static readonly EVERYTHING = new Bounds3( Number.NEGATIVE_INFINITY, Number.NEGATIVE_INFINITY, Number.NEGATIVE_INFINITY, Number.POSITIVE_INFINITY, Number.POSITIVE_INFINITY, Number.POSITIVE_INFINITY ); + + public static readonly Bounds3IO = new IOType( 'Bounds3IO', { + valueType: Bounds3, + documentation: 'a 3-dimensional bounds (bounding box)', + stateSchema: { + minX: NumberIO, minY: NumberIO, minZ: NumberIO, + maxX: NumberIO, maxY: NumberIO, maxZ: NumberIO + }, + toStateObject: bounds3 => ( { + minX: bounds3.minX, minY: bounds3.minY, minZ: bounds3.minZ, + maxX: bounds3.maxX, maxY: bounds3.maxY, maxZ: bounds3.maxZ + } ), + fromStateObject: stateObject => new Bounds3( + stateObject.minX, stateObject.minY, stateObject.minZ, + stateObject.maxX, stateObject.maxY, stateObject.maxZ + ) + } ); +} dot.register( 'Bounds3', Bounds3 ); @@ -1443,49 +1139,4 @@ Poolable.mixInto( Bounds3, { initialize: Bounds3.prototype.setMinMax } ); -/** - * A constant Bounds3 with minimums = $\infty$, maximums = $-\infty$, so that it represents "no bounds whatsoever". - * @public - * - * 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. - * - * @constant {Bounds3} NOTHING - */ -Bounds3.NOTHING = new Bounds3( Number.POSITIVE_INFINITY, Number.POSITIVE_INFINITY, Number.POSITIVE_INFINITY, Number.NEGATIVE_INFINITY, Number.NEGATIVE_INFINITY, Number.NEGATIVE_INFINITY ); - -/** - * A constant Bounds3 with minimums = $-\infty$, maximums = $\infty$, so that it represents "all bounds". - * @public - * - * 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. - * - * @constant {Bounds3} EVERYTHING - */ -Bounds3.EVERYTHING = new Bounds3( Number.NEGATIVE_INFINITY, Number.NEGATIVE_INFINITY, Number.NEGATIVE_INFINITY, Number.POSITIVE_INFINITY, Number.POSITIVE_INFINITY, Number.POSITIVE_INFINITY ); - -Bounds3.Bounds3IO = new IOType( 'Bounds3IO', { - valueType: Bounds3, - documentation: 'a 3-dimensional bounds (bounding box)', - stateSchema: { - minX: NumberIO, minY: NumberIO, minZ: NumberIO, - maxX: NumberIO, maxY: NumberIO, maxZ: NumberIO - }, - toStateObject: bounds3 => ( { - minX: bounds3.minX, minY: bounds3.minY, minZ: bounds3.minZ, - maxX: bounds3.maxX, maxY: bounds3.maxY, maxZ: bounds3.maxZ - } ), - fromStateObject: stateObject => new Bounds3( - stateObject.minX, stateObject.minY, stateObject.minZ, - stateObject.maxX, stateObject.maxY, stateObject.maxZ - ) -} ); - export default Bounds3;