Added maximumTiltAngle to limit how much the camera can tilt

CHANGES.md

@@ -33,6 +33,7 @@ This is an npm-only release to extra source maps included in 1.121
 - Added `WaterMask` globe material, which visualizes areas of water or land based on the terrain's water mask. [#12149](https://github.com/CesiumGS/cesium/pull/12149)
 - Made the `time` parameter optional for `Property`, using `JulianDate.now()` as default. [#12099](https://github.com/CesiumGS/cesium/pull/12099)
 - Exposes `ScreenSpaceCameraController.zoomFactor` to allow adjusting the zoom factor (speed). [#9145](https://github.com/CesiumGS/cesium/pull/9145)
+- Added `ScreenSpaceCameraController.maximumTiltAngle` to limit how much the camera can tilt.
 
 ##### Fixes :wrench:
 

CONTRIBUTORS.md

@@ -186,6 +186,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to contribute to Cesiu
   - [Tang Xiaofei](https://github.com/vtxf)
 - [Maxar](https://www.maxar.com)
   - [Erik Dahlström](https://github.com/erikdahlstrom)
+  - [Albin Ekberg](https://github.com/albek446)
 - [Novatron Oy](https://novatron.fi/en/)
   - [Jussi Hirvonen](https://github.com/VsKatshuma)
 - [Sierra Nevada Corp](https://www.sncorp.com/)

packages/engine/Source/Scene/ScreenSpaceCameraController.js

@@ -271,6 +271,11 @@ function ScreenSpaceCameraController(scene) {
    * @default true
    */
   this.enableCollisionDetection = true;
+  /**
+   * If set, the camera will not be able to tilt past this angle, expressed in radians.
+   * @type {number}
+   */
+  this.maximumTiltAngle = undefined;
 
   this._scene = scene;
   this._globe = undefined;
@@ -2058,7 +2063,16 @@ function rotate3D(
   );
 
   const deltaPhi = rotateRate * phiWindowRatio * Math.PI * 2.0;
-  const deltaTheta = rotateRate * thetaWindowRatio * Math.PI;
+  let deltaTheta = rotateRate * thetaWindowRatio * Math.PI;
+
+  if (defined(constrainedAxis) && defined(controller.maximumTiltAngle)) {
+    const maximumTiltAngle = controller.maximumTiltAngle;
+    const dotProduct = Cartesian3.dot(camera.direction, constrainedAxis);
+    const tilt = Math.PI - Math.acos(dotProduct) + deltaTheta;
+    if (tilt > maximumTiltAngle) {
+      deltaTheta -= tilt - maximumTiltAngle;
+    }
+  }
 
   if (!rotateOnlyVertical) {
     camera.rotateRight(deltaPhi);

packages/engine/Specs/Scene/ScreenSpaceCameraControllerSpec.js

@@ -1566,6 +1566,79 @@ describe("Scene/ScreenSpaceCameraController", function () {
     expect(camera.direction).not.toEqual(direction);
   });
 
+  it("maximum tilt angle is 0 in 3D", function () {
+    setUp3D();
+    const originalCameraPosition = Cartesian3.clone(camera.position);
+    const originalCameraDirection = Cartesian3.clone(camera.direction);
+    controller.maximumTiltAngle = 0;
+    const startPosition = new Cartesian2(
+      canvas.clientWidth / 2,
+      canvas.clientHeight / 2
+    );
+    const endPosition = new Cartesian2(
+      canvas.clientWidth / 2,
+      canvas.clientHeight / 4
+    );
+
+    moveMouse(MouseButtons.MIDDLE, startPosition, endPosition);
+    updateController();
+
+    expect(camera.position).toEqualEpsilon(
+      originalCameraPosition,
+      CesiumMath.EPSILON8
+    );
+    expect(camera.position).not.toEqualEpsilon(
+      originalCameraDirection,
+      CesiumMath.EPSILON8
+    );
+
+    const dotProduct = Cartesian3.dot(
+      camera.direction,
+      originalCameraDirection
+    );
+    const acos = Math.acos(dotProduct);
+    const angle = (acos * 180) / Math.PI;
+    expect(angle).toEqual(0);
+  });
+
+  it("maximum tilt angle is 45 degrees in 3D", function () {
+    setUp3D();
+    const originalCameraPosition = Cartesian3.clone(camera.position);
+    const originalCameraDirection = Cartesian3.clone(camera.direction);
+    controller.maximumTiltAngle = (45 * Math.PI) / 180;
+    const startPosition = new Cartesian2(
+      canvas.clientWidth / 2,
+      canvas.clientHeight / 2
+    );
+    const endPosition = new Cartesian2(
+      canvas.clientWidth / 2,
+      canvas.clientHeight / 4
+    );
+
+    moveMouse(MouseButtons.MIDDLE, startPosition, endPosition);
+    updateController();
+    moveMouse(MouseButtons.MIDDLE, startPosition, endPosition);
+    updateController();
+
+    expect(camera.position).not.toEqualEpsilon(
+      originalCameraPosition,
+      CesiumMath.EPSILON8
+    );
+    expect(camera.position).not.toEqualEpsilon(
+      originalCameraDirection,
+      CesiumMath.EPSILON8
+    );
+
+    const dotProduct = Cartesian3.dot(
+      camera.direction,
+      originalCameraDirection
+    );
+    const acos = Math.acos(dotProduct);
+    const angle = (acos * 180) / Math.PI;
+    expect(angle).toBeLessThanOrEqual(45);
+    expect(angle).toBeGreaterThan(44);
+  });
+
   it("looks in 3D", function () {
     setUp3D();
     const position = Cartesian3.clone(camera.position);