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
The following are required for this tutorial:
An ArcGIS account to access API keys. If you don't have an account, sign up for free.
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.
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 26: Android 8.0 (O)
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:
1
2
3
4
5
6
7
8
9
10
11
// 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.10' 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:
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.
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.
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 Maps SDK for Kotlin.
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.
In MainActivity.kt, create a read-only lazy variable named activityMainBinding referencing the generated Android class ActivityMainBinding. This variable will be initialized with DataBindingUtil.setContentView(this, R.layout.activity_main) when called.
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.
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
// set up your scene here. You will call this method from onCreate()privatefunsetupScene() {
val scene = ArcGISScene(BasemapStyle.ArcGISImagery).apply {
// add base surface for elevation dataval elevationSource = ArcGISTiledElevationSource("https://elevation3d.arcgis.com/arcgis/rest/services/WorldElevation3D/Terrain3D/ImageServer")
val surface = Surface().apply {
elevationSources.add(elevationSource)
// add an exaggeration factor to increase the 3D effect of the elevation. elevationExaggeration = 2.5f }
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:
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
// set up your scene here. You will call this method from onCreate()privatefunsetupScene() {
val scene = ArcGISScene(BasemapStyle.ArcGISImagery).apply {
}
// set the scene on the scene view sceneView.scene = scene
}
Expand
In the onCreate() method, call lifecycle.addObserver(sceneView) to add the sceneView to the lifecycle scope. Then call setupScene(), which has been defined in the previous steps.
Creating a new Android Studio project for Kotlin or Java automatically uses setContentView(R.layout.activity_main). You can run the scene view from the activity_main layout, but this requires a separate extension in the gradle script.
An API Key enables access to services, web maps, and web scenes hosted in ArcGIS Online.
Go to your developer dashboard to get your API key.
For these tutorials, use your default API key. It is scoped to include all of the services demonstrated in the tutorials.
Create the setApiKey() method, where you will set the ArcGISEnvironment.apiKey property by calling ApiKey.create() and passing your API key as a string. Don't forget the quotes.
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
privatefunsetApiKey(){
// set your API key// Note: it is not best practice to store API keys in source code. The API key is referenced// here for the convenience of this tutorial. ArcGISEnvironment.apiKey = ApiKey.create("YOUR_API_KEY")
}
// set up your scene here. You will call this method from onCreate()privatefunsetupScene() {
val scene = ArcGISScene(BasemapStyle.ArcGISImagery).apply {
Call setApiKey() in the onCreate() lifecycle method, before the setupScene() call.
When you build and run an app in Android Studio, you must first select a device. From the Android Studio toolbar, you can access the drop-down list of your currently available devices, both virtual and physical.
.
If you cannot access the list on the toolbar, click Tools > Device Manager.
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.
