Add unified saveCharacter function for FBX/GLTF parity (#753)

Summary:

After D85530152 added marker sequence support to fbx, we have functionality parity between fbx and gltf. This diff created a unified `saveCharacter()` function in `character_io` that automatically selects between FBX and GLTF export based on file extension.

Added .fbx support to `loadMarkers()` as the unified function for loading marker data from any supported format.

Added an additional unified `saveCharacter()` function in `character_io` that takes skeleton states as input instead of model parameters.

Rename `saveCharacter()` in `gltf_io` to `saveGltfCharacter()`, but keeping the existing ones for backwards compatibility for now. It will be removed in a later diff when downstreams are updated.

Differential Revision: D85517572

Author: yutingye

CMakeLists.txt

@@ -452,6 +452,7 @@ mt_library(
   PRIVATE_LINK_LIBRARIES
     io_common
     io_gltf
+    io_fbx
     ezc3d
 )
 

momentum/io/character_io.cpp

@@ -8,6 +8,7 @@
 #include "momentum/io/character_io.h"
 
 #include "momentum/character/character.h"
+#include "momentum/character/skeleton_state.h"
 #include "momentum/io/fbx/fbx_io.h"
 #include "momentum/io/gltf/gltf_io.h"
 #include "momentum/io/shape/pose_shape_io.h"
@@ -139,4 +140,76 @@ Character loadFullCharacterFromBuffer(
   return character.value();
 }
 
+void saveCharacter(
+    const filesystem::path& filename,
+    const Character& character,
+    const MatrixXf& motion,
+    const VectorXf& offsets,
+    const std::vector<std::vector<Marker>>& markerSequence,
+    float fps) {
+  // Parse format from file extension
+  const auto format = parseCharacterFormat(filename);
+  MT_THROW_IF(
+      format == CharacterFormat::Unknown,
+      "Unknown character format for path: {}. Supported formats: .fbx, .glb, .gltf",
+      filename.string());
+
+  if (format == CharacterFormat::Gltf) {
+    saveGltfCharacter(
+        filename,
+        character,
+        fps,
+        {character.parameterTransform.name, motion},
+        {character.skeleton.getJointNames(), offsets},
+        markerSequence);
+  } else if (format == CharacterFormat::Fbx) {
+    // Save as FBX
+    saveFbx(
+        filename,
+        character,
+        motion,
+        offsets,
+        static_cast<double>(fps),
+        true, // saveMesh
+        FBXCoordSystemInfo(),
+        false, // permissive
+        markerSequence);
+  } else {
+    MT_THROW(
+        "{} is not a supported format. Supported formats: .fbx, .glb, .gltf", filename.string());
+  }
+}
+
+void saveCharacter(
+    const filesystem::path& filename,
+    const Character& character,
+    std::span<const SkeletonState> skeletonStates,
+    const std::vector<std::vector<Marker>>& markerSequence,
+    float fps) {
+  // Parse format from file extension
+  const auto format = parseCharacterFormat(filename);
+  MT_THROW_IF(
+      format == CharacterFormat::Unknown,
+      "Unknown character format for path: {}. Supported formats: .fbx, .glb, .gltf",
+      filename.string());
+
+  if (format == CharacterFormat::Gltf) {
+    saveGltfCharacter(filename, character, fps, skeletonStates, markerSequence);
+  } else if (format == CharacterFormat::Fbx) {
+    // Save as FBX
+    saveFbxWithSkeletonState(
+        filename,
+        character,
+        skeletonStates,
+        static_cast<double>(fps),
+        true, // saveMesh
+        FBXCoordSystemInfo(),
+        false, // permissive
+        markerSequence);
+  } else {
+    MT_THROW(
+        "{} is not a supported format. Supported formats: .fbx, .glb, .gltf", filename.string());
+  }
+}
+
 } // namespace momentum

momentum/io/character_io.h

@@ -8,10 +8,13 @@
 #pragma once
 
 #include <momentum/character/fwd.h>
+#include <momentum/character/marker.h>
+#include <momentum/common/filesystem.h>
 #include <momentum/math/fwd.h>
 #include <momentum/math/types.h>
 
 #include <string>
+#include <vector>
 
 namespace momentum {
 
@@ -53,4 +56,28 @@ enum class CharacterFormat : uint8_t {
     std::span<const std::byte> paramBuffer = std::span<const std::byte>(),
     std::span<const std::byte> locBuffer = std::span<const std::byte>());
 
+/// High level function to save a character with motion and markers to any supported format.
+///
+/// The format is determined by the file extension (.fbx, .glb, .gltf).
+/// This is a unified interface that automatically selects between FBX and GLTF based on extension.
+/// @param[in] filename The path where the character file will be saved.
+/// @param[in] character The Character object to save.
+/// @param[in] motion The motion represented in model parameters (numModelParams, numFrames).
+/// @param[in] offsets Offset values per joint capturing skeleton bone lengths (7*numJoints, 1).
+/// @param[in] markerSequence Optional marker sequence data to save with the character.
+/// @param[in] fps Frame rate for the animation (default: 120.0).
+void saveCharacter(
+    const filesystem::path& filename,
+    const Character& character,
+    const MatrixXf& motion /* = MatrixXf()*/,
+    const VectorXf& offsets = VectorXf(),
+    const std::vector<std::vector<Marker>>& markerSequence = {},
+    float fps = 120.0f);
+
+void saveCharacter(
+    const filesystem::path& filename,
+    const Character& character,
+    std::span<const SkeletonState> skeletonStates,
+    const std::vector<std::vector<Marker>>& markerSequence,
+    float fps = 120.0f);
 } // namespace momentum

