The FBX Converter reads one or more Autodesk FBX files and creates a file with models stored in JSON format accompanied with a binary file with raw data.

The JSON file created by the FBX Converter contains the following:

  • A render model. This model has a list of textures, a list of joints, a list of tags, and a list of surfaces. Each surface has a material with a type and references to the textures used. The material textures may include a diffuse, specular, normal, emissive and reflection texture. Each surface also has a set of indexed vertices. The vertices may include the following attributes: position, normal, tangent, binormal, color, uv0, uv1, joint weights, joint indices. Two sets of UVs are supported, one set for a diffuse/normal/specular texture and a separate set for an optional emissive texture.
  • A wall collision model. This model is used to prevent an avatar from walking through walls. This is a list of polytopes where each polytope is described by a set of planes. The polytopes are not necessarily bounded or convex.
  • A ground collision model. This model determines the floor height of the avatar. This model is also no more than a list of polytopes.
  • A ray trace model. This is a triangle soup with a Surface Area Heuristic (SAH) optimized KD-tree for fast ray tracing. Meshes or triangles will have to be annotated to allow interactive focus tracking or gaze selection.

Textures for the render model can be embedded in an FBX file and will be extracted by the FBX Converter. Embedded textures are extracted into a folder named <filename>.fbm/, which is a sub-folder of the folder where the FBX file <filename>.fbx is located. Instead of embedding textures, they can also simply be stored in the same folder as the FBX file. The following source texture formats are supported: BMP, TGA, PNG, JPG. For the best quality, a lossy compression format like JPG should be avoided.

The JSON file with models and the binary file are stored in a temporary folder named <filename>_tmp/, which is a sub-folder of the folder where the FBX Converter is launched, where <filename> is the output file name specified with the -o command-line option. The FBX Converter will also create a <filename>_pack.bat batch file in the folder where the FBX Converter is launched.

This batch file is used to compress the render model textures to a platform specific compression format. A texture will be compressed to ETC2 (with or without alpha) for OpenGL ES mobile platforms and to S3TC (either DXT1/BC1 or DXT5/BC3) for the PC. The batch file uses file time stamps only to compress textures for which there is not already a compressed version that is newer than the source texture. The -clean command-line option may be used to force recompression of all textures.

The batch file will also copy the JSON model file, the binary file with raw data and the platform specific compressed textures into a folder named <filename>_tmp/pack/, which is a sub-folder of the aforementioned <filename>_tmp/ folder. 7-Zip is then used to zip up the 'pack' folder into a single package that can be loaded by the application. The -pack command-line option can be used to automatically execute the <filename>_pack.bat batch file from the FBX Converter.

Coordinate System

The Oculus SDK uses the same coordinates system as the default coordinate system in 3D Studio Max or Luxology MODO. This is a right handed coordinate system with:


The Oculus SDK uses the metric system for measurements, where one unit is equal to one meter. 3D Studio Max and Luxology MODO do not use any specific unit of measure, but one unit in either application maps to one unit in the Oculus SDK. However, when the data from Luxology MODO is saved to an FBX file, all units are automatically multiplied by one hundred. In other words, the unit of measure in the FBX file ends up being centimeter. Therefore there is always a scale of 1/100 specified on the FBX Converter command-line when converting FBX files from Luxology MODO: -scale 0.01

The FBX Converter supports several command-line options to transform the FBX geometry (translate, rotate, scale, et cetera). The transformations will be applied to the geometry in the order in which they are listed on the command-line.


Each render model surface stored in the JSON models file has a material.

Such a material has a type and references to the textures used. The material textures may include a diffuse, specular, normal, emissive and reflection texture. These textures are retrieved from the FBX file as:


Most modeling tools will map similarly named textures to the above textures in the FBX file. For instance, using Luxology MODO, the 'Emissive color' texture is mapped to the 'EmissiveColor' texture in the FBX file.

During rendering the diffuse texture is multiplied with the emissive texture as follows:

color = DiffuseColor(uv0) * EmissiveColor(uv1) * 1.5

Surface reflections look into a cube map (or environment map). The textures for the 6 cube map sides should be named:


The reflection texture 'ReflectionColor' should be set to one of these 6 textures used to create the cube map. The FBX Converter automatically picks up the other 5 textures and combines all 6 textures into a cube map.

The normal map that is used to calculate the surface reflection is expected to be in local (tangent) space. During rendering the color of reflection mapped materials is calculated as follows:

  surfaceNormal = normalize( NormalMap(uv0).x * tangent +
                   NormalMap(uv0).y * binormal +
                   NormalMap(uv0).z * normal )
  reflection = dot( eyeVector, surfaceNormal ) * 2.0 * surfaceNormal - eyeVector
  color = DiffuseColor(uv0) * EmissiveColor(uv1) * 1.5 +
       SpecularColor(uv0) * ReflectionColor(reflection)

The material type is one of the following:

  1. opaque
  2. perforated
  3. transparent
  4. additive

The first three material types are based on the alpha channel of the diffuse texture. The -alpha command-line option must be used to enable the 'perforated' and 'transparent' material types. Without the -alpha command-line option, the alpha channel of the diffuse texture will be removed.

The 'additive' material type cannot be derived from the textures. An additive texture is specified by appending _additive to the material name in the FBX file.


There is currently not a full blown animation system, but having vertices weighted to joints is still very useful to programmatically move geometry, while rendering as few surfaces as possible. Think about things like the buttons and joystick on the arcade machines in VrArcade. An artist can setup the vertex weighting for skinning, but the FBX Converter also has an option to rigidly bind the vertices of a FBX source mesh to a single joint. In this case the joint name will be the name of the FBX source mesh. The meshes that need to be rigidly skinned to a joint are specified using the -skin command-line option. There is currently a limit of 16 joints per FBX file.

The FBX Converter can also apply some very basic parametric animations to joints.

These simple animations are specified using the -anim command-line option. The types of animation are rotate, sway and bob. One of these types is specified directly following the -anim command-line option. Several parameters that define the animation are specified after the type. For the rotate and sway these parameters are pitch, yaw and roll in degrees per second. For the bob the parameters are x, y and z in meters per second. Following these parameters, a time offset and scale can be specified. The time offset is typically use to animated multiple joints out of sync and the time scale can be used to speed up or slow down the animation. Last but not least, one or more joints are specified to which the animation should be applied.

When a mesh is rigidly skinned to a joint using the -skin command-line option, the FBX Converter stores the mesh node transform on the joint. This mesh node transform is used as the frame of reference (pivot and axes) for animations.


A tag is used to define a position and frame of reference in the world.

A tag can, for instance, be used to define a screen or a view position in a cinema. A tag can also be used to place objects in the world.

The -tag command-line option is used to turn one or more FBX meshes from the render model into tags. The name of a tag will be the name of the mesh. The position and frame of reference are derived from the first triangle of the mesh and are stored in a 4x4 matrix. The position is the corner of the triangle that is most orthogonal. The edges that come out of this corner define the first two basis vectors of the frame of reference. These basis vectors are not normalized to maintain the dimensions of the frame. The third basis vector is the triangle normal vector.

Multiple tags can be created by specifying multiple FBX mesh names after the -tag command-line option. The -tag command-line option does not remove the listed meshes from the render model. The -remove command-line option can be used to remove the meshes from the render model.