Skip to content

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.

display a scene

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:

  1. You need an ArcGIS Location Platform or ArcGIS Online account.

  2. Your system meets the system requirements.

  3. The ArcGIS Maps SDK for Qt, version 200.8.0 or later is installed.

  4. The Qt 6.8.2 software development framework or later is installed.

Set up authentication

To access the secure ArcGIS location services used in this tutorial, you must implement API key authentication or user authentication using an ArcGIS Location Platform or an ArcGIS Online account.

To complete this tutorial, click on the tab in the switcher below for your authentication type of choice, either API key authentication or User authentication.

Create a new API key access token with privileges to access the secure resources used in this tutorial.

  1. Complete the Create an API key tutorial and create an API key with the following privilege(s):

    • Privileges
      • Location services > Basemaps
  2. Copy and paste the API key access token into a safe location. It will be used in a later step.

Because this tutorial is the foundation (or starting point) for several other tutorials, you will want to follow one path for authentication (either API Key authentication or User authentication (via OAuth)) and use that same pattern for the other tutorials. If you wish to change authentication patterns as you move through the other tutorials you will want to complete this tutorial, Display a scene, again using the other authentication pattern.

Develop or Download

You have two options for completing this tutorial:

  1. Option 1: Develop the code or
  2. Option 2: Download the completed solution

Option 1: Develop the code

Create a new ArcGIS Maps Qt Creator Project

  1. Start Qt Creator.

  2. In the top menu bar, click File > New Project.

  3. In the New Project dialog, in the left frame, under Projects, select ArcGIS. Then select the ArcGIS Maps 200.8.0 Qt Quick C++ app project template (or a later version) and click Choose. This will launch the template wizard.

  4. In the Project Location template, name your project Display_a_scene. You can specify your own "create in" location for where the project will be created or leave the default. Click Next.

  5. In the Define Build System template, select qmake for your build system. Click Next.

  6. In the Define Project Details template, give this app a description or leave as is. Check ON the 3D project check box. At the ArcGIS Online Basemap dropdown menu, select Imagery. Accept the default value for the ArcGIS Online Elevation (WorldElevation3D) dropdown. Do not supply an API Key (also called an access token) at this time, leave it blank. You will do this in another step when you set your developer credentials. Click Next.

  7. In the Kit Selection template, check on the kit you previously set up when you installed Qt (Desktop Qt 6.8.2 MSVC2022 64bit or higher required). Click Next.

  8. In the Project Management template, the option to Add as a subproject to root project is only available if you have already created a root project. If you have a version control system set up, you can select it in the dropdown but it is not needed to complete this tutorial. Click Finish to complete the template wizard.