momentum/io/fbx/fbx_io.cpp

@@ -849,6 +849,39 @@ void saveFbxWithJointParams(
       fbxNamespace);
 }
 
+void saveFbxWithSkeletonState(
+    const filesystem::path& filename,
+    const Character& character,
+    std::span<const SkeletonState> skeletonStates,
+    const double framerate,
+    const bool saveMesh,
+    const FBXCoordSystemInfo& coordSystemInfo,
+    bool permissive,
+    const std::vector<std::vector<Marker>>& markerSequence,
+    std::string_view fbxNamespace) {
+  const size_t nFrames = skeletonStates.size();
+  MatrixXf jointParams(character.parameterTransform.zero().v.size(), nFrames);
+  for (size_t iFrame = 0; iFrame < nFrames; ++iFrame) {
+    jointParams.col(iFrame) =
+        skeletonStateToJointParameters(skeletonStates[iFrame], character.skeleton).v;
+  }
+
+  // Call the helper function to save FBX file with joint values.
+  // Set skipActiveJointParamCheck=true to skip the active joint param check as the joint params are
+  // passed in directly from user.
+  saveFbxCommon(
+      filename,
+      character,
+      jointParams,
+      framerate,
+      saveMesh,
+      true,
+      coordSystemInfo,
+      permissive,
+      markerSequence,
+      fbxNamespace);
+}
+
 void saveFbxModel(
     const filesystem::path& filename,
     const Character& character,

momentum/io/fbx/fbx_io.h

@@ -125,6 +125,28 @@ void saveFbxWithJointParams(
     const std::vector<std::vector<Marker>>& markerSequence = {},
     std::string_view fbxNamespace = "");
 
+/// Save a character with animation using skeleton states directly.
+/// @param filename Path to the output FBX file
+/// @param character The character to save
+/// @param skeletonStates SkeletonState for each frame (empty for bind pose only)
+/// @param framerate Animation framerate in frames per second
+/// @param saveMesh Whether to include mesh geometry in the output
+/// @param coordSystemInfo Coordinate system configuration for the FBX file
+/// @param permissive Permissive mode allows saving mesh-only characters (without skin weights)
+/// @param markerSequence Optional marker sequence data to save with the character
+/// @param fbxNamespace Optional namespace to prepend to all node names (e.g., "ns" will become
+/// "ns:")
+void saveFbxWithSkeletonState(
+    const filesystem::path& filename,
+    const Character& character,
+    std::span<const SkeletonState> skeletonStates,
+    double framerate = 120.0,
+    bool saveMesh = false,
+    const FBXCoordSystemInfo& coordSystemInfo = FBXCoordSystemInfo(),
+    bool permissive = false,
+    const std::vector<std::vector<Marker>>& markerSequence = {},
+    std::string_view fbxNamespace = "");
+
 /// Save a character model (skeleton and mesh) without animation.
 /// @param filename Path to the output FBX file
 /// @param character The character to save

momentum/io/fbx/fbx_io_openfbx_only.cpp

@@ -74,6 +74,20 @@ void saveFbxWithJointParams(
       "FBX saving is not supported in OpenFBX-only mode. FBX loading is available via OpenFBX, but saving requires the full Autodesk FBX SDK.");
 }
 
