Tutorial: Change the static basemap tiles style

Learn how to change static basemap tiles style.

You can display a scene with raster basemap tiles using the static basemap tiles service (beta). The service supports a number of ArcGIS styles such as navigation, streets, outdoor, and light-gray. The tiles are returned as PNG files.

In this tutorial, you customize the BaseLayerPicker widget to display the different basemap layer styles and display them as raster tiles on your scene.

Prerequisites

Steps

Get the starter app

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

Set up authentication

Create developer credentials in your portal for the type of authentication you selected.

Set developer credentials

Use the API key or OAuth developer credentials created in the previous step in your application.

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_URL", // 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_URL", // 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's viewpoint

1. Change the camera's destination to -91.2996, 37.1174, 4622324.434309. This will focus the camera on the United States of America.

   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
   103
   104
   105
   106
   107
   108
   109
   110
   111
   112
   113
   114
   115
   116
   117
   118
       viewer.camera.setView({
   
         destination: Cesium.Cartesian3.fromDegrees(-91.2996, 37.1174, 4622324.434309),
   
         orientation: {
           heading: Cesium.Math.toRadians(0.0),
           pitch: Cesium.Math.toRadians(-90.0),
         }
       });
   

   Expand

Remove base layer references

1. Remove arcGisImagery, terrain, and the baseLayer properties from the viewer.
   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
       const arcGisImagery = Cesium.ArcGisMapServerImageryProvider.fromBasemapType(Cesium.ArcGisBaseMapType.SATELLITE);
   
       const viewer = new Cesium.Viewer("cesiumContainer", {
   
         baseLayer: Cesium.ImageryLayer.fromProviderAsync(arcGisImagery),
   
         terrain: Cesium.Terrain.fromWorldTerrain(),
   
         timeline: false,
         animation: false,
         geocoder: false
   
       });
   

Load the basemaps

