fix(camera): let a camera above the zoom ceiling zoom in without a jump

Cesium clamps any zoom that starts above maximumZoomDistance to that
limit, in either direction, so a share link or flight that left the
camera above 40,000 km jumped to the ceiling on the first wheel tick.
While the camera is above the ceiling, the guard now uses its current
height as the limit and lowers it as the camera descends.

src/app/zoomOutGuard.js

@@ -78,16 +78,35 @@ export function installZoomOutGuard(
   const controller = scene?.screenSpaceCameraController;
   const camera = viewer?.camera;
   const canvas = viewer?.canvas;
-  if (!controller || !camera || !canvas || !scene.preRender)
+  if (
+    !controller ||
+    !camera ||
+    !canvas ||
+    !scene.preRender ||
+    !scene.postUpdate
+  )
     throw new TypeError('A complete Cesium viewer is required');
 
   const aggregator = createAggregator(canvas);
   const originalMaximumZoomDistance = controller.maximumZoomDistance;
-  const maximumZoomDistance = Math.min(
+  const ownsCeiling = originalMaximumZoomDistance > MAXIMUM_ZOOM_DISTANCE_M;
+  let maximumZoomDistance = Math.min(
     originalMaximumZoomDistance,
     MAXIMUM_ZOOM_DISTANCE_M,
   );
   controller.maximumZoomDistance = maximumZoomDistance;
+  // Cesium clamps any zoom that starts above the limit to the limit, in either
+  // direction. A camera placed higher by a flight or share link keeps its own
+  // height as the limit, so it zooms in gradually and can't climb further.
+  const followCeiling = () => {
+    if (!ownsCeiling || controller.maximumZoomDistance !== maximumZoomDistance)
+      return;
+    const height = camera.positionCartographic?.height;
+    maximumZoomDistance =
+      height > MAXIMUM_ZOOM_DISTANCE_M ? height : MAXIMUM_ZOOM_DISTANCE_M;
+    controller.maximumZoomDistance = maximumZoomDistance;
+  };
+  followCeiling();
 
   let lastHeight = camera.positionCartographic?.height;
   let lastPosition = Cesium.Cartesian3.clone(camera.position);
@@ -175,6 +194,8 @@ export function installZoomOutGuard(
     }
   };
   const removePreRender = scene.preRender.addEventListener(guard);
+  // Fires every frame, after Cesium has applied this frame's input.
+  const removePostUpdate = scene.postUpdate.addEventListener(followCeiling);
   const removeCameraHandoff = subscribeCameraHandoff?.(() => {
     cancel();
     // Discard input queued before an explicit navigation action took ownership.
@@ -187,6 +208,7 @@ export function installZoomOutGuard(
     active = false;
     removeCameraHandoff?.();
     removePreRender?.();
+    removePostUpdate?.();
     aggregator.destroy();
     if (controller.maximumZoomDistance === maximumZoomDistance)
       controller.maximumZoomDistance = originalMaximumZoomDistance;

src/app/zoomOutGuard.test.mjs

@@ -35,6 +35,7 @@ test('maxPitchForHeight steepens monotonically with height', () => {
 
 function guardFixture({ maximumZoomDistance = Infinity } = {}) {
   const preRender = new Set();
+  const postUpdate = new Set();
   const handoffs = new Set();
   const container = new EventTarget();
   const canvas = new EventTarget();
@@ -107,6 +108,12 @@ function guardFixture({ maximumZoomDistance = Infinity } = {}) {
         return () => preRender.delete(handler);
       },
     },
+    postUpdate: {
+      addEventListener(handler) {
+        postUpdate.add(handler);
+        return () => postUpdate.delete(handler);
+      },
+    },
   };
   const renders = [];
   const dispose = installZoomOutGuard(
@@ -125,6 +132,7 @@ function guardFixture({ maximumZoomDistance = Infinity } = {}) {
   );
   const frame = (height = camera.height) => {
     camera.height = height;
+    for (const handler of postUpdate) handler();
     for (const handler of preRender) handler();
   };
   const movement = (type, deltaY, { modifier, tiltDeltaY = 0 } = {}) => {
@@ -163,6 +171,7 @@ function guardFixture({ maximumZoomDistance = Infinity } = {}) {
     scene,
     aggregator,
     preRender,
+    postUpdate,
     handoffs,
     handoff: () => {
       for (const listener of handoffs) listener();
@@ -402,6 +411,7 @@ test('installer sets the ceiling and disposer releases aggregator and frame list
   const f = guardFixture();
   assert.equal(f.controller.maximumZoomDistance, MAXIMUM_ZOOM_DISTANCE_M);
   assert.equal(f.preRender.size, 1);
+  assert.equal(f.postUpdate.size, 1);
   f.frame();
   assert.ok(f.aggregator.resets > 0);
   f.dispose();
@@ -409,6 +419,7 @@ test('installer sets the ceiling and disposer releases aggregator and frame list
   assert.equal(f.controller.maximumZoomDistance, Infinity);
   assert.equal(f.aggregator.destroys, 1);
   assert.equal(f.preRender.size, 0);
+  assert.equal(f.postUpdate.size, 0);
   assert.equal(f.handoffs.size, 0);
 });
 
@@ -466,6 +477,7 @@ test('a real Cesium camera settles across the north heading wrap at Istanbul', (
     mode: Cesium.SceneMode.SCENE3D,
     pixelRatio: 1,
     preRender: new Cesium.Event(),
+    postUpdate: new Cesium.Event(),
     screenSpaceCameraController: {
       maximumZoomDistance: Infinity,
       enableInputs: true,
@@ -560,3 +572,126 @@ test('explicit navigation cancels outward inertia before a climbing UI tilt', ()
   assert.ok(f.camera.views.length > writes);
   f.dispose();
 });
+
+// A real Cesium camera and controller, fed by DOM wheel events on the canvas.
+function realControllerScene(startHeight) {
+  const canvas = Object.assign(new EventTarget(), {
+    clientWidth: 1200,
+    clientHeight: 800,
+    width: 1200,
+    height: 800,
+    style: {},
+    // Keep Cesium's input handler off the missing `document`.
+    disableRootEvents: true,
+    onwheel: null,
+    getBoundingClientRect: () => ({
+      left: 0,
+      top: 0,
+      width: 1200,
+      height: 800,
+    }),
+  });
+  const scene = {
+    canvas,
+    drawingBufferWidth: 1200,
+    drawingBufferHeight: 800,
+    mapProjection: new Cesium.GeographicProjection(),
+    ellipsoid: Cesium.Ellipsoid.WGS84,
+    mapMode2D: Cesium.MapMode2D.INFINITE_SCROLL,
+    mode: Cesium.SceneMode.SCENE3D,
+    pixelRatio: 1,
+    verticalExaggeration: 1,
+    verticalExaggerationRelativeHeight: 0,
+    preRender: new Cesium.Event(),
+    postUpdate: new Cesium.Event(),
+  };
+  const camera = new Cesium.Camera(scene);
+  scene.camera = camera;
+  const controller = new Cesium.ScreenSpaceCameraController(scene);
+  controller.inertiaZoom = 0;
+  scene.screenSpaceCameraController = controller;
+  const setHeight = (h) =>
+    camera.setView({
+      destination: Cesium.Cartesian3.fromDegrees(28.9784, 41.0082, h),
+      orientation: { heading: 0, pitch: -Cesium.Math.PI_OVER_TWO, roll: 0 },
+    });
+  setHeight(startHeight);
+  const dispose = installZoomOutGuard(
+    { scene, camera, canvas },
+    { requestRender() {} },
+  );
+  // Scene.render order: the controller applies input, then postUpdate, then
+  // preRender on frames that draw.
+  const frame = () => {
+    controller.update();
+    scene.postUpdate.raiseEvent(scene);
+    scene.preRender.raiseEvent(scene);
+  };
+  const wheel = (deltaY) =>
+    canvas.dispatchEvent(
+      Object.assign(new Event('wheel'), {
+        deltaY,
+        deltaMode: 0,
+        clientX: 600,
+        clientY: 400,
+      }),
+    );
+  const height = () => camera.positionCartographic.height;
+  return {
+    scene,
+    camera,
+    controller,
+    setHeight,
+    frame,
+    wheel,
+    height,
+    dispose,
+  };
+}
+
+test('a camera placed above the ceiling cannot zoom out and zooms in without a jump', () => {
+  const s = realControllerScene(60_000_000);
+  try {
+    s.frame();
+    s.wheel(1);
+    s.frame();
+    assert.ok(Math.abs(s.height() - 60_000_000) < 1, `${s.height()} m`);
+    s.wheel(-1);
+    s.frame();
+    const firstStep = s.height();
+    assert.ok(firstStep < 60_000_000, 'zooms in');
+    assert.ok(firstStep > 50_000_000, `${firstStep} m is gradual`);
+    // The camera can no longer climb back above where it has descended to.
+    s.wheel(1);
+    s.frame();
+    assert.ok(Math.abs(s.height() - firstStep) < 1, `${s.height()} m`);
+    for (let i = 0; i < 40; i++) {
+      s.wheel(-100);
+      s.frame();
+    }
+    assert.ok(s.height() < MAXIMUM_ZOOM_DISTANCE_M);
+    assert.equal(s.controller.maximumZoomDistance, MAXIMUM_ZOOM_DISTANCE_M);
+    for (let i = 0; i < 80; i++) {
+      s.wheel(100);
+      s.frame();
+    }
+    assert.ok(Math.abs(s.height() - MAXIMUM_ZOOM_DISTANCE_M) < 1_000);
+  } finally {
+    s.dispose();
+  }
+  assert.equal(s.controller.maximumZoomDistance, Infinity);
+});
+
+test('a share-link view restored above the ceiling is honoured by later frames', () => {
+  const s = realControllerScene(1_000_000);
+  try {
+    s.frame();
+    s.setHeight(97_679_259);
+    s.frame();
+    s.wheel(100);
+    s.frame();
+    assert.ok(Math.abs(s.height() - 97_679_259) < 1, `${s.height()} m`);
+  } finally {
+    s.dispose();
+  }
+});