Skip to main content

Visualize Metadata

Starting with Cesium for Unreal version 1.5.0, users can now access 3D Tiles metadata in Unreal Engine. 

Metadata is information embedded in tilesets that contains information about the whole tileset or features within the tileset. Access to this information enables countless possibilities, such as displaying the address of each building, automating location-aware game mechanics, or altering the look of a building based on the year it was built.

The first three sections of this tutorial provide step-by-step instructions for accessing metadata. The fourth section details the Blueprint nodes designed for metadata. To get straight to the reference, click Reference: Blueprint Library in the left sidebar.

You’ll learn how to:

  • Access metadata of a tileset with Blueprint
  • Select features in play to visualize feature metadata
  • Use nodes from the Cesium Metadata Blueprint library in your Blueprints

Metadata shown in a UMG widget from Cesium for Unreal Samples.

Information

Want to see metadata in action without implementing it yourself? Check out the Cesium for Unreal Samples. Explore the premade sample scene and UMG widget. Feel free to experiment with it or include it in your own projects.

Prerequisites

  • Unreal Engine (4.26 or later)
  • The Cesium for Unreal plugin (1.5.0 or later)
  • Know how to set up a basic Cesium for Unreal application. Check out our Cesium for Unreal Quickstart guide for instructions on getting started with the Cesium for Unreal plugin.
  • A Cesium ion account. If you don’t have one, you can log in with your Epic Games account.

1Add the New York City tileset

This tutorial uses a tileset of New York City 3D buildings from Cesium ion, with over 1 million buildings. Each building in this tileset has metadata properties, including height, age, and ownership.

1Start with a scene that includes Cesium World Terrain, CesiumSunSky, and a DynamicPawn. You can create a scene like this by following the Quickstart guide.

2Make sure you’re connected to Cesium ion in the Cesium panel.

3Open the Cesium ion Assets window. If you don’t see the window in the Unreal Engine Editor, open it using Window/Cesium ion Assets, or press the Add button in the Cesium panel.

4Find New York City 3D Buildings in the asset list and select it. Click Add to Level.

Information

Is New York City 3D Buildings missing from the asset list? Visit the New York City 3D Buildings Asset Depot page and click Add to my assets. Then return to Unreal Engine. Click the blue Refresh button in the top left corner of the Cesium ion Assets panel to refresh the asset list.

5Double-click on the CesiumGeoreference in the World Outliner. In the Details panel, set the Georeference Origin to the following coordinates:

Origin Latitude: 40.700001
Origin Longitude: -74.002998
Origin Height: 418.0

At this new location, you’ll see the tileset you just added.

6Right-click on the DynamicPawn in the World Outliner. Select Snap Object to View from the menu that appears to make sure the game will start at the new location.

2Set up interaction

1Open the Level Blueprint Event Graph.

2Right-click in an empty space on the graph and search for “Left Mouse Button.” Create a Left Mouse Button input node.

3Click and drag the DynamicPawn actor from the World Outliner to the Level Blueprint graph. This will create a reference to your DynamicPawn in the Level Blueprint.

4Click on the blue pin of DynamicPawn and drag out to an empty spot on the graph. Release the mouse. Search for “Get Camera View” in the menu that appears. Select this node.

5Connect the Left Mouse Button input node to the Get Camera View node. Now, you should have a node graph that obtains the camera view from the Dynamic Pawn when the left mouse button is pressed.

6Drag out from the white pin of Get Camera View to create a LineTraceByChannel node.

7You’ll need to add a start and end for the line trace. Drag out from the blue DesiredView pin of Get Camera View and create a Break MinimalViewInfo node. Connect the yellow Location pin of Break MinimalViewInfo directly to the Start pin of LineTraceByChannel.

8To get the End location, create a GetRotationXVector node from the Rotation pin of BreakMinimalViewInfo.

Create a vector * float node and multiply the RotationXVector return value by 500000.
Create a vector + vector node to add the result to the camera location.

Depending on your application, you may want to set the multiplier of the RotationXVector higher or lower.

9Return to the LineTraceByChannel node. Change the Draw Debug Type to For Duration. Now, you’ll be able to see your line traces in the world. If you wish, you can also change Trace Color and Trace Hit Color. If you don’t see these options on the LineTraceByChannel node, click the small arrow near the center bottom of the node to expand the pins.

10Save and compile the Blueprint.

Now, you should have a blueprint that creates a line trace from the center of your screen and can collide with the world. 

Test it out by playing in the editor. Left click to cast a ray from the center of your screen. 

Right now, nothing happens if the line trace hits something, but in the next step you’ll add logic to print metadata about the feature that the line trace hits.

3Use Blueprint to access metadata

In order to retrieve the relevant metadata, the Blueprint will need to know which building the line trace is pointing at. In the steps below, you’ll learn how to get the Face Index and Hit Component of your line trace. Both of these values are used to look up the correct metadata for a building. 

1From the Out Hit pin of LineTraceByChannel, create a Break Hit Result node. Click on the arrow at the bottom of the node to expand the node and show all of the output pins. You’ll only need two of them: Hit Component and Face Index.

Hit Component represents the geometry component that the line trace has found. Face Index is the ID of the specific geometric face of the Hit Component. For example, the Hit Component represents the building model, and the Face Index represents the specific face (perhaps a window or wall) that the line trace hit on the building.

2Create a Get Metadata Values as String for Face node. Connect Hit Component to Component and connect Face Index to Face ID.

