Skip to main content

Adding Datasets

This tutorial shows you how to use Cesium for Unreal to import models. 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.

Video version of this tutorial. Keep reading for the written tutorial.

You’ll learn how to:

  • Add a city-scale 3D Tiles photogrammetry model from Cesium ion to your level.
  • Use the CesiumGeoreference Actor to geoposition your level on the globe.
  • Use a local 3D Tiles dataset from your computer.

Prerequisites

  • Unreal Engine (at least 4.26 or later) and the Cesium for Unreal plugin are installed.
  • A Cesium ion account to stream the Melbourne tileset into Unreal Engine.
Information

See the Cesium for Unreal Quickstart to learn how to install Cesium for Unreal and connect it with Cesium ion.

1Create a project and level

See the Quickstart for detailed instructions. Stop before Step 6, Add global 3D buildings to your scene, because you will be adding photogrammetry-derived buildings instead.

2Add the Melbourne photogrammetry model from Cesium ion

1Open the Cesium panel by clicking the icon in the toolbar.

Cesium for Unreal photogrammetry toolbar

2Connect to Cesium ion if you haven’t already.

Cesium for Unreal photogrammetry connect

3Click the Add button to open the Cesium ion Assets panel.

Cesium for Unreal photogrammetry add button

4Find Melbourne Photogrammetry in the asset list, click on it, and then click Add to Level.

Cesium for Unreal photogrammetry asset list
Information

Is Melbourne Photogrammetry missing from the asset list? Visit the Melbourne Photogrammetry Asset Depot page and click Add to my assets. Then return to Unreal Engine, close the Cesium ion Assets panel, and click the Add button again on the Cesium panel to re-open and refresh the asset list.

5Double-click Melbourne Photogrammetry in the World Outliner to point the viewport at Melbourne.

Cesium for Unreal photogrammetry world outliner

It will likely be oriented strangely, and you may even be looking at the bottom of it.

Cesium for Unreal photogrammetry zoomed to melbourne

3Center the Unreal world at Melbourne

The orientation of Melbourne on the screen is strange because the Unreal Editor camera is maintaining its normal “+Z direction is up” orientation. On planet Earth - unlike in most games - the “up” direction in an Earth-centered coordinate system changes depending on where you are in the world.

Let’s reposition the Unreal Engine world in a more useful way:

1Click on the CesiumGeoreference-1 in the World Outliner.

Cesium for Unreal photogrammetry georeference in outliner

2On the Details tab, click the Place Georeference Origin Here button.

Cesium for Unreal photogrammetry georeference details

The city will flip upright. If the scene turns black, it’s probably because it’s nighttime in Melbourne. Try adjusting the Solar Time property on the CesiumSunSky.

Cesium for Unreal photogrammetry melbourne upright

The Place Georeference Origin Here button didn’t just change the orientation. If you watched closely, you may have noticed that the Origin Latitude, Origin Longitude, and Origin Height fields below the button also changed when you pressed it. In precise terms, the button repositioned the coordinate system of the Unreal Engine level so that its center point, (0, 0, 0), is located exactly where the camera was located previously. And it aligned the Unreal axes so that +X points to the East at that point, +Y points to the South, and +Z points up.

It’s also possible to type in the LatitudeLongitude, and Height values directly to position the world at a precise location.

This ability to position the world origin somewhere on the globe is very helpful because many things in Unreal Engine, from cameras to foliage to physics, prefer a coordinate system with relatively small values and with +Z pointing up. By “georeferencing” the Unreal world in this way, we allow normal Unreal objects to be placed in and around Melbourne and act just as they would in any other game.

4Adding global context

At this point, Melbourne is a city floating in a sea of darkness. Let’s add some global context:

1In the Cesium panel, click the + next to Cesium World Terrain + Bing Maps Aerial imagery, or another Cesium World Terrain option of your choosing.

Cesium for Unreal photogrammetry quick add cwt

The area around Melbourne will be filled in with the global assets you added:

Cesium for Unreal photogrammetry with cwt

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:

Cesium for Unreal photogrammetry terrain through

This happens because Cesium World Terrain and Melbourne photogrammetry are both high-resolution datasets, and may overlap the same geography. A future version of Cesium for Unreal will allow you to “clip away” Cesium World Terrain to make room for the photogrammetry model. For now, let’s move the photogrammetry model upward so that the terrain model no longer pokes through.

2Select the Melbourne Photogrammetry Actor and adjust the Location Z coordinate by clicking inside the Z coordinate box and dragging toward the right, or by typing a number.

Add 3D Tileset from local directory

Information

The following section is currently only available for users on Windows machines. The file:/// functionality does not work on Linux or Mac.

For this section, you will use a 3D Tileset that contains boxes of various heights. This 3D Tileset can be downloaded here. Be sure to download the entire Tileset folder, which includes the tileset.json file as well as all of the referenced .b3dm files. You can also use your own 3D Tileset instead.

Information

If you are new to the 3D Tiles format, check out the 3D Tiles Specification to learn more.

1In the Cesium UI to the left of the editor, under the Quick Add Basic Actors section, click on the button next to Blank 3D Tiles Tileset. This adds a new blank Cesium 3D Tileset to the scene.

2Select the Cesium3D Tileset actor in the World Outliner and rename it to “LocalTileset”.

3In the Details panel, look for the Cesium Category. Typically to load data from Cesium ion, you would fill out the Ion Asset ID and Ion Access Token fields. For loading local data, you will fill out the Url field instead with the path to the 3D Tileset’s main tileset.json file. Locate the 3D Tileset data in your local directory system.

For example, if the directory is:

C:\Users\username\document\Unreal Projects\CesiumForUnrealSamples\Data\Tileset\tileset.json

then the Url would look be: 

file:///C:/Users/username/document/Unreal Projects/CesiumForUnrealSamples/Data/Tileset/tileset.json

Note the triple forward slashes after file:.

The Transform dialog with the Cesium Url field highlighted

4In World Outliner, double click on the LocalTileset actor to focus on it in the viewport.

The world and the asset may be oriented incorrectly, like this:

Local assets and a green field displayed in Unreal Engine, tilted to the left

This is because the origin of the CesiumGeoreference actor is far from the LocalTileset actor.

5With the viewport still focused on the LocalTileset actor, head over to the World Outliner, select the CesiumGeoreference actor, and look for the Place Georeference Origin Here button. Click on this button to re-orient the world.

In UE, the tileset in a green field oriented correctly

6Adjust the Location transform of the LocalTileset in the Details panel to place it at the desired location. For example, to position the base of the 3D Tileset on top of the terrain, change the Z coordinate of the Location transform to 7400.

Tiles raised so they appear like tall buildings above the green field
Information

Currently, loading local quantized-mesh terrain files using Cesium for Unreal is not supported. However, terrain assets can be loaded from any server, including localhost. To load terrain assets completely offline, consider setting up a localhost to serve the terrain. The Url field can be filled using the same steps as above with http://localhost:portNumber/terrainAsset.

Resources

Next steps

Read on to the next tutorial, Placing Objects on the Globe, to learn more about placing objects in Cesium for Unreal levels.

Content and code examples at cesium.com/learn are available under the Apache 2.0 license. You can use the code examples in your commercial or non-commercial applications.