Display a scene

Learn how to create and display a scene with a basemap layer and an elevation layer. Set properties of the scene's camera to control the 3D perspective.

Like a map, a scene contains layers of geographic data. It contains a basemap layer and, optionally, one or more data layers. To provide a realistic view of the terrain, you can also add elevation layers to define the height of the surface across the scene. The 3D perspective of the scene is controlled by the scene's camera, which defines the position of the scene observer in 3D space.

In this tutorial, you create and display a scene using the imagery basemap layer. The surface of the scene is defined with an elevation layer and the camera is positioned to display an area of the Santa Monica Mountains in the scene view.

The scene and code will be used as the starting point for other 3D tutorials.

Prerequisites

Before starting this tutorial:

You need an ArcGIS Location Platform or ArcGIS Online account.
Confirm that your system meets the system requirements.
An IDE for Android development in Kotlin.

Steps

Create a new Android Studio project

Use Android Studio to create an app and configure it to reference the API.

Open Android Studio.
- In the menu bar, click File > New > New Project....
- In the Create New Project window, make sure Phone and Tablet tab is selected, and then select Empty Activity. Click Next.
Gradle is the default build tool in Android Studio. If you are unable to use Gradle, see Getting the API Manually.
- In the Configure your project window, set the following configuration options:
  - Name: Display a scene.
  - Package name: Change to com.example.app. Or change to match your organization.
  - Save location: Set to a new folder.
  - Language: Kotlin
  - Minimum SDK: API 23: Android 6.0 (Marshmallow)
In the Project tool window, make sure that your current view is Android. These tutorial instructions refer to that view.

If your view name is something other than Android (such as Project or Packages), click on the leftmost control in the title bar of the Project tool window, and select Android from the list.

From the Project tool window, open Gradle Scripts > build.gradle (Project: Display_a_scene). Replace the contents of the file with the following code:

build.gradle (Project: Display_a_scene)
Use dark colors for code blocks
1
2
3
4
5
6
7
8
9
10
11
Change lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange line// Top-level build file where you can add configuration options common to all sub-projects/modules.

plugins {
    id 'com.android.application' version '7.2.1' apply false
    id 'com.android.library' version '7.2.1' apply false
    id 'org.jetbrains.kotlin.android' version '1.7.0' apply false
}

task clean(type: Delete) {
    delete rootProject.buildDir
}

From the Project tool window, open Gradle Scripts > build.gradle (Module: Display_a_scene.app). Replace the contents of the file with the following code:

build.gradle (Module: Display_a_scene.app)
Use dark colors for code blocks
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
Change lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineplugins {
    id 'com.android.application'
    id 'org.jetbrains.kotlin.android'
}

android {
    compileSdkVersion 32

    defaultConfig {
        applicationId "com.example.app"
        minSdkVersion 23
        targetSdkVersion 32
        versionCode 1
        versionName "1.0"
    }

    buildTypes {
        release {
            minifyEnabled false
            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
        }
    }

    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }

    kotlinOptions {
        jvmTarget = JavaVersion.VERSION_1_8.toString()
    }

    buildFeatures {
        viewBinding true
    }

    packagingOptions {
        exclude 'META-INF/DEPENDENCIES'
    }

}

dependencies {
    implementation fileTree(dir: "libs", include: ["*.jar"])
    implementation 'androidx.appcompat:appcompat:1.4.2'
    implementation 'androidx.constraintlayout:constraintlayout:2.1.4'
    implementation 'androidx.multidex:multidex:2.0.1'
    implementation 'com.google.android.material:material:1.6.1'

    implementation 'com.esri.arcgisruntime:arcgis-android:100.15.0'
}

From the Project tool window, open Gradle Scripts > settings.gradle. Replace the contents of the file with the following code:

settings.gradle (Display a map)
Use dark colors for code blocks
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
Change lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineimport org.gradle.api.initialization.resolve.RepositoriesMode

