NathanMOlson
diff --git a/‎CHANGELOG.md‎
Lines changed: 1 addition & 0 deletions b/‎CHANGELOG.md‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎src/geo/projection/camera_helper.ts‎
Lines changed: 32 additions & 2 deletions b/‎src/geo/projection/camera_helper.ts‎
Lines changed: 32 additions & 2 deletions
diff --git a/‎src/geo/projection/globe_camera_helper.ts‎
Lines changed: 14 additions & 12 deletions b/‎src/geo/projection/globe_camera_helper.ts‎
Lines changed: 14 additions & 12 deletions
diff --git a/‎src/geo/projection/globe_transform.test.ts‎
Lines changed: 10 additions & 0 deletions b/‎src/geo/projection/globe_transform.test.ts‎
Lines changed: 10 additions & 0 deletions
diff --git a/‎src/geo/projection/globe_transform.ts‎
Lines changed: 28 additions & 11 deletions b/‎src/geo/projection/globe_transform.ts‎
Lines changed: 28 additions & 11 deletions
diff --git a/‎src/geo/projection/globe_utils.ts‎
Lines changed: 2 additions & 2 deletions b/‎src/geo/projection/globe_utils.ts‎
Lines changed: 2 additions & 2 deletions
diff --git a/‎src/geo/projection/mercator_camera_helper.ts‎
Lines changed: 12 additions & 10 deletions b/‎src/geo/projection/mercator_camera_helper.ts‎
Lines changed: 12 additions & 10 deletions
diff --git a/‎src/geo/projection/mercator_transform.test.ts‎
Lines changed: 12 additions & 1 deletion b/‎src/geo/projection/mercator_transform.test.ts‎
Lines changed: 12 additions & 1 deletion
@@ -1,6 +1,7 @@
 ## main
 
 ### ✨ Features and improvements
