iTwin Exporter for Datasmith

The iTwin Exporter for Datasmith provides a viewer interface and tools to load and export iTwin data as a .udatasmith file and the corresponding Datasmith _Assets directory. Use Unreal Engine's Datasmith importer plugin and our iTwin Datasmith plugin to import the exported datasmith content. The Datasmith scene can be created with all of your geometric element metadata embedded for accessing at runtime in Unreal Engine and at import time when using Visual Dataprep to process the scene during import.

Table of Contents

1. iTwin Unreal Datasmith Plugin
   1. Plugin compatibility
2. Animations and schedule scripts
   1. Combined-mesh export animation support
   2. Non-combined-mesh export animation support
3. Performance considerations
   1. Combined-mesh export is the default
   2. Non-combined-mesh export does not preserve the element hierarchy
   3. Filtering exported elements
   4. Filtering with Visual Dataprep
4. Materials
   1. Custom materials with visibility-animated combined-mesh exports
5. Metadata
   1. Limitations
   2. Animation data
6. Command line interface
   1. Using the command line interface

iTwin Unreal Datasmith Plugin

The iTwin Exporter for Datasmith helps you install the iTwin Unreal Datasmith Plugin providing C++ and Blueprint APIs for controlling the animations of your iTwin. This plugin also provides the default materials for your scene. See the Blueprint API reference.

Plugin compatibility

The plugin is compatible and has been tested with Unreal Engine versions 4.26.1 through 5.0.0. The plugin may successfuly recompile on older versions but there is a bug in the Datasmith importer for those versions that could impact some animations.

Animations and schedule scripts

Combined-mesh export animation support

In combined-mesh exports we currently support

• cutting plane (growing) animations
• color animations (such as SYNCHRO appearance profiles)
• visibility animations
• transformation animations such as rotation, translation, and scaling
• transformation-animated (moving) objects do not support color or cutting plane animations

All non-transformation animations for combined-mesh scenes are performed by special dynamic materials applied to your meshes by the ScheduledActor class from the iTwin Unreal Datasmith Plugin, which exposes a Blueprint and C++ API for managing the animation state. All transformation-animated objects are exported as separated objects and animated using an Unreal which you must add to the scene and manually manage due to limitations in the Datasmith API. Consult Unreal Engine's Sequencer Overview for more information on level sequences.

Non-combined-mesh export animation support

We do not currently support cutting plane (growing) animations or color animations in non-combined mesh exports due to limitations in the Datasmith API. Visibility and transform animations are supported.

An Unreal Level Sequence provides animations for non-combined mesh scenes. You must add a level sequence actor to the scene yourself and control it using Unreal's sequencer. Consult Unreal Engine's Sequencer Overview for more information on level sequences.

You may notice useless visibility tracks on some static meshes, this is an issue in Datasmith, and we are working closely with Epic to resolve it.

Performance considerations

Consider the following when trying to improve the performance of your scene. But always be aware that hardware is often a significant bottleneck when performing intense graphical work, such as working with scenes in Unreal Engine.

Combined-mesh export is the default

Many scenes are too large to handle directly in Unreal without manually processing them. As such, we recommend using the "combined meshes" feature during export. Combined-mesh exports combines all of the geometry in your scene into one static mesh. You can then apply high-fidelity materials to your material slots; see the Materials section for limitations.

If you have an extremely high amount of instanced geometry or pieces of your geometry are too distant to be visible together, you may benefit from performing a separate or non-combined mesh export. Non-combined mesh export enables frustum culling of separate objects in the scene which generally increases performance in those cases, and makes it easier to edit your objects in Unreal.

Non-combined-mesh export does not preserve the element hierarchy

iModels meticulously split geometry into a sprawling hierarchy of elements. While this is great for your data and its organization, translating them into Unreal actors can be much less performant than collapsing the hierarchy. As such, the hierarchy of elements in your iModel is not preserved since it would require a lot of empty actors; it is instead flattened into a list of geometry-containing elements. This ensures speedier imports and the best runtime performance possible, even when using a non-combined-mesh export.

To use the hierarchy information when writing your own Visual Dataprep recipes, every mesh element of the actor scene has a metadata property ElementPathByLabel, a forward-slash delimited string of User Labels (or Ids) of parent elements and models to reach your element in the scene. For instance, /0x1/0x20000000003/Site.dwfx/Walls (13)/Basic Wall (13)/Site Perimeter Fence (13)/Basic Wall [613789].

Filtering exported elements