pluginManagement {
    repositories {
        gradlePluginPortal()
        google()
        mavenCentral()
    }
}
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()

        maven {
            url 'https://esri.jfrog.io/artifactory/arcgis'
        }
    }
}

rootProject.name = "Display a scene"

include ':app'

Sync the Gradle changes. Click the Sync now prompt or click the refresh icon (Sync Project with Gradle Files) in the toolbar. This may take several minutes.
From the Project tool window, open app > manifests > AndroidManifest.xml. Update the Android manifest to allow network access, and also to indicate the app uses OpenGL 2.0 or above.

Insert these new elements within the manifest element. Do not alter or remove any other statements.
Depending on what ArcGIS functionality you add in future tutorials, it is likely you will need to add additional permissions to your manifest.
AndroidManifest.xml
Expand
Use dark colors for code blocks
2 2 3 4 5 6 7 8 9 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10
Add line.Add line.Add line.Add line.
```
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    package="com.example.app">

    <uses-permission android:name="android.permission.INTERNET" />
    <uses-feature
        android:glEsVersion="0x00020000"
        android:required="true" />
```
Expand

Add import statements

Open app > java > com.example.app MainActivity.kt, and add import statements to reference the ArcGIS Runtime API.

MainActivity.kt
Use dark colors for code blocks
package com.example.app

import androidx.appcompat.app.AppCompatActivity
import android.os.Bundle

import com.esri.arcgisruntime.ArcGISRuntimeEnvironment
import com.esri.arcgisruntime.geometry.Point
import com.esri.arcgisruntime.geometry.SpatialReferences
import com.esri.arcgisruntime.mapping.ArcGISScene
import com.esri.arcgisruntime.mapping.ArcGISTiledElevationSource
import com.esri.arcgisruntime.mapping.BasemapStyle
import com.esri.arcgisruntime.mapping.Surface
import com.esri.arcgisruntime.mapping.view.Camera
import com.esri.arcgisruntime.mapping.view.SceneView

import com.example.app.databinding.ActivityMainBinding

Add a UI for the scene view

A scene view is a UI component that displays a scene. It also handles user interactions with the scene, including navigating with touch gestures. Use XML to add a scene view to the UI and make it available to the main activity source code.

In app > res > layout > activity_main.xml, replace the entire TextView element with a SceneView element.

If you do not see the XML code, select the Code tab to switch out of design mode and display the XML code in the editor.

Your SceneView element creates an instance of the SceneView class from the ArcGIS Runtime API for Android.

In your main activity source code, you can access the SceneView using an implicit property, which is declared in the value of the android:id attribute. In this case, the property will be named sceneView.

activity_main.xml
Use dark colors for code blocks
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
Change lineChange lineChange lineChange lineChange lineChange lineChange lineChange line<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".MainActivity">

    <com.esri.arcgisruntime.mapping.view.SceneView
        android:id="@+id/sceneView"
        android:layout_width="0dp"
        android:layout_height="0dp"
        app:layout_constraintBottom_toBottomOf="parent"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintTop_toTopOf="parent" />

</androidx.constraintlayout.widget.ConstraintLayout>

In MainActivity.kt, create a read-only local variable named activityMainBinding referencing the generated Android class ActivityMainBinding.

