Frequently Asked Questions
If you’re new to Cesium for Unreal, begin with the Quickstart tutorials for hands-on instructions on using the plugin.
Requirements, installing, and upgrading
- How does Cesium ion work with Cesium for Unreal?
- Do I need an internet connection to use Cesium for Unreal?
- What versions of Unreal Engine can I use with Cesium for Unreal?
- How do I update the plugin?
- How do I access pre-release versions of the plugin?
- How do I access older versions of the plugin?
Attribution
Contributing
Data Formats
- What file formats can I load with Cesium for Unreal?
- Can I load vector data (KML, SHP, GeoJSON, CZML) with Cesium for Unreal?
- Can I download datasets from Cesium ion?
Features
- What is a 3D Tileset?
- What is a Raster Overlay?
- What is the water mask? How do I enable the water mask on Cesium World Terrain?
- Can I hide parts of a tileset?
- How do I load tilesets offline?
- How can I optimize my scene’s performance?
Troubleshooting
- Why is my scene bright white?
- Why is my scene black?
- How do I prevent characters or other objects from falling through the terrain?
- Why can’t I see my data in the viewport?
- Why did my tilesets disappear, if they were previously rendering?
- How do I access debug information about my tileset?
- Why can’t I see my tilesets when I use remote desktop software?
In this section:
How does Cesium ion work with Cesium for Unreal?
Cesium for Unreal streams and visualizes data from Cesium ion using open standards, enabling you to build rich 3D geospatial applications.
The Cesium platform follows an open core model: the Cesium for Unreal plugin is free and open source under the Apache 2.0 license, with an optional commercial subscription to Cesium ion for global 3D data and tiling pipelines. Cesium ion users get access to assets such as Cesium World Terrain, Bing Maps Imagery, Cesium OSM buildings, along with high-resolution city data as photogrammetry and 3D buildings.
You can sign up for Cesium ion at https://ion.cesium.com/signup/.
Do I need an internet connection to use Cesium for Unreal?
Cesium ion data assets such as Cesium World Terrain, Bing Maps Imagery, and Cesium OSM Buildings are hosted on the web and require an internet connection. Cesium ion assets are also available for on-premises deployment for disconnected use under a commercial license. Reach out to us at https://cesium.com/contact/ to learn more.
You may also use your own or third party geospatial data services that follow supported industry standards. Depending on how the data is available to you, you may load it directly off the disk, or load it from a server. Loading from a server requires either a local network or an internet connection.
See also:
How do I update the plugin?
Always back up your project before updating Cesium for Unreal.
Unreal Engine Marketplace
If you are using Cesium for Unreal from the Unreal Engine Marketplace, you can update using the Epic Launcher.
On the Library page of the Epic Launcher, you’ll see a section called Engine Versions. If an update is available for the plugin, you’ll see an exclamation point next to the Installed Plugins button under an engine version.
Github
If you are using Cesium for Unreal from a packaged GitHub release, you can download new releases from the GitHub repository. The newest release will be at the top. Delete the CesiumForUnreal folder in your project’s Plugins folder, and replace it with the new downloaded release.
How do I access pre-release versions of the plugin?
If you would like to access pre-release, development versions of the plugin, Cesium for Unreal has Travis CI integration that prepares packages with each CI build. To access these packages, go to the GitHub repository and navigate to the branch or commit you’d like to use.
Click the ✔️ icon on the GitHub branch or commit and click the Details next to the entry for your engine version.
Then, extract the downloaded plugin package into your Unreal project's Plugins directory.
Plugins in a project’s Plugins folder will take priority over engine plugins installed through the Epic Launcher.
How do I access older versions of the plugin?
You can find previous Cesium for Unreal releases on GitHub. Find the release for your desired version of Cesium for Unreal, and download the .zip file appropriate for your version of Unreal Engine. Then, extract the downloaded plugin package into your Unreal project's Plugins directory.
Can I remove the Cesium attribution?
The assets in Cesium ion may use third-party commercial and open data sources. Users of Cesium ion services, including Cesium itself, are responsible for providing attribution appropriately.
You may not remove the Cesium attribution entirely, but you may move it to a different position.
Cesium ion attribution is required on the main application window.
For mobile applications, you may move the Cesium ion attribution to a splash screen or about page.
See also:
I have an idea for the plugin - how can I get involved?
Cesium is open source and your contributions are welcome. There are many different ways you can contribute.
- Contribute directly to the plugin’s source code or assets. Follow the developer setup to get started. Once you’ve made changes, you can submit a pull request for review.
- Submit issues for bugs or new features in the GitHub repository.
- Triage issues. Browse open issues and comment on issues that are no longer reproducible or on issues for which you have additional information.
- Be active on the Cesium community forum by answering questions and providing input on Cesium's direction.
- Write tutorials, create examples, and improve the reference documentation.
You can also showcase your Cesium for Unreal apps on the Cesium blog. Contact us at hello@cesium.com.
See also:
What file formats can I load with Cesium for Unreal?
Cesium for Unreal can load 3D Tiles, terrain, and tiled imagery. Tilesets and imagery can be loaded from Cesium ion, other supported streaming servers, and local file directories depending on the data formats.
Models like photogrammetry and terrain are loaded as 3D Tilesets using the Cesium3DTileset actor. 3D Tilesets can contain a variety of different content types/payloads. Some 3D Tiles payloads are not currently supported in Cesium for Unreal.
Imagery like satellite image or map data is draped over a tileset by attaching a Cesium Raster Overlay component to a Cesium3DTileset actor. Imagery must be hosted with a tile map service.
Refer to the tables below to see which file formats are supported.
Supported data types
| 3D Tiles payloads | Imagery protocols |
|---|---|
| ✔️ glTF 2.0 + extensions* | ✔️ Tile map Service (TMS) |
| ✔️ quantized-mesh terrain (.terrain) | ✔️ Web Map Service (WMS) |
| ✔️ Batched 3D Models (.b3dm) | ✔️ Bing Maps |
| ✔️ Composite Tiles (.cmpt)** |
* Only glTF 2.0 is supported in Unreal. If you are using a tileset containing glTF 1.0 data, see this forum thread.
** Composite Tiles may not load if they contain .pnts or .i3dm data.
See also:
Can I download datasets from Cesium ion?
Assets that you upload to Cesium ion can be downloaded using Cesium ion's Archive feature. Assets from the Asset Depot (such as Cesium World Terrain and Cesium OSM Buildings) can not be downloaded.
We are evaluating the best way to enable offline access to Cesium content like Cesium World Terrain and Cesium OSM buildings. You can contribute to the conversation on the Cesium for Unreal Community Forum.
What is a 3D Tileset?
3D Tiles is a specification for streaming and rendering massive 3D geospatial content such as photogrammetry, terrain, BIM/CAD models, and other 3D models. 3D Tilesets consist of a set of tiles, arranged in a hierarchical level of detail, that represent the position, appearance, and other metadata properties for each feature in the tileset.
Loading your models as 3D Tilesets can improve the performance and rendering of your application by loading high detail close to the camera, and lower detail further away.
3D Tilesets are loaded in Unreal using the Cesium3DTileset actor. New tilesets can be added to your level from the Cesium panel or the Cesium ion Assets panel.
See also:
What is a Raster Overlay?
A Raster Overlay is an imagery layer that can be draped over a tileset. You can add a Raster Overlay to a tileset by selecting the tileset in your level and adding a Cesium Raster Overlay component.
Cesium for Unreal currently includes five different Cesium Raster Overlay components.
For tiled imagery like satellite or rasterized map data
- Cesium ion Raster Overlay streams from Cesium ion. It requires a Cesium ion asset ID and an ion access token.
- Cesium Tile Map Service Raster Overlay loads imagery tiles in the TMS format from other file services or your local disk.
- Cesium Bing Maps Raster Overlay connects to the Bing Maps API. It requires a Bing Maps Key and allows for switching between several different map styles. Your Cesium ion subscription includes access to Bing Maps which can be directly used with the Cesium ion Raster Overlay component.
There are also two other raster overlays that do not load imagery, but serve other functions.
- Cesium Polygon Raster Overlay can be used to clip tilesets or apply material effects in custom areas. It is used with Cartographic Polygons.
- Cesium Debug Colorize Tiles Raster Overlay randomly colors the loaded tiles, which is useful for debugging purposes.
See also:
What is the water mask? How do I enable the water mask on Cesium World Terrain?
The water mask is a global layer for Cesium World Terrain that designates major water bodies. The water mask covers most oceans and seas, but may not include all lakes, rivers, or other small water bodies. In Cesium for Unreal, the water mask can be turned on to render a water effect on oceans and seas.
To turn on the water mask in your level, select Cesium World Terrain. In the Details panel, find the Enable Water Mask property and make sure it is checked.
Default Cesium World Terrain (left) and Cesium World Terrain with the water mask enabled (right)
Can I hide parts of a tileset?
You can hide tilesets in user-defined areas by using Cartographic Polygons. Visit the Cartographic Polygon tutorial to learn how to hide parts of tilesets.
How do I load tilesets offline?
You can load tilesets from disk or from a local server. Tiles loaded in these ways will not need internet access to appear in Unreal. Note that Cesium World Terrain and other Cesium ion tilesets are not currently available offline.
To load datasets from disk, fill out the tileset’s URL field with the filepath to your data. Some formatting requirements must be followed. Visit our Adding Datasets tutorial for a step-by-step walkthrough of loading local data, and to learn more about URL formatting requirements.
You can also load datasets from a local server, including localhost. The Adding Datasets tutorial contains a section on loading assets from a local server.
How can I optimize my scene's performance?
There are several ways to improve tileset performance.
The following settings can be found in the Details panel on each tileset.
- The Maximum Screen Space Error controls the level of detail of the tileset. Higher values in this field will allow lower resolution tiles to be loaded, improving performance. You can set the Maximum Screen Space error both on tilesets and on Raster Overlay components.
- In the Tile Loading section, there are several different settings that can be adjusted. Hover the mouse over each option for a description of the setting.
- The Create Physics Meshes setting can be disabled if you are not using physics or collision in your scene. Disabling this setting will improve tile loading performance.
- On Cesium World Terrain, disabling the Enable Water Mask setting will reduce material overhead.
The more tiles you load, the more work your computer will need to do. Scenes with high-speed travel, rapid camera movement, or multiple cameras over different areas of a tileset will all result in more performance overhead. Keeping this in mind when designing your applications can result in a smoother experience.
Beyond Cesium tilesets, your project’s mechanics, animation, lighting, materials, and many other factors can impact performance. Learning more about Unreal Engine best practices can help you optimize your scenes.
See also:
- Unreal Engine performance and profiling documentation
In this section:
- Why is my scene bright white?
- Why is my scene black?
- How do I prevent characters or other objects from falling through the terrain?
- Why can’t I see my data in the viewport?
- Why did my tilesets disappear, if they were previously rendering?
- How do I access debug information about my tileset?
- Why can’t I see my tilesets when I use remote desktop software?
Why is my scene bright white?
A white scene can occur if your lighting is too bright for your project’s exposure settings. Open your Project Settings and make sure the option Extend default luminance range in Auto Exposure settings is enabled.
If that setting is missing or you would prefer to lower the lighting intensity, see the CesiumSunSky reference.
Why is my scene black?
A black scene can occur when lighting is not present in the scene, or when the light is illuminating the other side of the earth.
First, ensure that there is lighting present in your scene, like CesiumSunSky or a directional light.
If you are using CesiumSunSky, try adjusting the Solar Time property in the Details panel.
If you are using a directional light, try rotating the directional light until it is facing down to your scene.
How do I prevent characters or other objects from falling through the terrain?
Cesium for Unreal optimizes by unloading tiles that are not in view. This means that physics objects that are not on screen run the risk of falling through the tileset.
There are several workarounds, including:
- Disable physics simulations on an actor when the user is not interacting with the actor.
- Add additional cameras to the scene to keep tiles fully loaded where needed. This may impact performance.
- Place non-tileset meshes like ground planes under critical areas. This approach works best in flat areas.
Why can't I see my data in the viewport?
There are several possible causes for data not appearing in the viewport. Follow the steps below to diagnose the issue.
- Check your setup. Confirm that access tokens, asset IDs, URLs, and filepaths are correct. If you’re using remote desktop software, see this question.
- Make sure that the tileset is a supported data type. Not all 3D Tileset types are supported in Cesium for Unreal. Notably, point clouds and mesh tilesets using glTF 1.0 are not supported.
- Look for error messages. Open the Output Log (Window>Developer Tools>Output Log).
- Restart Unreal Engine. Restarting Unreal or your computer can sometimes resolve issues.
Still having problems? Search the Cesium Community forum and Github issues. You can narrow down the search by including error messages, type of tileset, and other information about your setup.
If you are unable to find an answer that resolves your issue, please create a new post on the forum. Include as much of the following information as you can to help others answer your question.
- Error logs (pasted as text, not screenshots)
- Information about the dataset you are trying to load - e.g. type, host, how it was created
- Any other information that may be relevant
See also:
Why did my tilesets disappear, if they were previously rendering?
The most common reason for tilesets disappearing is due to access tokens. If you created your project from the Cesium for Unreal Samples, you may still be using the Sample project default token. The default token changes every month, and when a token is no longer valid tilesets will not load. Make sure that all tokens you are using in the project are up to date and allow access to the relevant tilesets.
If this was not caused by access tokens, go to Why can’t I see my data in the viewport?
Why can't I see my tilesets when I use remote desktop software?
Tilesets may not appear when accessing an Unreal project from a remote computer. This occurs because Unreal Editor automatically disables realtime updates to the viewport when using remote viewing software. 3D Tilesets require realtime updates to load and display in the viewport.
You can re-enable realtime rendering during a session by selecting the dropdown arrow in the top left corner of the viewport. A Viewport Options menu will appear. Check the Realtime option, and tilesets should display again.
You can change this setting by default in the Editor Preferences window. Find and uncheck the Disable realtime viewports by default in Remote Sessions setting.
Didn’t find the answer you were looking for? Visit the Cesium Community Forum to browse questions and topics from other users, and create your own.