Adding Datasets
This tutorial shows you how to use Cesium for Unity to bring real-world datasets into your projects. First, you’ll import a photogrammetry model from Cesium ion. You’ll use a model of one of the world’s most livable cities: Melbourne, Australia. Then, you’ll import a local dataset from your computer.
You’ll learn how to:
- Add a city-scale 3D Tiles photogrammetry model from Cesium ion to your scene.
- Use the CesiumGeoreference component to geoposition your scene on the globe.
- Add a local 3D Tiles dataset from your computer.
- Know how to set up a basic Cesium for Unity application. Check out our Cesium for Unity Quickstart guide for instructions on starting with the Cesium for Unity package.
- A Cesium ion account to stream the Melbourne tileset into Unity.
This tutorial assumes that you have already created a project and imported the Cesium for Unity package. If you have not yet created a project, see the Quickstart for detailed instructions.
1Create a new scene by clicking File > New Scene or pressing Ctrl+N on your keyboard. In the window that appears, select Standard (URP) and click Create.
When the file explorer appears, give your scene a name and hit Save. The new scene will then open in the Editor.
2Open the Cesium panel by going to Cesium > Cesium in the top menu.
3Connect to Cesium ion if you haven’t already.
4Click the Add button to open the Cesium ion Assets panel.
5Find Melbourne Photogrammetry in the asset list. Click on it, and then click Add to Level.
Is Melbourne Photogrammetry missing from the asset list? Visit the Melbourne Photogrammetry Asset Depot page and click Add to My Assets. Then return to Unity and refresh the asset list using the button in the upper left corner of the Cesium ion Assets window.
You should see two new game objects in the Hierarchy window: a parent game object named CesiumGeoreference and a child game object named Melbourne Photogrammetry.
6Click on Melbourne Photogrammetry in the Hierarchy window, and take a look at the Cesium 3D Tileset in the Inspector.
The ion Asset ID is pre-filled with the Asset ID of the Melbourne Photogrammetry dataset.
The ion Access Token is blank. This means that the asset is using the project's default token to access the data. There's no need to change either of these settings right now.
You can set a tileset's ion Access Token on a per-tileset basis by copying and pasting an access token from Cesium ion. Then, the tileset will use that token instead of the project's default token.
Configure your project's tokens using the Token button in the Cesium panel.
Want to learn more about access tokens? Check out the Cesium ion Access Tokens tutorial.
7Double-click on Melbourne Photogrammetry to move the Scene View to the new tileset. It will have a strange orientation, and you may even be looking at the bottom of it.
The orientation of Melbourne is strange because for the Unity camera, the positive Y direction is always up. But unlike in most games, the “up” direction in an Earth-centered coordinate system changes depending on where you are in the world. This is where the CesiumGeoreference comes into play.
1Click on the CesiumGeoreference game object in the Hierarchy window.
2In the Inspector window, locate the Cesium Georeference component and click Place Origin Here.
The city will flip upright.
The Place Origin Here button affects more than the orientation. You may have noticed that the Latitude, Longitude, and Height fields of the georeference have also changed. That is because the button tells the georeference to recenter the Unity origin at those coordinates. In other words, the point (0, 0, 0) in Unity will correspond to the real-world position defined by the georeference. It also aligns the Unity axes so that +X points from that position to the East, +Y points up, and +Z points to the North.
The ability to position the Unity world origin at some real-world location globe is very useful. Many things in Unity, from cameras to transforms to physics, prefer a coordinate system with relatively small values. By “georeferencing” the Unity scene in this way, we allow normal Unity objects to be placed in and around Melbourne and act just as they would in any other game.
At this point, Melbourne is a city floating in an empty environment. Let’s add some global context:
1In the Cesium panel, click the + icon next to Cesium World Terrain + Bing Maps Aerial imagery, or another Cesium World Terrain option of your choosing.
The area around Melbourne will be filled in with the global assets you added:
This looks good from a distance, but when we zoom in close we can see some places where the Cesium World Terrain sticks up through the photogrammetry model:
This happens because Cesium World Terrain and Melbourne photogrammetry are both high-resolution datasets, and may overlap the same geography. You can avoid this by moving the photogrammetry tileset higher in the level so that it no longer overlaps.
2Select the Melbourne Photogrammetry game object and move it higher in the Y-direction. You can change the Y-coordinate of the Position under the Transform component by typing in the desired value.
You can also do this by selecting the Move Tool in the Scene View and dragging the green transform arrow.
The following section is optional. If you are using only Cesium ion to stream assets, skip this section and jump down to "Next steps" to continue in the tutorial series.
Tilesets can be loaded from a location on your computer, such as a local file directory or a supported streaming server. In this section, you will learn how to load a tileset from a local file directory on your computer. The tutorial provides an example 3D Tileset that contains boxes of various heights. Alternatively, you can use any 3D Tileset that is downloaded to your computer.
If you'd like to learn more about the 3D Tiles format, check out the 3D Tiles Specification.
1Download the example 3D Tileset by clicking here. Extract the .zip archive. You can save the files anywhere on your computer, but take note of their location—you'll need it later.
2In the Unity Editor, add a Blank 3D Tileset to your scene using the Quick Add section of the Cesium window.
3Select the Cesium3DTileset game object in the Hierarchy window. It should appear underneath the existing CesiumGeoreference game object. In the Inspector, find the Cesium3DTileset’s Source parameter. Click on the dropdown and set it to "From URL". Setting this will enable the URL field.
4In your computer's files, locate the 3D Tileset that you previously downloaded. Copy the filepath.
To use the filepath in the tileset's URL field, you'll need to replace any backslashes with forward slashes, and any spaces with "%20". For example, the file C:\Users\username\My Project\Data\Tileset\tileset.json would become C:/Users/username/My%20Project/Data/Tileset/tileset.json.
Paste your edited path in the URL field for the tileset.
5Double-click the Cesium3DTileset in the Hierarchy window to zoom to the tileset. As with the Melbourne tileset, it will be oriented strangely. Click on CesiumGeoreference and press the Place Origin Here button. This should orient the tileset correctly on your screen.
The tileset is buried under Cesium World Terrain, so let’s fix that. You can adjust the Transform of a tileset in the Inspector like any other game object. To position the base of this 3D Tileset on top of the terrain, change the Y-coordinate of its Position to 74. The boxes should now appear on top of Cesium World Terrain.
Loading assets from a local server
3D Tilesets, terrain, and imagery can be loaded from any server, including localhost. To load assets completely offline, consider setting up a localhost to serve the data. The URL field can be filled with http://localhost:portNumber/path/to/asset.
If you are loading TMS imagery, the URL should point to the asset's primary tilemapresource.xml file (e.g., http://localhost:portNumber/imageryAsset/tilemapresource.xml).
Read on to the next tutorial, Placing Objects on the Globe, to learn more about placing objects in Cesium for Unity levels.