iTwin 3DFT Plugin for Unreal Engine

This repository contains the legacy iTwin 3DFT Plugin for Unreal Engine for viewing iModels streamed directly from the iTwin Platform. It also includes sample projects that demonstrate how to use the plugin and how to connect to various APIs of the iTwin platform.

You can get more information about the state of the plugin and the iTwin Mesh Export Service here.

Warning: Deprecated Tech Preview, soon to be removed

This project is a Technical Preview and will not be available for download after the end of June. Do not use in production.

The 3DFT plugin was Bentley’s first testing environment for streaming iModels from the cloud. We took the experience we collected from this tech demo and created a new plugin with even better technology and performance than the 3DFT technology which will turn into a full product with long-term commitment and constant updates.

This new plugin is the iTwin for Unreal plugin and it supersedes the 3DFT plugin. You can access the GitHub repository here.

License

This repository is licensed under an Apache license, except for the iTwin 3DFT native library which is licensed under a BENTLEY RIGHT-TO-RUN AUTHORIZATION license.

Table of contents

1. Pre-requisites
2. Usage
3. Limitations
4. Samples
5. Compile the project manually and debug it
6. iModel Actor Properties
7. Technology overview

Pre-requisites

Mac

Please, follow the url links to get detailed instructions on how to install the described applications.

1. Install Unreal Engine (we only support 5.0.3 at the time of writing this documentation)

2. Install XCode 13.x (Unreal Engine only supports XCode up to version 13.x at the time of writing this documentation, so you cannot install version 14 released during summer 2022.)

3. After XCode is installed, launch it to make sure it installs the command line tools and you accept the necessary terms and conditions. You can then close XCode.

4. Open the .uproject file at the root of this repository. Unreal Engine should offer you to build the plugin from source and proceed to load the editor.

5. If Unreal Engine shows errors when loading the .uproject, compile it manually.

Windows

Please, follow the url links to get detailed instructions on how to install the described applications.

1. Install Unreal Engine (we only support 5.0.3 at the time of writing this documentation)

2. Install Visual Studio or Visual Code.

3. Open the .uproject file at the root of this repository. Unreal Engine should offer you to build the plugin from source and proceed to load the editor.

4. If Unreal Engine shows errors when loading the .uproject, compile it manually.

Usage

1. Create and configure your iTwin Platform account.

   a) Go to the iTwin Platform developer portal and create an account.

   b) Go to My Models and create a new iModel.

   c) Go to My Apps and register a new iTwin App:

   • Application type: Desktop / Mobile
   • Redirect URIs: http://localhost:24363/authorize
   • Scopes:

     savedviews:read imodels:read mesh-export:read itwins:read mesh-export:modify imodelaccess:read

     

2. Configure your iTwin Client ID in the plugin:

   \Plugins\iTwin\Source\iTwin\Private\iTwinPlatform\iTwinAuthorizationService.cpp

   static constexpr auto iTwinAppId = TEXT("your_client_id_goes_here");

   Tip: delete the folders Plugins\iTwin\Binaries and Plugins\iTwin\Intermediate to "force" UE to recompile the plugin the next time you open the project. If not, your changes may not be reflected.

3. Open the sample iTwinExample project located in the root folder of this repository (UE should automatically compile the plugin).

4. Explore the sample levels iModel-Selection-Menu and Manual-iModel-Placement to see the plugin in action.

5. To use the plugin in your own projects, simply copy & paste the plugin in your projects and add the actor(s) provided by the plugin to your levels as shown in the sample levels.

6. Configure the actor(s) settings and the level blueprints to suit your needs.

Login and Access Authorization

Bentley iTwin APIs and SDKs require the end user to give consent to your application to retrieve and use data on user's behalf.

The plugin will automatically open a browser window to let the user login to the iTwin platform and authorize the plugin to access his data.

When the user accepts, the plugin automatically connects to the iTwin server, so the user can now close the browser window.

Model optimization

When the selected Model is opened for the first time, the 3D model is optimized so that it can be viewed at high speed.

The next time any user opens it, it will already have been optimized and will open very quickly.

Limitations

