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 `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

momentum/io/character_io.cpp

@@ -139,4 +139,43 @@ Character loadFullCharacterFromBuffer(
   return character.value();
 }
 
+void saveCharacterToFile(
+    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) {
+    saveCharacter(
+        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 if (format == CharacterFormat::Usd) {
+    MT_THROW("USD format is not yet supported for saving. Supported formats: .fbx, .glb, .gltf");
+  }
+}
+
 } // 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,21 @@ enum class CharacterFormat : uint8_t {
     gsl::span<const std::byte> paramBuffer = gsl::span<const std::byte>(),
     gsl::span<const std::byte> locBuffer = gsl::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 saveCharacterToFile(
+    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);
 } // namespace momentum

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/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 saveCharacterToFile(
+    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) {
@@ -217,6 +228,22 @@ void saveFBXCharacterToFileWithJointParams(
   }
 }
 
+void saveCharacterToFile(
+    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::saveCharacterToFile(
+      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);

pymomentum/geometry/momentum_io.h

@@ -72,6 +72,14 @@ void saveFBXCharacterToFileWithJointParams(
     std::optional<const momentum::FBXCoordSystemInfo> coordSystemInfo,
     std::string_view fbxNamespace = "");
 
+void saveCharacterToFile(
+    const std::string& path,
+    const momentum::Character& character,
+    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);
+
 std::tuple<momentum::Character, RowMatrixf, Eigen::VectorXf, float> loadGLTFCharacterWithMotion(
     const std::string& gltfFilename);