AssimpImporter: import animations

src/MagnumPlugins/AssimpImporter/AssimpImporter.conf

@@ -29,6 +29,26 @@ provides=XglImporter
 # Controls the workaround for an Assimp 4.1 "white ambient" bug
 forceWhiteAmbientToBlack=true
 
+# Optimize imported linearly-interpolated quaternion animation tracks to
+# ensure shortest path is always chosen. This can be controlled separately for
+# each animation import.
+optimizeQuaternionShortestPath=true
+
+# Normalize quaternion animation tracks, if they are not already.
+# This can be controlled separately for each animation import.
+normalizeQuaternions=true
+
+# Merge all animations into a single clip. Useful for preserving cinematic
+# animations when using the Blender glTF exporter, as it exports animation of
+# every object as a separate clip. See https://blender.stackexchange.com/q/5689
+# and https://github.com/KhronosGroup/glTF-Blender-Exporter/pull/166 for more
+# information.
+mergeAnimationClips=false
+
+# Remove dummy animation tracks inserted by Assimp that contain only a single
+# key/value pair with the default node transformation
+removeDummyAnimationTracks=true
+
 # AI_CONFIG_* values, can be changed only before the first file is opened
 ImportColladaIgnoreUpDirection=false
 

src/MagnumPlugins/AssimpImporter/AssimpImporter.h

@@ -185,8 +185,8 @@ See @ref building-plugins, @ref cmake-plugins, @ref plugins and
 
 @section Trade-AssimpImporter-behavior Behavior and limitations
 
-The plugin supports @ref ImporterFeature::OpenData and
-@ref ImporterFeature::FileCallback features. The Assimp library loads
+The plugin supports @ref ImporterFeature::OpenData, @ref ImporterFeature::OpenState
+and @ref ImporterFeature::FileCallback features. The Assimp library loads
 everything during initial import, meaning all external file loading callbacks
 are called with @ref InputFileCallbackPolicy::LoadTemporary and the resources
 can be safely freed right after the @ref openData() / @ref openFile() function
@@ -197,13 +197,57 @@ with @ref InputFileCallbackPolicy::LoadTemporary and
 @ref InputFileCallbackPolicy::Close is emitted right after the file is fully
 read.
 
-Import of animation data is not supported at the moment.
+Import of skeleton, skin and morph data is not supported at the moment.
 
 The importer recognizes @ref ImporterFlag::Verbose, enabling verbose logging
 in Assimp when the flag is enabled. However please note that since Assimp
 handles logging through a global singleton, it's not possible to have different
 verbosity levels in each instance.
 
+@subsection Trade-AssimpImporter-behavior-animation Animation import
+
+-   Assimp sometimes adds dummy animation tracks with a single key-value pair
+    and the default node transformation. If found, the importer removes these dummy
+    tracks and prints a message if verbose logging is enabled. Can be disabled
+    per-animation with the @cb{.ini} removeDummyAnimationTracks @ce option, see
+    @ref Trade-AssimpImporter-configuration "below".
+-   Channel order within animations is not always preserved
+    by Assimp, depending on file type and compiler. You may have to manually
+    order tracks by type and target after importing.
+-   Quaternion rotation tracks are postprocessed in order to make it
+    possible to use the faster
+    @ref Math::lerp(const Quaternion<T>&, const Quaternion<T>&, T) "Math::lerp()" /
+    @ref Math::slerp(const Quaternion<T>&, const Quaternion<T>&, T) "Math::slerp()"
+    functions instead of
+    @ref Math::lerpShortestPath(const Quaternion<T>&, const Quaternion<T>&, T) "Math::lerpShortestPath()" /
+    @ref Math::slerpShortestPath(const Quaternion<T>&, const Quaternion<T>&, T) "Math::slerpShortestPath()". Can be disabled per-animation with the
+    @cb{.ini} optimizeQuaternionShortestPath @ce option, see
+    @ref Trade-AssimpImporter-configuration "below".
+-   If quaternion rotation tracks are not normalized, the importer
+    prints a warning and normalizes them. Can be disabled per-animation with
+    the @cb{.ini} normalizeQuaternions @ce option, see
+    @ref Trade-AssimpImporter-configuration "below".
+-   Skeletons and skins are not supported
+-   Morph targets are not supported
+-   Animation tracks are always imported with
+    @ref Animation::Interpolation::Linear, because Assimp doesn't expose
+    any interpolation modes
+-   Animation tracks using `aiAnimBehaviour_DEFAULT` or `aiAnimBehaviour_REPEAT`
+    fall back to using @ref Animation::Extrapolation::Constant
+-   It's possible to request all animation clips to be merged into one using
+    the @cb{.ini} mergeAnimationClips @ce option in order to for example
+    preserve cinematic animations when using the Blender glTF exporter (as it
+    otherwise outputs a separate clip for each object). When this option is
+    enabled, @ref animationCount() always report either @cpp 0 @ce or
+    @cpp 1 @ce and the merged animation has no name. With this option enabled,
+    however, it can happen that multiple conflicting tracks affecting the same
+    node are merged in the same clip, causing the animation to misbehave.
+-   Assimp versions before commit [e3083c21f0a7beae6c37a2265b7919a02cbf83c4](https://github.com/assimp/assimp/commit/e3083c21f0a7beae6c37a2265b7919a02cbf83c4)
+    read spline-interpolated glTF animation tracks incorrectly and produce broken
+    animations. A warning is printed when importing glTF animations on these versions.
+    Because it's impossible to detect the actual brokenness, the warning is
+    printed even if the imported data may be correct.
+
 @subsection Trade-AssimpImporter-behavior-materials Material import
 
 -   Only materials with shading mode `aiShadingMode_Phong` are supported
@@ -326,6 +370,7 @@ importer state methods:
     -   @ref LightData::importerState() returns `aiLight`
     -   @ref ImageData2D::importerState() may return `aiTexture`, if texture was embedded
         into the loaded file.
+    -   @ref AnimationData::importerState() returns `aiAnimation`
 -   @ref 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)
 
