Magnum::Trade::AssimpImporter class
#include <MagnumPlugins/AssimpImporter/AssimpImporter.h>

Assimp importer.

Contents

Imports various formats using Assimp, in particular:

  • Autodesk FBX (*.fbx)
  • COLLADA (*.dae)
  • glTF (*.gltf, *.glb)
  • Blender 3D (*.blend)
  • 3ds Max 3DS and ASE (*.3ds, *.ase)
  • Wavefront OBJ (*.obj)
  • Industry Foundation Classes (IFC/Step) (*.ifc)
  • XGL (*.xgl, *.zgl)
  • Stanford PLY (*.ply)
  • AutoCAD DXF (*.dxf)
  • LightWave, LightWave Scene (*.lwo, *.lws)
  • Modo (*.lxo)
  • Stereolithography (*.stl)
  • DirectX X (*.x)
  • AC3D (*.ac)
  • Milkshape 3D (*.ms3d)
  • TrueSpace (*.cob, *.scn)
  • Biovision BVH (*.bvh)
  • CharacterStudio Motion (*.csm)
  • Ogre XML (*.xml)
  • Irrlicht Mesh and Scene (*.irrmesh, *.irr)
  • Quake I (*.mdl)
  • Quake II (*.md2)
  • Quake III Mesh (*.md3)
  • Quake III Map/BSP (*.pk3)
  • Return to Castle Wolfenstein (*.mdc)
  • Doom 3 (*.md5*)
  • Valve Model (*.smd, *.vta)
  • Open Game Engine Exchange (*.ogex)
  • Unreal (*.3d)
  • BlitzBasic 3D (*.b3d)
  • Quick3D (*.q3d, *.q3s)
  • Neutral File Format (*.nff)
  • Sense8 WorldToolKit (*.nff)
  • Object File Format (*.off)
  • PovRAY Raw (*.raw)
  • Terragen Terrain (*.ter)
  • 3D GameStudio (3DGS), 3D GameStudio (3DGS) Terrain (*.mdl, *.hmp)
  • Izware Nendo (*.ndo)

Supports importing of scene, object, camera, mesh, texture and image data.

This plugin depends on the Trade and Assimp libraries and is built if WITH_ASSIMPIMPORTER is enabled when building Magnum Plugins. To use as a dynamic plugin, you need to load the "AssimpImporter" plugin from MAGNUM_PLUGINS_IMPORTER_DIR. To use as a static plugin or as a dependency of another plugin with CMake, you need to request the AssimpImporter component of the MagnumPlugins package and link to the MagnumPlugins::AssimpImporter target. See Downloading and building plugins, Plugin usage with CMake and Loading and using plugins for more information.

This plugin provides 3dsImporter, Ac3dImporter, BlenderImporter, BvhImporter, CsmImporter, ColladaImporter, DirectXImporter, DxfImporter, FbxImporter, GltfImporter, IfcImporter, IrrlichtImporter, LightWaveImporter, ModoImporter, MilkshapeImporter, ObjImporter, OgreImporter, OpenGexImporter, StanfordImporter, StlImporter, TrueSpaceImporter, UnrealImporter, ValveImporter and XglImporter plugins.

Behavior and limitations

The plugin supports Feature::OpenData and Feature::FileCallback features. The Assimp library loads everything during initial import, meaning all external file loading callbacks are called with ImporterFileCallbackPolicy::LoadTemporary and the resources can be safely freed right after the openData() / openFile() function exits. In some cases, Assimp will explicitly call ImporterFileCallbackPolicy::Close on the opened file and then open it again. In case of images, the files are loaded on-demand inside image2D() calls with ImporterFileCallbackPolicy::LoadTemporary and ImporterFileCallbackPolicy::Close is emitted right after the file is fully read.

Import of animation data is not supported at the moment.

Material import

  • Only materials with shading mode aiShadingMode_Phong are supported
  • Only the first diffuse/specular/ambient texture is loaded
  • Two-sided property and alpha mode is not imported
  • For some reason, Assimp 4.1 imports STL models with ambient set to 0xffffff_srgbf, which causes all other color information to be discarded. If such a case is detected, the ambient is forced back to 0x000000_srgbf. See also assimp/assimp#2059.

Light import

  • The following properties are ignored:
    • Angle inner/outer cone
    • Linear/quadratic/constant attenuation
    • Ambient/specular color
  • Assimp does not load a property which can be mapped to LightData::intensity()
  • Light types other than aiLightSource_DIRECTIONAL, aiLightSource_POINT and aiLightSource_SPOT are unsupported

Camera import

  • Aspect and up vector properties are not imported

Mesh import

  • Only the first mesh of a aiNode is loaded
  • Only triangle meshes are loaded
  • Texture coordinate layers with other than two components are skipped
  • For some file formats (such as COLLADA), Assimp may create a dummy "skeleton visualizer" mesh if the file has no mesh data. For others (such as glTF) not.

Texture import

  • Textures with mapping mode/wrapping aiTextureMapMode_Decal are loaded with SamplerWrapping::ClampToEdge
  • Assimp does not appear to load any filtering information
  • Raw embedded image data is not supported

Scene import

  • For some file formats (such as COLLADA), Assimp fails to load the file if it doesn't contain any scene. For some (such as glTF) it will succeed and sceneCount() / object3DCount() will return zero.
  • If the root node imported by Assimp has children, it's ignored and only its children are exposed through object3D(). On the other hand, for example in presence of postprocessing flags such as PreTransformVertices, there's sometimes just a single root node. In that case the single node is imported as a single object3D() instead of being ignored.

Plugin-specific configuration

Assimp has a versatile set of processing operations applied on imported scenes. The [postprocess] group of configuration() contains boolean toggles that correspond to the aiPostProcessSteps enum. Some of them are enabled by default, some not; options for not yet supported features are omitted. The full form of the configuration is shown below:

[configuration/postprocess]
JoinIdenticalVertices=true
Triangulate=true
GenNormals=false
GenSmoothNormals=false
SplitLargeMeshes=false
PreTransformVertices=false
ValidateDataStructure=false
ImproveCacheLocality=false
RemoveRedundantMaterials=false
FixInfacingNormals=false
SortByPType=true
FindDegenerates=false
FindInvalidData=false
GenUVCoords=false
TransformUVCoords=false
FindInstances=false
OptimizeMeshes=false
OptimizeGraph=false
FlipUVs=false
FlipWindingOrder=false

Access to internal importer state

The Assimp structures used to import data from a file can be accessed through importer state methods:

Base classes

class AbstractImporter
Base for importer plugins.

Constructors, destructors, conversion operators

AssimpImporter() explicit
Default constructor.
AssimpImporter(PluginManager::Manager<AbstractImporter>& manager) explicit
Constructor.
AssimpImporter(PluginManager::AbstractManager& manager, const std::string& plugin) explicit
Plugin manager constructor.

Function documentation

Magnum::Trade::AssimpImporter::AssimpImporter() explicit

Default constructor.

In case you want to open images, use AssimpImporter(PluginManager::Manager<AbstractImporter>&) instead.

Magnum::Trade::AssimpImporter::AssimpImporter(PluginManager::Manager<AbstractImporter>& manager) explicit

Constructor.

The plugin needs access to plugin manager for importing images.