Navigation camera viewport API. (#2826)

Author: MaximAlien

CHANGELOG.md

@@ -39,6 +39,14 @@
 * Improved performance and decreased memory usage when downloading routing tiles. ([#2808](https://github.com/mapbox/mapbox-navigation-ios/pull/2808))
 * Renamed `PassiveLocationManager.startUpdatingLocation(completionHandler:)` to `PassiveLocationManager.startUpdatingLocation()`. This method now runs synchronously like `CLLocationManager.startUpdatingLocation()`. ([#2823](https://github.com/mapbox/mapbox-navigation-ios/pull/2823))
 
+### Camera
+
+* Added Navigation Viewport Camera APIs, which allow to control camera viewport system frames based on various properties, such as: current location, some or all of the remaining route line coordinates, upcoming maneuvers etc. This allows to provide a camera viewport system, which is optimal for visualization and animation in navigation applications. ([#2826](https://github.com/mapbox/mapbox-navigation-ios/pull/2826))
+* Removed `CarPlayNavigationViewController.tracksUserCourse`, `NavigationMapView.defaultAltitude`, `NavigationMapView.zoomedOutMotorwayAltitude`, `NavigationMapView.longManeuverDistance`, `NavigationMapView.showsUserLocation`, `NavigationMapView.tracksUserCourse`, `NavigationMapView.enableFrameByFrameCourseViewTracking(for:)`, `NavigationMapView.updateCourseTracking(location:camera:animated:)` `NavigationMapView.defaultPadding`, `NavigationMapView.setOverheadCameraView(from:along:for:)`, `NavigationMapView.recenterMap()`, `NavigationMapViewDelegate.navigationMapViewUserAnchorPoint(_:)`, `NavigationMapViewCourseTrackingDelegate`, `NavigationViewController.pendingCamera` in favor of new Navigation Viewport Camera APIs. ([#2826](https://github.com/mapbox/mapbox-navigation-ios/pull/2826))
+* Replaced `CourseUpdatable.update(location:pitch:direction:animated:tracksUserCourse:)` with `CourseUpdatable.update(location:pitch:direction:animated:navigationCameraState:)` to provide more agile way of handling `NavigationCameraState`. ([#2826](https://github.com/mapbox/mapbox-navigation-ios/pull/2826))
+* Added `NavigationMapView.init(frame:navigationCameraType:)` to be able to provide type of `NavigationCamera`, which should be used for that specific instance of `NavigationMapView` (either iOS or CarPlay). ([#2826](https://github.com/mapbox/mapbox-navigation-ios/pull/2826))
+* Added `NavigationCamera`, `ViewportDataSourceType`, `ViewportDataSourceDelegate`, `NavigationCameraState` Navigation Viewport Camera APIs. By default Navigation SDK for iOS provides default camera behavior via `NavigationViewportDataSource` and `NavigationCameraStateTransition` classes. If you'd like to override current behavior use `ViewportDataSource` and `CameraStateTransition` protocols for custom behavior. ([#2826](https://github.com/mapbox/mapbox-navigation-ios/pull/2826))
+
 ### CarPlay
 
 * Removed deprecated `CarPlayNavigationDelegate.carPlayNavigationViewControllerDidArrive(_:)`. ([#2808](https://github.com/mapbox/mapbox-navigation-ios/pull/2808))

Example/AppDelegate+CarPlay.swift

@@ -57,7 +57,7 @@ extension AppDelegate: CarPlayManagerDelegate {
 
     // MARK: CarPlayManagerDelegate
     func carPlayManager(_ carPlayManager: CarPlayManager, didBeginNavigationWith service: NavigationService) {
-        currentAppRootViewController?.beginNavigationWithCarplay(navigationService: service)
+        currentAppRootViewController?.beginNavigationWithCarPlay(navigationService: service)
         carPlayManager.currentNavigator?.compassView.isHidden = false
 
         // Render part of the route that has been traversed with full transparency, to give the illusion of a disappearing route.

Example/CustomViewController.swift

@@ -4,10 +4,16 @@ import MapboxNavigation
 import MapboxDirections
 import MapboxMaps
 
-// FIXME: Currently if `MapView` is created using storyboard crash occurs.
 class CustomViewController: UIViewController {
 
+    var destinationAnnotation: PointAnnotation! {
+        didSet {
+            navigationMapView.mapView.annotationManager.addAnnotation(destinationAnnotation)
+        }
+    }
+    
     var navigationService: NavigationService!
+    
     var simulateLocation = false
 
     var userIndexedRoute: IndexedRoute?
@@ -34,6 +40,7 @@ class CustomViewController: UIViewController {
         super.viewDidLoad()
 
         navigationMapView.mapView.style.styleURL = .custom(url: URL(string: "mapbox://styles/mapbox-map-design/ckd6dqf981hi71iqlyn3e896y")!)
+        navigationMapView.userCourseView.isHidden = false
 
         let locationManager = simulateLocation ? SimulatedLocationManager(route: userIndexedRoute!.0) : NavigationLocationManager()
         navigationService = MapboxNavigationService(route: userIndexedRoute!.0, routeIndex: userIndexedRoute!.1, routeOptions: userRouteOptions!, locationSource: locationManager, simulating: simulateLocation ? .always : .onPoorGPS)
@@ -51,13 +58,15 @@ class CustomViewController: UIViewController {
         // Start navigation
         navigationService.start()
 
-        // Center map on user
-        navigationMapView.recenterMap()
-        
         navigationMapView.mapView.on(.styleLoaded, handler: { [weak self] _ in
             guard let route = self?.navigationService.route else { return }
             self?.navigationMapView.show([route])
         })
+        
+        // By default `NavigationViewportDataSource` tracks location changes from `PassiveLocationDataSource`, to consume
+        // locations in active guidance navigation `ViewportDataSourceType` should be set to `.active`.
+        let navigationViewportDataSource = NavigationViewportDataSource(navigationMapView.mapView, viewportDataSourceType: .active)
+        navigationMapView.navigationCamera.viewportDataSource = navigationViewportDataSource
     }
 
     override func viewWillAppear(_ animated: Bool) {
@@ -101,8 +110,8 @@ class CustomViewController: UIViewController {
         instructionsBannerView.updateDistance(for: routeProgress.currentLegProgress.currentStepProgress)
         instructionsBannerView.isHidden = false
 
-        // Update the user puck
-        navigationMapView.updateCourseTracking(location: location, animated: true)
+        // Update `UserCourseView` to be placed on the most recent location.
+        navigationMapView.updateUserCourseView(location, animated: true)
     }
 
     @objc func updateInstructionsBanner(notification: NSNotification) {
@@ -122,7 +131,7 @@ class CustomViewController: UIViewController {
     }
 
     @IBAction func recenterMap(_ sender: Any) {
-        navigationMapView.recenterMap()
+        navigationMapView.navigationCamera.follow()
     }
 
     @IBAction func showFeedback(_ sender: Any) {
@@ -172,8 +181,7 @@ class CustomViewController: UIViewController {
         updatePreviewBannerWith(step: step, maneuverStep: maneuverStep)
 
         // stop tracking user, and move camera to step location
-        navigationMapView.tracksUserCourse = false
-        navigationMapView.enableFrameByFrameCourseViewTracking(for: 1)
+        navigationMapView.navigationCamera.stop()
         navigationMapView.mapView.cameraManager.setCamera(centerCoordinate: maneuverStep.maneuverLocation,
                                                           bearing: maneuverStep.initialHeading!,
                                                           animated: true)

Example/ViewController+FreeDrive.swift

@@ -10,9 +10,9 @@ import MapboxMaps
 
 extension ViewController {
 
-    func setupPassiveLocationManager(_ navigationMapView: NavigationMapView) {
+    func setupPassiveLocationManager() {
         setupFreeDriveStyledFeatures()
-        
+
         let passiveLocationDataSource = PassiveLocationDataSource()
         let passiveLocationManager = PassiveLocationManager(dataSource: passiveLocationDataSource)
         navigationMapView.mapView.locationManager.overrideLocationProvider(with: passiveLocationManager)
@@ -67,6 +67,12 @@ extension ViewController {
                                               color: .lightGray,
                                               lineWidth: 3.0,
                                               lineString: LineString([]))
+        
+        navigationMapView.mapView.on(.styleLoaded, handler: { [weak self] _ in
+            guard let self = self else { return }
+            self.addStyledFeature(self.trackStyledFeature)
+            self.addStyledFeature(self.rawTrackStyledFeature)
+        })
     }
 
     func updateFreeDriveStyledFeatures() {
@@ -116,7 +122,6 @@ extension ViewController {
             let branchNames = branchEdgeIdentifiers.flatMap { edgeNames(identifier: $0) }
             statusString += " at \(branchNames.joined(separator: ", "))"
         }
-        print(statusString)
     }
 
     func edgeNames(identifier: ElectronicHorizon.Edge.Identifier) -> [String] {

Example/ViewController+GuidanceCards.swift

@@ -19,8 +19,7 @@ extension ViewController: InstructionsCardCollectionDelegate {
         let maneuverStep = leg.steps[stepIndex + 1]
 
         // stop tracking user, and move camera to step location
-        navigationMapView.tracksUserCourse = false
-        navigationMapView.enableFrameByFrameCourseViewTracking(for: 1)
+        navigationMapView.navigationCamera.stop()
 
         let camera = CameraOptions(center: maneuverStep.maneuverLocation,
                                    zoom: navigationMapView.mapView.zoom,