Documentation

3D Assets Workflow

Prerequisites

  • A 3D model in FBX (.fbx) file format
  • Wikitude 3D Encoder for Windows or MacOS X

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:

  • FBX (.fbx) - max version: 7.5 (FBX SDK 2017)

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

  • Mesh types
    • Triangle-based meshes: The 3D models usually consist on a hierarchy of scenes nodes where the leaf nodes contain parts of a 3D mesh.
    • Skin-based meshes: mesh vertices a placed relative to a list of joint nodes, so-called bones.
  • Animations
    • Key-frame-based transformations/rotations/scalings applied to mesh vertices or scene nodes.
    • Bone animations for skin-based models.
  • Textures
    • All textures are converted to the PNG file format during the import. The converter accepts textures of the usual picture file formats, like JPEG, GIF, TIFF, ...
  • Lights
    • Diffuse (Lambert) lighting by specifying a directional light source.
    • Specular (Phong) lighting by specifying specular light source (direction and specular exponent). Several light sources can be used within a scene. However, only one light source (including diffuse+specular light) can be used for each mesh part, i.e., scene node. Thereby the light source which is closest to the scene node within the scene hierarchy (by traversing the tree upwards) is used. That is, a light source specified as a root node will be applied to all mesh parts in a scene. Other light sources will be applied to all mesh parts which are lower in the scene hierarchy.
  • NURBS (will be tessellated on import)
  • Transparency
    • Semi-transparent surfaces, like windows of a car, can visualized. , but only one semi-transparent layer can be visualized accordingly. The result of rendering several semi-transparent layers upon each other is
  • Model size: There is no limit on the size of the 3D models in terms of numbers of mesh vertices or textures. However, for rendering the 3D models fluently on mobile devices we recommend to keep the total file size below 5-10 MB and the number of mesh vertices below 100k.

Features that are not (yet) supported

  • bump maps/normal maps (normals are only evaluated on mesh vertices)
  • multiple light sources per node
  • multi-textured surfaces (more than one texture on the same mesh)
  • multiple transparent layers (transparent layers are not depth queued)
  • animated textures on 3D models
  • height maps

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
animation.start();

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:

  • No grouping: Each animation of the 3D model is listed and can be triggered separately. (Note! Animations on joint nodes of a skin-base mesh are still grouped into a single animation, one per skin.)

  • Grouping on root nodes: The animations are grouped on the top-level nodes of the scene (see screenshot below). The next section discusses this grouping mode in detail. Animations grouped on root nodes This allows to trigger the animations on certain mesh parts separately. Animations grouped on root nodes

  • Grouping on takes: This refers to "takes" in terms of the FBX file format which provides a list of takes where each take is regarded as a single, selectable animation (eventually affecting different parts of the 3D scene). Grouping on takes therefore groups all animations of a scene to a single animation, one per take, named according to the take's name which can be changed within the 3D modeling tool of your choice (Maya, 3ds Max, Blender, ...). Most 3D models contain only one take, the default take "Take 001" (see screenshot below). Animations grouped on takes Grouping the animations to a single "take" will trigger all grouped animations at once. Animations grouped on takes

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

  • In Blender avoid transformations on bones before you skin them to a mesh and export it to an FBX file.
  • Exporting a 3D model with animations from Blender to FBX creates additional animations for camera, lights or motion paths. These can be safely ignored.

Lighting

Ambient Light (Blender only!)

The ambient light of a scene can be changed in Blender in the World tab of the Properties view. However, this value is not exported propperly to FBX. A workaround for that is specify the ambient light via an additional point light source as follows:

  1. Add a point light to the scene
  2. Set it to "invisible" by disabling the eye icon in the Outliner view
  3. Set the color of this point light to your preferred ambient light value
  4. Set the Falloff to "constant"

Optionally you can re-name the node to "Ambient" to remember that this is not a regular light source.

Blender settings of a point light for emualting ambient light

Directional Light (Blender only!)

Directional light in Blender is provided by the light source type Sun. Note that the position of the light source does not influence the lighting at all; only the direction of the light changes a scene's appearance. The direction of the sun light source can be changed in the Object tab in the Properties view by changing the rotation values.