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

# Camera position

The Mapbox Maps SDK for Android gives you complete control over the position of the map camera. The camera's location and behavior is defined by its properties:

-   **`center`**: The longitude and latitude at which the camera is pointed.
-   **`bearing`**: The visual rotation of the map. The bearing value is the compass direction the camera points to show the user which way is "up". For example, a bearing of 90° orients the map so that east is up.
-   **`pitch`**: The visual tilt of the map. A pitch of 0° is perpendicular to the surface, looking straight down at the map, while a greater value like 60° looks ahead towards the horizon.
-   **`zoom`**: The zoom level specifies how close the camera is to the features being viewed. At zoom level 0, the viewport shows continents and oceans. A middle value of 11 shows city-level details, and at a higher zoom level the map begins to show buildings and points of interest.
-   **`padding`**: Insets from each edge of the map. The padding value impacts the location at which the `center` point is rendered.
-   **`anchor`**: The point in the map's coordinate system around which `zoom` and `bearing` are applied. Mutually exclusive with `center`.

> **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.

Camera position interactive map is not available in this environment.

## Set camera position

The Maps SDK allows you to set the camera's position on map initialization, or after the map has already been initialized. You can also set the camera's position based on the user's location or fit the camera to a specific shape.

### Set camera on map initialization

You can configure many of your map's characteristics, including the starting camera position or the location of the compass on the screen, in your activity's layout file.

```xml
<com.mapbox.maps.MapView
  xmlns:android="http://schemas.android.com/apk/res/android"
  xmlns:tools="http://schemas.android.com/tools"
  xmlns:mapbox="http://schemas.android.com/apk/res-auto"
  android:id="@+id/mapView"
  android:layout_width="match_parent"
  android:layout_height="match_parent"
  mapbox:mapbox_cameraTargetLat="40.7128"
  mapbox:mapbox_cameraTargetLng="-74.0060"
  mapbox:mapbox_cameraZoom="9.0"
/>
```

