Allow to use map SDK location layer during turn-by-turn navigation

[ShanMa1991]

Description

This pr is to allow developer choose between UserCourseView and map SDK location layer.

• allow the developer to use map SDK
• allow the map puck receiving location update
• allow the map puck receiving heading update
• update the vanishing route line synced with the map sdk puck.
• allow the customized Puck update orientation under PassiveLocationManager
• Fix UserPuckCourseView should be subclassable #3033. update the UserHaloCourseView and UserPuckCourseView to open access and subclassable.

Implementation

Added the ability to allow developers choose between NavigationMapView.userCourseView and map SDK location layer through the NavigationMapView.puckType . The default puck is the NavigationMapView.userCourseView. To configure a customized 2D Puck as following :

        var configuration = Puck2DConfiguration()
        if #available(iOS 13.0, *) {
            configuration.topImage = UIImage(systemName: "arrow.up")
            configuration.scale = .constant(2.0)
        }

To configure a customized 3D Puck as following:

        let uri = Bundle.main.url(forResource: "someModelFile", withExtension: "gltf")
        let myModel = Model(uri: uri,
                            position: [-122.396152, 37.79129], // Coordinates of the model in `[longitude, latitude]`format
                            orientation: [0, 0, 90])
        let scalingExpression = someExpression // Setting an expression to  scale the model based on camera zoom
        let configuration = Puck3DConfiguration(model: myModel, modelScale: .expression(scalingExpression))

To display the puck on NavigationMapView, use navigationMapView.puckType = .puck3D(configuration: configuration).
To display the puck during turn-by-turn navigation, use navigationViewController.navigationMapView.puckType = .puck3D(configuration: configuration)

To allow the puck rotate under PassiveLocationManager, developers need to receive Notification.passiveLocationDataSourceDidUpdate and call the navigationMapView.updateUserCourseView(location) when there's a new location to adjust the rotation of the customized puck.

Screenshots or Gifs

2D customized puck example during turn-by-turn navigation:

3D customized puck example during turn-by-turn navigation:

3D customized puck example under PassiveLocationManager:

[ShanMa1991]

When we call the mapView.location.locationProvider(_:didUpdateLocations:), it will automatically assign the latestLocation.heading to the puck. And the SimulatedLocationManager doesn't have a function to update a simulated CLHeading.

[ShanMa1991]

Instead of creating a routeLine as a LocationConsumer to receive location update, the vanishing route line in navigationMapView also need routeProgress to calculate the fractionTraveled. So it keeps synced with the map SDK puck at the same rate. The map SDK puck also avoids receiving location update directly from the default AppleLocationProvider(), especially during simulation mode or PassiveLocationManager.

[ShanMa1991]

Now the camera is shaking stronger than #2998, when in simulation mode during turn-by-turn navigation, the camera should only receive the routeProgress for the location Update

[zugaldia]

Per team chat, we've decided that #2998 is not blocking this PR to land. However, we expect a fix from upstream dependencies ahead of the final v2 release. We will be using #2998 to track that work.

[ShanMa1991]

Because right now the mapSDK doesn't support the puck layer bearing rotation based on course but on heading. Now when the CLHeading is missing from the Location information, the mapSDK puck would not rotate and will always point to one side.

To handle this issue, the following cases are considered:

1. During free drive, we're using PassiveLocationManager, and call the navigationMapView.updateUserCourseView(location) to receive location update from NotificationCenter. instead of from the mapView.location.locationProvider.
2. During the turn-by-turn navigation. If it's under simulation mode, the mapSDK puck will only be updated from navigationMapView.updateUserCourseView, to avoid the influence of the mapView.location.locationProvider, which may cause the shifting of puck location and bearing, we stop the location update from it.
3. During turn-by-turn navigation. If it's not under simulation mode, we only receive location update to update the puck from the mapView.location.locationProvider, using the snapped location to indicate the true location and true heading.

[1ec5]

Is it possible to use Model more directly, rather than serializing to JSON?

[ShanMa1991]

Because the source type of the 3D puck layer isModelSource, which is internal and could not be updated directly.

[1ec5]