Hide elements, models, and categories in the viewport using the element tree on the right or, once an element is selected, with the visibility tools in the top-left horizontal toolbar. Once you've hidden the objects you want to filter, use the "Export Current View" tool in the top-left horizontal toolbar to export and filter those elements.

Use the Saved-Views Widget to save your viewport state if you want to re-export the scene again with these parts hidden. Use advanced export to write ECSQL queries to customize which elements are filtered using custom logic such as geometric queries.

Filtering with Visual Dataprep

Another technique for getting more performance out of your iModel geometry in Unreal is using Datasmith's Visual Dataprep to process your scene. Use Dataprep recipes to filter out obscured and unnecessary actors and to optimize geometry with Datasmith's support for the proxy geometry tool.

Reducing your actor count, getting rid of any unnecessary geometry, and optimizing unnecessarily dense geometry will all help lower the runtime costs of your scene.

Materials

In the combined-mesh export, differently colored or textured parts of your iModel will be split into different material slots; geometry with the same underlying color but different textures in the All meshes, combined or not, store the original color of underlying graphics in the corresponding mesh vertices for use in materials.

If dividing material slots further would improve your workflow, either by category and model or by using ECSQL, please vote for that feature on our ideas portal.

Custom materials with visibility-animated combined-mesh exports

Materials need to opt-in to the visibility animation if controlled by the ScheduledActor. To do so:

1. In the lower right corner of the Content Browser, press View Options, and mark the Show Plugin Content checkbox.

   

2. Open the the offending material in the material editor, set its blend mode to "Masked" (or if it's transparent, keep it).

   

3. Add a material function node, set it to use the iTwin Datasmith Importer Plugin's MF_SynchroVisibilityAnimate material function, and connect it to your material's opacity. You may want to blend (e.g. with a multiply node) the visibility animation's opacity with any other opacity your material is already using.

Metadata

There are multiple options for exporting metadata. Due to how metadata is attached in Unreal Engine, metadata is only available when not using the "combine meshes" option. The default metadata export setting is "element metadata", which includes data directly attached to the exported geometric elements.

Limitations

The "all metadata" option will bring in all data corresponding to all exported elements from the iModel, but can be significantly slower than the default option. In all cases, because only geometric elements are exported, the metadata of other elements in the hierarchy is not brought into Unreal.

Animation data

The ScheduledActor and the SceneMetaData actor when exporting will contain a metadata entry ScheduleScript, which will contain the entire scene's animation data in a JSON format which comes from the iTwin.js RenderSchedule.Script.

The ScheduledActor actually parses and uses this at runtime to perform the combined-scene animation, and that code ships with the plugin and is therefore freely available to view and extend in your own projects.

Command line interface

The iTwin Exporter for Datasmith application comes with a command line interface, sometimes called the CLI. This can be useful in advanced automation cases. With it, you can run an export without opening the graphical user-interface of the application at all, as well as any amount of filtered exports in a row without any user interaction.

Using the command line interface

Because the iTwin Exporter for Datasmith is only available for the Windows operating system, we recommend using PowerShell to use the command line interface of programs such as the iTwin Exporter for Datasmith.

You must first find the application's executable file, it is typically installed at C:\Users\<YOUR_USER_NAME>\AppData\Local\iTwinDatasmithExporter\app-<YOUR_APP_VERSION>\iTwinDatasmithExporter.exe.

Open a terminal with a shell, such as PowerShell, or Command Prompt, both of which come with modern Windows, and try the following command. Be sure to replace the executable path containing <YOUR_USER_NAME> and <YOUR_APP_VERSION> with the complete path you find on your local computer.

C:\Users\<YOUR_USER_NAME>\AppData\Local\iTwinDatasmithExporter\app-<YOUR_APP_VERSION>\iTwinDatasmithExporter.exe export --help

The --help command will list all currently available options and their defaults. If you do not use the export keyword as the first argument after the executable path, the graphical-user interface will be launched instead.

Following is a sample usage of the CLI to export an online model as a combined mesh scene with a z offset of 200 (and x and y are the default offset to the center of the unreal space), all filtered by a saved view named "My Saved View".

C:\Users\<YOUR_USER_NAME>\AppData\Local\iTwinDatasmithExporter\app-<YOUR_APP_VERSION>\iTwinDatasmithExporter.exe export `
  --iTwinId b3416222-bf0f-4009-92c9-25bed16a2cc" `
  --iModelId 64b4a1e5-2f7e-4e8e-942d-314bdc274aa5 `
  --savedViewName "My Saved View" `
  --combineMeshes `
  -z 200 `
  --destination D:\Somewhere\On\Disk\my-model.udatasmith