Assimp  v3.0 (July 2012)
assimp - Open Asset Import Library

Introduction

assimp is a library to load and process geometric scenes from various data formats. It is tailored at typical game scenarios by supporting a node hierarchy, static or skinned meshes, materials, bone animations and potential texture data. The library is not designed for speed, it is primarily useful for importing assets from various sources once and storing it in a engine-specific format for easy and fast every-day-loading. assimp is also able to apply various post processing steps to the imported data such as conversion to indexed meshes, calculation of normals or tangents/bitangents or conversion from right-handed to left-handed coordinate systems.

assimp currently supports the following file formats (note that some loaders lack some features of their formats because some file formats contain data not supported by assimp, some stuff would require so much conversion work that it has not been implemented yet and some (most ...) formats lack proper specifications):



Collada ( *.dae;*.xml )
Blender ( *.blend ) 3
Biovision BVH ( *.bvh )
3D Studio Max 3DS ( *.3ds )
3D Studio Max ASE ( *.ase )
Wavefront Object ( *.obj )
Stanford Polygon Library ( *.ply )
AutoCAD DXF ( *.dxf )
IFC-STEP, Industry Foundation Classes ( *.ifc )
Neutral File Format ( *.nff )
Sense8 WorldToolkit ( *.nff )
Valve Model ( *.smd,*.vta ) 3
Quake I ( *.mdl )
Quake II ( *.md2 )
Quake III ( *.md3 )
Quake 3 BSP ( *.pk3 ) 1
RtCW ( *.mdc )
Doom 3 ( *.md5mesh;*.md5anim;*.md5camera )
DirectX X ( *.x ).
Quick3D ( *.q3o;q3s ).
Raw Triangles ( .raw
).
AC3D ( *.ac ).
Stereolithography ( *.stl ).
Autodesk DXF ( *.dxf ).
Irrlicht Mesh ( *.irrmesh;*.xml ).
Irrlicht Scene ( *.irr;*.xml ).
Object File Format ( *.off ).
Terragen Terrain ( *.ter )
3D GameStudio Model ( *.mdl )
3D GameStudio Terrain ( *.hmp )
Ogre (*.mesh.xml, *.skeleton.xml, *.material)3
Milkshape 3D ( *.ms3d )
LightWave Model ( *.lwo )
LightWave Scene ( *.lws )
Modo Model ( *.lxo )
CharacterStudio Motion ( *.csm )
Stanford Ply ( *.ply )
TrueSpace ( *.cob, *.scn )2
XGL ( *.xgl, *.zgl )


See the Importer Notes Page for informations, what a specific importer can do and what not. Note that although this paper claims to be the official documentation, http://assimp.sourceforge.net/main_features_formats.html
is usually the most up-to-date list of file formats supported by the library.

1: Experimental loaders
2: Indicates very limited support - many of the format's features don't map to Assimp's data structures.
3: These formats support animations, but assimp doesn't yet support them (or they're buggy)


assimp is independent of the Operating System by nature, providing a C++ interface for easy integration with game engines and a C interface to allow bindings to other programming languages. At the moment the library runs on any little-endian platform including X86/Windows/Linux/Mac and X64/Windows/Linux/Mac. Special attention was paid to keep the library as free as possible from dependencies.

Big endian systems such as PPC-Macs or PPC-Linux systems are not officially supported at the moment. However, most formats handle the required endian conversion correctly, so large parts of the library should work.

The assimp linker library and viewer application are provided under the BSD 3-clause license. This basically means that you are free to use it in open- or closed-source projects, for commercial or non-commercial purposes as you like as long as you retain the license informations and take own responsibility for what you do with it. For details see the LICENSE file.

You can find test models for almost all formats in the <assimp_root>/test/models directory. Beware, they're free, but not all of them are open-source. If there's an accompagning '<file>.txt' file don't forget to read it.

Installation

assimp can be used in two ways: linking against the pre-built libraries or building the library on your own. The former option is the easiest, but the assimp distribution contains pre-built libraries only for Visual C++ 2005 and 2008. For other compilers you'll have to build assimp for yourself. Which is hopefully as hassle-free as the other way, but needs a bit more work. Both ways are described at the Installation page.

Usage

When you're done integrating the library into your IDE / project, you can now start using it. There are two separate interfaces by which you can access the library: a C++ interface and a C interface using flat functions. While the former is easier to handle, the latter also forms a point where other programming languages can connect to. Upto the moment, though, there are no bindings for any other language provided. Have a look at the Usage page for a detailed explanation and code examples.

Data Structures

When the importer successfully completed its job, the imported data is returned in an aiScene structure. This is the root point from where you can access all the various data types that a scene/model file can possibly contain. The Data Structures page describes how to interpret this data.

Extending the library

There are many 3d file formats in the world, and we're happy to support as many as possible. If you need support for a particular file format, why not implement it yourself and add it to the library? Writing importer plugins for assimp is considerably easy, as the whole postprocessing infrastructure is available and does much of the work for you. See the Extending the library page for more information.

Support & Feedback

If you have any questions/comments/suggestions/bug reports you're welcome to post them in our forums. Alternatively there's a mailing list, assimp-discussions.