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

Summary:
Pull Request resolved: #753

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

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

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
+    saveFbxWithSkelState(
+        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 saveFbxWithSkelState(
+    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,17 @@ void saveFbxWithJointParams(
     const std::vector<std::vector<Marker>>& markerSequence = {},
     std::string_view fbxNamespace = "");
 
+void saveFbxWithSkelState(
+    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/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

@@ -124,6 +124,22 @@ void saveCharacter(
     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,
@@ -137,6 +153,19 @@ void saveCharacter(
     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 saveGltfCharacter(
+    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());
+
 std::vector<std::byte> saveCharacterToBytes(
     const Character& character,
     float fps = 120.0f,

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

pymomentum/geometry/momentum_io.cpp

@@ -17,6 +17,17 @@
 #include <momentum/io/gltf/gltf_io.h>
 #include <momentum/io/marker/marker_io.h>
 
+// Forward declaration for unified save function
+namespace momentum {
+void saveCharacter(
+    const filesystem::path& filename,
+    const Character& character,
+    const MatrixXf& motion,
+    const VectorXf& offsets,
+    const std::vector<std::vector<Marker>>& markerSequence,
+    float fps);
+} // namespace momentum
+
 namespace pymomentum {
 
 momentum::Character loadGLTFCharacterFromFile(const std::string& path) {
@@ -117,7 +128,7 @@ void saveGLTFCharacterToFile(
         poses.rows(),
         poses.cols());
   }
-  momentum::saveCharacter(
+  momentum::saveGltfCharacter(
       path,
       character,
       fps,
@@ -147,7 +158,7 @@ void saveGLTFCharacterToFileFromSkelStates(
   std::vector<momentum::SkeletonState> skeletonStates =
       arrayToSkeletonStates(skel_states, character);
 
-  momentum::saveCharacter(
+  momentum::saveGltfCharacter(
       path,
       character,
       fps,
@@ -217,6 +228,22 @@ void saveFBXCharacterToFileWithJointParams(
   }
 }
 
+void saveCharacter(
+    const std::string& path,
+    const momentum::Character& character,
+    const float fps,
+    const std::optional<const Eigen::MatrixXf>& motion,
+    const std::optional<const Eigen::VectorXf>& offsets,
+    const std::optional<const std::vector<std::vector<momentum::Marker>>>& markers) {
+  momentum::saveCharacter(
+      path,
+      character,
+      motion.has_value() ? motion.value().transpose() : Eigen::MatrixXf{},
+      offsets.value_or(Eigen::VectorXf{}),
+      markers.value_or(std::vector<std::vector<momentum::Marker>>{}),
+      fps);
+}
+
 std::tuple<momentum::Character, RowMatrixf, Eigen::VectorXf, float> loadGLTFCharacterWithMotion(
     const std::string& gltfFilename) {
   const auto [character, motion, identity, fps] = momentum::loadCharacterWithMotion(gltfFilename);