Navigation viewport camera
Navigation viewport camera system is a set of APIs, that allow developers to combine full-screen navigation experiences with UI overlays and animate the map through changing location-related data. The viewport is defined by edge insets that allow the user to frame important features on the map in areas of the screen that don’t conflict with UI elements.
By default navigation viewport camera allows control of camera viewport system frames based on various properties, such as current location, some or all of the remaining route line coordinates, upcoming maneuvers, etc. It provides a camera viewport system, which is optimal for visualization and animation in navigation applications.
The navigation viewport camera is also customizable, it allows you to change certain camera-related options if the need arises.
Navigation viewport camera APIs are available both on iOS (when using NavigationMapView
or NavigationViewController
) and on CarPlay
(when using CarPlayMapViewController
or CarPlayNavigationViewController
).
How to use navigation viewport camera
Navigation viewport camera functionality is exposed via NavigationMapView.navigationCamera
property.
NavigationCamera
provides such APIs to control camera behavior:
NavigationCamera.follow(_:)
- transitions camera to theNavigationCameraState.following
state.NavigationCamera.moveToOverview(_:)
- transitions camera to theNavigationCameraState.overview
state.NavigationCamera.stop()
- movesNavigationCamera
toNavigationCameraState.idle
state at once and stops all pending transitions.
By default navigation viewport camera listens to the location updates, provided by the PassiveLocationManager
during free-drive navigation and by the RouteController
during active-guidance navigation.
It's also possible to listen to the raw location updates. To do this provide ViewportDataSourceType.raw
value in NavigationViewportDataSource.init(_:viewportDataSourceType:)
.
Default navigation viewport camera options
NavigationViewportDataSourceOptions
struct provides multiple ways of changing navigation viewport camera behavior. Here are some of them:
Bearing smoothing
Bearing smoothing allows control of how much the navigation camera bearing can deviate from the course of the location, in degrees. The navigation camera bearing will be affected by the course of the current location and the direction of the upcoming framed geometry. This allows to maximize the viewable area. This option is enabled by default.
To change bearing smoothing behavior you can use BearingSmoothing
struct.
For example, here's the viewable area when bearing smoothing is disabled:
Viewable area when bearing smoothing is enabled and BearingSmoothing.maximumBearingSmoothingAngle
is equal to 45.0
degrees:
This code snippet can be used to change default bearing smoothing on iOS:
if let navigationViewportDataSource = navigationViewController.navigationMapView?.navigationCamera.viewportDataSource as? NavigationViewportDataSource {
navigationViewportDataSource.options.followingCameraOptions.bearingSmoothing.maximumBearingSmoothingAngle = 30.0
}
Geometry framing after maneuver
Geometry framing after the maneuver option extends the view by appending additional coordinates after the upcoming maneuver. This option is enabled by default.
For example, here's the viewable area when the geometry framing after the maneuver option is disabled:
Viewable area when geometry framing after maneuver is enabled and GeometryFramingAfterManeuver.distanceToFrameAfterManeuver
is equal to 1000.0
meters:
This code snippet can be used to change geometry framing after the maneuver on iOS:
if let navigationViewportDataSource = navigationViewController.navigationMapView?.navigationCamera.viewportDataSource as? NavigationViewportDataSource {
navigationViewportDataSource.options.followingCameraOptions.geometryFramingAfterManeuver.distanceToCoalesceCompoundManeuvers = 160.0
navigationViewportDataSource.options.followingCameraOptions.geometryFramingAfterManeuver.distanceToFrameAfterManeuver = 110.0
}
Pitch near maneuver
Pitch near maneuver option allows to control whether CameraOptions.pitch
will update to 0.0
near upcoming maneuver. This option is enabled by default.
For example, here's viewable area when pitch near maneuver option is disabled:
Viewable area when pitch near maneuver is enabled and PitchNearManeuver.triggerDistanceToManeuver
is equal to 180.0
meters:
This code snippet can be used to change pitch near maneuver on iOS:
if let navigationViewportDataSource = navigationViewController.navigationMapView?.navigationCamera.viewportDataSource as? NavigationViewportDataSource {
navigationViewportDataSource.options.followingCameraOptions.pitchNearManeuver.triggerDistanceToManeuver = 200.0
}
Custom navigation viewport camera options
Navigation viewport camera provides the ability to use custom CameraOptions
parameters on iOS and CarPlay. To change such CameraOptions
on iOS use:
ViewportDataSource.followingMobileCamera
ViewportDataSource.overviewMobileCamera
On CarPlay use:
ViewportDataSource.followingCarPlayCamera
ViewportDataSource.overviewCarPlayCamera
If you'd like to provide custom CameraOptions
on CarPlay, consider such example:
if let navigationViewportDataSource = carPlayManager.navigationMapView?.navigationCamera.viewportDataSource as? NavigationViewportDataSource {
navigationViewportDataSource.options.followingCameraOptions.zoomUpdatesAllowed = false
navigationViewportDataSource.followingCarPlayCamera.zoom = 10.0
}
Example shown above allows to provide custom zoom level on iOS and CarPlay in free-drive navigation mode. To provide custom zoom level during active-guidance navigation, consider such example:
if let navigationViewportDataSource = carPlayManager.carPlayNavigationViewController?.navigationMapView?.navigationCamera.viewportDataSource as? NavigationViewportDataSource {
navigationViewportDataSource.options.followingCameraOptions.zoomUpdatesAllowed = false
navigationViewportDataSource.followingCarPlayCamera.zoom = 10.0
}
Make sure that CarPlayManager
and other dependent properties are valid at the time of CameraOptions
modification. If you are using free-drive navigation, do this check in the CPTemplateApplicationSceneDelegate.templateApplicationScene(_:didConnect:to:)
delegate method. Otherwise, CarPlayManager
and CarPlayNavigationViewController
should be valid within the CarPlayManagerDelegate.carPlayManager(_:didPresent:)
delegate method.
Custom navigation viewport camera
Navigation viewport camera provides the ability to fully override default camera behavior. To do this you can conform to CameraStateTransition
and ViewportDataSource
protocols to implement custom camera transitions and CameraOptions
data source, respectively.