This node returns a table of metadata for a given face, in string format. This data is expressed in Unreal Engine as a Blueprint Map. The map consists of the metadata property name, or key, and the property value. Get Metadata Values as String for Face converts the values from their original type to a string, which is convenient for the purposes of printing these values on the screen. However, the conversion means that the original data type is lost.


If you require the original data types, use the node Get Metadata Values for Face. Visit the Metadata Blueprint reference in the section below for more information.

3From the output map, create a Keys node, which returns an array of every key in the table. Create a For Each Loop node to cycle through that array. Make sure to connect the Exec pins of these new nodes.

4Create an Append node to append strings. In order to view the metadata in an easily readable format, you’ll append a key to its value with a colon and space between the two.

Drag the Array Element from For Each Loop to the A pin of the Append node.
In the B pin, type a colon and a space (“: “). 
Click Add pin on the Append node to add a third input.

5From the output of Get Metadata Values as String for Face, create a Find node. Connect the Array Element from For Each Loop to the empty pin on the Find node. Finally, connect the output of Find to the C pin of Append.

6Now, all you have to do is print the result. Create a Print String node in the Loop Body of For Each Loop. Connect the Return Value of Append to the In String pin of Print String.

7Be sure to compile and save your Blueprint. Then, return to the editor and test it out! You should see metadata properties in the top left corner. You can edit the Print String node to change the color of the text or adjust the duration that it stays on screen.

Reference: Blueprint library

There are three different nodes to retrieve metadata from a given component. Each one is detailed in its own section below.

  • Each of the above nodes requires a Primitive Component, retrieved in this example from the line trace Hit Result
  • Face ID is retrieved using the Face Index of the line trace Hit Result.

Some tilesets with metadata have different metadata per geometric face or even per geometric vertex of a mesh. 

Get Metadata Values for Face and Get Metadata Values as String for Face can show the specific metadata of a requested face, while Get Primitive Metadata retrieves the metadata for the entire mesh component. If the tileset does not have unique per-face metadata, the nodes requiring a Face ID will still work, but they will return the same values for every face of the component. 

Get Metadata Values for Face

  • Gets the metadata for a face of a Primitive Component, preserving the original data type.
  • Returns a map of key-value pairs.
  • If the primitive has multiple feature tables, the node returns the metadata of the first feature table.
  • Metadata keys can be retrieved using a Keys node. Metadata values can be retrieved by using a Find node and providing a key.

Get Metadata Values as String for Face

Because this method converts the properties to strings, this node is primarily used for printing or displaying data on screen.

  • Gets the metadata of a face of a Primitive Component as a map of strings.
  • Returns a map of key-value pairs.
  • If the primitive has multiple feature tables, the node returns the metadata of the first feature table.

Metadata keys can be retrieved using a Keys node. Metadata values can be retrieved by using a Find node and providing a key.

Get Primitive Metadata

  • Gets the metadata of a Primitive Component.
  • Returns a Cesium Metadata Primitive Structure, which can contain multiple feature tables.

Use with a Get Feature Tables node or Get Feature ID for Face node.

Get Feature ID for Face

  • Gets the Feature ID given a Feature Table and a Face ID. 
  • Use a Get Feature Tables node to retrieve the feature table. Use the Face ID from the hit’s Face Index.

Get Feature Tables

  • Gets an array of all feature tables belonging to a given metadata primitive component.
  • Select a specific feature table using a Get (a copy) node. 
  • Use this node to retrieve information about a specific feature table, such as the feature ID for a given vertex (Get Feature ID For Vertex), the number of features in the table (Get Number Of Features), or the map of properties (Get Properties). You can also retrieve maps of metadata values from feature IDs with Get Metadata Values for Feature ID and Get Metadata Values as Strings for Feature ID.

Get Properties

  • Gets a map of all properties in a given feature table.
  • The output properties can be used with the property Get nodes outlined below.

Get Metadata Values for Feature ID and Get Metadata Values as Strings for Feature ID

  • Gets a map of property names and property values, given a feature table and a feature ID.
  • Get Metadata Values for Feature ID returns the values in their original data type, which can be used with the generic value Get nodes outlined below.
  • Get Metadata Values as Strings for Feature ID converts the values from their original type to strings, which is useful for printing or displaying the metadata.

Getting Values

Along with the above nodes, there are a variety of Get nodes that retrieve information from metadata properties or tables. 

While metadata properties can come in a variety of types, only some types are available in Blueprint. You can retrieve metadata as a Boolean, Byte, Integer, Integer64, Float, String, or Array. The node will attempt to convert values to the requested data type. 

If you require the original type, you can use a GetTrueType method to retrieve the actual underlying type.

You can also access a “best fit” Blueprint-supported lossless data type with GetBlueprintType. For example, if the original type is a Double, it will be converted to a String, which is the only lossless option available in Blueprint.

These conversion functions are available for metadata properties, arrays, or generic values. You can supply a Default Value in case the input is invalid or can’t be converted.

  • Property Get functions require an input property (from GetProperties) and a Feature ID (from GetFeatureIDFromFace or GetFeatureIDFromVertex). 
  • Array Get functions require an input array (from GetArray (property) or GetArray (generic value)) and an array index.
  • Generic Value Get functions only require an input value (from a map value obtained with Get Metadata Values for Face or Get Metadata Values for Feature ID). 

Next Steps

How are you using metadata in your Cesium for Unreal projects? Tweet your creations to us @CesiumJS

Further Reading:

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.