• Textures are not supported
• UV channels are not exported
• Material mapping supports Base Color, Specular, Roughness and Metallic
• Reality Data is not supported
• Saved views API is minimally supported (only certain camera transitions are supported to demonstrate how to transform iModel coordinates)
• Issues API is not supported
• Scheduling animation is not exported.

Samples

iModel-Selection-Menu

This sample demonstrates how to list your iTwins/iModels/Changesets and open them dynamically.

Users can navigate using saved views or click on elements to query its unique value.

Manual-iModel-Placement

This sample demonstrates how to place a specific iModel directly into the scene.

For that, the iModelId and ChangesetId has to be set.

The plugin will automatically optimize the model if necessary before loading it.

Compile the project and debug it manually

Mac

You can generate the XCode project files from a terminal using a script provided by the Unreal Engine. This will generate a XCode Workspace which will allow you to build the plugin and run it from the debugger.

1. Open a terminal and run the following command : /Users/Shared/Epic\ Games/UE_5.0/Engine/Build/BatchFiles/Mac/GenerateProjectFiles.sh /path/to/your/iTwinExample.uproject

2. Locate the file named iTwinExample.xcworkspace which should have been created in the same location than the .uproject file and open it. This should open XCode.

3. Click the run button in XCode, this should build and start the Unreal Engine Editor.

4. Find more information about compiling game projects here.

Windows

1. Generate the Visual Studio project file by right-clicking on the .uproject file and selecting Generate Visual Studio project files.

2. You can also generate them manually following these instructions.

3. Use the Debug command to run and debug the project. It will automatically run the Unreal Editor with your project loaded.

4. Find more information about compiling game projects here.

iModel Actor Properties

• Loading

  • Loading Method:
    • Automatic: this method will automatically optimize if necessary and load the specific iModel/Changeset.
    • Manual: this method will load the specific export.
  • Object Loading Speed: defines the speed of creation of meshes. Big values produce drops on the framerate.
  • Requests in Parallel: defines the number of tiles that are downloaded in parallel.
  • Use Disk Cache: check this to let Unreal cache the downloaded parts of the iModel. This will speed-up the loading of the iModel the next time you visualize it.

• Render Materials

  • Opaque material: you can select your own materials to expand the capabilities of the renderer models.
  • Translucent material: the same but for translucent materials.

• Optimization

  • Max Triangles per batch: defines the maxium number of triangles that a mesh can have.
  • Shadow Distance Culling: after this distance, objects don't have shadows (improves rendering optimization)

• Geometry quality

  • Near Range: defines the geometry density of the near range objects.
  • Far Range: defines the geometry density of the far range objects.

• Elements

  • Element infos: Manual configuration of elements to change their visibility, offset position and pixel offset.

• Material Overrides

  • Material Overrides: change the visual aspect of a material.
  • Override Materials: activate the material overrides
  • Hide Translucent Materials: do not render translucent objects
  • Ignore Translucency: render all objects as opaque
  • Debug RGB: activate the "debug" mode
  • Default Material: changes the aspect of all the objects in general.

Technology Overview

Engineers are sitting on some incredible models that are too complicated to render in real-time using traditional methods.

3DFT (3D Fast Transmission) is a new rendering codec that rapidly optimizes/compresses large 3D models for high Unreal Engine framerates, without data loss.

Aimed to achieve the ”4 F’s” (fast encoding, fast transmission, fast decoding, fast rendering) 3DFT defines encoding and decoding methods, a persistence format and a rendering architecture.

3DFT is part of The Bentley iTwin platform, a collection of APIs and services designed to help you build digital twin applications and bring them to market quickly. It provides the foundation for building SaaS solutions to design, build, and operate infrastructure assets. Accelerate application development by letting the iTwin platform handle data integration, visualization, change tracking, security, and other complex challenges. Whether you are building SaaS solutions for your clients advancing their digital twin initiatives, or implementing bespoke solutions in your organization, this is the platform for you.

3DFT streams the 3d models stored in the iTwin platform to Unreal Engine directly, without the need to export/import them. The data streaming optimizes the transmission of data so only a fraction of the size of the model is transmitted, instead of exporting/importing the whole model.

If you want to learn more, click of the image to watch the session about 3DFT that we did at the Unreal Fest 2022.