Display a scene

  1. In the project Headers folder of Qt Creator, double-click the file Display_a_scene.h to open it.

  2. Add the declaration void setupScene(); under private:. Then save the file.

    Display_a_scene.h
    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
    private:
        Esri::ArcGISRuntime::SceneQuickView* sceneView() const;
        void setSceneView(Esri::ArcGISRuntime::SceneQuickView* sceneView);
    
        Esri::ArcGISRuntime::Scene* m_scene = nullptr;
        Esri::ArcGISRuntime::SceneQuickView* m_sceneView = nullptr;
    
        void setupScene();
    
    };
    
    #endif // DISPLAY_A_SCENE_H
  3. In the project Sources folder of Qt Creator, open the Display_a_scene.cpp file. This app will use a Camera object to display the scene. Add the following #include statement.

    Display_a_scene.cpp
    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
    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
    103
    104
    105
    106
    107
    108
    109
    110
    111
    112
    113
    114
    115
    116
    117
    118
    119
    120
    121
    122
    123
    124
    125
    126
    127
    128
    #include "Display_a_scene.h"
    
    
    #include "ArcGISTiledElevationSource.h"
    
    #include "Camera.h"
    
    #include "ElevationSourceListModel.h"
    #include "MapTypes.h"
    
    #include "Scene.h"
    #include "SceneQuickView.h"
    
    #include "Surface.h"
    
    #include <QUrl>
    
  4. Add the following line of code in the Display_a_scene constructor to call to the new method, setupScene, that you will create.

    Display_a_scene.cpp
    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
    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
    103
    104
    105
    106
    107
    108
    109
    110
    111
    112
    113
    114
    115
    116
    117
    118
    119
    120
    121
    122
    123
    124
    125
    126
    127
    128
    Display_a_scene::Display_a_scene(QObject* parent /* = nullptr */):
    
        QObject(parent),
    
        m_scene(new Scene(BasemapStyle::ArcGISImagery, this))
    
    {
    
        // create a new elevation source from Terrain3D rest service
        ArcGISTiledElevationSource* elevationSource = new ArcGISTiledElevationSource(
                    QUrl("https://elevation3d.arcgis.com/arcgis/rest/services/WorldElevation3D/Terrain3D/ImageServer"), this);
    
        // add the elevation source to the scene to display elevation
        m_scene->baseSurface()->elevationSources()->append(elevationSource);
    
        setupScene();
    
    
    }
    
  5. Create a new method named setupScene, near the end of the file.

    Display_a_scene.cpp
    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
    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
    103
    104
    105
    106
    107
    108
    109
    110
    111
    112
    113
    114
    115
    116
    117
    118
    119
    120
    121
    122
    123
    124
    125
    126
    127
    128
    void Display_a_scene::setupScene()
    {
    
    }
  6. Within the setupScene() method, create an ElevationSource instance to define the base surface for the scene. An elevation source can define a surface with 3D terrain in a scene. Without an elevation source, the default globe surface is used to display the scene.

    Display_a_scene.cpp
    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
    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
    103
    104
    105
    106
    107
    108
    109
    110
    111
    112
    113
    114
    115
    116
    117
    118
    119
    120
    121
    122
    123
    124
    125
    126
    127
    128
    void Display_a_scene::setupScene()
    {
    
      ArcGISTiledElevationSource* elevationSource = new ArcGISTiledElevationSource(QUrl("https://elevation3d.arcgis.com/arcgis/rest/services/WorldElevation3D/Terrain3D/ImageServer"), this);
    
    }
  7. Continuing within the setupScene() method, create a Surface instance and append the elevationSource to it.

Display_a_scene.cpp
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
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
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
void Display_a_scene::setupScene()
{

  ArcGISTiledElevationSource* elevationSource = new ArcGISTiledElevationSource(QUrl("https://elevation3d.arcgis.com/arcgis/rest/services/WorldElevation3D/Terrain3D/ImageServer"), this);

  Surface* elevationSurface = new Surface(this);
  elevationSurface->elevationSources()->append(elevationSource);

}
  1. Concluding the code changes within the setupScene() method, set the ElevationExaggeration value (to improve elevation visibility), and then set the elevationSurface for m_scene.

    Display_a_scene.cpp
    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
    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
    103
    104
    105
    106
    107
    108
    109
    110
    111
    112
    113
    114
    115
    116
    117
    118
    119
    120
    121
    122
    123
    124
    125
    126
    127
    128
    void Display_a_scene::setupScene()
    {
    
      ArcGISTiledElevationSource* elevationSource = new ArcGISTiledElevationSource(QUrl("https://elevation3d.arcgis.com/arcgis/rest/services/WorldElevation3D/Terrain3D/ImageServer"), this);
    
      Surface* elevationSurface = new Surface(this);
      elevationSurface->elevationSources()->append(elevationSource);
    
      elevationSurface->setElevationExaggeration(2.5);
      m_scene->setBaseSurface(elevationSurface);
    
    }
  2. The next code change will be within the setSceneView(SceneQuickView* sceneView) function, to create a Camera with the given parameters.

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

    • latitude: The measurement of distance north or south of the Equator
    • longitude: The measurement east or west of the prime meridian
    • altitude: The distance above sea level
    • heading: Azimuth of the camera's direction
    • pitch: Up and down angle
    • roll: Side-to-side angle
    Display_a_scene.cpp
    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
    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
    103
    104
    105
    106
    107
    108
    109
    110
    111
    112
    113
    114
    115
    116
    117
    118
    119
    120
    121
    122
    123
    124
    125
    126
    127
    128
    // Set the view (created in QML)
    void Display_a_scene::setSceneView(SceneQuickView* sceneView)
    {
        if (!sceneView || sceneView == m_sceneView)
        {
            return;
        }
    
        m_sceneView = sceneView;
        m_sceneView->setArcGISScene(m_scene);
    
        constexpr double latitude = 33.909;
        constexpr double longitude = -118.805;
        constexpr double altitude = 5330.0;
        constexpr double heading = 355.0;
        constexpr double pitch = 72.0;
        constexpr double roll = 0.0;
        const Camera sceneCamera(latitude, longitude, altitude, heading, pitch, roll);
        m_sceneView->setViewpointCameraAndWait(sceneCamera);
    
        emit sceneViewChanged();
    }
    

