WebMercatorViewport support external projectionMatrix (#5930)

Author: felixpalmer

docs/api-reference/core/web-mercator-viewport.md

@@ -51,13 +51,15 @@ Parameters:
   + `nearZMultiplier` (Number, optional) - Scaler for the near plane, 1 unit equals to the height of the viewport. Default to `0.1`.
   + `farZMultiplier` (Number, optional) - Scaler for the far plane, 1 unit equals to the distance from the camera to the top edge of the screen. Default to `1.01`.
   + `orthographic` (Boolean, optional) - Default `false`.
+  + `projectionMatrix` (Array, optional) - Optional 16-element 4x4 projection matrix, that overrides the matrix created from the parameters above.
 
 Remarks:
 
 * `altitude` has a default value that matches assumptions in mapbox-gl
 * `width` and `height` are forced to 1 if supplied as 0, to avoid division by zero. This is intended to reduce the burden of apps to check values before instantiating a `Viewport`.
 *  When using Mercator projection, per cartographic tradition, longitudes and latitudes are specified as degrees.
 * `latitude` of `90` or `-90` are projected to infinity in [Web Mercator projection](https://en.wikipedia.org/wiki/Web_Mercator_projection). Using pole locations with this viewport may result in `NaN`s. Many base map providers cut off at `85.051129` at which the full world becomes a square.
+* When constructing the viewport, a field of view is not specified, but rather is calculated from the `altitude` or (if present) the `projectionMatrix`. The value can be obtained from `this.fovy` (in degrees).
 
 Inherits all [Viewport methods](/docs/api-reference/core/viewport.md#methods).
 

examples/webpack.config.local.js

@@ -61,7 +61,7 @@ function makeLocalDevConfig(EXAMPLE_DIR = LIB_DIR, linkToLuma, linkToMath) {
       'geoid',
       'geospatial',
       'main',
-      'mercator',
+      'web-mercator',
       'polygon',
       'proj4',
       'sun',

modules/core/src/viewports/web-mercator-viewport.js

@@ -27,6 +27,7 @@ import {
   getViewMatrix,
   addMetersToLngLat,
   getProjectionParameters,
+  altitudeToFovy,
   fitBounds,
   getBounds
 } from '@math.gl/web-mercator';
@@ -53,6 +54,7 @@ export default class WebMercatorViewport extends Viewport {
       nearZMultiplier = 0.1,
       farZMultiplier = 1.01,
       orthographic = false,
+      projectionMatrix,
 
       repeat = false,
       worldOffset = 0
@@ -69,14 +71,27 @@ export default class WebMercatorViewport extends Viewport {
     // TODO - just throw an Error instead?
     altitude = Math.max(0.75, altitude);
 
-    const {fov, aspect, focalDistance, near, far} = getProjectionParameters({
-      width,
-      height,
-      pitch,
-      altitude,
-      nearZMultiplier,
-      farZMultiplier
-    });
+    let fovy;
+    let projectionParameters = null;
+    if (projectionMatrix) {
+      fovy = altitudeToFovy(projectionMatrix[5] / 2);
+    } else {
+      fovy = altitudeToFovy(altitude);
+      const {aspect, fov: fovyRadians, near, far} = getProjectionParameters({
+        width,
+        height,
+        pitch,
+        fovy,
+        nearZMultiplier,
+        farZMultiplier
+      });
+      projectionParameters = {
+        fovyRadians,
+        aspect,
+        near,
+        far
+      };
+    }
 
     // The uncentered matrix allows us two move the center addition to the
     // shader (cheap) which gives a coordinate system that has its center in
@@ -108,12 +123,9 @@ export default class WebMercatorViewport extends Viewport {
       zoom,
 
       // projection matrix parameters
-      orthographic,
-      fovyRadians: fov,
-      aspect,
-      focalDistance,
-      near,
-      far
+      ...projectionParameters,
+      fovy,
+      focalDistance: altitude
     });
 
     // Save parameters
@@ -123,6 +135,7 @@ export default class WebMercatorViewport extends Viewport {
     this.pitch = pitch;
     this.bearing = bearing;
     this.altitude = altitude;
+    this.fovy = fovy;
 
     this.orthographic = orthographic;
 

test/modules/core/viewports/web-mercator-viewport.spec.js

@@ -21,12 +21,15 @@
 import test from 'tape-catch';
 import {equals, config, Vector3} from 'math.gl';
 import {WebMercatorViewport} from 'deck.gl';
+import {Matrix4} from 'math.gl';
 
 // Adjust sensitivity of math.gl's equals
 const LNGLAT_TOLERANCE = 1e-6;
 const ALT_TOLERANCE = 1e-5;
 const OFFSET_TOLERANCE = 1e-5;
 
+const DEGREES_TO_RADIANS = Math.PI / 180;
+
 /* eslint-disable */
 const TEST_VIEWPORTS = [
   {
@@ -276,6 +279,21 @@ test('WebMercatorViewport.subViewports', t => {
   t.end();
 });
 
+test('WebMercatorViewport.projectionMatrix', t => {
+  const opts = {...TEST_VIEWPORTS[0]};
+
+  const fovy = 25;
+  const projectionMatrix = new Matrix4().perspective({
+    fovy: fovy * DEGREES_TO_RADIANS,
+    aspect: opts.width / opts.height,
+    near: 0.1,
+    far: 10
+  });
+  let viewport = new WebMercatorViewport({projectionMatrix, ...opts});
+  t.deepEqual(viewport.fovy, fovy, 'fovy is passed through');
+  t.end();
+});
+
 function getCulling(p, planes) {
   let outDir = null;
   p = new Vector3(p);