+- Add support for camera roll angle ([#4717](https://github.com/maplibre/maplibre-gl-js/issues/4717))
 - _...Add new stuff here..._
 
 ### 🐞 Bug fixes
 
@@ -4,13 +4,15 @@ import {LngLat, LngLatLike} from '../lng_lat';
 import {CameraForBoundsOptions, PointLike} from '../../ui/camera';
 import {PaddingOptions} from '../edge_insets';
 import {LngLatBounds} from '../lng_lat_bounds';
-import {warnOnce} from '../../util/util';
+import {getRollPitchBearing, RollPitchBearing, warnOnce} from '../../util/util';
+import {quat} from 'gl-matrix';
 
 export type MapControlsDeltas = {
     panDelta: Point;
     zoomDelta: number;
     bearingDelta: number;
     pitchDelta: number;
+    rollDelta: number;
     around: Point;
 }
 
@@ -23,6 +25,7 @@ export type CameraForBoxAndBearingHandlerResult = {
 export type EaseToHandlerOptions = {
     bearing: number;
     pitch: number;
+    roll: number;
     padding: PaddingOptions;
     offsetAsPoint: Point;
     around?: LngLat;
@@ -41,6 +44,7 @@ export type EaseToHandlerResult = {
 export type FlyToHandlerOptions = {
     bearing: number;
     pitch: number;
+    roll: number;
     padding: PaddingOptions;
     offsetAsPoint: Point;
     center?: LngLatLike;
@@ -78,7 +82,7 @@ export interface ICameraHelper {
         easingOffset: Point;
     };
 
-    handleMapControlsPitchBearingZoom(deltas: MapControlsDeltas, tr: ITransform): void;
+    handleMapControlsRollPitchBearingZoom(deltas: MapControlsDeltas, tr: ITransform): void;
 
     handleMapControlsPan(deltas: MapControlsDeltas, tr: ITransform, preZoomAroundLoc: LngLat): void;
 
@@ -90,3 +94,29 @@ export interface ICameraHelper {
 
     handleFlyTo(tr: ITransform, options: FlyToHandlerOptions): FlyToHandlerResult;
 }
+
+/**
+ * @internal
+ * Set a transform's rotation to a value interpolated between startRotation and endRotation
+ * @param startRotation - the starting rotation (rotation when k = 0)
+ * @param endRotation - the end rotation (rotation when k = 1)
+ * @param endEulerAngles - the end Euler angles. This is needed in case `endRotation` has an ambiguous Euler angle representation.
+ * @param tr - the transform to be updated
+ * @param k - the interpolation fraction, between 0 and 1.
+ */
+export function updateRotation(startRotation: quat, endRotation: quat, endEulerAngles: RollPitchBearing, tr: ITransform, k: number) {
+    // At pitch ==0, the Euler angle representation is ambiguous. In this case, set the Euler angles
+    // to the representation requested by the caller
+    if (k < 1) {
+        const rotation: quat = new Float64Array(4) as any;
+        quat.slerp(rotation, startRotation, endRotation, k);
+        const eulerAngles = getRollPitchBearing(rotation);
+        tr.setRoll(eulerAngles.roll);
+        tr.setPitch(eulerAngles.pitch);
+        tr.setBearing(eulerAngles.bearing);
+    } else {
+        tr.setRoll(endEulerAngles.roll);
+        tr.setPitch(endEulerAngles.pitch);
+        tr.setBearing(endEulerAngles.bearing);
+    }
+}
@@ -1,12 +1,12 @@
 import Point from '@mapbox/point-geometry';
 import {IReadonlyTransform, ITransform} from '../transform_interface';
-import {cameraBoundsWarning, CameraForBoxAndBearingHandlerResult, EaseToHandlerResult, EaseToHandlerOptions, FlyToHandlerResult, FlyToHandlerOptions, ICameraHelper, MapControlsDeltas} from './camera_helper';
+import {cameraBoundsWarning, CameraForBoxAndBearingHandlerResult, EaseToHandlerResult, EaseToHandlerOptions, FlyToHandlerResult, FlyToHandlerOptions, ICameraHelper, MapControlsDeltas, updateRotation} from './camera_helper';
 import {GlobeProjection} from './globe';
 import {LngLat, LngLatLike} from '../lng_lat';
 import {MercatorCameraHelper} from './mercator_camera_helper';
 import {angularCoordinatesToSurfaceVector, computeGlobePanCenter, getGlobeRadiusPixels, getZoomAdjustment, globeDistanceOfLocationsPixels, interpolateLngLatForGlobe} from './globe_utils';
-import {clamp, createVec3f64, differenceOfAnglesDegrees, remapSaturate, warnOnce} from '../../util/util';
-import {mat4, vec3} from 'gl-matrix';
+import {clamp, createVec3f64, differenceOfAnglesDegrees, remapSaturate, rollPitchBearingToQuat, warnOnce} from '../../util/util';
+import {mat4, quat, vec3} from 'gl-matrix';
 import {MAX_VALID_LATITUDE, normalizeCenter, scaleZoom, zoomScale} from '../transform_helper';
 import {CameraForBoundsOptions} from '../../ui/camera';
 import {LngLatBounds} from '../lng_lat_bounds';
@@ -48,9 +48,9 @@ export class GlobeCameraHelper implements ICameraHelper {
         };
     }
 
-    handleMapControlsPitchBearingZoom(deltas: MapControlsDeltas, tr: ITransform): void {
+    handleMapControlsRollPitchBearingZoom(deltas: MapControlsDeltas, tr: ITransform): void {
         if (!this.useGlobeControls) {
-            this._mercatorCameraHelper.handleMapControlsPitchBearingZoom(deltas, tr);
+            this._mercatorCameraHelper.handleMapControlsRollPitchBearingZoom(deltas, tr);
             return;
         }
 
@@ -59,6 +59,7 @@ export class GlobeCameraHelper implements ICameraHelper {
 
         if (deltas.bearingDelta) tr.setBearing(tr.bearing + deltas.bearingDelta);
         if (deltas.pitchDelta) tr.setPitch(tr.pitch + deltas.pitchDelta);
+        if (deltas.rollDelta) tr.setRoll(tr.roll + deltas.rollDelta);
         const oldZoomPreZoomDelta = tr.zoom;
         if (deltas.zoomDelta) tr.setZoom(tr.zoom + deltas.zoomDelta);
         const actualZoomDelta = tr.zoom - oldZoomPreZoomDelta;
@@ -191,6 +192,7 @@ export class GlobeCameraHelper implements ICameraHelper {
         clonedTr.setCenter(result.center);
         clonedTr.setBearing(result.bearing);
         clonedTr.setPitch(0);
+        clonedTr.setRoll(0);
         clonedTr.setZoom(result.zoom);
         const matrix = clonedTr.modelViewProjectionMatrix;
 
@@ -259,9 +261,12 @@ export class GlobeCameraHelper implements ICameraHelper {
         }
 
         const startZoom = tr.zoom;
-        const startBearing = tr.bearing;
-        const startPitch = tr.pitch;
         const startCenter = tr.center;
+        const startRotation = rollPitchBearingToQuat(tr.roll, tr.pitch, tr.bearing);
+        const endRoll = options.roll === undefined ? tr.roll : options.roll;
+        const endPitch = options.pitch === undefined ? tr.pitch : options.pitch;
+        const endBearing = options.bearing === undefined ? tr.bearing : options.bearing;
+        const endRotation = rollPitchBearingToQuat(endRoll, endPitch, endBearing);
 
         const optionsZoom = typeof options.zoom !== 'undefined';
 
@@ -312,11 +317,8 @@ export class GlobeCameraHelper implements ICameraHelper {
         isZooming = (endZoomWithShift !== startZoom);
 
         const easeFunc = (k: number) => {
-            if (startBearing !== options.bearing) {
-                tr.setBearing(interpolates.number(startBearing, options.bearing, k));
-            }
-            if (startPitch !== options.pitch) {
-                tr.setPitch(interpolates.number(startPitch, options.pitch, k));
+            if (!quat.equals(startRotation, endRotation)) {
+                updateRotation(startRotation, endRotation, {roll: endRoll, pitch: endPitch, bearing: endBearing}, tr, k);
             }
 
             if (options.around) {
 
@@ -130,6 +130,16 @@ describe('GlobeTransform', () => {
             globeTransform.setBearing(70);
             expectToBeCloseToArray(globeTransform.cameraPosition as Array<number>, [-0.7098603286961542, 2.002400604307631, 0.6154310261827212], precisionDigits);
 
+            globeTransform.setPitch(35);
+            globeTransform.setBearing(70);
+            globeTransform.setRoll(40);
+            expectToBeCloseToArray(globeTransform.cameraPosition as Array<number>, [-0.7098603286961542, 2.002400604307631, 0.6154310261827212], precisionDigits);
+
+            globeTransform.setPitch(35);
+            globeTransform.setBearing(70);
+            globeTransform.setRoll(180);
+            expectToBeCloseToArray(globeTransform.cameraPosition as Array<number>, [-0.7098603286961542, 2.002400604307631, 0.6154310261827212], precisionDigits);
+
             globeTransform.setCenter(new LngLat(-10, 42));
             expectToBeCloseToArray(globeTransform.cameraPosition as Array<number>, [-3.8450970996236364, 2.9368285470351516, 4.311953269048194], precisionDigits);
         });
 
@@ -93,6 +93,9 @@ export class GlobeTransform implements ITransform {
     setPitch(pitch: number): void {
         this._helper.setPitch(pitch);
     }
+    setRoll(roll: number): void {
+        this._helper.setRoll(roll);
+    }
     setFov(fov: number): void {
         this._helper.setFov(fov);
     }
@@ -151,9 +154,6 @@ export class GlobeTransform implements ITransform {
     get height(): number {
         return this._helper.height;
     }
-    get angle(): number {
-        return this._helper.angle;
-    }
     get lngRange(): [number, number] {
         return this._helper.lngRange;
     }
@@ -181,12 +181,27 @@ export class GlobeTransform implements ITransform {
     get pitch(): number {
         return this._helper.pitch;
     }
+    get pitchInRadians(): number {
+        return this._helper.pitchInRadians;
+    }
+    get roll(): number {
+        return this._helper.roll;
+    }
+    get rollInRadians(): number {
+        return this._helper.rollInRadians;
+    }
     get bearing(): number {
         return this._helper.bearing;
     }
+    get bearingInRadians(): number {
+        return this._helper.bearingInRadians;
+    }
     get fov(): number {
         return this._helper.fov;
     }
+    get fovInRadians(): number {
+        return this._helper.fovInRadians;
+    }
     get elevation(): number {
         return this._helper.elevation;
     }
@@ -472,13 +487,13 @@ export class GlobeTransform implements ITransform {
         // - "cam" is camera origin
         // - "C" is globe center
         // - "B" is the point on "top" of the globe - camera is looking at B - "B" is the intersection between the camera center ray and the globe
-        // - this._pitch is the angle at B between points cam,B,A
+        // - this._pitchInRadians is the angle at B between points cam,B,A
         // - this.cameraToCenterDistance is the distance from camera to "B"
         // - globe radius is (0.5 * this.worldSize)
         // - "T" is any point where a tangent line from "cam" touches the globe surface
         // - elevation is assumed to be zero - globe rendering must be separate from terrain rendering anyway
 
-        const pitch = this.pitch * Math.PI / 180.0;
+        const pitch = this.pitchInRadians;
         // scale things so that the globe radius is 1
         const distanceCameraToB = this.cameraToCenterDistance / globeRadiusPixels;
         const radius = 1;
@@ -504,7 +519,7 @@ export class GlobeTransform implements ITransform {
         // Note the swizzled components
         const planeVector: vec3 = [0, vectorCtoCamX, vectorCtoCamY];
         // Apply transforms - lat, lng and angle (NOT pitch - already accounted for, as it affects the tangent plane)
-        vec3.rotateZ(planeVector, planeVector, [0, 0, 0], this.angle);
+        vec3.rotateZ(planeVector, planeVector, [0, 0, 0], -this.bearingInRadians);
         vec3.rotateX(planeVector, planeVector, [0, 0, 0], -1 * this.center.lat * Math.PI / 180.0);
         vec3.rotateY(planeVector, planeVector, [0, 0, 0], this.center.lng * Math.PI / 180.0);
         // Scale the plane vector up
@@ -609,7 +624,7 @@ export class GlobeTransform implements ITransform {
         const globeMatrixUncorrected = createMat4f64();
         this._nearZ = 0.5;
         this._farZ = this.cameraToCenterDistance + globeRadiusPixels * 2.0; // just set the far plane far enough - we will calculate our own z in the vertex shader anyway
-        mat4.perspective(globeMatrix, this.fov * Math.PI / 180, this.width / this.height, this._nearZ, this._farZ);
+        mat4.perspective(globeMatrix, this.fovInRadians, this.width / this.height, this._nearZ, this._farZ);
 
         // Apply center of perspective offset
         const offset = this.centerOffset;
@@ -620,8 +635,9 @@ export class GlobeTransform implements ITransform {
         this._globeProjMatrixInverted = createMat4f64();
         mat4.invert(this._globeProjMatrixInverted, globeMatrix);
         mat4.translate(globeMatrix, globeMatrix, [0, 0, -this.cameraToCenterDistance]);
-        mat4.rotateX(globeMatrix, globeMatrix, -this.pitch * Math.PI / 180);
-        mat4.rotateZ(globeMatrix, globeMatrix, -this.angle);
+        mat4.rotateZ(globeMatrix, globeMatrix, this.rollInRadians);
+        mat4.rotateX(globeMatrix, globeMatrix, -this.pitchInRadians);
+        mat4.rotateZ(globeMatrix, globeMatrix, this.bearingInRadians);
         mat4.translate(globeMatrix, globeMatrix, [0.0, 0, -globeRadiusPixels]);
         // Rotate the sphere to center it on viewed coordinates
 
@@ -647,8 +663,9 @@ export class GlobeTransform implements ITransform {
         const zero = createVec3f64();
         this._cameraPosition = createVec3f64();
         this._cameraPosition[2] = this.cameraToCenterDistance / globeRadiusPixels;
-        vec3.rotateX(this._cameraPosition, this._cameraPosition, zero, this.pitch * Math.PI / 180);
-        vec3.rotateZ(this._cameraPosition, this._cameraPosition, zero, this.angle);
+        vec3.rotateZ(this._cameraPosition, this._cameraPosition, zero, -this.rollInRadians);
+        vec3.rotateX(this._cameraPosition, this._cameraPosition, zero, this.pitchInRadians);
+        vec3.rotateZ(this._cameraPosition, this._cameraPosition, zero, -this.bearingInRadians);
         vec3.add(this._cameraPosition, this._cameraPosition, [0, 0, 1]);
         vec3.rotateX(this._cameraPosition, this._cameraPosition, zero, -this.center.lat * Math.PI / 180.0);
         vec3.rotateY(this._cameraPosition, this._cameraPosition, zero, this.center.lng * Math.PI / 180.0);
 
@@ -137,13 +137,13 @@ export function getDegreesPerPixel(worldSize: number, lat: number): number {
  * @returns New center location to set to the map's transform to apply the specified panning.
  */
 export function computeGlobePanCenter(panDelta: Point, tr: {
-    readonly angle: number;
+    readonly bearingInRadians: number;
     readonly worldSize: number;
     readonly center: LngLat;
     readonly zoom: number;
 }): LngLat {
     // Apply map bearing to the panning vector
-    const rotatedPanDelta = panDelta.rotate(-tr.angle);
+    const rotatedPanDelta = panDelta.rotate(tr.bearingInRadians);
     // Compute what the current zoom would be if the transform center would be moved to latitude 0.
     const normalizedGlobeZoom = tr.zoom + getZoomAdjustment(tr.center.lat, 0);
     // Note: we divide longitude speed by planet width at the given latitude. But we diminish this effect when the globe is zoomed out a lot.
 
@@ -1,14 +1,15 @@
 import Point from '@mapbox/point-geometry';
 import {LngLat, LngLatLike} from '../lng_lat';
 import {IReadonlyTransform, ITransform} from '../transform_interface';
-import {cameraBoundsWarning, CameraForBoxAndBearingHandlerResult, EaseToHandlerResult, EaseToHandlerOptions, FlyToHandlerResult, FlyToHandlerOptions, ICameraHelper, MapControlsDeltas} from './camera_helper';
+import {cameraBoundsWarning, CameraForBoxAndBearingHandlerResult, EaseToHandlerResult, EaseToHandlerOptions, FlyToHandlerResult, FlyToHandlerOptions, ICameraHelper, MapControlsDeltas, updateRotation} from './camera_helper';
 import {CameraForBoundsOptions} from '../../ui/camera';
 import {PaddingOptions} from '../edge_insets';
 import {LngLatBounds} from '../lng_lat_bounds';
 import {normalizeCenter, scaleZoom, zoomScale} from '../transform_helper';
-import {degreesToRadians} from '../../util/util';
+import {degreesToRadians, rollPitchBearingToQuat} from '../../util/util';
 import {projectToWorldCoordinates, unprojectFromWorldCoordinates} from './mercator_utils';
 import {interpolates} from '@maplibre/maplibre-gl-style-spec';
+import {quat} from 'gl-matrix';
 
 /**
  * @internal
@@ -26,9 +27,10 @@ export class MercatorCameraHelper implements ICameraHelper {
         };
     }
 
-    handleMapControlsPitchBearingZoom(deltas: MapControlsDeltas, tr: ITransform): void {
+    handleMapControlsRollPitchBearingZoom(deltas: MapControlsDeltas, tr: ITransform): void {
         if (deltas.bearingDelta) tr.setBearing(tr.bearing + deltas.bearingDelta);
         if (deltas.pitchDelta) tr.setPitch(tr.pitch + deltas.pitchDelta);
+        if (deltas.rollDelta) tr.setRoll(tr.roll + deltas.rollDelta);
         if (deltas.zoomDelta) tr.setZoom(tr.zoom + deltas.zoomDelta);
     }
 
@@ -119,9 +121,12 @@ export class MercatorCameraHelper implements ICameraHelper {
 
     handleEaseTo(tr: ITransform, options: EaseToHandlerOptions): EaseToHandlerResult {
         const startZoom = tr.zoom;
-        const startBearing = tr.bearing;
-        const startPitch = tr.pitch;
         const startPadding = tr.padding;
+        const startRotation = rollPitchBearingToQuat(tr.roll, tr.pitch, tr.bearing);
+        const endRoll = options.roll === undefined ? tr.roll : options.roll;
+        const endPitch = options.pitch === undefined ? tr.pitch : options.pitch;
+        const endBearing = options.bearing === undefined ? tr.bearing : options.bearing;
+        const endRotation = rollPitchBearingToQuat(endRoll, endPitch, endBearing);
 
         const optionsZoom = typeof options.zoom !== 'undefined';
 
@@ -149,11 +154,8 @@ export class MercatorCameraHelper implements ICameraHelper {
             if (isZooming) {
                 tr.setZoom(interpolates.number(startZoom, endZoom, k));
             }
-            if (startBearing !== options.bearing) {
-                tr.setBearing(interpolates.number(startBearing, options.bearing, k));
-            }
-            if (startPitch !== options.pitch) {
-                tr.setPitch(interpolates.number(startPitch, options.pitch, k));
+            if (!quat.equals(startRotation, endRotation)) {
+                updateRotation(startRotation, endRotation, {roll: endRoll, pitch: endPitch, bearing: endBearing}, tr, k);
             }
             if (doPadding) {
                 tr.interpolatePadding(startPadding, options.padding, k);
 
@@ -50,7 +50,7 @@ describe('transform', () => {
             0, 1, 0, 0,
             0, 0, 1, 0,
             0, 0, 0, 1], 6);
-        expect([...transform.modelViewProjectionMatrix.values()]).toEqual([3, 0, 0, 0, 0, -2.954423259036624, -0.1780177690666898, -0.17364817766693033, 0, 0.006822967915294533, -0.013222891287479163, -0.012898324631281611, -786432, 774484.3308168967, 47414.91102496082, 46270.827886319785]);
+        expect([...transform.modelViewProjectionMatrix.values()]).toEqual([3, 0, 0, 0, 0, -2.954423259036624, -0.1780177690666898, -0.17364817766693033, -0, 0.006822967915294533, -0.013222891287479163, -0.012898324631281611, -786432, 774484.3308168967, 47414.91102496082, 46270.827886319785]);
         expect(fixedLngLat(transform.screenPointToLocation(new Point(250, 250)))).toEqual({lng: 0, lat: 0});
         expect(fixedCoord(transform.screenPointToMercatorCoordinate(new Point(250, 250)))).toEqual({x: 0.5, y: 0.5, z: 0});
         expect(transform.locationToScreenPoint(new LngLat(0, 0))).toEqual({x: 250, y: 250});
@@ -83,6 +83,17 @@ describe('transform', () => {
         expect(fixedLngLat(transform.screenPointToLocation(new Point(15, 45)))).toEqual({lng: 13, lat: 10});
     });
 
+    test('setLocationAt tilted rolled', () => {
+        const transform = new MercatorTransform(0, 22, 0, 60, true);
+        transform.resize(500, 500);
+        transform.setZoom(4);
+        transform.setPitch(50);
+        transform.setRoll(50);
+        expect(transform.center).toEqual({lng: 0, lat: 0});
+        transform.setLocationAtPoint(new LngLat(13, 10), new Point(15, 45));
+        expect(fixedLngLat(transform.screenPointToLocation(new Point(15, 45)))).toEqual({lng: 13, lat: 10});
+    });
+
     test('has a default zoom', () => {
         const transform = new MercatorTransform(0, 22, 0, 60, true);
         transform.resize(500, 500);