Processing iModel metadata in Unreal Visual Dataprep
Introduction
This tutorial guides you through the basics of using Visual Dataprep with iTwin metadata exported using the iTwin Exporter for Datasmith.
Prerequisites
This tutorial assumes that you have:
- Unreal Engine 4.26.1 and the iTwin Exporter for Datasmith installed.
- The full list of prerequisites can be found in the prerequisites section of Exporting iModel to Unreal Datasmith as a combined mesh.
- An existing Datasmith export made with the iTwin Exporter for Datasmith. If you need one, you may complete one of the following tutorials:
- An existing Unreal Engine project with the iTwin Unreal Datasmith Plugin installed.
- Depending on your Unreal Engine version, this may require Visual Studio to be installed. The prerequisites section of Exporting iModel to Unreal Datasmith as a combined mesh has instructions for recompiling the plugin.
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.
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.
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.
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.
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.