Add unified saveCharacter function for FBX/GLTF parity

Summary:
Created a high-level saveCharacter() function in character_io that automatically selects between FBX and GLTF export based on file extension. This achieves feature parity between the two formats for saving characters with motion and marker sequences.

Key changes:
- Added saveCharacter() overload that takes a filesystem path
- Function automatically detects format from extension (.fbx, .glb, .gltf)
- Routes to appropriate format-specific save function (saveFbx or GLTF saveCharacter)
- Supports motion, offsets, and marker sequences for both formats
- Provides clear error messages for unknown/unsupported formats

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);