feat(culling): Add BoundingVolume interface

docs/table-of-contents.json

@@ -66,10 +66,12 @@
           "title": "@math.gl/culling",
           "entries": [
             {"entry": "modules/culling/docs"},
+            {"entry": "modules/culling/docs/api-reference/axis-aligned-bounding-box"},
             {"entry": "modules/culling/docs/api-reference/bounding-sphere"},
+            {"entry": "modules/culling/docs/api-reference/bounding-volume"},
             {"entry": "modules/culling/docs/api-reference/culling-volume"},
             {"entry": "modules/culling/docs/api-reference/oriented-bounding-box"},
-            {"entry": "modules/culling/docs/api-reference/plane"}
+x            {"entry": "modules/culling/docs/api-reference/plane"}
           ]
         },
         {

docs/whats-new.md

@@ -27,11 +27,18 @@
 
 ## v3.5 (In development)
 
+Release Date: TBD
+
 **`@math.gl/polygon`**
 
 - Improve performance of `getPolygonSignedArea()` by 3x
 - Addition of `earcut()` method for triangulating polygons
 
+**`math.gl/culling`**
+
+- New TypeScript interface `BoundingVolume` with common operations for bounding volumes (`BoundingSphere`, `AxisAlignedBoundingBox`, `OrientedBoundingBox`).
+- `BoundingVolume.transform()` supported on all bounding volumes.
+
 ## v3.4
 
 Release Date: Jan 7, 2020

modules/culling/docs/api-reference/axis-aligned-bounding-box.md

@@ -23,6 +23,10 @@ const box = makeAxisAlignedBoundingBoxFromPoints([
 ]);
 ```
 
+## Inheritance
+
+`class AxisAlignedBoundingBox implements` [`BoundingVolume`](/modules/culling/docs/api-reference/bounding-volume).
+
 ## Global Functions
 
 ### makeAxisAlignedBoundingBoxFromPoints(positions : Array[3][], result? : AxisAlignedBoundingBox) : AxisAlignedBoundingBox

modules/culling/docs/api-reference/bounding-sphere.md

@@ -25,6 +25,10 @@ spheres.sort(
 );
 ```
 
+## Inheritance
+
+`class BoundingSphere implements` [`BoundingVolume`](/modules/culling/docs/api-reference/bounding-volume).
+
 ## Global Functions
 
 ### makeBoundingSphereFromPoints(positions : iterator, result? : BoundingSphere) : BoundingSphere

modules/culling/docs/api-reference/bounding-volume.md

@@ -0,0 +1,73 @@
+# BoundingVolume (Interface)
+
+An interface defining common operations for bounding volumes (i.e. `BoundingSphere`, `AxisAlignedBoundingBox`, `OrientedBoundingBox`).
+
+## Global Functions
+
+## Members
+
+### intersectPlane(plane : Plane) : INTERSECTION
+
+Determines which side of a plane a sphere is located.
+
+- `plane` The plane to test against.
+  Returns
+- `INTERSECTION.INSIDE` if the entire sphere is on the side of the plane the normal is pointing
+- `INTERSECTION.OUTSIDE` if the entire sphere is on the opposite side
+- `INTERSECTION.INTERSECTING` if the sphere intersects the plane.
+
+### transform(transform : Number[16]) : BoundingSphere
+
+Applies a 4x4 affine transformation matrix to a bounding sphere.
+
+- `transform` The transformation matrix to apply to the bounding sphere.
+
+### distanceSquaredTo(point) : Number
+
+Computes the estimated distance squared from the closest point on a bounding sphere to a point.
+
+- `point` The point
+
+Returns
+
+- The estimated distance squared from the bounding sphere to the point.
+
+<!--
+### transformWithoutScale(sphere, transform, result)
+
+Applies a 4x4 affine transformation matrix to a bounding sphere where there is no scale
+The transformation matrix is not verified to have a uniform scale of 1.
+This method is faster than computing the general bounding sphere transform using {@link BoundingSphere.transform}.
+
+@param {BoundingSphere} sphere The bounding sphere to apply the transformation to.
+@param {Matrix4} transform The transformation matrix to apply to the bounding sphere.
+
+- `result` Optional object onto which to store the result.
+
+Returns
+
+- The modified `result` parameter or a new `BoundingSphere` instance if none was provided.
+
+@example
+var modelMatrix = Transforms.eastNorthUpToFixedFrame(positionOnEllipsoid);
+var boundingSphere = new BoundingSphere();
+var newBoundingSphere = BoundingSphere.transformWithoutScale(boundingSphere, modelMatrix);
+
+
+### computePlaneDistances (sphere, position, direction, result)
+
+The distances calculated by the vector from the center of the bounding sphere to position projected onto direction plus/minus the radius of the bounding sphere.
+
+If you imagine the infinite number of planes with normal direction, this computes the smallest distance to the closest and farthest planes from position that intersect the bounding sphere.
+
+@param {BoundingSphere} sphere The bounding sphere to calculate the distance to.
+@param {Cartesian3} position The position to calculate the distance from.
+@param {Cartesian3} direction The direction from position.
+@param {Interval} [result] A Interval to store the nearest and farthest distances.
+@returns {Interval} The nearest and farthest distances on the bounding sphere from position in direction.
+
+-->
+
+## Attribution
+
+This class was ported from [Cesium](https://github.com/AnalyticalGraphicsInc/cesium) under the Apache 2 License.

modules/culling/docs/api-reference/oriented-bounding-box.md

@@ -40,6 +40,10 @@ const box = makeOrientedBoundingBoxFromPoints([
 ]);
 ```
 
+## Inheritance
+
+`class OrientedBoundingBox implements` [`BoundingVolume`](/modules/culling/docs/api-reference/bounding-volume).
+
 ## Global Functions
 
 ### makeOrientedBoundingBoxFromPoints(positions : Array[3][], result? : OrientedBoundingBox) : OrientedBoundingBox

modules/culling/src/index.d.ts

@@ -1,15 +1,17 @@
-export {default as AxisAlignedBoundingBox} from './lib/axis-aligned-bounding-box';
-export {default as BoundingSphere} from './lib/bounding-sphere';
+export {default as BoundingVolume} from './lib/bounding-volumes/bounding-volume';
+export {default as BoundingSphere} from './lib/bounding-volumes/bounding-sphere';
+export {default as AxisAlignedBoundingBox} from './lib/bounding-volumes/axis-aligned-bounding-box';
+export {default as OrientedBoundingBox} from './lib/bounding-volumes/oriented-bounding-box';
+
 export {default as CullingVolume} from './lib/culling-volume';
-export {default as OrientedBoundingBox} from './lib/oriented-bounding-box';
 export {default as Plane} from './lib/plane';
 
-export {default as makeBoundingSphereFromPoints} from './algorithms/bounding-sphere-from-points';
+export {default as makeBoundingSphereFromPoints} from './lib/algorithms/bounding-sphere-from-points';
 export {
   makeAxisAlignedBoundingBoxFromPoints,
   makeOrientedBoundingBoxFromPoints
-} from './algorithms/bounding-box-from-points';
-export {default as computeEigenDecomposition} from './algorithms/compute-eigen-decomposition';
+} from './lib/algorithms/bounding-box-from-points';
+export {default as computeEigenDecomposition} from './lib/algorithms/compute-eigen-decomposition';
 
 // Experimental, decide how to handle enums in typescript
 export {INTERSECTION_ENUM, INTERSECTION} from './constants';

modules/culling/src/index.js

@@ -3,21 +3,21 @@
 
 export {INTERSECTION} from './constants';
 
-export {default as AxisAlignedBoundingBox} from './lib/axis-aligned-bounding-box';
-export {default as BoundingSphere} from './lib/bounding-sphere';
-export {default as OrientedBoundingBox} from './lib/oriented-bounding-box';
+export {default as AxisAlignedBoundingBox} from './lib/bounding-volumes/axis-aligned-bounding-box';
+export {default as BoundingSphere} from './lib/bounding-volumes/bounding-sphere';
+export {default as OrientedBoundingBox} from './lib/bounding-volumes/oriented-bounding-box';
 export {default as CullingVolume} from './lib/culling-volume';
 export {default as Plane} from './lib/plane';
 
 export {default as _PerspectiveOffCenterFrustum} from './lib/perspective-off-center-frustum';
 export {default as _PerspectiveFrustum} from './lib/perspective-frustum';
 
-export {default as makeBoundingSphereFromPoints} from './algorithms/bounding-sphere-from-points';
+export {default as makeBoundingSphereFromPoints} from './lib/algorithms/bounding-sphere-from-points';
 export {
   makeAxisAlignedBoundingBoxFromPoints,
   makeOrientedBoundingBoxFromPoints
-} from './algorithms/bounding-box-from-points';
-export {default as computeEigenDecomposition} from './algorithms/compute-eigen-decomposition';
+} from './lib/algorithms/bounding-box-from-points';
+export {default as computeEigenDecomposition} from './lib/algorithms/compute-eigen-decomposition';
 
 // Deprecated
 export {INTERSECTION as Intersect} from './constants';

modules/culling/src/algorithms/bounding-box-from-points.d.ts → modules/culling/src/lib/algorithms/bounding-box-from-points.d.ts

@@ -1,5 +1,5 @@
-import OrientedBoundingBox from '../lib/oriented-bounding-box';
-import AxisAlignedBoundingBox from '../lib/axis-aligned-bounding-box';
+import OrientedBoundingBox from '../bounding-volumes/oriented-bounding-box';
+import AxisAlignedBoundingBox from '../bounding-volumes/axis-aligned-bounding-box';
 
 /**
  * Computes an instance of an OrientedBoundingBox of the given positions.

modules/culling/src/algorithms/bounding-box-from-points.js → modules/culling/src/lib/algorithms/bounding-box-from-points.js

@@ -3,8 +3,8 @@
 
 import {Vector3, Matrix3} from '@math.gl/core';
 import computeEigenDecomposition from './compute-eigen-decomposition';
-import OrientedBoundingBox from '../lib/oriented-bounding-box';
-import AxisAlignedBoundingBox from '../lib/axis-aligned-bounding-box';
+import OrientedBoundingBox from '../bounding-volumes/oriented-bounding-box';
+import AxisAlignedBoundingBox from '../bounding-volumes/axis-aligned-bounding-box';
 
 const scratchVector2 = new Vector3();
 

modules/culling/src/algorithms/bounding-sphere-from-points.d.ts → modules/culling/src/lib/algorithms/bounding-sphere-from-points.d.ts

@@ -1,4 +1,4 @@
-import BoundingSphere from '../lib/bounding-sphere';
+import BoundingSphere from '../bounding-volumes/bounding-sphere';
 
 /**
  * Computes a tight-fitting bounding sphere enclosing a list of 3D Cartesian points.

modules/culling/src/algorithms/bounding-sphere-from-points.js → modules/culling/src/lib/algorithms/bounding-sphere-from-points.js

@@ -2,7 +2,7 @@
 // See LICENSE.md and https://github.com/AnalyticalGraphicsInc/cesium/blob/master/LICENSE.md
 
 import {Vector3} from '@math.gl/core';
-import BoundingSphere from '../lib/bounding-sphere';
+import BoundingSphere from '../bounding-volumes/bounding-sphere';
 
 /* eslint-disable */
 const fromPointsXMin = new Vector3();

modules/culling/src/lib/bounding-volumes/axis-aligned-bounding-box.d.ts

@@ -0,0 +1,51 @@
+import {BoundingVolume} from './bounding-volume';
+import {Vector3} from '@math.gl/core';
+import Plane from '../plane';
+import {INTERSECTION_ENUM} from '../../constants';
+
+/**
+* An axis aligned bounding box - aligned with coordinate axes
+* @see BoundingVolume
+* @see BoundingRectangle
+* @see OrientedBoundingBox
+*/
+export default class AxisAlignedBoundingBox implements BoundingVolume {
+  /** The center point of the bounding box. */
+  readonly center: Vector3;
+  /** The positive half diagonal of the bounding box. */
+  readonly halfDiagonal: Vector3;
+  /** The minimum point defining the bounding box. [0, 0, 0] for empty box */
+  readonly minimum: Vector3;
+  /** The maximum point defining the bounding box. [0, 0, 0] for empty box */
+  readonly maximum: Vector3;
+
+  /**
+   * Creates an instance of an AxisAlignedBoundingBox from the minimum and maximum points along the x, y, and z axes.
+   * @param minimum=[0, 0, 0] The minimum point along the x, y, and z axes.
+   * @param maximum=[0, 0, 0] The maximum point along the x, y, and z axes.
+   * @param center The center of the box; automatically computed if not supplied.
+   */
+  constructor(minimum?: readonly number[], maximum?: readonly number[], center?: readonly number[]);
+
+  /** Duplicates a AxisAlignedBoundingBox instance. */
+  clone(): AxisAlignedBoundingBox;
+  /** Compares the provided AxisAlignedBoundingBox component wise */
+  equals(right: AxisAlignedBoundingBox): boolean;
+
+  // BoundingVolume interface
+
+  /**
+   * Applies a 4x4 affine transformation matrix to a bounding sphere.
+   * @param transform The transformation matrix to apply to the bounding sphere.
+   * @returns itself, i.e. the modified BoundingVolume.
+   */
+  transform(transform: readonly number[]): this;
+
+  /** Computes the estimated distance from the closest point on a bounding box to a point. */
+  distanceTo(point: readonly number[]): number;
+  /** Computes the estimated distance squared from the closest point on a bounding box to a point. */
+  distanceSquaredTo(point: readonly number[]): number;
+
+  /** Determines which side of a plane a box is located. */
+  intersectPlane(plane: Plane): INTERSECTION_ENUM;
+}

modules/culling/src/lib/axis-aligned-bounding-box.js → modules/culling/src/lib/bounding-volumes/axis-aligned-bounding-box.js

@@ -1,5 +1,5 @@
 import {Vector3} from '@math.gl/core';
-import {INTERSECTION} from '../constants';
+import {INTERSECTION} from '../../constants';
 
 const scratchVector = new Vector3();
 const scratchNormal = new Vector3();
@@ -13,15 +13,7 @@ export default class AxisAlignedBoundingBox {
         .copy(minimum)
         .add(maximum)
         .scale(0.5);
-    /**
-     * The center point of the bounding box.
-     * @type {Vector3}
-     */
     this.center = new Vector3(center);
-    /**
-     * The positive half diagonal of the bounding box.
-     * @type {Vector3}
-     */
     this.halfDiagonal = new Vector3(maximum).subtract(this.center);
 
     /**