Processing iModel metadata in Unreal Visual Dataprep


This tutorial guides you through the basics of using Visual Dataprep with iTwin metadata exported using the iTwin Exporter for Datasmith.


Skill level:



10 minutes


This tutorial assumes that you have:

1. Import your Datasmith content into a new Dataprep recipe

Create a new Dataprep recipe. Right-click within the content browser. Under Create Advanced Asset, select the Dataprep asset category, then the Dataprep Asset type.

Double-click the new asset in the content browser to open it in the Dataprep Recipe Editor. At the top right in the Inputs section, press the plus button, then browse for the .udatasmith file created during your export. This adds your Datasmith content to the Recipe editor.

When the import is complete, select any actor in the viewport. In the Property Pane on the right side, scroll down to Asset User Data > Datasmith User Data to inspect fields that are available to match on, as well as compare those values on different objects.

inspect metadata properties in the dataprep editor

It may be helpful to read the text in read-only entries using the tooltips. To do so, hover over them, or even right-click to be able to copy the text. For clarity, the above image has a few sample labels annotated.

Alternatively, inspect your element properties in the iTwin Exporter for Datasmith in the Properties tab. Be aware that names here will not be the same as names in the metadata in Unreal. To avoid name collisions and because Datasmith has specific rules for metadata entry names, we have added prefixes to the names in Unreal. Because of this, it is recommended to find the entry name in Unreal once you have the metadata you intend to match on.

inspect metadata properties in the itwin exporter for Datasmith app

2. Substitute a material

Dateprep recipes allow you to programmatically modify your scene. For example, quickly substituting pieces of an imported scene, such as the materials used or placed actors. For demonstration purposes, let’s substitute a default material with one of Unreal’s high-quality starter content materials.

Search through your iTwin’s imported metadata for something you want to match on. In our iTwin we found the objectStructualUsage_StructuralMaterial metadata property, and see that it has a value of Timber for our inspected actor, which we will filter on to make sure all “Timber” items use a high-quality wood material. Add a Metadata Value filter and set the match type to Exact Match. Then, add a Set Material operator and choose from any material in your project.

Your metadata will not necessarily match the properties we use here. The metadata in your iTwin is entirely dependent on the source files synchronized to it. If you expect to see specific metadata in your iTwin but do not see it in the viewer's Properties tab, please ask why at the iTwin.js Github Discussions page.

When you are satisifed with your changes to the Dataprep recipe, press the Execute button to run the operator graph and make your material substitution visible in the viewport.

The execute button in the dataprep editor

3. Substituting materials with a table

For managing substitution of many materials, it may be useful to use Dataprep’s Substitute Material By Table operator. Add the operator and in its parameters click the Material Data Table parameter’s asset selection. Under the Create New Asset section at the top, click Data Table. In the Pick Row Structure dialog, pick MaterialSubstitutionDataTable and choose the folder to create the new asset in. Double-click the asset’s thumbnail in the operator parameters to quickly open your new table in the data table editor. Click the Add Row button to add a material substitution which consists of a search string, search match type, and the target material. Unreal also supports loading table rows from CSV and JSON data from the Details Pane in the data table editor.

This concludes our demonstration of using iTwin metadata in Dataprep. Dataprep has many more operators for common processes like simplifying, decimating, and merging geometry, or populating surfaces with high-quality assets such as animated foliage assets. You can also create your own Dataprep operators with Unreal’s Blueprints. The full Dataprep documentation from Unreal can be found here.

More resources that you may like

Extended functionality and workflow descriptions in iTwin Exporter for Datasmith
Follow this tutorial to get iModel data into the Datasmith format as a combined mesh.
Unreal's documentation on Visual Dataprep