MainActivity.kt
Expand
Use dark colors for code blocks
34
34
34
34
34
34
34
34
34
34
34
34
34
34
34
34
34
34
34
34
34
34
34
34
34
34
34
34
34
34
34
34
34
34
35
36
37
38
39
40
40
40
40
39
39
39
39
39
39
38
37
36
35
35
35
34
33
32
31
30
29
28
27
26
25
24
23
22
21
20
19
18
17
16
15
14
13
12
11
10
9
8
7
6
5
4
3
2
1
0
-1
-2
-3
-4
-5
-6
-7
-8
-9
-10
-11
-11
Add line.Add line.Add line.class MainActivity : AppCompatActivity() {

    private val activityMainBinding: ActivityMainBinding by lazy {
        ActivityMainBinding.inflate(layoutInflater)
    }

Expand

Create a read-only variable named sceneView and bind it to the sceneView created in activity_main.xml.

MainActivity.kt
Expand
Use dark colors for code blocks
34
34
34
34
34
34
34
34
34
34
34
34
34
34
34
34
34
34
34
34
34
34
34
34
34
34
34
34
34
34
34
34
34
34
35
36
37
38
39
40
41
42
43
43
43
43
43
43
43
42
41
40
39
39
39
38
37
36
35
34
33
32
31
30
29
28
27
26
25
24
23
22
21
20
19
18
17
16
15
14
13
12
11
10
9
8
7
6
5
4
3
2
1
0
-1
-2
-3
-4
-5
-6
-7
-7
Add line.Add line.Add line.class MainActivity : AppCompatActivity() {

    private val activityMainBinding: ActivityMainBinding by lazy {
        ActivityMainBinding.inflate(layoutInflater)
    }

    private val sceneView: SceneView by lazy {
        activityMainBinding.sceneView
    }
Expand

Add a scene

Use the scene view to display a scene centered on the Santa Monica Mountains in California. The scene will contain a imagery basemap layer.

In MainActivity.kt, add a new setupScene() method in your MainActivity class and create an ArcGISScene with an imagery basemap.

MainActivity.kt
Expand
Use dark colors for code blocks
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
75
74
73
72
72
72
71
70
69
68
67
66
65
64
63
62
61
60
59
58
57
56
55
54
53
52
51
52
53
54
55
56
56
56
56
56
56
56
56
56
56
55
54
54
54
54
54
54
54
54
55
55
55
Add line.    // set up your scene here. You will call this method from onCreate()
    private fun setupScene() {

        val scene = ArcGISScene(BasemapStyle.ARCGIS_IMAGERY_STANDARD)

    }
Expand

Set the scene property of sceneView to the new ArcGISScene.

MainActivity.kt
Expand
Use dark colors for code blocks
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
75
74
73
72
72
72
71
70
69
68
67
66
65
64
63
62
61
60
59
58
57
56
55
54
53
52
51
52
53
54
55
56
57
58
59
59
59
59
59
59
59
58
57
57
57
57
57
57
57
57
58
58
58
Add line.Add line.    // set up your scene here. You will call this method from onCreate()
    private fun setupScene() {

        val scene = ArcGISScene(BasemapStyle.ARCGIS_IMAGERY_STANDARD)

        // set the scene on the scene view
        sceneView.scene = scene

    }
Expand

Create a new ArcGISTiledElevationSource and use it to create a new Surface. Then set the elevationExaggeration property on the surface to 2.5f to increase the 3D effect of the elevation.

MainActivity.kt
Expand
Use dark colors for code blocks
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
75
74
73
72
72
72
71
70
69
68
67
66
65
64
63
62
61
60
59
58
57
56
55
54
53
52
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
64
63
63
63
63
63
63
63
63
64
64
64
Add line.Add line.Add line.Add line.Add line.Add line.    // set up your scene here. You will call this method from onCreate()
    private fun setupScene() {

        val scene = ArcGISScene(BasemapStyle.ARCGIS_IMAGERY_STANDARD)

        // set the scene on the scene view
        sceneView.scene = scene

        // add base surface for elevation data
        val elevationSource = ArcGISTiledElevationSource("https://elevation3d.arcgis.com/arcgis/rest/services/WorldElevation3D/Terrain3D/ImageServer")
        val surface = Surface(listOf(elevationSource))
        // add an exaggeration factor to increase the 3D effect of the elevation.
        surface.elevationExaggeration = 2.5f

    }
Expand

Set the baseSurface property of the scene to the surface.

MainActivity.kt
Expand
Use dark colors for code blocks
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
75
74
73
72
72
72
71
70
69
68
67
66
65
64
63
62
61
60
59
58
57
56
55
54
53
52
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
67
67
67
67
67
67
67
68
68
68
Add line.    // set up your scene here. You will call this method from onCreate()
    private fun setupScene() {

        val scene = ArcGISScene(BasemapStyle.ARCGIS_IMAGERY_STANDARD)

        // set the scene on the scene view
        sceneView.scene = scene

        // add base surface for elevation data
        val elevationSource = ArcGISTiledElevationSource("https://elevation3d.arcgis.com/arcgis/rest/services/WorldElevation3D/Terrain3D/ImageServer")
        val surface = Surface(listOf(elevationSource))
        // add an exaggeration factor to increase the 3D effect of the elevation.
        surface.elevationExaggeration = 2.5f

        scene.baseSurface = surface

    }
Expand

Create a Point for the camera and assign it to cameraLocation. Then create a Camera, passing the cameraLocation and values for the camera's heading, pitch, and roll.

The position from which you view the scene is defined by a Camera. The following properties of the camera are used to define an observation point in the scene:

3D location: Latitude, longitude, and altitude
Heading: Azimuth of the camera's direction
Pitch: Up and down angle
Roll: Side-to-side angle

MainActivity.kt
Expand
Use dark colors for code blocks
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
75
74
73
72
72
72
71
70
69
68
67
66
65
64
63
62
61
60
59
58
57
56
55
54
53
52
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
72
72
73
73
73
Add line.Add line.Add line.Add line.Add line.    // set up your scene here. You will call this method from onCreate()
    private fun setupScene() {

        val scene = ArcGISScene(BasemapStyle.ARCGIS_IMAGERY_STANDARD)

        // set the scene on the scene view
        sceneView.scene = scene

        // add base surface for elevation data
        val elevationSource = ArcGISTiledElevationSource("https://elevation3d.arcgis.com/arcgis/rest/services/WorldElevation3D/Terrain3D/ImageServer")
        val surface = Surface(listOf(elevationSource))
        // add an exaggeration factor to increase the 3D effect of the elevation.
        surface.elevationExaggeration = 2.5f

        scene.baseSurface = surface

        // Point(x, y, z, spatialReference)
        val cameraLocation = Point(-118.794, 33.909, 5330.0, SpatialReferences.getWgs84())
        // Camera(location, heading, pitch, roll)
        val camera = Camera(cameraLocation, 355.0, 72.0, 0.0)

    }
Expand

Call setViewpointCamera() on the sceneView and pass in the camera.

MainActivity.kt
Expand
Use dark colors for code blocks
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
75
74
73
72
72
72
71
70
69
68
67
66
65
64
63
62
61
60
59
58
57
56
55
54
53
52
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
75
75
Add line.    // set up your scene here. You will call this method from onCreate()
    private fun setupScene() {

        val scene = ArcGISScene(BasemapStyle.ARCGIS_IMAGERY_STANDARD)

        // set the scene on the scene view
        sceneView.scene = scene

        // add base surface for elevation data
        val elevationSource = ArcGISTiledElevationSource("https://elevation3d.arcgis.com/arcgis/rest/services/WorldElevation3D/Terrain3D/ImageServer")
        val surface = Surface(listOf(elevationSource))
        // add an exaggeration factor to increase the 3D effect of the elevation.
        surface.elevationExaggeration = 2.5f

        scene.baseSurface = surface

        // Point(x, y, z, spatialReference)
        val cameraLocation = Point(-118.794, 33.909, 5330.0, SpatialReferences.getWgs84())
        // Camera(location, heading, pitch, roll)
        val camera = Camera(cameraLocation, 355.0, 72.0, 0.0)

        sceneView.setViewpointCamera(camera)

    }
Expand

In the onCreate() method, modify the setContentView() call to take activityMainBinding.root as its parameter. Next, call setupScene().

Android Studio's Create New Project wizard, which you used to create this project, usually passes the parameter R.layout.activity_main to the setContentView() call.

MainActivity.kt
Expand
Use dark colors for code blocks
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
45
46
47
48
49
49
49
50
51
52
52
51
50
49
48
47
46
45
44
43
42
41
40
39
38
37
36
35
34
33
32
31
31
31
31
31
31
31
31
31
31
31
31
31
31
31
31
31
31
31
31
31
31
31
31
31
31
31
Change lineAdd line.    override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    setContentView(activityMainBinding.root)

    setupScene()

    }
Expand

Override the Android life cycle methods onPause(), onResume(), and onDestroy() to pause, resume and dispose of the sceneView.

The sceneView needs to know when your app goes to the background or is restored from background in order to properly manage the view. When the view is no longer needed, its resources should be released by calling dispose() on sceneView.
You can place these methods anywhere inside your MainActivity class definition.
MainActivity.kt
Expand
Use dark colors for code blocks
55 55 55 55 55 55 55 55 55 55 55 55 55 55 55 55 55 55 55 55 55 55 55 55 55 55 55 55 55 55 55 55 55 55 55 55 55 55 55 55 55 55 55 55 55 55 55 55 55 54 53 53 53 53 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 67 66 65 64 63 62 61 61 61 61 61 61 61 61 61 61 61 61 61 61 61 61 61 61 61 61 61 61 61 61 61 61 61
Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.
```
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
    override fun onPause() {
        sceneView.pause()
        super.onPause()
    }

    override fun onResume() {
        super.onResume()
        sceneView.resume()
    }

    override fun onDestroy() {
        sceneView.dispose()
        super.onDestroy()
    }
```
Expand

Get an access token

You need an access token to use the location services used in this tutorial.

Go to the Create an API key tutorial to obtain an access token.
Ensure that the following privilege is enabled: Location services > Basemaps > Basemap styles service.
Copy the access token as it will be used in the next step.

To learn more about other ways to get an access token, go to Types of authentication.

Set your API key

Create the setApiKeyForApp() method, in which you set the apiKey property on the ArcGISRuntimeEnvironment using the access token. Paste your access token inside the quotes, replacing YOUR_ACCESS_TOKEN.

MainActivity.kt
Expand
Use dark colors for code blocks
65
65
65
65
65
65
65
65
65
65
65
65
65
65
65
65
65
65
65
65
65
65
65
65
65
65
65
65
65
65
65
65
65
65
65
65
65
65
65
65
65
65
65
65
65
65
65
65
65
64
63
63
63
63
63
63
63
63
63
63
63
63
63
63
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
Add line.Add line.Add line.Add line.Add line.    override fun onDestroy() {
        sceneView.dispose()
        super.onDestroy()
    }

    private fun setApiKeyForApp(){

        ArcGISRuntimeEnvironment.setApiKey("YOUR_ACCESS_TOKEN")

    }

    // set up your scene here. You will call this method from onCreate()
    private fun setupScene() {

        val scene = ArcGISScene(BasemapStyle.ARCGIS_IMAGERY_STANDARD)
Expand

In onCreate(), call setAPIKeyForApp().

MainActivity.kt
Expand
Use dark colors for code blocks
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
45
46
47
48
49
50
51
52
53
54
54
54
54
54
54
54
54
54
54
54
54
54
54
54
54
54
54
54
54
54
54
54
54
54
54
54
54
54
54
54
54
54
54
54
54
54
54
54
54
54
54
54
54
54
54
54
54
54
Add line.    override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    setContentView(activityMainBinding.root)

    setApiKeyForApp()

    setupScene()

    }
Expand

Click Run > Run > app to run the app.

The Android Emulator should display and run your app in the Android Virtual Devcie (AVD) selected in the Android Studio toolbar:

If your app builds but no AVD displays, you need to add one. Click Tools > AVD Manager > Create Virtual Device...

You should see a scene with the imagery basemap layer centered on the Santa Monica Mountains in California. Pinch, drag, and double-tap the scene view to explore the scene.

What's next?

Learn how to use additional API features, ArcGIS location services, and ArcGIS tools in these tutorials: