> For the complete documentation index, see [llms.txt](https://docs.mapbox.com/ios/ja/navigation/llms.txt)

# 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`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/navigationmapview/) or [`NavigationViewController`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationuikit/navigationviewcontroller/)) and on [`CarPlay`](https://docs.mapbox.com/ios/ja/navigation/guides/system-integration/carplay/) (when using [`CarPlayMapViewController`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationuikit/carplaymapviewcontroller/) or [`CarPlayNavigationViewController`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationuikit/carplaynavigationviewcontroller/)).

## How to use navigation viewport camera

Navigation viewport camera functionality is exposed via [`NavigationMapView.navigationCamera`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/navigationmapview/navigationcamera/) property.

[`NavigationCamera`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/navigationcamera/) provides such APIs to control camera behavior:

-   [`NavigationCamera.update(cameraState:)`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/navigationcamera/update(camerastate:)/) - transitions the camera to a different [state](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/navigationcamera/currentcamerastate/).
-   [`NavigationCamera.stop()`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/navigationcamera/stop()/) - moves the `NavigationCamera` to [`NavigationCameraState.idle`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/navigationcamerastate/idle/) state at once and stops all pending transitions.

By default navigation viewport camera listens to the location updates, provided by the `location` publisher, passed to the [initializer](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/navigationcamera/init(_:location:routeprogress:heading:navigationcameratype:viewportdatasource:camerastatetransition:)/), during free-drive navigation and active-guidance navigation.

## Default navigation viewport camera options

[`NavigationViewportDataSourceOptions`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/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`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/bearingsmoothing/) struct.

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

![Bearing smoothing in navigation camera is disabled.](https://docs.mapbox.com/ios/ja/assets/ideal-img/navigation-v3-camera-bearing-smoothing-disabled.583898b.480.png)

Viewable area when bearing smoothing is enabled and [`BearingSmoothing.maximumBearingSmoothingAngle`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/bearingsmoothing/maximumbearingsmoothingangle/) is equal to `45.0` degrees:

![Bearing smoothing in navigation camera is enabled.](https://docs.mapbox.com/ios/ja/assets/ideal-img/navigation-v3-camera-bearing-smoothing-enabled.000b785.480.png)

This code snippet can be used to change default bearing smoothing on iOS:

```swift
if let viewportDataSource = navigationViewController.navigationMapView?.navigationCamera.viewportDataSource as? MobileViewportDataSource {
    viewportDataSource.options.followingCameraOptions.bearingSmoothing.maximumBearingSmoothingAngle = 30.0
}
```

> **Related content (playground): [Location Helper](https://labs.mapbox.com/location-helper/)**
> 
> To experiment with camera pitch, bearing, tilt, and zoom and get values to use in your code, try our *Location Helper* tool.

### 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:

![Geometry framing after the maneuver in navigation camera is disabled.](https://docs.mapbox.com/ios/ja/assets/ideal-img/navigation-v3-camera-geometry-framing-after-maneuver-disabled.f908679.480.png)

Viewable area when geometry framing after the maneuver is enabled and [`GeometryFramingAfterManeuver.distanceToFrameAfterManeuver`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/followingcameraoptions/geometryframingaftermaneuver/) is equal to `1000.0` meters:

![Geometry framing after the maneuver in navigation camera is enabled.](https://docs.mapbox.com/ios/ja/assets/ideal-img/navigation-v3-camera-geometry-framing-after-maneuver-enabled.8f43bf6.480.png)

This code snippet can be used to change geometry framing after the maneuver on iOS:

```swift
if let viewportDataSource = navigationViewController.navigationMapView?.navigationCamera.viewportDataSource as? MobileViewportDataSource {
    viewportDataSource.options.followingCameraOptions.geometryFramingAfterManeuver.distanceToCoalesceCompoundManeuvers = 160.0
    viewportDataSource.options.followingCameraOptions.geometryFramingAfterManeuver.distanceToFrameAfterManeuver = 110.0
}
```

### Pitch near maneuver

Pitch near maneuver option allows to control whether [`CameraOptions.pitch`](https://docs.mapbox.com/ios/maps/api/latest/documentation/mapboxmaps/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:

![Pitch near maneuver in navigation camera is disabled.](https://docs.mapbox.com/ios/ja/assets/ideal-img/navigation-v3-camera-pitch-near-maneuver-disabled.cf6fb9a.480.png)

Viewable area when pitch near maneuver is enabled and [`PitchNearManeuver.triggerDistanceToManeuver`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/pitchnearmaneuver/triggerdistancetomaneuver/) is equal to `180.0` meters:

![Pitch near maneuver in navigation camera is enabled.](https://docs.mapbox.com/ios/ja/assets/ideal-img/navigation-v3-camera-pitch-near-maneuver-enabled.7cef142.480.png)

This code snippet can be used to change pitch near maneuver on iOS:

```swift
if let viewportDataSource = navigationViewController.navigationMapView?.navigationCamera.viewportDataSource as? MobileViewportDataSource {
    viewportDataSource.options.followingCameraOptions.pitchNearManeuver.triggerDistanceToManeuver = 200.0
}
```

## Custom navigation viewport camera options

Navigation viewport camera provides the ability to use custom [`CameraOptions`](https://docs.mapbox.com/ios/maps/api/latest/documentation/mapboxmaps/cameraoptions/) parameters on iOS and CarPlay. To change such `CameraOptions` use:

-   `ViewportDataSource.currentNavigationCameraOptions.followingCamera`
-   `ViewportDataSource.currentNavigationCameraOptions.overviewCamera`

### Mobile

To provide custom zoom level during active guidance navigation, consider such example:

```swift
if let viewportDataSource = navigationViewController.navigationMapView?.navigationCamera.viewportDataSource as? MobileViewportDataSource {
    viewportDataSource.options.followingCameraOptions.zoomUpdatesAllowed = false
    viewportDataSource.currentNavigationCameraOptions.followingCamera.zoom = 10.0
}
```

### CarPlay

If you create a map view for CarPlay, specify [`NavigationCameraType.carPlay`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/navigationcameratype/carplay/) while creating [`NavigationMapView`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/navigationmapview/init(location:routeprogress:navigationcameratype:heading:predictivecachemanager:)/):

```swift
let navigationMapView = NavigationMapView(
    location: mapboxNavigation.navigation()
        .locationMatching.map(\.mapMatchingResult.enhancedLocation)
        .eraseToAnyPublisher(),
    routeProgress: mapboxNavigation.navigation()
        .routeProgress.map(\.?.routeProgress)
        .eraseToAnyPublisher(),
    navigationCameraType: .carPlay,
    predictiveCacheManager: mapboxNavigationProvider.predictiveCacheManager
)
```

To provide custom zoom level during free drive navigation in CarPlay, configure viewport for `CarPlayManager`. Consider such example:

```swift
func templateApplicationScene(
    _ templateApplicationScene: CPTemplateApplicationScene,
    didConnect interfaceController: CPInterfaceController,
    to window: CPWindow
) {
    /// carPlayManager configuration
    /// ...
    carPlayManager.templateApplicationScene(
        templateApplicationScene,
        didConnectCarInterfaceController: interfaceController,
        to: window
    )

    if let viewportDataSource = carPlayManager.navigationMapView?.navigationCamera.viewportDataSource as? CarPlayViewportDataSource {
        viewportDataSource.options.followingCameraOptions.zoomUpdatesAllowed = false
        viewportDataSource.currentNavigationCameraOptions.followingCamera.zoom = 10.0
    }
}
```

To provide custom zoom level during active guidance navigation, configure viewport for `CarPlayNavigationViewController`:

```swift
func carPlayManager(
    _ carPlayManager: CarPlayManager,
    didPresent navigationViewController: CarPlayNavigationViewController
) {
    if let viewportDataSource = navigationViewController.navigationMapView?.navigationCamera.viewportDataSource as? CarPlayViewportDataSource {
        viewportDataSource.options.followingCameraOptions.zoomUpdatesAllowed = false
        viewportDataSource.currentNavigationCameraOptions.followingCamera.zoom = 10
    }
}
```

Make sure that [`CarPlayManager`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationuikit/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`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationuikit/carplaymanager/) and [`CarPlayNavigationViewController`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationuikit/carplaynavigationviewcontroller/) should be valid within the [`CarPlayManagerDelegate.carPlayManager(_:didPresent:)`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationuikit/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`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/camerastatetransition/) and [`ViewportDataSource`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/viewportdatasource/) protocols to implement custom camera transitions and [`CameraOptions`](https://docs.mapbox.com/ios/maps/api/latest/documentation/mapboxmaps/cameraoptions/) data source, respectively.

> **Related content (example): [Custom navigation camera](https://github.com/mapbox/mapbox-navigation-ios/blob/main/Examples/AdditionalExamples/Examples/Custom-Navigation-Camera.swift)**
> 
> Demonstrates how to add a custom data source and transition to the navigation camera.