ModelSource became internal in mapbox/mapbox-maps-ios#198. I don’t see any rationale associated with it, so it might have been just for lack of external demand. ModelSource would be more type-safe and forward-compatible than raw JSON usage. Since this is how the map SDK currently requires you to use the models property, let’s track ModelSource usage as tail work and also request an upstream change.

/cc @macdrevx

[MaximAlien]

This is basically a duplicate of code in .default case (other than newFractionTraveled and fractionTraveled properties usage). Can it be extracted into separate method?

[ShanMa1991]

Thanks for the suggestion, I'll update the implementation of the vanishing route line.

[ShanMa1991]

Due to the comment below, the vanishing route line method now is still using the Timer incase of overwhelming calculation.

[ShanMa1991]

After test, the another constraint that block using the frame to update vanishing route line is based on the following reason.

1. For example, we could implement the following way in the RouteLineController.init(_:) to replace the Timer:

        init(_ navigationViewData: NavigationViewData) {
            self.navigationViewData = navigationViewData
            routeProgress = navigationViewData.router.routeProgress
            let date = Date()
            self.navigationMapView.mapView.mapboxMap.onEvery(.renderFrameFinished) { [weak self] _ in
                print("timeInterval:\(abs(date.timeIntervalSinceNow))")
                guard let self = self,
                      let location = self.navigationMapView.mostRecentUserCourseViewLocation else { return }
                self.navigationMapView.updateUserCourseView(location)
                self.navigationMapView.updateTraveledRouteLine(location.coordinate)
                self.navigationMapView.updateRoute(self.routeProgress)
            }
        }

During the turn by turn navigation, if we zoom pretty close, and we have a following log of the time interval of the render frame finished:

timeInterval:6.394365072250366
timeInterval:6.417618036270142
timeInterval:6.426851034164429
timeInterval:6.450319051742554
//That's a long time interval where the frame will not be updated
timeInterval:19.978631019592285
timeInterval:19.996222019195557
timeInterval:20.01080596446991
timeInterval:20.027930974960327
timeInterval:20.043519020080566
timeInterval:20.059892058372498
timeInterval:20.076043009757996

That means that when we zoom pretty close and the route line would not be updated because the frame will not keep rendering update. There would show a tail of the route line behind the puck.

2. And another way to replace the Timer is to use location Indicator callback similar as in Android(though we don't have it right now). But the current constraint is that the rotation of the mapSDK puck is only based on heading, not course. When in simulation mode, or other circumstances, the puck would always point to one side. To fix this issue, in this pr, we stop receiving the location update from mapView.locationProvider in these cases to update the puck, and use the navigationMapView.updateUserCourseView(_:animated:) to update the puck layer and source properties directly as a workaround for the course based rotation. Only after mapSDK could allow the puck rotation based on course, we could allow the puck receive location update from the locationProvider in these cases. And then we could use the locationConsumer of other way to update the vanishing route line.

So based on the above reasons, the tail work of replacing the Timer of vanishing route line would be resolved and addressed in another separate ticket with the render frame rate improvement, or the rotation improvement.

[1ec5]

ModelSource became internal in mapbox/mapbox-maps-ios#198. I don’t see any rationale associated with it, so it might have been just for lack of external demand. ModelSource would be more type-safe and forward-compatible than raw JSON usage. Since this is how the map SDK currently requires you to use the models property, let’s track ModelSource usage as tail work and also request an upstream change.

/cc @macdrevx

[ShanMa1991]

The tail work of the vanishing route line implementation will be addressed in #3069 separately.

[1ec5]

Overall, I’m concerned about special-casing specific location managers/providers to achieve the normal behavior, which could leave an application-defined location manager/provider with unexpected behavior despite conforming to the right protocols.

I’m approving this PR on the condition that simulatesLocation be based on a property of the location manager class (via the NavigationLocationManager class and any necessary overrides), as discussed in #2968 (comment). I think that’s the minimum necessary to ensure that custom subclasses still work correctly. But we should investigate #2968 (comment) as tail work soon while there’s still time: having NavigationLocationManager conform to LocationProvider would be pretty elegant compared to the confusing and limiting PassiveLocationDataSource/PassiveLocationManager split we have now.