Set developer credentials

To allow your app users to access ArcGIS location services, use the developer credentials that you created in the Set up authentication step to authenticate requests for resources.

For the final steps of this tutorial, click the tab below for either API key authentication or User authentication to use the correct authentication pattern to run the application.

Set the API Key

  1. In the project Sources folder of Qt Creator, open the main.cpp file.

  2. Modify the code to set the accessToken using your API key access token (highlighted in yellow).

    main.cpp
    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
    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
    103
    104
    105
    106
    107
    108
        // The following methods grant an access token:
    
        // 1. User authentication: Grants a temporary access token associated with a user's ArcGIS account.
        // To generate a token, a user logs in to the app with an ArcGIS account that is part of an
        // organization in ArcGIS Online or ArcGIS Enterprise.
    
        // 2. API key authentication: Get a long-lived access token that gives your application access to
        // ArcGIS location services. Go to the tutorial at https://links.esri.com/create-an-api-key.
        // Copy the API Key access token.
    
        const QString accessToken = QString("");
    
        if (accessToken.isEmpty())
        {
            qWarning() << "Use of ArcGIS location services, such as the basemap styles service, requires" <<
                          "you to authenticate with an ArcGIS account or set the API Key property.";
        }
        else
        {
            ArcGISRuntimeEnvironment::setApiKey(accessToken);
        }
    
  3. Save the main.cpp file.

Best Practice: The access token is stored directly in the code as a convenience for this tutorial. Do not store credentials directly in source code in a production environment.

Press Ctrl + R to run the app.

You should see a scene with the topographic basemap layer centered on the Santa Monica Mountains in California. Double-click, drag, and scroll the mouse wheel over the scene view to explore the scene.

Alternatively, you can download the tutorial solution, as follows.

Option 2: Download the solution

  1. Click the Download solution link under Solution and unzip the file to a location on your machine.

  2. Open the .pro project file in Qt Creator.

Since the downloaded solution does not contain authentication credentials, you must add the developer credentials that you created in the Set up authentication section.

Set developer credentials in the solution

Set the API Key

To allow your app users to access ArcGIS location services, use your API key access token that you created in the Set up authentication section to authenticate requests for resources.

  1. In the project Sources folder of Qt Creator, open the main.cpp file.

  2. Modify the code to set the accessToken using your API key access token (highlighted in yellow).

    main.cpp
    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
    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
    103
    104
    105
    106
    107
    108
        // The following methods grant an access token:
    
        // 1. User authentication: Grants a temporary access token associated with a user's ArcGIS account.
        // To generate a token, a user logs in to the app with an ArcGIS account that is part of an
        // organization in ArcGIS Online or ArcGIS Enterprise.
    
        // 2. API key authentication: Get a long-lived access token that gives your application access to
        // ArcGIS location services. Go to the tutorial at https://links.esri.com/create-an-api-key.
        // Copy the API Key access token.
    
        const QString accessToken = QString("");
    
        if (accessToken.isEmpty())
        {
            qWarning() << "Use of ArcGIS location services, such as the basemap styles service, requires" <<
                          "you to authenticate with an ArcGIS account or set the API Key property.";
        }
        else
        {
            ArcGISRuntimeEnvironment::setApiKey(accessToken);
        }
    
  3. Save main.cpp file.

Best Practice: The access token is stored directly in the code as a convenience for this tutorial. Do not store credentials directly in source code in a production environment.

Run the app

Press Ctrl + R to run the app.

You should see a scene with the topographic basemap layer centered on the Santa Monica Mountains in California. Double-click, drag, and scroll the mouse wheel over 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:

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.