Bounds3¶

Overview¶

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.

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

Class Bounds3¶

import { Bounds3 } from 'scenerystack/dot';

Constructor¶

new Bounds3( minX : number, minY : number, minZ : number, maxX : number, maxY : number, maxZ : number )¶

Instance Methods¶

getWidth() : number¶

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

getHeight() : number¶

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

getDepth() : number¶

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

getX() : number¶

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

getY() : number¶

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

getZ() : number¶

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

getMinX() : number¶

Alias for minX, supporting the explicit getter function style.

getMinY() : number¶

Alias for minY, supporting the explicit getter function style.

getMinZ() : number¶

Alias for minZ, supporting the explicit getter function style.

getMaxX() : number¶

Alias for maxX, supporting the explicit getter function style.

getMaxY() : number¶

Alias for maxY, supporting the explicit getter function style.

getMaxZ() : number¶

Alias for maxZ, supporting the explicit getter function style.

getLeft() : number¶

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

getTop() : number¶

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

getBack() : number¶

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

getRight() : number¶

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

getBottom() : number¶

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

getFront() : number¶

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

getCenterX() : number¶

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

getCenterY() : number¶

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

getCenterZ() : number¶

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

getCenter() : Vector3¶

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

isEmpty() : boolean¶

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

isFinite() : boolean¶

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

hasNonzeroVolume() : boolean¶

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

isValid() : boolean¶

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

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

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

@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

containsPoint( point : Vector3 ) : boolean¶

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

containsBounds( bounds : Bounds3 ) : boolean¶

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

intersectsBounds( bounds : Bounds3 ) : boolean¶

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

toString() : string¶

Debugging string for the bounds.

equals( other : Bounds3 ) : boolean¶

Exact equality comparison between this bounds and another bounds.

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

Approximate equality comparison between this bounds and another bounds. @returns - Whether difference between the two bounds has no min/max with an absolute value greater than epsilon.

copy( bounds? : Bounds3 ) : Bounds3¶

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

This is the immutable form of the function set(), if a bounds is provided. This will return a new bounds, and will not modify this bounds. @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.

union( bounds : Bounds3 ) : Bounds3¶

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

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

intersection( bounds : Bounds3 ) : Bounds3¶

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

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

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

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

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

withPoint( point : Vector3 ) : Bounds3¶

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

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

withMinX( minX : number ) : Bounds3¶

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

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

withMinY( minY : number ) : Bounds3¶

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

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

withMinZ( minZ : number ) : Bounds3¶

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

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

withMaxX( maxX : number ) : Bounds3¶

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

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

withMaxY( maxY : number ) : Bounds3¶

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

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

withMaxZ( maxZ : number ) : Bounds3¶

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

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

roundedOut() : Bounds3¶

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

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

roundedIn() : Bounds3¶

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

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

transformed( matrix : Matrix4 ) : Bounds3¶

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

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

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

dilated( d : number ) : Bounds3¶

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

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

dilatedX( x : number ) : Bounds3¶

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

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

dilatedY( y : number ) : Bounds3¶

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

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

dilatedZ( z : number ) : Bounds3¶

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

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

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

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

This is the immutable form of the function dilateXYZ(). This will return a new bounds, and will not modify this bounds. @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)

eroded( amount : number ) : Bounds3¶

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

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

erodedX( x : number ) : Bounds3¶

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

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

erodedY( y : number ) : Bounds3¶

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

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

erodedZ( z : number ) : Bounds3¶

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

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

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

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

This is the immutable form of the function erodeXYZ(). This will return a new bounds, and will not modify this bounds. @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)

shiftedX( x : number ) : Bounds3¶

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

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

shiftedY( y : number ) : Bounds3¶

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

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

shiftedZ( z : number ) : Bounds3¶

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

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

shiftedXYZ( x : number, y : number, z : number ) : Bounds3¶

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

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

shifted( v : Vector3 ) : Bounds3¶

Returns our bounds, translated by a vector, returned as a copy.

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

Sets each value for this bounds, and returns itself.

setMinX( minX : number ) : Bounds3¶

Sets the value of minX.

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

setMinY( minY : number ) : Bounds3¶

Sets the value of minY.

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

setMinZ( minZ : number ) : Bounds3¶

Sets the value of minZ.

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

setMaxX( maxX : number ) : Bounds3¶

Sets the value of maxX.

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

setMaxY( maxY : number ) : Bounds3¶

Sets the value of maxY.

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

setMaxZ( maxZ : number ) : Bounds3¶

Sets the value of maxZ.

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

set( bounds : Bounds3 ) : Bounds3¶

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

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

includeBounds( bounds : Bounds3 ) : Bounds3¶

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

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

constrainBounds( bounds : Bounds3 ) : Bounds3¶

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

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

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

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

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

addPoint( point : Vector3 ) : Bounds3¶

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

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

roundOut() : Bounds3¶

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

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

roundIn() : Bounds3¶

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

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

transform( matrix : Matrix4 ) : Bounds3¶

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

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

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

dilate( d : number ) : Bounds3¶

Expands this bounds on all sides by the specified amount.

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

dilateX( x : number ) : Bounds3¶

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

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

dilateY( y : number ) : Bounds3¶

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

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

dilateZ( z : number ) : Bounds3¶

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

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

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

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

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

erode( d : number ) : Bounds3¶

Contracts this bounds on all sides by the specified amount.

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

erodeX( x : number ) : Bounds3¶

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

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

erodeY( y : number ) : Bounds3¶

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

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

erodeZ( z : number ) : Bounds3¶

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

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

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

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

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

shiftX( x : number ) : Bounds3¶

Translates our bounds horizontally by x.

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

shiftY( y : number ) : Bounds3¶

Translates our bounds vertically by y.

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

shiftZ( z : number ) : Bounds3¶

Translates our bounds depth-wise by z.

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

shiftXYZ( x : number, y : number, z : number ) : Bounds3¶

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

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

shift( v : Vector3 ) : Bounds3¶

Translates our bounds by the given vector.

Instance Properties¶

isBounds¶

(readonly)

Helps to identify the dimension of the bounds

dimension¶

(readonly)

Static Methods¶

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

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

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

point( x : number, y : number, z : number ) : 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.

Static Properties¶

NOTHING : Bounds3¶

(readonly)

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

EVERYTHING : Bounds3¶

(readonly)

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

Bounds3IO : IOType¶

(readonly)

Source Code¶

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