Assimp: Importer Notes

assimp - Open Asset Import Library

Assimp  v3.1.1 (June 2014)
Importer Notes


This section contains implementation notes for the Blender3D importer.


assimp provides a self-contained reimplementation of Blender's so called SDNA system ( SDNA allows Blender to be fully backward and forward compatible and to exchange files across all platforms. The BLEND format is thus a non-trivial binary monster and the loader tries to read the most of it, naturally limited by the scope of the aiScene output data structure. Consequently, if Blender is the only modeling tool in your asset work flow, consider writing a custom exporter from Blender if assimps format coverage does not meet the requirements.

Current status

The Blender loader does not support animations yet, but is apart from that considered relatively stable.


When filing bugs on the Blender loader, always give the Blender version (or, even better, post the file caused the error).


This section contains implementation notes on the IFC-STEP importer.


The library provides a partial implementation of the IFC2x3 industry standard for automatized exchange of CAE/architectural data sets. See for more information on the format. We aim at getting as much 3D data out of the files as possible.

Current status

IFC support is new and considered experimental. Please report any bugs you may encounter.


  • Only the STEP-based encoding is supported. IFCZIP and IFCXML are not (but IFCZIP can simply be unzipped to get a STEP file).
  • The importer leaves vertex coordinates untouched, but applies a global scaling to the root transform to convert from whichever unit the IFC file uses to metres.
  • If multiple geometric representations are provided, the choice which one to load is based on how expensive a representation seems to be in terms of import time. The loader also avoids representation types for which it has known deficits.
  • Not supported are arbitrary binary operations (binary clipping is implemented, though).
  • Of the various relationship types that IFC knows, only aggregation, containment and material assignment are resolved and mapped to the output graph.
  • The implementation knows only about IFC2X3 and applies this rule set to all models it encounters, regardless of their actual version. Loading of older or newer files may fail with parsing errors.


IFC file properties (IfcPropertySet) are kept as per-node metadata, see aiNode::mMetaData.


ATTENTION*: The Ogre-Loader is currently under development, many things have changed after this documentation was written, but they are not final enough to rewrite the documentation. So things may have changed by now!

This section contains implementations notes for the OgreXML importer.


Ogre importer is currently optimized for the Blender Ogre exporter, because thats the only one that I use. You can find the Blender Ogre exporter at:

What will be loaded?

Mesh: Faces, Positions, Normals and all TexCoords. The Materialname will be used to load the material.

Material: The right material in the file will be searched, the importer should work with materials who have 1 technique and 1 pass in this technique. From there, the texturename (for 1 color- and 1 normalmap) and the materialcolors (but not in custom materials) will be loaded. Also, the materialname will be set.

Skeleton: Skeleton with Bone hierarchy (Position and Rotation, but no Scaling in the skeleton is supported), names and transformations, animations with rotation, translation and scaling keys.

How to export Files from Blender

You can find informations about how to use the Ogreexporter by your own, so here are just some options that you need, so the assimp importer will load everything correctly:

  • Use either "Rendering Material" or "Custom Material" see Materials
  • do not use "Flip Up Axies to Y"
  • use "Skeleton name follow mesh"

XML Format

There is a binary and a XML mesh Format from Ogre. This loader can only Handle xml files, but don't panic, there is a command line converter, which you can use to create XML files from Binary Files. Just look on the Ogre page for it.

Currently you can only load meshes. So you will need to import the *.mesh.xml file, the loader will try to find the appendant material and skeleton file.

The skeleton file must have the same name as the mesh file, e.g. fish.mesh.xml and fish.skeleton.xml.


The material file can have the same name as the mesh file (if the file is model.mesh or model.mesh.xml the loader will try to load model.material), or you can use Importer::Importer::SetPropertyString(AI_CONFIG_IMPORT_OGRE_MATERIAL_FILE, "materiafile.material") to specify the name of the material file. This is especially usefull if multiply materials a stored in a single file. The importer will first try to load the material with the same name as the mesh and only if this can't be open try to load the alternate material file. The default material filename is "Scene.material".

We suggest that you use custom materials, because they support multiple textures (like colormap and normalmap). First of all you should read the custom material sektion in the Ogre Blender exporter Help File, and than use the assimp.tlp template, which you can find in scripts/OgreImpoter/Assimp.tlp in the assimp source. If you don't set all values, don't worry, they will be ignored during import.

If you want more properties in custom materials, you can easily expand the ogre material loader, it will be just a few lines for each property. Just look in OgreImporterMaterial.cpp


  • IMPORT_OGRE_TEXTURETYPE_FROM_FILENAME: Normally, a texture is loaded as a colormap, if no target is specified in the materialfile. Is this switch is enabled, texture names ending with _n, _l, _s are used as normalmaps, lightmaps or specularmaps.
    Property type: Bool. Default value: false.
  • IMPORT_OGRE_MATERIAL_FILE: Ogre Meshes contain only the MaterialName, not the MaterialFile. If there is no material file with the same name as the material, Ogre Importer will try to load this file and search the material in it.
    Property type: String. Default value: guessed.


  • Load colors in custom materials
  • extend custom and normal material loading
  • fix bone hierarchy bug
  • test everything elaboratly
  • check for non existent animation keys (what happens if a one time not all bones have a key?)
Generated on Sun Feb 21 2016 19:42:29 for Assimp by   doxygen 1.8.11