+void saveFbxWithSkeletonState(
+    const filesystem::path& /* filename */,
+    const Character& /* character */,
+    std::span<const SkeletonState> /* skeletonStates */,
+    double /* framerate */,
+    bool /* saveMesh */,
+    const FBXCoordSystemInfo& /* coordSystemInfo */,
+    bool /* permissive */,
+    const std::vector<std::vector<Marker>>& /* markerSequence */,
+    std::string_view /* fbxNamespace */) {
+  MT_THROW(
+      "FBX saving is not supported in OpenFBX-only mode. FBX loading is available via OpenFBX, but saving requires the full Autodesk FBX SDK.");
+}
+
 void saveFbxModel(
     const filesystem::path& /* filename */,
     const Character& /* character */,

momentum/io/gltf/gltf_io.cpp

@@ -1308,7 +1308,7 @@ MarkerSequence loadMarkerSequence(const filesystem::path& filename) {
   return result;
 }
 
-void saveCharacter(
+void saveGltfCharacter(
     const filesystem::path& filename,
     const Character& character,
     const float fps,
@@ -1326,6 +1326,19 @@ void saveCharacter(
 }
 
 void saveCharacter(
+    const filesystem::path& filename,
+    const Character& character,
+    const float fps,
+    const MotionParameters& motion,
+    const IdentityParameters& offsets,
+    const std::vector<std::vector<Marker>>& markerSequence,
+    const GltfFileFormat fileFormat,
+    const GltfOptions& options) {
+  return saveGltfCharacter(
+      filename, character, fps, motion, offsets, markerSequence, fileFormat, options);
+}
+
+void saveGltfCharacter(
     const filesystem::path& filename,
     const Character& character,
     const float fps,
@@ -1341,6 +1354,18 @@ void saveCharacter(
   GltfBuilder::save(model, filename, fileFormat, kEmbedResources);
 }
 
+void saveCharacter(
+    const filesystem::path& filename,
+    const Character& character,
+    const float fps,
+    std::span<const SkeletonState> skeletonStates,
+    const std::vector<std::vector<Marker>>& markerSequence,
+    const GltfFileFormat fileFormat,
+    const GltfOptions& options) {
+  return saveGltfCharacter(
+      filename, character, fps, skeletonStates, markerSequence, fileFormat, options);
+}
+
 std::vector<std::byte> saveCharacterToBytes(
     const Character& character,
     float fps,

momentum/io/gltf/gltf_io.h

@@ -114,23 +114,52 @@ fx::gltf::Document makeCharacterDocument(
 /// numFrames)
 /// @param[in] offsets Offset values per joint capturing the skeleton bone lengths using translation
 /// and scale offset (7*numJoints, 1)
-void saveCharacter(
+[[deprecated("Use saveGltfCharacter() instead")]] void saveCharacter(
     const filesystem::path& filename,
-    const Character& Character,
+    const Character& character,
     float fps = 120.0f,
     const MotionParameters& motion = {},
     const IdentityParameters& offsets = {},
     const std::vector<std::vector<Marker>>& markerSequence = {},
     GltfFileFormat fileFormat = GltfFileFormat::Extension,
     const GltfOptions& options = GltfOptions());
 
+/// Saves character motion to a glb file.
+///
+/// @param[in] motion The model parameters representing the motion of the character (numModelParams,
+/// numFrames)
+/// @param[in] offsets Offset values per joint capturing the skeleton bone lengths using translation
+/// and scale offset (7*numJoints, 1)
+void saveGltfCharacter(
+    const filesystem::path& filename,
+    const Character& character,
+    float fps = 120.0f,
+    const MotionParameters& motion = {},
+    const IdentityParameters& offsets = {},
+    const std::vector<std::vector<Marker>>& markerSequence = {},
+    GltfFileFormat fileFormat = GltfFileFormat::Extension,
+    const GltfOptions& options = GltfOptions());
+
+/// Saves character skeleton states to a glb file.
+///
+/// @param[in] skeletonStates The skeleton states for each frame of the motion sequence (numFrames,
+/// numJoints, 8)
+[[deprecated("Use saveGltfCharacter() instead")]] void saveCharacter(
+    const filesystem::path& filename,
+    const Character& character,
+    float fps,
+    std::span<const SkeletonState> skeletonStates,
+    const std::vector<std::vector<Marker>>& markerSequence = {},
+    GltfFileFormat fileFormat = GltfFileFormat::Extension,
+    const GltfOptions& options = GltfOptions());
+
 /// Saves character skeleton states to a glb file.
 ///
 /// @param[in] skeletonStates The skeleton states for each frame of the motion sequence (numFrames,
 /// numJoints, 8)
-void saveCharacter(
+void saveGltfCharacter(
     const filesystem::path& filename,
-    const Character& Character,
+    const Character& character,
     float fps,
     std::span<const SkeletonState> skeletonStates,
     const std::vector<std::vector<Marker>>& markerSequence = {},

momentum/io/marker/marker_io.cpp

@@ -10,6 +10,7 @@
 #include "momentum/character/marker.h"
 #include "momentum/common/filesystem.h"
 #include "momentum/common/log.h"
+#include "momentum/io/fbx/fbx_io.h"
 #include "momentum/io/gltf/gltf_io.h"
 #include "momentum/io/marker/c3d_io.h"
 #include "momentum/io/marker/trc_io.h"
@@ -40,6 +41,8 @@ std::vector<MarkerSequence> loadMarkers(
       return {loadTrc(filename, up)};
     } else if (ext == ".glb") {
       return {loadMarkerSequence(filename)};
+    } else if (ext == ".fbx") {
+      return {loadFbxMarkerSequence(filename)};
     } else {
       MT_LOGE("{} Unknown marker file type {}", __func__, filename);
       return {};

pymomentum/CMakeLists.txt

@@ -158,6 +158,7 @@ mt_python_binding(
   LINK_LIBRARIES
     character
     character_test_helpers
+    io
     io_fbx
     io_gltf
     io_legacy_json