1. Create a variable called viewModel to obtain the BaseLayerPicker widget. You will be able to customize the widget through this variable.

   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
   103
   104
   105
   106
   107
   108
   109
   110
   111
   112
   113
   114
   115
   116
   117
   118
       /* 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_URL", // The redirect URL registered in your OAuth credentials
       //   portal: "YOUR_PORTAL_URL" // Your portal URL
       // })
   
       // const accessToken = session.token;
   
       const cesiumAccessToken = "YOUR_CESIUM_ACCESS_TOKEN";
   
       Cesium.Ion.defaultAccessToken = cesiumAccessToken;
   
       const viewer = new Cesium.Viewer("cesiumContainer", {
         timeline: false,
         animation: false,
         geocoder: false,
       });
   
       const viewModel = viewer.baseLayerPicker.viewModel;
   
       viewer.camera.setView({
   
         destination: Cesium.Cartesian3.fromDegrees(-91.2996, 37.1174, 4622324.434309),
   
         orientation: {
           heading: Cesium.Math.toRadians(0.0),
           pitch: Cesium.Math.toRadians(-90.0),
         }
       });
   

   Expand

2. Create an async function called loadBasemaps.

   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
   103
   104
   105
   106
   107
   108
   109
   110
   111
   112
   113
   114
   115
   116
   117
   118
       /* 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_URL", // The redirect URL registered in your OAuth credentials
       //   portal: "YOUR_PORTAL_URL" // Your portal URL
       // })
   
       // const accessToken = session.token;
   
       const cesiumAccessToken = "YOUR_CESIUM_ACCESS_TOKEN";
   
       Cesium.Ion.defaultAccessToken = cesiumAccessToken;
   
       const viewer = new Cesium.Viewer("cesiumContainer", {
         timeline: false,
         animation: false,
         geocoder: false,
       });
   
       const viewModel = viewer.baseLayerPicker.viewModel;
   
       async function loadBasemaps() {
   
       }
   
       viewer.camera.setView({
   
         destination: Cesium.Cartesian3.fromDegrees(-91.2996, 37.1174, 4622324.434309),
   
         orientation: {
           heading: Cesium.Math.toRadians(0.0),
           pitch: Cesium.Math.toRadians(-90.0),
         }
       });
   

   Expand

3. Inside the function, use the fetch method to call the service URL and pass in the accessToken. Store the JSON-formatted response in a variable called data.

   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
   103
   104
   105
   106
   107
   108
   109
   110
   111
   112
   113
   114
   115
   116
   117
   118
       async function loadBasemaps() {
   
         const response = await fetch(`https://static-map-tiles-api.arcgis.com/arcgis/rest/services/static-basemap-tiles-service/beta/self?token=${accessToken}`);
         const data = await response.json();
   
       }
   

   Expand

4. Create an empty list of imageryProviders. We will use this list to store the basemap styles that will be displayed in the base layer picker.

   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
   103
   104
   105
   106
   107
   108
   109
   110
   111
   112
   113
   114
   115
   116
   117
   118
       async function loadBasemaps() {
   
         const response = await fetch(`https://static-map-tiles-api.arcgis.com/arcgis/rest/services/static-basemap-tiles-service/beta/self?token=${accessToken}`);
         const data = await response.json();
   
         const imageryProviders = []
   
       }
   

   Expand

5. For each basemap style returned by the service, create a new Cesium.ProviderViewModel and push it into our imageryProviders 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
   103
   104
   105
   106
   107
   108
   109
   110
   111
   112
   113
   114
   115
   116
   117
   118
       async function loadBasemaps() {
   
         const response = await fetch(`https://static-map-tiles-api.arcgis.com/arcgis/rest/services/static-basemap-tiles-service/beta/self?token=${accessToken}`);
         const data = await response.json();
   
         const imageryProviders = []
   
         for (const style of data.styles) {
   
           imageryProviders.push(new Cesium.ProviderViewModel({
             name: style.name,
             iconUrl: style.thumbnailUrl,
             creationFunction: () => {
               return new Cesium.UrlTemplateImageryProvider({
                 url: style.templateUrl + "?token=" + accessToken,
                 tileWidth: 512,
                 tileHeight: 512,
   
               });
             }
           }));
         }
   
       }
   

   Expand

6. Apply the imageryProviders list into the viewModel and use the first basemap style as the default basemap.

   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
   103
   104
   105
   106
   107
   108
   109
   110
   111
   112
   113
   114
   115
   116
   117
   118
       async function loadBasemaps() {
   
         const response = await fetch(`https://static-map-tiles-api.arcgis.com/arcgis/rest/services/static-basemap-tiles-service/beta/self?token=${accessToken}`);
         const data = await response.json();
   
         const imageryProviders = []
   
         for (const style of data.styles) {
   
           imageryProviders.push(new Cesium.ProviderViewModel({
             name: style.name,
             iconUrl: style.thumbnailUrl,
             creationFunction: () => {
               return new Cesium.UrlTemplateImageryProvider({
                 url: style.templateUrl + "?token=" + accessToken,
                 tileWidth: 512,
                 tileHeight: 512,
   
               });
             }
           }));
         }
   
         viewModel.imageryProviderViewModels = imageryProviders;
         viewModel.selectedImagery = imageryProviders[0]; // set the first basemap style as the default style
   
       }
   

   Expand

Load the new base layer picker

1. Call the loadBasemaps function to load the new base layer picker with the static basemap styles.

   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
   103
   104
   105
   106
   107
   108
   109
   110
   111
   112
   113
   114
   115
   116
   117
   118
       loadBasemaps();
   
       viewer.camera.setView({
   
         destination: Cesium.Cartesian3.fromDegrees(-91.2996, 37.1174, 4622324.434309),
   
         orientation: {
           heading: Cesium.Math.toRadians(0.0),
           pitch: Cesium.Math.toRadians(-90.0),
         }
       });
   

   Expand

Add attribution

You are required to provide data attribution to the static basemap tiles service. CesiumJS does not add the attribution automatically. Therefore, you are required to add it manually. To do this, you make another call to the service to retrieve the basemap style's metadata, then attach the copyrightText attribute to the imagery provider's credit.

1. Inside the for loop, make a call to the style's URL to retrieve its metadata. Store the JSON response into a variable called attributionData.

   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
   103
   104
   105
   106
   107
   108
   109
   110
   111
   112
   113
   114
   115
   116
   117
   118
       async function loadBasemaps() {
   
         const response = await fetch(`https://static-map-tiles-api.arcgis.com/arcgis/rest/services/static-basemap-tiles-service/beta/self?token=${accessToken}`);
         const data = await response.json();
   
         const imageryProviders = []
   
         for (const style of data.styles) {
   
           const attributionResponse = await fetch(`${style.url}?token=${accessToken}`);
           const attributionData = await attributionResponse.json();
   
           imageryProviders.push(new Cesium.ProviderViewModel({
             name: style.name,
             iconUrl: style.thumbnailUrl,
             creationFunction: () => {
               return new Cesium.UrlTemplateImageryProvider({
                 url: style.templateUrl + "?token=" + accessToken,
                 tileWidth: 512,
                 tileHeight: 512,
   
               });
             }
           }));
         }
   
         viewModel.imageryProviderViewModels = imageryProviders;
         viewModel.selectedImagery = imageryProviders[0]; // set the first basemap style as the default style
   
       }
   

   Expand

2. In the creationFunction of the style, use the copyrightText from the attributionData in the credit attribute.

   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
   103
   104
   105
   106
   107
   108
   109
   110
   111
   112
   113
   114
   115
   116
   117
   118
       async function loadBasemaps() {
   
         const response = await fetch(`https://static-map-tiles-api.arcgis.com/arcgis/rest/services/static-basemap-tiles-service/beta/self?token=${accessToken}`);
         const data = await response.json();
   
         const imageryProviders = []
   
         for (const style of data.styles) {
   
           const attributionResponse = await fetch(`${style.url}?token=${accessToken}`);
           const attributionData = await attributionResponse.json();
   
           imageryProviders.push(new Cesium.ProviderViewModel({
             name: style.name,
             iconUrl: style.thumbnailUrl,
             creationFunction: () => {
               return new Cesium.UrlTemplateImageryProvider({
                 url: style.templateUrl + "?token=" + accessToken,
                 tileWidth: 512,
                 tileHeight: 512,
   
                 credit: new Cesium.Credit(attributionData.copyrightText)
   
               });
             }
           }));
         }
   
         viewModel.imageryProviderViewModels = imageryProviders;
         viewModel.selectedImagery = imageryProviders[0]; // set the first basemap style as the default style
   
       }
   

   Expand

Run the app

Run the app.

The scene should display an area of the United States of America with a customized base layer picker.

What's next?

Learn how to use additional ArcGIS location services in these tutorials: