Tutorial: Change the base layer

Learn how to customize the CesiumJS base layer picker to display ArcGIS data provider options.

ArcGIS provides base layers for both imagery and terrain that you can use in your CesiumJS applications. You can use map tiles from the ArcGIS Basemap Styles service to create an ImageryProvider.

In this tutorial, you customize the BaseLayerPicker widget to display the different ArcGIS base layers available for imagery and terrain.

Prerequisites

Steps

Get the starter app

Select a type of authentication and follow the steps to create a new app.

Set up authentication

Set developer credentials

Get a Cesium ion access token

All Cesium applications must use an access token provided through Cesium ion. This token allows you to access assets such as Cesium World Terrain in your application.

1. Go to your Cesium ion dashboard to generate an access token. Copy the key to your clipboard.

2. Create a cesiumAccessToken variable and replace YOUR_CESIUM_ACCESS_TOKEN with the access token you copied from the Cesium ion dashboard.

   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
       <script>
   
       /* Use for API key authentication */
       const accessToken = "YOUR_ACCESS_TOKEN";
   
       // or
   
       /* Use for user authentication */
       // const session = await arcgisRest.ArcGISIdentityManager.beginOAuth2({
       //   clientId: "YOUR_CLIENT_ID", // Your client ID from OAuth credentials
       //   redirectUri: "YOUR_REDIRECT_URI", // The redirect URL registered in your OAuth credentials
       //   portal: "YOUR_PORTAL_URL" // Your portal URL
       // })
   
       // const accessToken = session.token;
   
       Cesium.ArcGisMapService.defaultAccessToken = accessToken;
   
       const cesiumAccessToken = "YOUR_CESIUM_ACCESS_TOKEN";
   
       </script>
   

3. Configure Cesium.Ion.defaultAccessToken with the Cesium access token to validate the application.

   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
       <script>
   
       /* Use for API key authentication */
       const accessToken = "YOUR_ACCESS_TOKEN";
   
       // or
   
       /* Use for user authentication */
       // const session = await arcgisRest.ArcGISIdentityManager.beginOAuth2({
       //   clientId: "YOUR_CLIENT_ID", // Your client ID from OAuth credentials
       //   redirectUri: "YOUR_REDIRECT_URI", // The redirect URL registered in your OAuth credentials
       //   portal: "YOUR_PORTAL_URL" // Your portal URL
       // })
   
       // const accessToken = session.token;
   
       Cesium.ArcGisMapService.defaultAccessToken = accessToken;
   
       const cesiumAccessToken = "YOUR_CESIUM_ACCESS_TOKEN";
   
       Cesium.Ion.defaultAccessToken = cesiumAccessToken;
   
       </script>
   

Update the camera position

1. Change the camera position to -122.4106, 37.7908, 200000 to focus on San Francisco.

   Expand

   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
       viewer.camera.flyTo({
         destination: Cesium.Cartesian3.fromDegrees(-122.4106, 37.7908, 200000)
       });
   

   Expand

Add a terrain provider

To create accurate and realistic terrain in your CesiumJS scene, you need to use a geoid service. This service will allow the elevation of your base layer to align with the elevation values of Cesium World Terrain.

1. Initialize a terrain provider called arcGisTerrain that references the Terrain 3D. This terrain will provide global elevation surface for your basemap layer.

   Expand

   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
       const arcGisTerrain = new Cesium.ProviderViewModel({
         name: "ArcGIS World Terrain",
         iconUrl: "https://www.arcgis.com/sharing/rest/content/items/58a541efc59545e6b7137f961d7de883/info/thumbnail/thumbnail1585609861151.png",
         creationFunction: () => {
           return Cesium.ArcGISTiledElevationTerrainProvider.fromUrl("https://elevation3d.arcgis.com/arcgis/rest/services/WorldElevation3D/Terrain3D/ImageServer");
         }
       });
       viewModel.terrainProviderViewModels = [arcGisTerrain];
   
   

   Expand

2. Add the data attribution for the elevation layer source.

   • Go to the Terrain 3D item.
   • Scroll down to the Acknowledgments section and copy its value.
   • Paste the copied value to the credit property.
     Expand

     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
         const arcGisTerrain = new Cesium.ProviderViewModel({
           name: "ArcGIS World Terrain",
           iconUrl: "https://www.arcgis.com/sharing/rest/content/items/58a541efc59545e6b7137f961d7de883/info/thumbnail/thumbnail1585609861151.png",
           creationFunction: () => {
             return Cesium.ArcGISTiledElevationTerrainProvider.fromUrl("https://elevation3d.arcgis.com/arcgis/rest/services/WorldElevation3D/Terrain3D/ImageServer");
           }
         });
         viewModel.terrainProviderViewModels = [arcGisTerrain];
     
         // Attribution text retrieved from https://www.arcgis.com/home/item.html?id=7029fb60158543ad845c7e1527af11e4
         viewer.creditDisplay.addStaticCredit(new Cesium.Credit("Sources: Maxar, Airbus DS, USGS, NGA, NASA, CGIAR, GEBCO, N Robinson, NCEAS, NLS, OS, NMA, Geodatastyrelsen and the GIS User Community", false));
     

     Expand

Change the imagery providers

CesiumJS includes a baseLayerPicker by default that includes imagery layers from multiple providers. Customize this widget to include additional offerings from ArcGIS.

1. Inside viewer, set the baseLayerPicker property to true.

   Expand

   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
       const viewer = new Cesium.Viewer("cesiumContainer", {
   
         baseLayer: Cesium.ImageryLayer.fromProviderAsync(arcGisImagery),
   
         terrain: Cesium.Terrain.fromWorldTerrain(),
   
         baseLayerPicker: true,
   
         timeline: false,
         animation: false,
         geocoder: false
   
       });
   

   Expand

2. Access the baseLayerPicker.viewModel to manage the available base layer options.

   Expand

   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
       const viewModel = viewer.baseLayerPicker.viewModel;
   

   Expand

3. Define a set of base layers you want to include in your base layer picker, e.g. ArcGIS World Imagery, ArcGIS World Hillshade, and Esri World Ocean.

   Expand

   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
       const imageryProviderNames = ["ArcGIS World Imagery", "ArcGIS World Hillshade", "Esri World Ocean"];
   
   

   Expand

4. The viewModel.imageryProviderViewModels contains all available basemaps by default. Use a for loop to filter and select only the desired basemaps.

   Expand

   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
       const imageryProviderNames = ["ArcGIS World Imagery", "ArcGIS World Hillshade", "Esri World Ocean"];
   
       const imageryProviders = [];
   
       for (imageryProvider of viewModel.imageryProviderViewModels) {
         if (imageryProviderNames.includes(imageryProvider.name)) {
           imageryProviders.push(imageryProvider);
         }
       }
   
   

   Expand

5. Replace the viewModel.imageryProviderViewModels with the filtered list.

   Expand

   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
       const imageryProviderNames = ["ArcGIS World Imagery", "ArcGIS World Hillshade", "Esri World Ocean"];
   
       const imageryProviders = [];
   
       for (imageryProvider of viewModel.imageryProviderViewModels) {
         if (imageryProviderNames.includes(imageryProvider.name)) {
           imageryProviders.push(imageryProvider);
         }
       }
   
       viewModel.imageryProviderViewModels = imageryProviders;
   

   Expand

Run the app

Run the app.

Open the base layer picker and ensure that only the specified basemaps are available for selection.

What's next?

Learn how to use additional location services in these tutorials: