Data import using assimp

The Open Asset Import Library, assimp, is a great resource to get access to a large variety of 3D model file formats. tinyScenegraph recently implemented an interface to assimp and uses it automatically in case the assimp library is found on disk and it cannot handle a given file format on it's own. In fact, assimp works so well that tinySG dropped it's own loader implementations for lwo and 3ds and uses assimp instead.

Assimp knows a bunch of postprocessing steps, like normal- or tangent creation, vertex-joining or polygon triangulation. For a complete list of features please check with the assimp home page directly. The library code is open source (BSD license) and written in C++. It also provides a C-interface and Python/c# and D-bindings. The source code includes a little viewer application that demonstrates how to load models and access their data structures.

Although the documentation of assimp is excellent and far more complete, the following sections try to provide insights on a basic integration of assimp in other applications.

Assimp integration into tinySG

tinySG's glue code is less than 500 lines of code, translating assimp objects into tinySG scenegraph nodes, loading external files like textures or shaders and adding a little eye candy, like bumpmap shader nodes if a bump map is found. The diagram on the right shows the main entities that are translated to tinySG.

An import can work with as little as a single call into the library:

   aiScene pScene;
   Assimp::Importer importer;
   pScene = importer.ReadFile(filename, 
                aiProcess_Triangulate);

The importer object automatically frees the returned memory when running out of scope, so you do not even have to clean up yourself. Most properties can be accessed by public data members of the objects associated with the returned scene. Take a look at the UML diagram above: An aiScene holds a pointer to an aiNode - the scenes root node - which in turn maintains pointers to child nodes. These pointer define the scene structure recursively.

An aiScene also serves as the central storage for all meshes, materials or light sources. Instances of aiNode just index into these arrays held by the scene.

aiMaterials are perhaps the only slightly tricky thing: Instead of having public attributes, they provide a template function Get() that gives access to their properties. It's signature is more complicated, but fortunately there are predefined macros that make access pretty easy. This is what the function looks like

   template 
   inline aiReturn aiMaterial::Get(const char* pKey,unsigned int type,
                                    unsigned int idx,Type& pOut) const

... and this is how for example the material's diffuse color is accessed, using the AI_MATKEY_COLOR_DIFFUSE macro:

  for (unsigned int i=0; imNumMaterials; i++) {
    aiMaterial *pMat = m_aiScene->mMaterials[i];
    aiColor3D   color (0.f,0.f,0.f);
    
    pMat->Get (AI_MATKEY_COLOR_DIFFUSE, color);
    tsgMat->diffuseColor.Set (color.r, color.g, color.b);
    ...


The Touareg dataset imported from .lwo format - environment reflections, shadowmapped, baked ground shadow (click to enlarge).	Same dataset, placed into the Tegernsee environment (click to enlarge).

Conclusion

Kudos to the creators of assimp! Thanks to this cool library, tinyScenegraph now has access to more than three dozen model file formats, including the famous obj, 3ds, lwo, collada, blender and ply formats. External dependencies are zero, since assimp itself has no dependencies and it is build as a static library. Integration is done by linking the glue DLL against assimp and load/bind it on demand during runtime (which is almost no effort as there is just one entry point required). Although tinySG's internal node structure differs to a certain amount (special group nodes, different vertex attribute organisation, local light sources, etc.), the integration has been pretty easy.

Once the conversion of assimp objects to tinySG scenegraph nodes is done, all formats supported by the library become available. The other way, conversion from tinySG nodes to assimp objects, would make export formats available as well. However, this is less attractive (as of today, only the simple formats dae, obj, stl and ply are available) and has not yet been implemented.

Keep rendering,
Christian

Acknowledgements:

Assimp is available on source forge.
The VW Touareg dataset is available at DMI and kindly provided for non-commercial, private use.
The UML diagram has been created with the free violet UML editor.
Environment maps used for reflections are by courtesy of Emil Persson (aka "Humus"), provided under a Creative Commons license.