@math.gl/geospatial 4.2.0-alpha.3 → 4.2.0-alpha.6

package/src/ellipsoid-tangent-plane.ts

@@ -6,19 +6,15 @@
 // See LICENSE.md and https://github.com/AnalyticalGraphicsInc/cesium/blob/master/LICENSE.md
 
 import {Vector2, Vector3, Matrix4} from '@math.gl/core';
-import {Plane, Ray} from '@math.gl/culling';
+import {Plane} from '@math.gl/culling';
 import {Ellipsoid} from './ellipsoid';
 
 const scratchOrigin = new Vector3();
 const scratchCart3 = new Vector3();
 const scratchEastNorthUp = new Matrix4();
-const scratchPlane = new Plane();
-
-const scratchProjectPointOntoPlaneRay = new Ray();
 const scratchProjectPointOntoPlaneCartesian3 = new Vector3();
-const scratchDirection = new Vector3();
 
-/** A plane tangent to the WGS84 ellipsoid at the provided origin */
+/** A two-dimensional east-north plane tangent to an ellipsoid. */
 export class EllipsoidTangentPlane {
   private _origin: Vector3;
   private _xAxis: Vector3;
@@ -27,45 +23,38 @@ export class EllipsoidTangentPlane {
 
   /**
    * Creates a new plane tangent to the WGS84 ellipsoid at the provided origin.
-   * If origin is not on the surface of the ellipsoid, it's surface projection will be used.
+   * If origin is not on the surface of the ellipsoid, its surface projection will be used.
    *
-   * @param {Cartesian3} origin The point on the surface of the ellipsoid where the tangent plane touches.
+   * @param origin A nonzero Cartesian point on or near the ellipsoid.
+   * @param ellipsoid The ellipsoid to which the origin belongs. Defaults to WGS84.
    */
-  constructor(origin: number[]) {
-    origin = Ellipsoid.WGS84.scaleToGeodeticSurface(origin, scratchOrigin);
+  constructor(origin: number[], ellipsoid: Ellipsoid = Ellipsoid.WGS84) {
+    const originOnSurface = ellipsoid.scaleToGeodeticSurface(origin, scratchOrigin);
 
-    const eastNorthUp = Ellipsoid.WGS84.eastNorthUpToFixedFrame(origin, scratchEastNorthUp);
+    const eastNorthUp = ellipsoid.eastNorthUpToFixedFrame(originOnSurface, scratchEastNorthUp);
 
-    this._origin = origin as Vector3;
+    this._origin = new Vector3(originOnSurface);
     this._xAxis = new Vector3(scratchCart3.from(eastNorthUp.getColumn(0)));
     this._yAxis = new Vector3(scratchCart3.from(eastNorthUp.getColumn(1)));
     const normal = new Vector3(scratchCart3.from(eastNorthUp.getColumn(2)));
 
-    this._plane = scratchPlane.fromPointNormal(origin, normal);
+    this._plane = new Plane().fromPointNormal(this._origin, normal);
   }
 
   /**
    * Computes the projection of the provided 3D position onto the 2D plane, along the plane normal.
    *
-   * @param {Vector3} cartesian The point to project.
-   * @param {Vector2} [result] The object onto which to store the result.
-   * @returns {Vector2} The modified result parameter or a new Cartesian2 instance if none was provided.
+   * @param cartesian The WGS84 Cartesian point to project.
+   * @param result The optional object in which to store the local east-north coordinates.
+   * @returns The supplied result or a new Vector2.
    */
   projectPointToNearestOnPlane(cartesian: Vector3, result?: Vector2): Vector2 {
     if (!result) result = new Vector2();
 
-    const plane = this._plane;
-
-    const ray = scratchProjectPointOntoPlaneRay;
-    scratchProjectPointOntoPlaneRay.origin = cartesian;
-    scratchProjectPointOntoPlaneRay.direction = scratchDirection.copy(plane.normal);
-
-    let intersectionPoint = plane.intersectWithRay(ray, scratchProjectPointOntoPlaneCartesian3);
-
-    if (!intersectionPoint) {
-      ray.direction = ray.direction.negate();
-      intersectionPoint = plane.intersectWithRay(ray, scratchProjectPointOntoPlaneCartesian3);
-    }
+    const intersectionPoint = this._plane.projectPointOntoPlane(
+      cartesian,
+      scratchProjectPointOntoPlaneCartesian3
+    );
 
     const v = intersectionPoint.subtract(this._origin);
     const x = this._xAxis.dot(v);
@@ -76,23 +65,23 @@ export class EllipsoidTangentPlane {
     return result;
   }
 
-  get plane() {
+  get plane(): Plane {
     return this._plane;
   }
 
-  get origin() {
+  get origin(): Vector3 {
     return this._origin;
   }
 
-  get xAxis() {
+  get xAxis(): Vector3 {
     return this._xAxis;
   }
 
-  get yAxis() {
+  get yAxis(): Vector3 {
     return this._yAxis;
   }
 
-  get zAxis() {
+  get zAxis(): Vector3 {
     return this._plane.normal;
   }
 }

package/src/ellipsoid.ts

@@ -89,7 +89,10 @@ export class Ellipsoid {
     return this.radii.toString();
   }
 
-  /** Converts the provided cartographic to Cartesian representation. */
+  /** Converts the provided cartographic position to Cartesian representation.
+   * The position is supplied as [longitude, latitude, height], where longitude and latitude
+   * are in degrees and height is in meters above the ellipsoid.
+   */
   cartographicToCartesian(cartographic: number[], result: Vector3): Vector3;
   cartographicToCartesian(cartographic: number[], result?: number[]): number[];
 
@@ -111,8 +114,10 @@ export class Ellipsoid {
     return k.to(result);
   }
 
-  /** Converts the provided cartesian to cartographic (lng/lat/z) representation.
-   * The cartesian is undefined at the center of the ellipsoid. */
+  /** Converts the provided Cartesian position to [longitude, latitude, height],
+   * where longitude and latitude are in degrees and height is in meters above the ellipsoid.
+   * The cartographic position is undefined at the center of the ellipsoid.
+   */
   cartesianToCartographic(cartesian: Readonly<NumericArray>, result: Vector3): Vector3;
   cartesianToCartographic(cartesian: Readonly<NumericArray>, result?: number[]): number[];
 
@@ -155,7 +160,7 @@ export class Ellipsoid {
     origin: Readonly<NumericArray>,
     result?: Matrix4
   ): Matrix4;
-  localFrameToFixedFrame<Matrix4T>(
+  localFrameToFixedFrame<_Matrix4T>(
     firstAxis: AxisDirection,
     secondAxis: AxisDirection,
     thirdAxis: AxisDirection,
@@ -183,7 +188,9 @@ export class Ellipsoid {
     return scratchVector.from(cartesian).normalize().to(result);
   }
 
-  /** Computes the normal of the plane tangent to the surface of the ellipsoid at provided position. */
+  /** Computes the normal of the plane tangent to the surface of the ellipsoid at the provided
+   * [longitude, latitude, height], where longitude and latitude are in degrees.
+   */
   geodeticSurfaceNormalCartographic<NumArray>(
     cartographic: Readonly<NumericArray>,
     result: NumArray

package/src/index.ts

@@ -5,4 +5,6 @@
 export {Ellipsoid} from './ellipsoid';
 export {EllipsoidTangentPlane} from './ellipsoid-tangent-plane';
 export {LngLatRectangle} from './lng-lat-rectangle';
+export {makeOBBFromRegion} from './make-obb-from-region';
+export type {GeodeticRegion, MakeOBBFromRegionOptions} from './make-obb-from-region';
 export {isWGS84} from './type-utils';

package/src/lng-lat-rectangle.ts

@@ -55,7 +55,7 @@ export class LngLatRectangle {
     return result;
   }
 
-  get width() {
+  get width(): number {
     let east = this.east;
     const west = this.west;
 

package/src/make-obb-from-region.ts

@@ -5,7 +5,7 @@
 // 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
 
-import {Vector2, Vector3, degrees, _MathUtils} from '@math.gl/core';
+import {Matrix3, Matrix4, Vector2, Vector3, degrees, radians, _MathUtils} from '@math.gl/core';
 import {OrientedBoundingBox, Plane} from '@math.gl/culling';
 // @ts-ignore
 // eslint-disable-next-line import/no-unresolved
@@ -39,22 +39,89 @@ const scratchPlaneXAxis = new Vector3();
 const scratchHorizonCartesian = new Vector3();
 const scratchHorizonProjected = new Vector2();
 const scratchMaxY = new Vector3();
-const scratchMinY = new Vector3();
 const scratchZ = new Vector3();
 
 const VECTOR3_UNIT_X = new Vector3(1, 0, 0);
 const VECTOR3_UNIT_Z = new Vector3(0, 0, 1);
 
+export type GeodeticRegion = readonly [
+  west: number,
+  south: number,
+  east: number,
+  north: number,
+  minimumHeight: number,
+  maximumHeight: number
+];
+
+export type MakeOBBFromRegionOptions = {
+  /** Longitude and latitude units. Defaults to radians, as in 3D Tiles regions. */
+  units?: 'radians' | 'degrees';
+  /** Affine transform from ellipsoid-fixed coordinates into the caller's world space. */
+  transform?: Matrix4;
+};
+
 /**
- * Computes an OrientedBoundingBox that bounds a region on the surface of the WGS84 ellipsoid.
- * There are no guarantees about the orientation of the bounding box.
+ * Creates a conservative oriented bounding box for a geodetic region.
  *
- * @param {number[]} region The cartographic region ([west, south, east, north, minimum height, maximum height])
- *                          on the surface of the ellipsoid.
- * @returns {OrientedBoundingBox} The modified result parameter or a new OrientedBoundingBox instance if none was provided.
+ * Longitudes and latitudes are radians by default. An east longitude smaller than west
+ * denotes the directed eastward interval crossing the antimeridian; equal longitudes denote
+ * zero width unless the original endpoints differ by a full turn.
+ * Heights use the ellipsoid's linear unit. Inputs and the supplied ellipsoid and transform are
+ * never mutated.
  */
 // eslint-disable-next-line max-statements
-export function makeOBBfromRegion(region: number[]): OrientedBoundingBox {
+export function makeOBBFromRegion(
+  region: readonly number[],
+  ellipsoid: Ellipsoid = Ellipsoid.WGS84,
+  options: MakeOBBFromRegionOptions = {}
+): OrientedBoundingBox {
+  if (!region || region.length !== 6 || region.some(value => !Number.isFinite(value))) {
+    throw new Error('makeOBBFromRegion: region must contain exactly six finite numbers');
+  }
+  const unitScale = options.units === 'degrees' ? radians(1) : 1;
+  const [rawWest, rawSouth, rawEast, rawNorth, minimumHeight, maximumHeight] = region;
+  if (minimumHeight > maximumHeight) {
+    throw new Error('makeOBBFromRegion: minimumHeight must not exceed maximumHeight');
+  }
+  const south = rawSouth * unitScale;
+  const north = rawNorth * unitScale;
+  const west = normalizeLongitude(rawWest * unitScale);
+  let east = normalizeLongitude(rawEast * unitScale);
+  // Preserve a complete directed turn, which would otherwise collapse when both endpoints
+  // are normalized to the same longitude. Reversed boundaries retain Cesium/3D Tiles semantics.
+  const directedSpan = rawEast * unitScale - rawWest * unitScale;
+  if (directedSpan >= _MathUtils.TWO_PI - 1e-12) {
+    east = west + _MathUtils.TWO_PI;
+  }
+  const latitudeTolerance = 1e-12;
+  if (
+    south > north ||
+    south < -_MathUtils.PI_OVER_TWO - latitudeTolerance ||
+    north > _MathUtils.PI_OVER_TWO + latitudeTolerance
+  ) {
+    throw new Error('makeOBBFromRegion: latitude must be within [-π/2, π/2] and south ≤ north');
+  }
+  // Avoid passing a tiny out-of-range value to the ellipsoid conversion at a boundary.
+  const clampedSouth = Math.max(-_MathUtils.PI_OVER_TWO, Math.min(_MathUtils.PI_OVER_TWO, south));
+  const clampedNorth = Math.max(-_MathUtils.PI_OVER_TWO, Math.min(_MathUtils.PI_OVER_TWO, north));
+  return makeOBBFromNormalizedRegion(
+    [west, clampedSouth, east, clampedNorth, minimumHeight, maximumHeight],
+    ellipsoid,
+    options.transform
+  );
+}
+
+function normalizeLongitude(value: number): number {
+  const normalized =
+    ((((value + Math.PI) % _MathUtils.TWO_PI) + _MathUtils.TWO_PI) % _MathUtils.TWO_PI) - Math.PI;
+  return normalized === -Math.PI && value > 0 ? Math.PI : normalized;
+}
+
+function makeOBBFromNormalizedRegion(
+  region: GeodeticRegion,
+  ellipsoid: Ellipsoid,
+  transform?: Matrix4
+): OrientedBoundingBox {
   const obb = new OrientedBoundingBox();
 
   const [west, south, east, north, minimumHeight, maximumHeight] = region;
@@ -84,8 +151,8 @@ export function makeOBBfromRegion(region: number[]): OrientedBoundingBox {
   if (rectangle.width <= _MathUtils.PI) {
     const westDeg = degrees(west);
 
-    const tangentPoint = Ellipsoid.WGS84.cartographicToCartesian(tangentPointCartographic);
-    const ellipsoidTangentPlane = new EllipsoidTangentPlane(tangentPoint);
+    const tangentPoint = ellipsoid.cartographicToCartesian(tangentPointCartographic);
+    const ellipsoidTangentPlane = new EllipsoidTangentPlane(tangentPoint, ellipsoid);
 
     const latCenter = southDeg < 0.0 && northDeg > 0.0 ? 0.0 : tangentPointCartographic.y;
 
@@ -115,23 +182,23 @@ export function makeOBBfromRegion(region: number[]): OrientedBoundingBox {
       maximumHeight
     ]);
 
-    const perimeterCartesianNC = Ellipsoid.WGS84.cartographicToCartesian(
+    const perimeterCartesianNC = ellipsoid.cartographicToCartesian(
       perimeterCartographicNC,
       scratchPerimeterCartesianNC
     );
-    let perimeterCartesianNW = Ellipsoid.WGS84.cartographicToCartesian(
+    let perimeterCartesianNW = ellipsoid.cartographicToCartesian(
       perimeterCartographicNW,
       scratchPerimeterCartesianNW
     );
-    const perimeterCartesianCW = Ellipsoid.WGS84.cartographicToCartesian(
+    const perimeterCartesianCW = ellipsoid.cartographicToCartesian(
       perimeterCartographicCW,
       scratchPerimeterCartesianCW
     );
-    let perimeterCartesianSW = Ellipsoid.WGS84.cartographicToCartesian(
+    let perimeterCartesianSW = ellipsoid.cartographicToCartesian(
       perimeterCartographicSW,
       scratchPerimeterCartesianSW
     );
-    const perimeterCartesianSC = Ellipsoid.WGS84.cartographicToCartesian(
+    const perimeterCartesianSC = ellipsoid.cartographicToCartesian(
       perimeterCartographicSC,
       scratchPerimeterCartesianSC
     );
@@ -164,11 +231,11 @@ export function makeOBBfromRegion(region: number[]): OrientedBoundingBox {
     minY = Math.min(perimeterProjectedSW.y, perimeterProjectedSC.y);
 
     perimeterCartographicNW.z = perimeterCartographicSW.z = minimumHeight;
-    perimeterCartesianNW = Ellipsoid.WGS84.cartographicToCartesian(
+    perimeterCartesianNW = ellipsoid.cartographicToCartesian(
       perimeterCartographicNW,
       scratchPerimeterCartesianNW
     );
-    perimeterCartesianSW = Ellipsoid.WGS84.cartographicToCartesian(
+    perimeterCartesianSW = ellipsoid.cartographicToCartesian(
       perimeterCartographicSW,
       scratchPerimeterCartesianSW
     );
@@ -180,18 +247,21 @@ export function makeOBBfromRegion(region: number[]): OrientedBoundingBox {
     );
     maxZ = maximumHeight;
 
-    return fromPlaneExtents(
-      ellipsoidTangentPlane.origin,
-      ellipsoidTangentPlane.xAxis,
-      ellipsoidTangentPlane.yAxis,
-      ellipsoidTangentPlane.zAxis,
-      minX,
-      maxX,
-      minY,
-      maxY,
-      minZ,
-      maxZ,
-      obb
+    return applyTransform(
+      fromPlaneExtents(
+        ellipsoidTangentPlane.origin,
+        ellipsoidTangentPlane.xAxis,
+        ellipsoidTangentPlane.yAxis,
+        ellipsoidTangentPlane.zAxis,
+        minX,
+        maxX,
+        minY,
+        maxY,
+        minZ,
+        maxZ,
+        obb
+      ),
+      transform
     );
   }
 
@@ -205,7 +275,7 @@ export function makeOBBfromRegion(region: number[]): OrientedBoundingBox {
       ? northDeg
       : 0.0;
 
-  const planeOrigin = Ellipsoid.WGS84.cartographicToCartesian(
+  const planeOrigin = ellipsoid.cartographicToCartesian(
     [lonCenterDeg, latitudeNearestToEquator, maximumHeight],
     scratchPlaneOrigin
   );
@@ -218,7 +288,7 @@ export function makeOBBfromRegion(region: number[]): OrientedBoundingBox {
   const planeXAxis = scratchPlaneXAxis.copy(planeNormal).cross(planeYAxis);
   plane = scratchPlane.fromPointNormal(planeOrigin, planeNormal);
 
-  const horizonCartesian = Ellipsoid.WGS84.cartographicToCartesian(
+  const horizonCartesian = ellipsoid.cartographicToCartesian(
     [degrees(lonCenter + _MathUtils.PI_OVER_TWO), latitudeNearestToEquator, maximumHeight],
     scratchHorizonCartesian
   );
@@ -229,16 +299,12 @@ export function makeOBBfromRegion(region: number[]): OrientedBoundingBox {
   maxX = projectedPoint.dot(planeXAxis);
   minX = -maxX;
 
-  maxY = Ellipsoid.WGS84.cartographicToCartesian(
-    [0.0, northDeg, fullyBelowEquator ? minimumHeight : maximumHeight],
-    scratchMaxY
-  ).z;
-  minY = Ellipsoid.WGS84.cartographicToCartesian(
-    [0.0, southDeg, fullyAboveEquator ? minimumHeight : maximumHeight],
-    scratchMinY
-  ).z;
+  const northHeight = fullyBelowEquator ? minimumHeight : maximumHeight;
+  const southHeight = fullyAboveEquator ? minimumHeight : maximumHeight;
+  maxY = latitudeZExtent(ellipsoid, northDeg, northHeight, true);
+  minY = latitudeZExtent(ellipsoid, southDeg, southHeight, false);
 
-  const farZ = Ellipsoid.WGS84.cartographicToCartesian(
+  const farZ = ellipsoid.cartographicToCartesian(
     [eastDeg, latitudeNearestToEquator, maximumHeight],
     scratchZ
   );
@@ -246,24 +312,65 @@ export function makeOBBfromRegion(region: number[]): OrientedBoundingBox {
   minZ = plane.getPointDistance(farZ);
   maxZ = 0.0;
 
-  return fromPlaneExtents(
-    planeOrigin,
-    planeXAxis,
-    planeYAxis,
-    planeNormal,
-    minX,
-    maxX,
-    minY,
-    maxY,
-    minZ,
-    maxZ,
-    obb
+  return applyTransform(
+    fromPlaneExtents(
+      planeOrigin,
+      planeXAxis,
+      planeYAxis,
+      planeNormal,
+      minX,
+      maxX,
+      minY,
+      maxY,
+      minZ,
+      maxZ,
+      obb
+    ),
+    transform
   );
 }
 
-const scratchScale = new Vector3();
+function applyTransform(obb: OrientedBoundingBox, transform?: Matrix4): OrientedBoundingBox {
+  if (!transform) return obb;
+  // A general affine transform turns an OBB into a parallelepiped. Refit its eight
+  // corners to an axis-aligned OBB so culling methods that assume orthogonal axes remain safe.
+  const axes = [0, 1, 2].map(column => obb.halfAxes.getColumn(column, new Vector3()));
+  const center = transform.transformAsPoint(obb.center) as number[];
+  const minimum = [Infinity, Infinity, Infinity];
+  const maximum = [-Infinity, -Infinity, -Infinity];
+  for (let mask = 0; mask < 8; mask++) {
+    const corner = new Vector3(center);
+    for (let axis = 0; axis < 3; axis++) {
+      const transformedAxis = transform.transformAsVector(axes[axis]) as number[];
+      corner.add(new Vector3(transformedAxis).scale((mask & (1 << axis)) === 0 ? -1 : 1));
+    }
+    for (let component = 0; component < 3; component++) {
+      minimum[component] = Math.min(minimum[component], corner[component]);
+      maximum[component] = Math.max(maximum[component], corner[component]);
+    }
+  }
+  obb.center.copy(minimum).add(maximum).scale(0.5);
+  const halfSize = new Vector3(maximum).subtract(minimum).scale(0.5);
+  obb.halfAxes = new Matrix3().set(halfSize.x, 0, 0, 0, halfSize.y, 0, 0, 0, halfSize.z);
+  return obb;
+}
 
-/** helper function for OrientedBoundingBox.fromRegion() */
+function latitudeZExtent(
+  ellipsoid: Ellipsoid,
+  latitude: number,
+  height: number,
+  maximum: boolean
+): number {
+  let extent = maximum ? -Infinity : Infinity;
+  // A triaxial ellipsoid's fixed-latitude extrema occur at a principal longitude.
+  for (const longitude of [0, 90, 180, 270]) {
+    const z = ellipsoid.cartographicToCartesian([longitude, latitude, height], scratchMaxY).z;
+    extent = maximum ? Math.max(extent, z) : Math.min(extent, z);
+  }
+  return extent;
+}
+
+/** Helper function for makeOBBFromRegion(). */
 // eslint-disable-next-line max-params
 function fromPlaneExtents(
   planeOrigin: Vector3,
@@ -284,20 +391,24 @@ function fromPlaneExtents(
   halfAxes.setColumn(1, planeYAxis);
   halfAxes.setColumn(2, planeZAxis);
 
-  let centerOffset = scratchOffset;
-  centerOffset.x = (minimumX + maximumX) / 2.0;
-  centerOffset.y = (minimumY + maximumY) / 2.0;
-  centerOffset.z = (minimumZ + maximumZ) / 2.0;
-  centerOffset = halfAxes.multiplyByVector(centerOffset, scratchOffset);
-
-  const scale = scratchScale;
-  scale.x = (maximumX - minimumX) / 2.0;
-  scale.y = (maximumY - minimumY) / 2.0;
-  scale.z = (maximumZ - minimumZ) / 2.0;
-
-  planeOrigin = center.copy(planeOrigin);
-  result.center = planeOrigin.add(centerOffset);
-  result.halfAxes = halfAxes.multiplyByScale(scale, halfAxes);
+  const centerOffset = scratchOffset
+    .set((minimumX + maximumX) / 2.0, (minimumY + maximumY) / 2.0, (minimumZ + maximumZ) / 2.0)
+    .transformByMatrix3(halfAxes);
+
+  const scaleX = (maximumX - minimumX) / 2.0;
+  const scaleY = (maximumY - minimumY) / 2.0;
+  const scaleZ = (maximumZ - minimumZ) / 2.0;
+  halfAxes[0] *= scaleX;
+  halfAxes[1] *= scaleX;
+  halfAxes[2] *= scaleX;
+  halfAxes[3] *= scaleY;
+  halfAxes[4] *= scaleY;
+  halfAxes[5] *= scaleY;
+  halfAxes[6] *= scaleZ;
+  halfAxes[7] *= scaleZ;
+  halfAxes[8] *= scaleZ;
+
+  center.copy(planeOrigin).add(centerOffset);
 
   return result;
 }