Getting Started

This tutorial will help you load your first imagery and terrain assets into Cesium ion using our scalable, cloud-based 3D tiling pipeline and stream them into CesiumJS. No prior experience with ion or CesiumJS is required.
Read time: 10 min

Sample data

We have provided some sample data for you to use. To download, click on the following links:

Uploading data to Cesium ion

Make sure you’re logged into ion. If you don’t already have a free Community ion account, you can create one on the sign up page.

Uploading imagery

  1. Drag and drop Space_Needle_Ortho.tiff into the browser window.
  2. Raster data can represent either imagery or terrain, so you need to tell ion what you’re uploading. Under Select the asset type: click Imagery.
  3. Click the button.

You’ll be taken to the My assets page and the imagery asset you just created will be automatically selected.

Uploading Space_Needle_Ortho.tiff

You will notice a small upload progress bar appear in the lower right corner. Depending on the speed of your Internet connection this may turn green instantly, indicating the upload is finished.

Once the upload is complete, the image is tiled by the ion 3D tiling pipeline and a streamable imagery tileset is created. You can monitor the progress in the preview window on the upper right.

When processing is finished, the preview window will automatically fly to the new asset and it is ready to be used in CesiumJS apps. Before streaming it into CesiumJS, let’s process our terrain data.

Uploading terrain

Converting terrain is not all that different from imagery but does require some additional configuration.

  1. Drag and drop Space_Needle_Terrain.tiff into the browser window.
  2. This time, select Terrain under Select the asset type:.
  3. Click the button.

You will now be on the Terrain Settings page. The most common defaults are already selected, but it’s important to make sure these settings match your own raster terrain data. Most terrain datasets include a README or other metadata file, which will contain the settings you need.

Terrain Settings

For this tutorial, you’re only going to modify the Base Terrain option. By default, terrain source data is blended with mean sea level (MSL). That is, anywhere not covered by our terrain will have a height that matches MSL. This can be undesirable if you have a small area that you wish to fit seamlessly into its surroundings, as is the case with our sample data. We can blend our new terrain into the Cesium World Terrain by selecting it in the Base Terrain list.

You can click the contextual help button () to get detailed information on each of the other settings. Each page in the ion interface has a similar help button with details specific to that page. Once you’re done exploring, click the button.

From here on, the process is identical to that of imagery. A progress bar will appear and the preview window will fly to the terrain location as soon as processing is complete.

Load your new assets into CesiumJS

Cesium Sandcastle is a sandbox app we ship with CesiumJS to make it easy to play with the Cesium API. If you click on the Space_Needle_Ortho asset we created earlier, you’ll notice both a sample code block and a link labeled Open complete code example in Sandcastle. Click on that link and a new window will open. Without any typing, you have a fully functioning complete code example that can be used in any CesiumJS app.

Sandcastle imagery

This example only covers the imagery, but we can extend it to include terrain as well. Leave this Sandcastle window open and switch back to ion. Find Space_Needle_Terrain in the list of assets and click on it. Rather than opening a new Sandcastle example, we can press the copy button () to copy the minimal amount of code needed to load the asset into an existing Cesium app.

Switch back to Sandcastle and replace the line var viewer = new Cesium.Viewer('cesiumContainer'); with the data you just copied into your clipboard. Press the Run button in Sandcastle to load your updated code. You now have both assets loaded into CesiumJS!

Sandcastle terrain

Let’s review the ion specific parts of the code:

The first line is perhaps the most important. It configures CesiumJS to use your ion account, which grants access to all of the assets in My Assets. If you ever need to provide access to specific assets instead of all assets in your account, you can create tokens on the Access tokens page.

// Grant CesiumJS access to your ion assets
Cesium.Ion.defaultAccessToken = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiIyMGFmZWJkYi0xZWEwLTQyNGItYjhkZS00NDRlMDU3NmU5NGQiLCJpZCI6MiwiaWF0IjoxNTI1MTIxNzQ4fQ.gTbqw42HZO7AFearFm8qYAN4g-KavnG7eiuZmFFuWdA';

The next line creates the Viewer widget and configures it to use the Space_Needle_Terrain asset we just created. The default global base layer will also be an ion provided asset, Bing Maps Aerial, which is included with your account. The number 934 is the asset identifier. Every asset has a unique id, so yours will be different.

var viewer = new Cesium.Viewer('cesiumContainer',{
    terrainProvider : new Cesium.CesiumTerrainProvider({
        url: Cesium.IonResource.fromAssetId(934)

Finally, we add our Space Needle imagery using CesiumJS’s IonImageryProvider class.

var imageryLayer = viewer.imageryLayers.addImageryProvider(
    new Cesium.IonImageryProvider({ assetId: 932 })

Congratulations! You have created your first ion assets!

What’s next?

This tutorial covers only the basics. For example, ion lets you mosaic multiple raster files into a single imagery or terrian layer. If you have data like that, give it a try!

We hope you continue to explore the site and occasionally check the Changelog for information on new features as we add them.

If you’re new to CesiumJS, be sure to check out its tutorials.

Please do not hesitate to email with any feedback you have or create an issue in our Cesium ion community GitHub repository.