All docsNavigation SDK for iOS v2GuidesNavigation viewport camera

Navigation viewport camera

Navigation viewport camera system is a set of APIs, which 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 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. It provides a camera viewport system, which is optimal for visualization and animation in navigation applications.

Navigation viewport camera is also customizable, it allows 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 the NavigationCameraState.following state.
  • NavigationCamera.moveToOverview(_:) - transitions camera to the NavigationCameraState.overview state.
  • NavigationCamera.stop() - immediately moves NavigationCamera to NavigationCameraState.idle state 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 to control how much the navigation camera bearing can deviate from the course of the location, in degrees. Navigation camera bearing will be affected not only by the course of the current location, but also by the direction to the upcoming framed geometry. This allows to maximize the viewable area. This option is enabled by default.

To modify bearing smoothing behavior you can use BearingSmoothing struct.

For example, here's viewable area when bearing smoothing is disabled:

Viewable area when bearing smoothing is enabled and BearingSmoothing.maximumBearingSmoothingAngle is equal to 45.0 degress:

This code snippet can be used to modify 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 maneuver option allows to extend the view by appending additional coordinates after upcoming maneuver. This option is enabled by default.

For example, here's viewable area when geometry framing after 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 modify geometry framing after 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 be set 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 modify 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 modify 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.followingMobileCamera.zoom = 10.0
    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.followingMobileCamera.zoom = 10.0
    navigationViewportDataSource.followingCarPlayCamera.zoom = 10.0
}

Make sure that CarPlayManager and other dependant properties are valid at the time of CameraOptions modification. In case of free-drive such modification can be performed in CPTemplateApplicationSceneDelegate.templateApplicationScene(_:didConnect:to:) delegate method. In case of active-guidance CarPlayManager and CarPlayNavigationViewController should be valid in CarPlayManagerDelegate.carPlayManager(_:didPresent:) delegate.

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.

Further resources