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
We have provided some sample data for you to use. To download, click on the following links:
Select the asset type:click
You’ll be taken to the
My assets page and the imagery asset you just created will be automatically selected.
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.
Converting terrain is not all that different from imagery but does require some additional configuration.
Select the asset type:.
You will now see the Terrain Settings panel. 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.
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.
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.
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!
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.
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.
Finally, we add our Space Needle imagery using CesiumJS’s
Congratulations! You have created your first ion assets!
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.