@math.gl/culling 4.0.0-beta.1 → 4.0.1

package/dist/lib/culling-volume.js

@@ -1,102 +1,121 @@
-import _defineProperty from "@babel/runtime/helpers/esm/defineProperty";
+// This file is derived from the Cesium math library under Apache 2 license
+// See LICENSE.md and https://github.com/AnalyticalGraphicsInc/cesium/blob/master/LICENSE.md
+/* eslint-disable */
 import { Vector3, assert } from '@math.gl/core';
 import { INTERSECTION } from "../constants.js";
 import { Plane } from "./plane.js";
+// X, Y, Z Unit vectors
 const faces = [new Vector3([1, 0, 0]), new Vector3([0, 1, 0]), new Vector3([0, 0, 1])];
 const scratchPlaneCenter = new Vector3();
 const scratchPlaneNormal = new Vector3();
+// const scratchPlane = new Plane(new Vector3(1.0, 0.0, 0.0), 0.0);
+/** A culling volume defined by planes. */
 export class CullingVolume {
-  constructor(planes = []) {
-    _defineProperty(this, "planes", void 0);
-
-    this.planes = planes;
-  }
-
-  fromBoundingSphere(boundingSphere) {
-    this.planes.length = 2 * faces.length;
-    const center = boundingSphere.center;
-    const radius = boundingSphere.radius;
-    let planeIndex = 0;
-
-    for (const faceNormal of faces) {
-      let plane0 = this.planes[planeIndex];
-      let plane1 = this.planes[planeIndex + 1];
-
-      if (!plane0) {
-        plane0 = this.planes[planeIndex] = new Plane();
-      }
-
-      if (!plane1) {
-        plane1 = this.planes[planeIndex + 1] = new Plane();
-      }
-
-      const plane0Center = scratchPlaneCenter.copy(faceNormal).scale(-radius).add(center);
-      plane0.fromPointNormal(plane0Center, faceNormal);
-      const plane1Center = scratchPlaneCenter.copy(faceNormal).scale(radius).add(center);
-      const negatedFaceNormal = scratchPlaneNormal.copy(faceNormal).negate();
-      plane1.fromPointNormal(plane1Center, negatedFaceNormal);
-      planeIndex += 2;
+    /**
+     * Create a new `CullingVolume` bounded by an array of clipping planed
+     * @param planes Array of clipping planes.
+     * */
+    constructor(planes = []) {
+        this.planes = planes;
     }
-
-    return this;
-  }
-
-  computeVisibility(boundingVolume) {
-    let intersect = INTERSECTION.INSIDE;
-
-    for (const plane of this.planes) {
-      const result = boundingVolume.intersectPlane(plane);
-
-      switch (result) {
-        case INTERSECTION.OUTSIDE:
-          return INTERSECTION.OUTSIDE;
-
-        case INTERSECTION.INTERSECTING:
-          intersect = INTERSECTION.INTERSECTING;
-          break;
-
-        default:
-      }
+    /**
+     * Constructs a culling volume from a bounding sphere. Creates six planes that create a box containing the sphere.
+     * The planes are aligned to the x, y, and z axes in world coordinates.
+     */
+    fromBoundingSphere(boundingSphere) {
+        this.planes.length = 2 * faces.length;
+        const center = boundingSphere.center;
+        const radius = boundingSphere.radius;
+        let planeIndex = 0;
+        for (const faceNormal of faces) {
+            let plane0 = this.planes[planeIndex];
+            let plane1 = this.planes[planeIndex + 1];
+            if (!plane0) {
+                plane0 = this.planes[planeIndex] = new Plane();
+            }
+            if (!plane1) {
+                plane1 = this.planes[planeIndex + 1] = new Plane();
+            }
+            const plane0Center = scratchPlaneCenter.copy(faceNormal).scale(-radius).add(center);
+            // const plane0Distance = -faceNormal.dot(plane0Center);
+            plane0.fromPointNormal(plane0Center, faceNormal);
+            const plane1Center = scratchPlaneCenter.copy(faceNormal).scale(radius).add(center);
+            const negatedFaceNormal = scratchPlaneNormal.copy(faceNormal).negate();
+            // const plane1Distance = -negatedFaceNormal.dot(plane1Center);
+            plane1.fromPointNormal(plane1Center, negatedFaceNormal);
+            planeIndex += 2;
+        }
+        return this;
     }
-
-    return intersect;
-  }
-
-  computeVisibilityWithPlaneMask(boundingVolume, parentPlaneMask) {
-    assert(Number.isFinite(parentPlaneMask), 'parentPlaneMask is required.');
-
-    if (parentPlaneMask === CullingVolume.MASK_OUTSIDE || parentPlaneMask === CullingVolume.MASK_INSIDE) {
-      return parentPlaneMask;
+    /** Determines whether a bounding volume intersects the culling volume. */
+    computeVisibility(boundingVolume) {
+        // const planes = this.planes;
+        let intersect = INTERSECTION.INSIDE;
+        for (const plane of this.planes) {
+            const result = boundingVolume.intersectPlane(plane);
+            switch (result) {
+                case INTERSECTION.OUTSIDE:
+                    // We are done
+                    return INTERSECTION.OUTSIDE;
+                case INTERSECTION.INTERSECTING:
+                    // If no other intersection is outside, return INTERSECTING
+                    intersect = INTERSECTION.INTERSECTING;
+                    break;
+                default:
+            }
+        }
+        return intersect;
     }
-
-    let mask = CullingVolume.MASK_INSIDE;
-    const planes = this.planes;
-
-    for (let k = 0; k < this.planes.length; ++k) {
-      const flag = k < 31 ? 1 << k : 0;
-
-      if (k < 31 && (parentPlaneMask & flag) === 0) {
-        continue;
-      }
-
-      const plane = planes[k];
-      const result = boundingVolume.intersectPlane(plane);
-
-      if (result === INTERSECTION.OUTSIDE) {
-        return CullingVolume.MASK_OUTSIDE;
-      } else if (result === INTERSECTION.INTERSECTING) {
-        mask |= flag;
-      }
+    /**
+     * Determines whether a bounding volume intersects the culling volume.
+     *
+     * @param parentPlaneMask A bit mask from the boundingVolume's parent's check against the same culling
+     *   volume, such that if (planeMask & (1 << planeIndex) === 0), for k < 31, then
+     *   the parent (and therefore this) volume is completely inside plane[planeIndex]
+     *   and that plane check can be skipped.
+     */
+    computeVisibilityWithPlaneMask(boundingVolume, parentPlaneMask) {
+        assert(Number.isFinite(parentPlaneMask), 'parentPlaneMask is required.');
+        if (parentPlaneMask === CullingVolume.MASK_OUTSIDE ||
+            parentPlaneMask === CullingVolume.MASK_INSIDE) {
+            // parent is completely outside or completely inside, so this child is as well.
+            return parentPlaneMask;
+        }
+        // Start with MASK_INSIDE (all zeros) so that after the loop, the return value can be compared with MASK_INSIDE.
+        // (Because if there are fewer than 31 planes, the upper bits wont be changed.)
+        let mask = CullingVolume.MASK_INSIDE;
+        const planes = this.planes;
+        for (let k = 0; k < this.planes.length; ++k) {
+            // For k greater than 31 (since 31 is the maximum number of INSIDE/INTERSECTING bits we can store), skip the optimization.
+            const flag = k < 31 ? 1 << k : 0;
+            if (k < 31 && (parentPlaneMask & flag) === 0) {
+                // boundingVolume is known to be INSIDE this plane.
+                continue;
+            }
+            const plane = planes[k];
+            const result = boundingVolume.intersectPlane(plane);
+            if (result === INTERSECTION.OUTSIDE) {
+                return CullingVolume.MASK_OUTSIDE;
+            }
+            else if (result === INTERSECTION.INTERSECTING) {
+                mask |= flag;
+            }
+        }
+        return mask;
     }
-
-    return mask;
-  }
-
 }
-
-_defineProperty(CullingVolume, "MASK_OUTSIDE", 0xffffffff);
-
-_defineProperty(CullingVolume, "MASK_INSIDE", 0x00000000);
-
-_defineProperty(CullingVolume, "MASK_INDETERMINATE", 0x7fffffff);
-//# sourceMappingURL=culling-volume.js.map
+/**
+ * For plane masks (as used in {@link CullingVolume#computeVisibilityWithPlaneMask}), this special value
+ * represents the case where the object bounding volume is entirely outside the culling volume.
+ */
+CullingVolume.MASK_OUTSIDE = 0xffffffff;
+/**
+ * For plane masks (as used in {@link CullingVolume.prototype.computeVisibilityWithPlaneMask}), this value
+ * represents the case where the object bounding volume is entirely inside the culling volume.
+ */
+CullingVolume.MASK_INSIDE = 0x00000000;
+/**
+ * For plane masks (as used in {@link CullingVolume.prototype.computeVisibilityWithPlaneMask}), this value
+ * represents the case where the object bounding volume (may) intersect all planes of the culling volume.
+ */
+CullingVolume.MASK_INDETERMINATE = 0x7fffffff;

package/dist/lib/perspective-frustum.d.ts

@@ -1,6 +1,6 @@
 import { Matrix4, NumericArray, Vector2 } from '@math.gl/core';
-import { CullingVolume } from './culling-volume';
-declare type PerspectiveFrustumOptions = {
+import { CullingVolume } from "./culling-volume.js";
+type PerspectiveFrustumOptions = {
     /** The angle of the field of view (FOV), in radians. */
     fov?: number;
     /** The aspect ratio of the frustum's width to it's height. */
@@ -149,4 +149,3 @@ export declare class PerspectiveFrustum {
     private _update;
 }
 export {};
-//# sourceMappingURL=perspective-frustum.d.ts.map

package/dist/lib/perspective-frustum.js

@@ -1,142 +1,190 @@
-import _defineProperty from "@babel/runtime/helpers/esm/defineProperty";
+// This file is derived from the Cesium math library under Apache 2 license
+// See LICENSE.md and https://github.com/AnalyticalGraphicsInc/cesium/blob/master/LICENSE.md
+// Note: This class is still an experimental export, mainly used by other test cases
+// - It has not been fully adapted to math.gl conventions
+// - Documentation has not been ported
 import { assert, Vector2 } from '@math.gl/core';
 import { PerspectiveOffCenterFrustum } from "./perspective-off-center-frustum.js";
-
-const defined = val => val !== null && typeof val !== 'undefined';
-
+const defined = (val) => val !== null && typeof val !== 'undefined';
+/**
+ * The viewing frustum is defined by 6 planes.
+ * Each plane is represented by a {@link Vector4} object, where the x, y, and z components
+ * define the unit vector normal to the plane, and the w component is the distance of the
+ * plane from the origin/camera position.
+ *
+ * @alias PerspectiveFrustum
+ *
+ * @example
+ * var frustum = new PerspectiveFrustum({
+ *     fov : Math.PI_OVER_THREE,
+ *     aspectRatio : canvas.clientWidth / canvas.clientHeight
+ *     near : 1.0,
+ *     far : 1000.0
+ * });
+ *
+ * @see PerspectiveOffCenterFrustum
+ */
 export class PerspectiveFrustum {
-  constructor(options = {}) {
-    _defineProperty(this, "_offCenterFrustum", new PerspectiveOffCenterFrustum());
-
-    _defineProperty(this, "fov", void 0);
-
-    _defineProperty(this, "_fov", void 0);
-
-    _defineProperty(this, "_fovy", void 0);
-
-    _defineProperty(this, "_sseDenominator", void 0);
-
-    _defineProperty(this, "aspectRatio", void 0);
-
-    _defineProperty(this, "_aspectRatio", void 0);
-
-    _defineProperty(this, "near", void 0);
-
-    _defineProperty(this, "_near", void 0);
-
-    _defineProperty(this, "far", void 0);
-
-    _defineProperty(this, "_far", void 0);
-
-    _defineProperty(this, "xOffset", void 0);
-
-    _defineProperty(this, "_xOffset", void 0);
-
-    _defineProperty(this, "yOffset", void 0);
-
-    _defineProperty(this, "_yOffset", void 0);
-
-    const {
-      fov,
-      aspectRatio,
-      near = 1.0,
-      far = 500000000.0,
-      xOffset = 0.0,
-      yOffset = 0.0
-    } = options;
-    this.fov = fov;
-    this.aspectRatio = aspectRatio;
-    this.near = near;
-    this.far = far;
-    this.xOffset = xOffset;
-    this.yOffset = yOffset;
-  }
-
-  clone() {
-    return new PerspectiveFrustum({
-      aspectRatio: this.aspectRatio,
-      fov: this.fov,
-      near: this.near,
-      far: this.far
-    });
-  }
-
-  equals(other) {
-    if (!defined(other) || !(other instanceof PerspectiveFrustum)) {
-      return false;
+    constructor(options = {}) {
+        this._offCenterFrustum = new PerspectiveOffCenterFrustum();
+        const { fov, aspectRatio, near = 1.0, far = 500000000.0, xOffset = 0.0, yOffset = 0.0 } = options;
+        this.fov = fov;
+        this.aspectRatio = aspectRatio;
+        this.near = near;
+        this.far = far;
+        this.xOffset = xOffset;
+        this.yOffset = yOffset;
     }
-
-    this._update();
-
-    other._update();
-
-    return this.fov === other.fov && this.aspectRatio === other.aspectRatio && this.near === other.near && this.far === other.far && this._offCenterFrustum.equals(other._offCenterFrustum);
-  }
-
-  get projectionMatrix() {
-    this._update();
-
-    return this._offCenterFrustum.projectionMatrix;
-  }
-
-  get infiniteProjectionMatrix() {
-    this._update();
-
-    return this._offCenterFrustum.infiniteProjectionMatrix;
-  }
-
-  get fovy() {
-    this._update();
-
-    return this._fovy;
-  }
-
-  get sseDenominator() {
-    this._update();
-
-    return this._sseDenominator;
-  }
-
-  computeCullingVolume(position, direction, up) {
-    this._update();
-
-    return this._offCenterFrustum.computeCullingVolume(position, direction, up);
-  }
-
-  getPixelDimensions(drawingBufferWidth, drawingBufferHeight, distance, result) {
-    this._update();
-
-    return this._offCenterFrustum.getPixelDimensions(drawingBufferWidth, drawingBufferHeight, distance, result || new Vector2());
-  }
-
-  _update() {
-    assert(Number.isFinite(this.fov) && Number.isFinite(this.aspectRatio) && Number.isFinite(this.near) && Number.isFinite(this.far));
-    const f = this._offCenterFrustum;
-
-    if (this.fov !== this._fov || this.aspectRatio !== this._aspectRatio || this.near !== this._near || this.far !== this._far || this.xOffset !== this._xOffset || this.yOffset !== this._yOffset) {
-      assert(this.fov >= 0 && this.fov < Math.PI);
-      assert(this.aspectRatio > 0);
-      assert(this.near >= 0 && this.near < this.far);
-      this._aspectRatio = this.aspectRatio;
-      this._fov = this.fov;
-      this._fovy = this.aspectRatio <= 1 ? this.fov : Math.atan(Math.tan(this.fov * 0.5) / this.aspectRatio) * 2.0;
-      this._near = this.near;
-      this._far = this.far;
-      this._sseDenominator = 2.0 * Math.tan(0.5 * this._fovy);
-      this._xOffset = this.xOffset;
-      this._yOffset = this.yOffset;
-      f.top = this.near * Math.tan(0.5 * this._fovy);
-      f.bottom = -f.top;
-      f.right = this.aspectRatio * f.top;
-      f.left = -f.right;
-      f.near = this.near;
-      f.far = this.far;
-      f.right += this.xOffset;
-      f.left += this.xOffset;
-      f.top += this.yOffset;
-      f.bottom += this.yOffset;
+    /**
+     * Returns a duplicate of a PerspectiveFrustum instance.
+     */
+    clone() {
+        return new PerspectiveFrustum({
+            aspectRatio: this.aspectRatio,
+            fov: this.fov,
+            near: this.near,
+            far: this.far
+        });
+    }
+    /**
+     * Compares the provided PerspectiveFrustum componentwise and returns
+     * <code>true</code> if they are equal, <code>false</code> otherwise.
+     */
+    equals(other) {
+        if (!defined(other) || !(other instanceof PerspectiveFrustum)) {
+            return false;
+        }
+        this._update();
+        other._update();
+        return (this.fov === other.fov &&
+            this.aspectRatio === other.aspectRatio &&
+            this.near === other.near &&
+            this.far === other.far &&
+            this._offCenterFrustum.equals(other._offCenterFrustum));
+    }
+    /**
+     * Gets the perspective projection matrix computed from the view this.
+     */
+    get projectionMatrix() {
+        this._update();
+        return this._offCenterFrustum.projectionMatrix;
+    }
+    /**
+     * The perspective projection matrix computed from the view frustum with an infinite far plane.
+     */
+    get infiniteProjectionMatrix() {
+        this._update();
+        return this._offCenterFrustum.infiniteProjectionMatrix;
+    }
+    /**
+     * Gets the angle of the vertical field of view, in radians.
+     */
+    get fovy() {
+        this._update();
+        return this._fovy;
+    }
+    /**
+     * @private
+     */
+    get sseDenominator() {
+        this._update();
+        return this._sseDenominator;
+    }
+    /**
+     * Creates a culling volume for this this.ion.
+     * @returns {CullingVolume} A culling volume at the given position and orientation.
+     *
+     * @example
+     * // Check if a bounding volume intersects the this.
+     * var cullingVolume = this.computeCullingVolume(cameraPosition, cameraDirection, cameraUp);
+     * var intersect = cullingVolume.computeVisibility(boundingVolume);
+     */
+    computeCullingVolume(
+    /** A Vector3 defines the eye position. */
+    position, 
+    /** A Vector3 defines the view direction. */
+    direction, 
+    /** A Vector3 defines the up direction. */
+    up) {
+        this._update();
+        return this._offCenterFrustum.computeCullingVolume(position, direction, up);
+    }
+    /**
+     * Returns the pixel's width and height in meters.
+     * @returns {Vector2} The modified result parameter or a new instance of {@link Vector2} with the pixel's width and height in the x and y properties, respectively.
+     *
+     * @exception {DeveloperError} drawingBufferWidth must be greater than zero.
+     * @exception {DeveloperError} drawingBufferHeight must be greater than zero.
+     *
+     * @example
+     * // Example 1
+     * // Get the width and height of a pixel.
+     * var pixelSize = camera.this.getPixelDimensions(scene.drawingBufferWidth, scene.drawingBufferHeight, 1.0, new Vector2());
+     *
+     * @example
+     * // Example 2
+     * // Get the width and height of a pixel if the near plane was set to 'distance'.
+     * // For example, get the size of a pixel of an image on a billboard.
+     * var position = camera.position;
+     * var direction = camera.direction;
+     * var toCenter = Vector3.subtract(primitive.boundingVolume.center, position, new Vector3());      // vector from camera to a primitive
+     * var toCenterProj = Vector3.multiplyByScalar(direction, Vector3.dot(direction, toCenter), new Vector3()); // project vector onto camera direction vector
+     * var distance = Vector3.magnitude(toCenterProj);
+     * var pixelSize = camera.this.getPixelDimensions(scene.drawingBufferWidth, scene.drawingBufferHeight, distance, new Vector2());
+     */
+    getPixelDimensions(
+    /** The width of the drawing buffer. */
+    drawingBufferWidth, 
+    /** The height of the drawing buffer. */
+    drawingBufferHeight, 
+    /** The distance to the near plane in meters. */
+    distance, 
+    /** The object onto which to store the result. */
+    result) {
+        this._update();
+        return this._offCenterFrustum.getPixelDimensions(drawingBufferWidth, drawingBufferHeight, distance, result || new Vector2());
+    }
+    // eslint-disable-next-line complexity, max-statements
+    _update() {
+        assert(Number.isFinite(this.fov) &&
+            Number.isFinite(this.aspectRatio) &&
+            Number.isFinite(this.near) &&
+            Number.isFinite(this.far));
+        // 'fov, aspectRatio, near, or far parameters are not set.'
+        const f = this._offCenterFrustum;
+        if (this.fov !== this._fov ||
+            this.aspectRatio !== this._aspectRatio ||
+            this.near !== this._near ||
+            this.far !== this._far ||
+            this.xOffset !== this._xOffset ||
+            this.yOffset !== this._yOffset) {
+            assert(this.fov >= 0 && this.fov < Math.PI);
+            // throw new DeveloperError('fov must be in the range [0, PI).');
+            assert(this.aspectRatio > 0);
+            // throw new DeveloperError('aspectRatio must be positive.');
+            assert(this.near >= 0 && this.near < this.far);
+            // throw new DeveloperError('near must be greater than zero and less than far.');
+            this._aspectRatio = this.aspectRatio;
+            this._fov = this.fov;
+            this._fovy =
+                this.aspectRatio <= 1
+                    ? this.fov
+                    : Math.atan(Math.tan(this.fov * 0.5) / this.aspectRatio) * 2.0;
+            this._near = this.near;
+            this._far = this.far;
+            this._sseDenominator = 2.0 * Math.tan(0.5 * this._fovy);
+            this._xOffset = this.xOffset;
+            this._yOffset = this.yOffset;
+            f.top = this.near * Math.tan(0.5 * this._fovy);
+            f.bottom = -f.top;
+            f.right = this.aspectRatio * f.top;
+            f.left = -f.right;
+            f.near = this.near;
+            f.far = this.far;
+            f.right += this.xOffset;
+            f.left += this.xOffset;
+            f.top += this.yOffset;
+            f.bottom += this.yOffset;
+        }
     }
-  }
-
 }
-//# sourceMappingURL=perspective-frustum.js.map

package/dist/lib/perspective-off-center-frustum.d.ts

@@ -1,6 +1,6 @@
 import { Vector2, Matrix4, NumericArray } from '@math.gl/core';
-import { CullingVolume } from './culling-volume';
-declare type PerspectiveOffCenterFrustumOptions = {
+import { CullingVolume } from "./culling-volume.js";
+type PerspectiveOffCenterFrustumOptions = {
     left?: number;
     right?: number;
     top?: number;
@@ -155,4 +155,3 @@ export declare class PerspectiveOffCenterFrustum {
     private _update;
 }
 export {};
-//# sourceMappingURL=perspective-off-center-frustum.d.ts.map