[ios, macos] Added MGLMapCamera.viewingDistance property

Co-authored-by: Dave Prukop <dave.prukop@mapbox.com>

platform/darwin/src/MGLMapCamera.h

@@ -25,9 +25,27 @@ MGL_EXPORT
  */
 @property (nonatomic) CGFloat pitch;
 
-/** Meters above ground level. */
+/**
+ The altitude (measured in meters) above the map at which the camera is
+ situated.
+ 
+ The altitude is the distance from the viewpoint to the map, perpendicular to
+ the map plane. This property does not account for physical elevation.
+ 
+ This property’s value may be less than that of the `viewingDistance` property.
+ Setting this property automatically updates the `viewingDistance` property
+ based on the `pitch` property’s current value.
+ */
 @property (nonatomic) CLLocationDistance altitude;
 
+/**
+ The straight-line distance from the viewpoint to the `centerCoordinate`.
+ 
+ Setting this property automatically updates the `altitude` property based on
+ the `pitch` property’s current value.
+ */
+@property (nonatomic) CLLocationDistance viewingDistance;
+
 /** Returns a new camera with all properties set to 0. */
 + (instancetype)camera;
 

platform/darwin/src/MGLMapCamera.mm

@@ -131,6 +131,20 @@ BOOL MGLEqualFloatWithAccuracy(CGFloat left, CGFloat right, CGFloat accuracy)
                                                                heading:_heading];
 }
 
++ (NSSet<NSString *> *)keyPathsForValuesAffectingViewingDistance {
+    return [NSSet setWithObjects:@"altitude", @"pitch", nil];
+}
+
+- (CLLocationDistance)viewingDistance {
+    CLLocationDirection eyeAngle = 90 - self.pitch;
+    return self.altitude / sin(MGLRadiansFromDegrees(eyeAngle));
+}
+
+- (void)setViewingDistance:(CLLocationDistance)distance {
+    CLLocationDirection eyeAngle = 90 - self.pitch;
+    self.altitude = distance * sin(MGLRadiansFromDegrees(eyeAngle));
+}
+
 - (NSString *)description
 {
     return [NSString stringWithFormat:@"<%@: %p; centerCoordinate = %f, %f; altitude = %.0fm; heading = %.0f°; pitch = %.0f°>",

platform/darwin/test/MGLMapCameraTests.m

@@ -9,7 +9,7 @@
 
 @implementation MGLMapCameraTests
 
-- (void)testViewingDistance {
+- (void)testViewingDistanceInitialization {
     CLLocationCoordinate2D fountainSquare = CLLocationCoordinate2DMake(39.10152215, -84.5124439696089);
     MGLMapCamera *camera = [MGLMapCamera cameraLookingAtCenterCoordinate:fountainSquare
                                                           acrossDistance:10000
@@ -46,4 +46,22 @@
     XCTAssertEqual(camera.altitude, 10000, @"Tilted camera should use altitude verbatim.");
 }
 
+- (void)testViewingDistance {
+    MGLMapCamera *camera = [MGLMapCamera camera];
+    camera.altitude = 10000;
+    XCTAssertEqual(camera.altitude, 10000);
+    XCTAssertEqual(camera.viewingDistance, 10000);
+    camera.viewingDistance = 10000;
+    XCTAssertEqual(camera.altitude, 10000);
+    XCTAssertEqual(camera.viewingDistance, 10000);
+    
+    camera.pitch = 60;
+    camera.altitude = 10000;
+    XCTAssertEqual(camera.altitude, 10000);
+    XCTAssertEqualWithAccuracy(camera.viewingDistance, 20000, 0.01);
+    camera.viewingDistance = 10000;
+    XCTAssertEqualWithAccuracy(camera.altitude, 5000, 0.01);
+    XCTAssertEqual(camera.viewingDistance, 10000);
+}
+
 @end