When you add a map to your application programmatically instead of using XML, specify the camera position when you initialize the map by defining [`CameraOptions`](https://docs.mapbox.com/android/maps/api/latest/mapbox-maps-android/com.mapbox.maps/-camera-options/), passing those options to [`MapInitOptions`](https://docs.mapbox.com/android/maps/api/latest/mapbox-maps-android/com.mapbox.maps/-map-init-options/), and using those options when initializing the [`MapView`](https://docs.mapbox.com/android/maps/api/latest/mapbox-maps-android/com.mapbox.maps/-map-view/). This approach is best if you know what part of the world you want to show a user first. Since the SDK will load the tiles around the specified location first, the map may appear to load faster.

`CameraOptions` parameters are optional. For any parameters that aren't specified, the SDK will use the default value.

```kotlin
// set initial camera position
val initialCameraOptions = CameraOptions.Builder()
  .center(Point.fromLngLat(-74.0066, 40.7135))
  .pitch(45.0)
  .zoom(15.5)
  .bearing(-17.6)
  .build()

val mapInitOptions = MapInitOptions(
    context = this,
    mapOptions = mapOptions,
    plugins = plugins,
    cameraOptions = initialCameraOptions,
    textureView = true
  )
mapView = MapView(this, mapInitOptions)
```

![Extrude the building layer in the Mapbox Light style using FillExtrusionLayer and set up the light position.](https://docs.mapbox.com/android/ja/assets/ideal-img/maps-examples-fill-extrusion.0262054.480.png)

> **Note: Default camera position**
> 
> If you don't specify the camera position when the style is loaded, default values will be used. If the style being loaded has `center`, `bearing`, `pitch`, and `zoom` properties defined, the position will be determined by those values. If these properties are not defined in the style JSON, the map will be centered on the coordinates `0,0` with a `bearing` and `pitch` of `0` at `zoom` level `0`.

### Set after map initialization

In some cases you may want to set the camera's position *after* the map has been initialized based on an event or user interaction. For example, you may want to center the map camera on an annotation when a user clicks on it.

```kotlin
val pointAnnotationManager = mapView.annotations.createPointAnnotationManager().apply {
  // listen for click event
  addClickListener(
    OnPointAnnotationClickListener {
      // define camera position
      val cameraPosition = CameraOptions.Builder()
        .zoom(14.0)
        .center(it.point)
        .build()
      // set camera position
      mapView.mapboxMap.setCamera(cameraPosition)
      true
    }
  )
}
```

> **Related content (example): [Change camera position on map click](https://github.com/mapbox/mapbox-maps-android/blob/main/app/src/main/java/com/mapbox/maps/testapp/examples/globe/GlobeFlyToActivity.kt)**
> 
> After the map has been initialized, use `OnMapClickListener` to listen for a user action, then change the camera position using `flyTo`.

### Set camera for Jetpack Compose

With Jetpack Compose extension, you can set the camera with `MapViewportState`. You can set the initial value with `rememberMapViewportState` initialization block, and hoist the map viewport state to interact with camera later based on user interactions.

```kotlin
val mapViewportState = rememberMapViewportState {
  // set initial camera position
  setCameraOptions {
    center(Point.fromLngLat(-74.0066, 40.7135))
    pitch(45.0)
    zoom(15.5)
    bearing(-17.6)
  }
}
MapboxMap(
  modifier = Modifier.fillMaxSize(),
  mapViewportState = mapViewportState,
  onMapClickListener = { clickedPoint ->
    // listen for click event and ease to the clicked point
    mapViewportState.easeTo(
      cameraOptions {
        center(clickedPoint)
      }
    )
    true
  }
)
```

> **Related content (example): [(Compose) Map viewport animation](https://docs.mapbox.com/android/ja/maps/examples/compose/map-viewport-animation/)**
> 
> Showcase the camera animations based on `MapViewportState` API

### Set camera based on device location

You can set the camera based on the location of the device. Users must grant permission before an app can access information about their location. For more information about asking for the user's location, see the [User location](https://docs.mapbox.com/android/ja/maps/guides/user-location/) guide.

After the user has granted this permission, you can pass their location to the app and center the camera on it.

> **Related content (guide): [Use Viewport API to track location](https://docs.mapbox.com/android/ja/maps/guides/user-location/location-on-map/#location-tracking)**
> 
> Learn how to use high level `Viewport` API to track device location.

**Android View**

```kotlin

// Get the user's location as coordinates
private val onIndicatorBearingChangedListener = OnIndicatorBearingChangedListener {
  mapView.mapboxMap.setCamera(CameraOptions.Builder().bearing(it).build())
}

private val onIndicatorPositionChangedListener = OnIndicatorPositionChangedListener {
  mapView.mapboxMap.setCamera(CameraOptions.Builder().center(it).build())
  mapView.gestures.focalPoint = mapView.mapboxMap.pixelForCoordinate(it)
}
...

// Pass the user's location to camera
mapView.location.addOnIndicatorPositionChangedListener(onIndicatorPositionChangedListener)
mapView.location.addOnIndicatorBearingChangedListener(onIndicatorBearingChangedListener)
```

**Jetpack Compose**

```kotlin

val mapViewportState = rememberMapViewportState()
MapboxMap(
  modifier = Modifier.fillMaxSize(),
  mapViewportState = mapViewportState,
) {
  MapEffect(key1 = Unit) { mapView ->
    // Get the user's location as coordinates
    val onIndicatorBearingChangedListener = OnIndicatorBearingChangedListener {
      mapViewportState.setCameraOptions(CameraOptions.Builder().bearing(it).build())
    }

    val onIndicatorPositionChangedListener = OnIndicatorPositionChangedListener {
      mapViewportState.setCameraOptions(CameraOptions.Builder().center(it).build())
      mapView.gestures.focalPoint = mapView.mapboxMap.pixelForCoordinate(it)
    }
    mapView.location.apply {
      enabled = true
      addOnIndicatorBearingChangedListener(onIndicatorBearingChangedListener)
      addOnIndicatorPositionChangedListener(onIndicatorPositionChangedListener)
    }
  }
}
```

![Shows location puck on the map](https://docs.mapbox.com/android/ja/assets/ideal-img/maps-examples-location-component.0869b80.480.png)

> **Related content (example): [Location component](https://docs.mapbox.com/android/ja/maps/examples/android-view/location-component/)**
> 
> Shows location puck on the map

> **Related content (example): [(Compose) Location component](https://docs.mapbox.com/android/ja/maps/examples/compose/location-component/)**
> 
> Shows location puck on the map

You can also set the camera position to update as the user's location changes. For example, the map can stay centered on a user's location as they walk down the street.

![Display the user's location on a map with the default user location puck.](https://docs.mapbox.com/android/ja/assets/ideal-img/maps-examples-location-tracking.fb985b9.480.png)

> **Related content (example): [Display the user's location](https://docs.mapbox.com/android/ja/maps/guides/user-location/location-on-map/)**
> 
> Use `OnMoveListener` and `LocationComponentPlugin` to update the camera based on a user's location.

### Fit the camera to a given shape

You can position the camera to fit a specified shape within the viewport. [`MapboxMap`](https://docs.mapbox.com/android/maps/api/latest/mapbox-maps-android/com.mapbox.maps/-mapbox-map/) includes a convenience method [`cameraForCoordinates`](https://docs.mapbox.com/android/maps/api/latest/mapbox-maps-android/com.mapbox.maps/-mapbox-map/camera-for-coordinates.html?query=open%20override%20fun%20cameraForCoordinates(coordinates:%20List%3CPoint%3E,%20camera:%20CameraOptions,%20coordinatesPadding:%20EdgeInsets?,%20maxZoom:%20Double?,%20offset:%20ScreenCoordinate?):%20CameraOptions) to generate a [`CameraOptions`](https://docs.mapbox.com/android/maps/api/latest/mapbox-maps-android/com.mapbox.maps.dsl/camera-options.html) based on given coordinates or geometries.

This example uses `cameraForCoordinates` to set the camera view on the triangle defined in `triangleCoordinates`:

**Android View**

```kotlin
// Create a polygon
val triangleCoordinates = listOf(
  Point.fromLngLat(-3.363937, -10.733102),
  Point.fromLngLat(1.754703, -19.716317),
  Point.fromLngLat(-15.747196, -21.085074),
  Point.fromLngLat(-3.363937, -10.733102)
)
// Convert to a camera options from given coordinates and padding
mapboxMap.cameraForCoordinates(
  coordinates = triangleCoordinates,
  camera = cameraOptions { },
  coordinatesPadding = EdgeInsets(50.0, 50.0, 50.0, 50.0),
  maxZoom = null,
  offset = null
  ) { cameraPosition ->
    // Set camera position
    mapboxMap.setCamera(cameraPosition)
  }
```

**Jetpack Compose**

```kotlin

val mapViewportState = rememberMapViewportState()
MapboxMap(
  modifier = Modifier.fillMaxSize(),
  mapViewportState = mapViewportState,
  mapState = mapState
) {
  MapEffect(key1 = Unit) { mapView ->
    // Create a polygon
    val triangleCoordinates = listOf(
      listOf(
        Point.fromLngLat(-3.363937, -10.733102),
        Point.fromLngLat(1.754703, -19.716317),
        Point.fromLngLat(-15.747196, -21.085074),
        Point.fromLngLat(-3.363937, -10.733102)
      )
    )
    val polygon = Polygon.fromLngLats(triangleCoordinates)
    // Convert to a camera options from a given geometry and padding
    val cameraPosition = mapView.mapboxMap.awaitCameraForCoordinates(
      polygon.coordinates().flatten(),
      cameraOptions { },
      EdgeInsets(1.0, 1.0, 1.0, 1.0)
    )
    // Set camera position
    mapViewportState.setCameraOptions(cameraPosition)
  }
}
```

> **Related content (example): [Fit the camera to a set of coordinates](https://github.com/mapbox/mapbox-maps-android/blob/main/app/src/main/java/com/mapbox/maps/testapp/examples/linesandpolygons/MovingIconWithTrailingLineActivity.kt)**
> 
> Use `cameraForCoordinates` to set the camera view to the specified coordinates.

## Listen for camera changes

The Maps SDK provides camera change callbacks that can tell you whether any camera change events have happened. The SDK gives different camera listeners to determine if the camera change event was caused by a user gesture, built-in API animations, or a developer-controlled movement.

**Android View**

```kotlin

val callback = CameraChangedCallback { cameraChanged ->
  // Do something when the camera position changes
}

// Subscribe the camera changed event
val cancelable = mapboxMap.subscribeCameraChanged(callback)

// To cancel the subscription
cancelable.cancel()

// Note that the subscription will be automatically canceled when the map is destroyed.
```

**Jetpack Compose**

```kotlin

val coroutineScope = rememberCoroutineScope()
val mapState = rememberMapState {
  // Subscribe the camera changed event
  val job = coroutineScope.launch {
    cameraChangedEvents.collect { cameraChanged ->
      // Do something when the camera position changes
    }
  }
  // To cancel the subscription
  job.cancel()
}
MapboxMap(
  modifier = Modifier.fillMaxSize(),
  mapState = mapState
)
```

> **Related content (example): [Listen for camera changes to update an inset map](https://docs.mapbox.com/android/ja/maps/examples/android-view/inset-map/)**
> 
> This example shows an inset map on a larger map and uses `OnCameraChangeListener` to listen for camera changes on the keep the two map's cameras in sync.

## Get camera position

Once the map has been initialized, you can retrieve the camera's position to understand what the user is viewing, and other camera-related information, using the [`CameraState`](https://docs.mapbox.com/android/maps/api/latest/mapbox-maps-android/com.mapbox.maps/-camera-state/) property.

For example, you could display the longitude and latitude of the center point of the map as text:

**Android View**

```kotlin

// Get the cameraState.center
val center = mapView.mapboxMap.cameraState.center
```

**Jetpack Compose**

```kotlin

val mapViewportState = rememberMapViewportState()
MapboxMap(
  modifier = Modifier.fillMaxSize(),
  mapViewportState = mapViewportState,
  onMapClickListener = {
    // Get the cameraState.center
    val center = mapViewportState.cameraState.center
    false
  }
)
```

## Restrict camera

Use `MapboxMap`'s [`setBounds`](https://docs.mapbox.com/android/maps/api/latest/mapbox-maps-android/com.mapbox.maps/-mapbox-map/set-bounds.html?query=open%20override%20fun%20setBounds(options:%20CameraBoundsOptions):%20Expected%3CString,%20None%3E) function to restrict a user's panning to limit the map camera to a chosen area.

For example, you could create a location-specific app experience in which a user's panning behavior is limited to a specific country, like Iceland.

**Android View**

```kotlin

// Define camera bounds
private val cameraBoundsOptions = CameraBoundsOptions.Builder()
  .bounds(
    CoordinateBounds(
      Point.fromLngLat(-122.66336, 37.492987),
      Point.fromLngLat(-122.250481, 37.87165),
      false
    )
  )
  .minZoom(10.0)
  .build()
// Fit camera to the bounding box
mapboxMap.setBounds(cameraBoundsOptions)
```

**Jetpack Compose**

```kotlin

val mapViewportState = rememberMapViewportState()
MapboxMap(
  modifier = Modifier.fillMaxSize(),
  mapViewportState = mapViewportState,
) {
  MapEffect(key1 = Unit) { mapView ->
    // Define camera bounds
    val cameraBoundsOptions = CameraBoundsOptions.Builder()
      .bounds(
        CoordinateBounds(
          Point.fromLngLat(-122.66336, 37.492987),
          Point.fromLngLat(-122.250481, 37.87165),
          false
        )
      )
      .minZoom(10.0)
      .build()
    // Fit camera to the bounding box
    mapView.mapboxMap.setBounds(cameraBoundsOptions)
  }
}
```

> **Related content (example): [Restrict the camera to a specific location](https://docs.mapbox.com/android/ja/maps/examples/android-view/restrict-map-panning/)**
> 
> Use `mapboxMap.setBounds` to set the camera view and restrict user gestures to fit a specified bounding box around Iceland.