@@ -401,6 +446,11 @@ class MAGNUM_ASSIMPIMPORTER_EXPORT AssimpImporter: public AbstractImporter {
         MAGNUM_ASSIMPIMPORTER_LOCAL UnsignedInt doImage2DLevelCount(UnsignedInt id) override;
         MAGNUM_ASSIMPIMPORTER_LOCAL Containers::Optional<ImageData2D> doImage2D(UnsignedInt id, UnsignedInt level) override;
 
+        MAGNUM_ASSIMPIMPORTER_LOCAL UnsignedInt doAnimationCount() const override;
+        MAGNUM_ASSIMPIMPORTER_LOCAL std::string doAnimationName(UnsignedInt id) override;
+        MAGNUM_ASSIMPIMPORTER_LOCAL Int doAnimationForName(const std::string& name) override;
+        MAGNUM_ASSIMPIMPORTER_LOCAL Containers::Optional<AnimationData> doAnimation(UnsignedInt id) override;
+
         MAGNUM_ASSIMPIMPORTER_LOCAL const void* doImporterState() const override;
 
         Containers::Pointer<Assimp::Importer> _importer;

src/MagnumPlugins/AssimpImporter/CMakeLists.txt

@@ -34,13 +34,38 @@ endif()
 configure_file(${CMAKE_CURRENT_SOURCE_DIR}/configure.h.cmake
                ${CMAKE_CURRENT_BINARY_DIR}/configure.h)
 
+# Go through all versions of interest and pick the highest one that compiles
+foreach(_version 20201123 20190915 20151031)
+    try_compile(_works ${CMAKE_CURRENT_BINARY_DIR}
+        ${CMAKE_CURRENT_SOURCE_DIR}/checkAssimpVersion.cpp
+        LINK_LIBRARIES Assimp::Assimp
+        COMPILE_DEFINITIONS
+            -DCHECK_VERSION=${_version}
+            # I thought I could make this use C++11 by linking to
+            # Corrade::Utility, but for some reason the effect of the
+            # CORRADE_CXX_STANDARD property doesn't get passed through. So I
+            # have to use an internal variable for that instead.
+            ${CORRADE_CXX11_STANDARD_FLAG}
+        OUTPUT_VARIABLE _version_output)
+    if(_works)
+        set(ASSIMP_VERSION ${_version})
+        break()
+    endif()
+endforeach()
+if(NOT ASSIMP_VERSION)
+    message(SEND_ERROR "Could not detect Assimp version. Maybe even older than 3.2? ${_version_output}")
+endif()
+configure_file(${CMAKE_CURRENT_SOURCE_DIR}/configureInternal.h.cmake
+               ${CMAKE_CURRENT_BINARY_DIR}/configureInternal.h)
+
 # AssimpImporter plugin
 add_plugin(AssimpImporter
     "${MAGNUM_PLUGINS_IMPORTER_DEBUG_BINARY_INSTALL_DIR};${MAGNUM_PLUGINS_IMPORTER_DEBUG_LIBRARY_INSTALL_DIR}"
     "${MAGNUM_PLUGINS_IMPORTER_RELEASE_BINARY_INSTALL_DIR};${MAGNUM_PLUGINS_IMPORTER_RELEASE_LIBRARY_INSTALL_DIR}"
     AssimpImporter.conf
     AssimpImporter.cpp
     AssimpImporter.h)
+target_include_directories(AssimpImporter PRIVATE ${CMAKE_CURRENT_BINARY_DIR})
 if(MAGNUM_ASSIMPIMPORTER_BUILD_STATIC AND BUILD_STATIC_PIC)
     set_target_properties(AssimpImporter PROPERTIES POSITION_INDEPENDENT_CODE ON)
 endif()