3D Assets Workflow


3D content within the Wikitude SDK can only be loaded from so-called Wikitude 3D Format files (.wt3). This is a compressed binary format for describing 3D content, which is optimized for fast loading and handling of 3D content on mobile devices. You still can use 3D models from your favorite 3D modeling tools (like Autodesk® Maya® or Blender), but need to convert them into wt3 file format using the Wikitude 3D Encoder (encoder for short). The Encoder loads Autodesk® FBX® files (.fbx) and exports them to .wt3 files.

This section should give an overview on how to choose the right 3D models for displaying it in Wikitude's augmented reality SDK. As Wikitude is basing 3D support on a converted file format (.wt3) it is good to follow the best practices below.

Input format

Supported 3D model files for encoding wt3 files are:

Features you can use in your 3D model source files:

Features that are not (yet) supported

Good practice

Use png textures

Textures are stored in png format within wt3 files. While Wikitude 3D Encoder takes care of automatically converting textures to png, it is good practice to use png textures in the source 3D Model file.

Use power of 2 textures

The rendering hardware on mobile devices often requires expects textures to have dimensions which are a power of 2 textures (e.g. 64x64, 128x128, ...). Other texture dimensions can lead to unexpected results. Additionally, using power-of-2 textures yields a better rendering performance.

Validate texture paths

Textures can be stored within the FBX file or referenced by a file path. In the latter case, make sure to not use absolute paths since these often are not valid on other machines. Instead use relative paths. Texture files are also searched in the directory which contains the FBX file. We therefore recommend to provide external textures files in the same directory as the 3D model, i.e. the FBX file, itself.

Keep texture sizes as low as possible

Keeping texture sizes as low as possible, while maintaining the required details has several benefits. The exported .wt3 file will be smaller and therefore quicker to load. And your application will require less memory.

Use only one light

To maintain a good rendering performance each part of your model (node) is only affected by a single light source. You may use multiple lights in the source file but at render time only a single node is selected to affect a mesh part. We make a best guess, utilizing the scene graph to assign a light to the node. If lighting is not required simply remove the lights from your source 3D model file and/or set the corresponding material properties. This helps to speed up rendering.

Resolving problems

Different 3D modeling tools encode the 3D models differently during the FBX export which may lead to different rendering results when viewing the 3D models with other applications. We therefore recommend to verify your 3D model with the free Autodesk "FBX Reviewer".

3D Model which uses joints (bones) is distorted

Create a root joint node such that all other joint nodes share the same root node.

3D Model shows up correctly in Wikitude 3D Encoder but does not show on the device.

Check the file size of your wt3 file. Limiting the textures to the lowest size that maintains the required details. Keep the number of mesh vertices reasonable such that your targeted mobile device can cope with it.

Textures are missing

Check the error/warning dialog during the import process of the model it will give you detailed information on which textures are problematic. Make sure the texture paths are valid and accessible.

Working with 3D Animations

Quick start

Export a model that contains one or more animations to a FBX file. After you load the 3D model into the Wikitude 3D Encoder the animations are displayed in a list on the right-hand side of your application window.

Animation listed in Wikitude 3D Encoder

Each row of the list contains the ID of the animation, a control button and the time that passed after you started the animation. Clicking the play button will start the animation from the beginning and play back the animation in the 3D view of the application. The stop button will stop animation and displays the frame, that was drawn last.

Check if your model looks and animates as expected and export it to a wt3 file. You need the IDs of the animations you want to use in your application. The IDs are displayed next to the animation control button (on the screenshot the animation ID is butterfly_animation). In your code you start an animation like this.

// instantiate the model object
var model = new AR.Model("butterfly.wt3");

// instantiate the model animation with the animation id
var animation = new AR.ModelAnimation(model, "butterfly_animation");

// start the animation

Export Animations

The Wikitude 3D Encoder supports different animations of 3D models. These include transformation animations on parts of a scene, including motion paths, or mesh deformer animations on mesh skins.

When exporting the model from a 3D modeling tool you have to bake your animations. For example, Maya bakes all unsupported constraints, including Maya-supported and FBX constraints, into animation curves.

Grouping Animations

Animations can be grouped in different ways which can be selected in the "Animation Grouping" sub-menu of the "Model" menu. The type of grouping affects the list of animations and the animation names, i.e., the IDs which are used to triggered animations in the Wikitude SDK:

Note: Changing the mode of animation grouping has effect only on the 3D models which are opened/imported after the change.

Creating Animation Groups

The following examples shows how to group 6 separate animations on 6 scene nodes into 2 group animations, one for each type of geometry. We assume 6 scene nodes, each with its own animation. The scene graph looks like the following and would yield 6 separate animations:

• sphere1
• sphere2
• sphere3
• cylinder1
• cylinder2
• cylinder3

For grouping all sphere animations into one animation and all cylinders animations into a second animation we create two new scene nodes which represent the parents of 3 child nodes each:

• spheres
  • sphere1
  • sphere2
  • sphere3
• cylinders
  • cylinder1
  • cylinder2
  • cylinder3

Choosing "Group on root nodes" as the animation grouping mode would yield two animations:

• spheres_animation
• cylinder_animation

Note: The grouping of the scene nodes has to done within the 3D modeling tool of your choice (Maya, 3ds Max, Blender, ...). The modified 3D model has then to exported to FBX and imported/loaded into the Wikitude 3D Encoder to take effect.

Known Issues