class
AssimpImporterAssimp 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 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.
Usage
This plugin depends on the Trade and Assimp libraries and the AnyImageImporter plugin and is built if WITH_ASSIMPIMPORTER
is enabled when building Magnum Plugins. To use as a dynamic plugin, load "AssimpImporter"
via Corrade::
Additionally, if you're using Magnum as a CMake subproject, bundle the magnum-plugins and assimp repositories and do the following. If you want to use system-installed Assimp, omit the first part and point CMAKE_PREFIX_PATH
to its installation dir if necessary.
# Disable Assimp tests, tools and exporter functionality set(ASSIMP_BUILD_ASSIMP_TOOLS OFF CACHE BOOL "" FORCE) set(ASSIMP_BUILD_TESTS OFF CACHE BOOL "" FORCE) set(ASSIMP_NO_EXPORT ON CACHE BOOL "" FORCE) # If you won't be accessing Assimp outside of the plugin, build it as static to # have the plugin binary self-contained set(BUILD_SHARED_LIBS OFF CACHE BOOL "" FORCE) # The following is important to avoid Assimp appending `d` to all your # binaries. You need Assimp >= 5.0.0 for this to work, also note that after # 5.0.1 this option is prefixed with ASSIMP_, so better set both variants. set(INJECT_DEBUG_POSTFIX OFF CACHE BOOL "" FORCE) set(ASSIMP_INJECT_DEBUG_POSTFIX OFF CACHE BOOL "" FORCE) add_subdirectory(assimp EXCLUDE_FROM_ALL) set(WITH_ANYIMAGEIMPORTER ON CACHE BOOL "" FORCE) add_subdirectory(magnum EXCLUDE_FROM_ALL) set(WITH_ASSIMPIMPORTER ON CACHE BOOL "" FORCE) add_subdirectory(magnum-plugins EXCLUDE_FROM_ALL) # So the dynamically loaded plugin gets built implicitly add_dependencies(your-app MagnumPlugins::AssimpImporter)
To use as a static plugin or as a dependency of another plugin with CMake, put FindMagnumPlugins.cmake and FindAssimp.cmake into your modules/
directory, request the AssimpImporter
component of the MagnumPlugins
package and link to the MagnumPlugins::AssimpImporter
target:
find_package(MagnumPlugins REQUIRED AssimpImporter) # ... target_link_libraries(your-app PRIVATE MagnumPlugins::AssimpImporter)
See Downloading and building plugins, Plugin usage with CMake, Loading and using plugins and File format support for more information.
Behavior and limitations
The plugin supports ImporterFeature::
Import of animation data is not supported at the moment.
The importer recognizes ImporterFlag::
Material import
- Only materials with shading mode
aiShadingMode_Phong
are supported - Two-sided property and alpha mode is not imported
- Assimp seems to ignore ambient textures in COLLADA files
- 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 and there's no ambient texture present, the ambient is forced back to0x000000_srgbf
. See also assimp/assimp#2059. This workaround can be disabled using the forceWhiteAmbientToBlack
configuration option.
Light import
- LightData::
intensity() is always 1.0f
, instead Assimp premultiplies LightData::color() with the intensity - Ambient lights are imported as LightData::
Type:: Point with attenuation set to {1.0f, 0.0f, 0.0f}
- The following properties are ignored:
- Specular color
- Custom light orientation vectors — the orientation is always only inherited from the node containing the light
- Area lights are not supported
Camera import
- Aspect and up vector properties are not imported
Mesh import
- Only point, triangle, and line meshes are loaded (quad and poly meshes are triangularized by Assimp)
- Custom mesh attributes (such as
object_id
in Stanford PLY files) are not imported. - 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.
- Per-face attributes in Stanford PLY files are not imported.
- Stanford PLY files that contain a comment before the format line fail to import.
- The importer follows types used by Assimp, thus indices are always MeshIndexType::
UnsignedInt, positions, normals, tangents and bitangents are always imported as VertexFormat:: Vector3, texture coordinates as VertexFormat:: Vector2 and colors as VertexFormat:: Vector4. In other words, everything gets expanded by Assimp to floats, even if the original file might be using different types. - The imported model always has either both MeshAttribute::
Tangent MeshAttribute:: Bitangent or neither of them, tangents are always three-component with binormals separate. - Multi-mesh nodes and multi-primitive meshes are loaded as follows, consistently with the behavior of TinyGltfImporter:
- Multi-primitive meshes are split by Assimp into individual meshes
- The meshCount() query returns a number of all primitives, not meshes
- The object3DCount() query returns a number of all nodes extended with number of extra objects for each additional mesh
- Each node referencing a multiple meshes is split into a sequence of MeshObjectData3D instances following each other; the extra nodes being a direct and immediate children of the first one with an identity transformation
- object3DForName() points to the first object containing the first mesh, object3DName() returns the same name for all objects in given sequence
The mesh is always indexed; positions are always present, normals, colors and texture coordinates are optional.
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 configuration options and processing operations applied on imported scenes. A subset of these is exposed via configuration(), the full form shown below. The first group of options matches the AI_
The [postprocess]
subgroup 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. These are passed to Assimp when opening a file, meaning a change in these will be always applied to the next opened file.
[configuration] # Controls the workaround for an Assimp 4.1 "white ambient" bug forceWhiteAmbientToBlack=true # AI_CONFIG_* values, can be changed only before the first file is opened ImportColladaIgnoreUpDirection=false # aiPostProcessSteps, applied to each opened file [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:
- Calling importerState() returns pointer to the imported
aiScene
- Calling
*importerState()
on data class instances returned from this importer return pointers to matching assimp structures:- AbstractMaterialData::
importerState() returns aiMaterial
- CameraData::
importerState() returns aiCamera
- TextureData::
importerState() returns std::pair<const aiMaterial*, aiTextureType>
, in which the first texture of given type in given material is referred to. - MeshData::
importerState() returns aiMesh
- ObjectData3D::
importerState() returns aiNode
- LightData::
importerState() returns aiLight
- ImageData2D::
importerState() may return aiTexture
, if texture was embedded into the loaded file.
- AbstractMaterialData::
- openState() expects a pointer to an Assimp scene (i.e.,
const aiScene*
) and optionally a path (in order to be able to load textures, if needed)
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::
Magnum:: Trade:: AssimpImporter:: AssimpImporter(PluginManager:: Manager<AbstractImporter>& manager) explicit
Constructor.
The plugin needs access to plugin manager for importing images.