pymomentum-cpu 0.1.93.post0__cp312-cp312-macosx_14_0_arm64.whl

include/momentum/gui/rerun/logging_redirect.h

@@ -0,0 +1,27 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#pragma once
+
+#include <rerun.hpp>
+
+#include <string>
+
+namespace momentum {
+
+/// Redirects logs from the XR_LOG framework to the Rerun logger.
+///
+/// This function registers a custom log sink for the XR_LOG framework, redirecting its log messages
+/// to the Rerun logger. The redirection is only performed once, and subsequent calls to this
+/// function have no effect.
+///
+/// @param[in] rec The recording stream to which to write the logs. You should make sure the
+/// lifetime of this is longer than the loggings from momentum libraries.
+/// @return Returns true if the redirection is successful or has already been done.
+bool redirectLogsToRerun(const rerun::RecordingStream& rec);
+
+} // namespace momentum

include/momentum/io/character_io.h

@@ -0,0 +1,98 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#pragma once
+
+#include <momentum/character/fwd.h>
+#include <momentum/character/marker.h>
+#include <momentum/common/filesystem.h>
+#include <momentum/io/file_save_options.h>
+#include <momentum/math/fwd.h>
+#include <momentum/math/types.h>
+
+#include <string>
+#include <vector>
+
+namespace momentum {
+
+/// Represents the supported character formats.
+enum class CharacterFormat : uint8_t {
+  Fbx, ///< FBX file format.
+  Gltf, ///< glTF file format.
+  Usd, ///< USD file format.
+  Unknown ///< Unknown or unsupported file format.
+};
+
+/// High level function to load a character of any type, with a local path.
+///
+/// @param[in] characterPath The path to the character file.
+/// @param[in] parametersPath The optional path to the file containing additional parameters for the
+/// character.
+/// @param[in] locatorsPath The optional path to the file containing additional locators for the
+/// character.
+/// @return The loaded Character object.
+///
+/// Currently, only supports .glb and .fbx. If you want to parse from a non-local path, you may need
+/// to parse it using your favorite resource retriever into a buffer and use the buffer version of
+/// this function.
+[[nodiscard]] Character loadFullCharacter(
+    const std::string& characterPath,
+    const std::string& parametersPath = std::string(),
+    const std::string& locatorsPath = std::string());
+
+/// Buffer version of loadFullCharacter function, supports .glb and .fbx file formats.
+///
+/// @param[in] format The character file format.
+/// @param[in] characterBuffer The buffer containing the character data.
+/// @param[in] paramBuffer The optional buffer containing additional parameters for the character.
+/// @param[in] locBuffer The optional buffer containing additional locators for the character.
+/// @return The loaded Character object.
+[[nodiscard]] Character loadFullCharacterFromBuffer(
+    CharacterFormat format,
+    std::span<const std::byte> characterBuffer,
+    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] fps Frame rate for the animation (default: 120.0f).
+/// @param[in] motion The motion represented in model parameters (numModelParams, numFrames).
+/// @param[in] markerSequence Optional marker sequence data to save with the character.
+/// @param[in] options Optional file save options for controlling output (default:
+/// FileSaveOptions{}).
+void saveCharacter(
+    const filesystem::path& filename,
+    const Character& character,
+    float fps = 120.f,
+    const MatrixXf& motion = MatrixXf(),
+    std::span<const std::vector<Marker>> markerSequence = {},
+    const FileSaveOptions& options = FileSaveOptions());
+
+/// High level function to save a character with motion in skeleton states 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] fps Frame rate for the animation.
+/// @param[in] skeletonStates The motion represented in skeleton states (ie. JointStates).
+/// @param[in] markerSequence Optional marker sequence data to save with the character.
+/// @param[in] options Optional file save options for controlling output (default:
+/// FileSaveOptions{}).
+void saveCharacter(
+    const filesystem::path& filename,
+    const Character& character,
+    float fps,
+    std::span<const SkeletonState> skeletonStates,
+    std::span<const std::vector<Marker>> markerSequence = {},
+    const FileSaveOptions& options = FileSaveOptions());
+} // namespace momentum

include/momentum/io/common/gsl_utils.h

@@ -0,0 +1,50 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#pragma once
+
+#include <gsl/gsl>
+
+namespace momentum {
+
+/// Casts a span of bytes to a span of a different type
+///
+/// This function takes a span of bytes and returns a span of a different type, by reinterpreting
+/// the bytes as the new type. This function is useful when working with serialized data or when
+/// dealing with raw memory. The function assumes that the size of the new type is an exact multiple
+/// of the size of the original span.
+///
+/// @tparam T The type to cast the span to
+/// @param bs The original span of bytes to cast
+///
+/// @return A span of the new type, with the same number of elements as the original span
+template <typename T>
+[[nodiscard]] std::span<T> cast_span(std::span<std::byte> bs) {
+  auto ptr = reinterpret_cast<T*>(bs.data());
+  auto tsize = gsl::narrow<decltype(bs)::size_type>(sizeof(T));
+  return {ptr, bs.size_bytes() / tsize};
+}
+
+/// Casts a span of const bytes to a span of a different type
+///
+/// This function takes a span of const bytes and returns a span of a different type, by
+/// reinterpreting the bytes as the new type. This function is useful when working with serialized
+/// data or when dealing with raw memory. The function assumes that the size of the new type is an
+/// exact multiple of the size of the original span.
+///
+/// @tparam T The type to cast the span to
+/// @param bs The original span of const bytes to cast
+///
+/// @return A span of the new type, with the same number of elements as the original span
+template <typename T>
+[[nodiscard]] std::span<const T> cast_span(std::span<const std::byte> bs) {
+  auto ptr = reinterpret_cast<const T*>(bs.data());
+  auto tsize = gsl::narrow<decltype(bs)::size_type>(sizeof(T));
+  return {ptr, bs.size_bytes() / tsize};
+}
+
+} // namespace momentum

include/momentum/io/common/stream_utils.h

@@ -0,0 +1,65 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#pragma once
+
+#include <gsl/gsl>
+
+#include <istream>
+#include <streambuf>
+#include <string>
+
+namespace momentum {
+
+/// Stream buffer based on a span.
+/// Used to avoid copying the span when creating a std::istream:
+///   spanstreambuf sbuf(str);
+///   std::istream inputStream(&sbuf);
+struct spanstreambuf : std::streambuf {
+  /// Construct a spanstreambuf with an optional buffer.
+  ///
+  /// @param buffer A std::span of const std::byte (default: empty span).
+  spanstreambuf(std::span<const std::byte> buffer = {});
+
+  /// Destructor.
+  virtual ~spanstreambuf() override;
+
+ protected:
+  /// Write a sequence of characters to the output buffer.
+  ///
+  /// @param s A pointer to the character sequence to be written.
+  /// @param n The number of characters to write.
+  /// @return The number of characters successfully written.
+  std::streamsize xsputn(const char_type* s, std::streamsize n) override;
+};
+
+/// istream that takes a span of const bytes as input.
+struct ispanstream : std::istream {
+  /// Construct an ispanstream with a buffer.
+  ///
+  /// @param buffer A std::span of const std::byte.
+  explicit ispanstream(std::span<const std::byte> buffer);
+
+  /// Destructor.
+  virtual ~ispanstream();
+
+ private:
+  /// Internal spanstreambuf instance.
+  spanstreambuf sbuf_;
+};
+
+/// Reads a line from the input stream, handling line endings for different platforms.
+///
+/// This function reads a line from the given input stream and stores it in the 'line' parameter.
+/// It properly handles line endings for different platforms (e.g., LF for Unix, CRLF for Windows).
+///
+/// @param[in,out] is Reference to the input stream from which the line should be read.
+/// @param[in,out] line Reference to the string variable where the line will be stored.
+/// @return Reference to the input stream after reading the line.
+std::istream& GetLineCrossPlatform(std::istream& is, std::string& line);
+
+} // namespace momentum

include/momentum/io/fbx/fbx_io.h

@@ -0,0 +1,135 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#pragma once
+
+#include <momentum/character/fwd.h>
+#include <momentum/character/marker.h>
+#include <momentum/common/filesystem.h>
+#include <momentum/io/file_save_options.h>
+#include <momentum/math/types.h>
+
+#include <span>
+
+#include <string_view>
+
+namespace momentum {
+
+// KeepLocators Specifies whether Nulls in the transform hierarchy should be turned into Locators.
+enum class KeepLocators { No, Yes };
+
+// LoadBlendShapes Specifies whether blendshapes should be loaded or not
+enum class LoadBlendShapes { No, Yes };
+
+// Using keepLocators means the Nulls in the transform hierarchy will be turned into Locators.
+// This is different from historical momentum behavior so it's off by default.
+// Permissive mode allows loading  mesh-only characters (without skin weights).
+Character loadFbxCharacter(
+    const filesystem::path& inputPath,
+    KeepLocators keepLocators = KeepLocators::No,
+    Permissive permissive = Permissive::No,
+    LoadBlendShapes loadBlendShapes = LoadBlendShapes::No,
+    bool stripNamespaces = true);
+
+// Using keepLocators means the Nulls in the transform hierarchy will be turned into Locators.
+// This is different from historical momentum behavior so it's off by default.
+// Permissive mode allows loading  mesh-only characters (without skin weights).
+Character loadFbxCharacter(
+    std::span<const std::byte> inputSpan,
+    KeepLocators keepLocators = KeepLocators::No,
+    Permissive permissive = Permissive::No,
+    LoadBlendShapes loadBlendShapes = LoadBlendShapes::No,
+    bool stripNamespaces = true);
+
+// Permissive mode allows loading mesh-only characters (without skin weights).
+std::tuple<Character, std::vector<MatrixXf>, float> loadFbxCharacterWithMotion(
+    const filesystem::path& inputPath,
+    KeepLocators keepLocators = KeepLocators::No,
+    Permissive permissive = Permissive::No,
+    LoadBlendShapes loadBlendShapes = LoadBlendShapes::No,
+    bool stripNamespaces = true);
+
+// Permissive mode allows loading mesh-only characters (without skin weights).
+std::tuple<Character, std::vector<MatrixXf>, float> loadFbxCharacterWithMotion(
+    std::span<const std::byte> inputSpan,
+    KeepLocators keepLocatorss = KeepLocators::No,
+    Permissive permissive = Permissive::No,
+    LoadBlendShapes loadBlendShape = LoadBlendShapes::No,
+    bool stripNamespaces = true);
+
+/// Save a character with animation to an FBX file.
+/// @param filename Path to the output FBX file
+/// @param character The character to save
+/// @param poses Model parameters for each frame (empty for bind pose only)
+/// @param identity Identity pose parameters (empty to use bind pose)
+/// @param framerate Animation framerate in frames per second
+/// @param markerSequence Optional marker sequence data to save with the character
+/// @param options Optional file save options for controlling output (default: FileSaveOptions{})
+void saveFbx(
+    const filesystem::path& filename,
+    const Character& character,
+    const MatrixXf& poses = MatrixXf(),
+    const VectorXf& identity = VectorXf(),
+    double framerate = 120.0,
+    std::span<const std::vector<Marker>> markerSequence = {},
+    const FileSaveOptions& options = FileSaveOptions());
+
+/// Save a character with animation using joint parameters directly.
+/// @param filename Path to the output FBX file
+/// @param character The character to save
+/// @param jointParams Joint parameters for each frame (empty for bind pose only)
+/// @param framerate Animation framerate in frames per second
+/// @param markerSequence Optional marker sequence data to save with the character
+/// @param options Optional file save options for controlling output (default: FileSaveOptions{})
+void saveFbxWithJointParams(
+    const filesystem::path& filename,
+    const Character& character,
+    const MatrixXf& jointParams = MatrixXf(),
+    double framerate = 120.0,
+    std::span<const std::vector<Marker>> markerSequence = {},
+    const FileSaveOptions& options = FileSaveOptions());
+
+/// 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 markerSequence Optional marker sequence data to save with the character
+/// @param options Optional file save options for controlling output (default: FileSaveOptions{})
+void saveFbxWithSkeletonStates(
+    const filesystem::path& filename,
+    const Character& character,
+    std::span<const SkeletonState> skeletonStates,
+    double framerate = 120.0,
+    std::span<const std::vector<Marker>> markerSequence = {},
+    const FileSaveOptions& options = FileSaveOptions());
+
+/// Save a character model (skeleton and mesh) without animation.
+/// @param filename Path to the output FBX file
+/// @param character The character to save
+/// @param options Optional file save options for controlling output (default: FileSaveOptions{})
+void saveFbxModel(
+    const filesystem::path& filename,
+    const Character& character,
+    const FileSaveOptions& options = FileSaveOptions());
+
+/// Loads a MarkerSequence from an FBX file.
+///
+/// This function reads motion capture marker data from an FBX file and returns
+/// it as a MarkerSequence. The markers must be stored in the FBX scene hierarchy
+/// under a "Markers" root node, and each marker node must have the custom property
+/// "Momentum_Marker" to be recognized. The Markers root node must have the custom
+/// property "Momentum_Markers_Root" to be identified.
+///
+/// @param[in] filename Path to the FBX file containing marker data.
+/// @param stripNamespaces Removes namespace from joints when true. True by default
+/// @return A MarkerSequence object containing the marker animation data, including
+///         marker positions per frame and fps. Returns an empty sequence if no
+///         markers or animations are found.
+MarkerSequence loadFbxMarkerSequence(const filesystem::path& filename, bool stripNamespaces = true);
+
+} // namespace momentum

include/momentum/io/fbx/fbx_memory_stream.h

@@ -0,0 +1,70 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#pragma once
+
+#ifdef MOMENTUM_WITH_FBX_SDK
+
+#include <fbxsdk.h>
+#include <fbxsdk/core/fbxstream.h>
+#include <span>
+
+#include <string_view>
+
+#define FBX_VERSION_GE(major, minor, patch)                               \
+  ((FBXSDK_VERSION_MAJOR > (major)) ||                                    \
+   (FBXSDK_VERSION_MAJOR == (major) && FBXSDK_VERSION_MINOR > (minor)) || \
+   (FBXSDK_VERSION_MAJOR == (major) && FBXSDK_VERSION_MINOR == (minor) && \
+    FBXSDK_VERSION_POINT >= (patch)))
+
+namespace momentum {
+
+// Simplest FbxStream to read file from a string_view memory buffer
+class FbxMemoryStream : public FbxStream {
+ public:
+  FbxMemoryStream(std::span<const std::byte> buffer, int pReaderId);
+  ~FbxMemoryStream() override;
+  EState GetState() override;
+  bool Open(void* pStreamData) override;
+  bool Close() override;
+  bool Flush() override;
+#if FBX_VERSION_GE(2020, 3, 2)
+  size_t Write(const void* buffer, FbxUInt64 count) override;
+  size_t Read(void* buffer, FbxUInt64 count) const override;
+#else
+  int Write(const void* buffer, int count) override;
+  int Read(void* buffer, int count) const override;
+#endif
+  int GetReaderID() const override;
+  int GetWriterID() const override;
+  void Seek(const FbxInt64& pOffset, const FbxFile::ESeekPos& pSeekPos) override;
+#if FBX_VERSION_GE(2020, 3, 2)
+  FbxInt64 GetPosition() const override;
+  void SetPosition(FbxInt64 pPosition) override;
+#else
+  long GetPosition() const override;
+  void SetPosition(long pPosition) override;
+#endif
+  int GetError() const override;
+  void ClearError() override;
+
+ private:
+  std::span<const std::byte> buffer_;
+  long length_;
+#if FBX_VERSION_GE(2020, 3, 2)
+  mutable FbxInt64 position_{0};
+#else
+  mutable long position_;
+#endif
+  EState state_;
+  int readerId_;
+  mutable int errorCode_;
+};
+
+} // namespace momentum
+
+#endif // MOMENTUM_WITH_FBX_SDK

include/momentum/io/fbx/openfbx_loader.h

@@ -0,0 +1,62 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#pragma once
+
+#include <momentum/character/fwd.h>
+#include <momentum/character/marker.h>
+#include <momentum/common/filesystem.h>
+#include <momentum/io/fbx/fbx_io.h>
+#include <momentum/math/types.h>
+
+#include <span>
+
+namespace momentum {
+
+// Custom property names for identifying Momentum-specific FBX nodes
+constexpr const char* kMomentumMarkersRootProperty = "Momentum_Markers_Root";
+constexpr const char* kMomentumMarkerProperty = "Momentum_Marker";
+
+// Using keepLocators means the Nulls in the transform hierarchy will be turned into Locators.
+// This is different from historical momentum behavior so it's off by default.
+// Permissive mode allows loading mesh-only characters (without skin weights).
+Character loadOpenFbxCharacter(
+    const filesystem::path& inputPath,
+    KeepLocators keepLocators = KeepLocators::No,
+    Permissive permissive = Permissive::No,
+    LoadBlendShapes loadBlendShapes = LoadBlendShapes::No,
+    bool stripNamespaces = true);
+
+// Permissive mode allows loading mesh-only characters (without skin weights).
+Character loadOpenFbxCharacter(
+    std::span<const std::byte> inputData,
+    KeepLocators keepLocators = KeepLocators::No,
+    Permissive permissive = Permissive::No,
+    LoadBlendShapes loadBlendShapes = LoadBlendShapes::No,
+    bool stripNamespaces = true);
+
+// Permissive mode allows loading mesh-only characters (without skin weights).
+std::tuple<Character, std::vector<MatrixXf>, float> loadOpenFbxCharacterWithMotion(
+    const filesystem::path& inputPath,
+    KeepLocators keepLocators = KeepLocators::No,
+    Permissive permissive = Permissive::No,
+    LoadBlendShapes loadBlendShapes = LoadBlendShapes::No,
+    bool stripNamespaces = true);
+
+// Permissive mode allows loading mesh-only characters (without skin weights).
+std::tuple<Character, std::vector<MatrixXf>, float> loadOpenFbxCharacterWithMotion(
+    std::span<const std::byte> inputData,
+    KeepLocators keepLocators = KeepLocators::No,
+    Permissive permissive = Permissive::No,
+    LoadBlendShapes loadBlendShapes = LoadBlendShapes::No,
+    bool stripNamespaces = true);
+
+MarkerSequence loadOpenFbxMarkerSequence(
+    const filesystem::path& filename,
+    bool stripNamespaces = true);
+
+} // namespace momentum

include/momentum/io/fbx/polygon_data.h

@@ -0,0 +1,60 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#pragma once
+
+#include <momentum/math/types.h>
+
+#include <span>
+
+#include <string>
+#include <vector>
+
+namespace momentum {
+
+// Structure for holding arbitrary polygon data.  We will read the data as-is from the
+// FBX file and then triangulate at the end for momentum.  Doing it this way allows us
+// to split up the functionality (triangulating while you read complicates handling
+// texture coordinates for example).
+struct PolygonData {
+  // We will pack polygons in an array like this:
+  // The indices array will contain all the polygons indices packed back-to-back.
+  //   1 2 3 4   2 3 4 6   ...
+  // The offsets array will include an offset for the start and end of each polygon.
+  //   0 4 8 ...
+  // The advantage of doing it this way is that we have random access into the
+  // polygons.  The disadvantage (compared to just providing an array of vertex counts)
+  // is that the offset array should always have one more than the number of polygons,
+  // which is a little confusing.
+  std::vector<uint32_t> indices;
+  std::vector<uint32_t> offsets;
+
+  // The texture coordinate indices for each face.
+  // Uses the same offsets array as the indices array.
+  // Note that this is allowed to be empty, but if not empty it
+  // must be the same size as the indices array.
+  std::vector<uint32_t> textureIndices;
+
+  PolygonData() : offsets{0} {}
+
+  // If there's a problem with the mesh, returns an error message.
+  // If everything is kosher, returns an empty string.
+  // This function is used in a few places when reading the mesh from
+  // disk to make sure it's valid.
+  [[nodiscard]] std::string errorMessage(size_t numVertices) const;
+
+  // Similar to errorMessage, but the issue is not severe enough to terminate.
+  [[nodiscard]] std::string warnMessage(size_t numTexVertices) const;
+
+  [[nodiscard]] size_t numPolygons() const;
+};
+
+std::vector<Eigen::Vector3i> triangulate(
+    std::span<const uint32_t> indices,
+    std::span<const uint32_t> offsets);
+
+} // namespace momentum

include/momentum/io/file_save_options.h

@@ -0,0 +1,107 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#pragma once
+
+#include <string_view>
+
+namespace momentum {
+
+// ============================================================================
+// Permissive Mode
+// ============================================================================
+
+// Permissive specifies whether we want to be able to load mesh-only characters (without skin
+// weights), and whether we want to bake the unhandled pose information into base skeleton.
+enum class Permissive { No, Yes };
+
+// ============================================================================
+// GLTF File Format
+// ============================================================================
+
+/// File format in which the character is saved
+enum class GltfFileFormat {
+  Auto = 0, // The file extension is used for deduction (e.g. ".gltf" --> ASCII)
+  Binary = 1, // Binary format (generally .glb)
+  Ascii = 2, // ASCII format (generally .gltf)
+};
+
+// ============================================================================
+// FBX Coordinate System Options
+// ============================================================================
+
+/// Specifies which canonical axis represents up in the system (typically Y or Z).
+/// Maps to fbxsdk::FbxAxisSystem::EUpVector
+enum class FbxUpVector { XAxis = 1, YAxis = 2, ZAxis = 3 };
+
+/// Vector with origin at the screen pointing toward the camera.
+/// This is a subset of enum EUpVector because axis cannot be repeated.
+/// We use the system of "parity" to define this vector because its value (X,Y or
+/// Z axis) really depends on the up-vector.
+/// Maps to fbxsdk::FbxAxisSystem::EFrontVector
+enum class FbxFrontVector { ParityEven = 1, ParityOdd = 2 };
+
+/// Specifies the third vector of the system.
+/// Maps to fbxsdk::FbxAxisSystem::ECoordSystem
+enum class FbxCoordSystem { RightHanded, LeftHanded };
+
+/// A struct containing the up, front vectors and coordinate system for FBX export.
+struct FbxCoordSystemInfo {
+  /// Default to the same orientations as FbxAxisSystem::eMayaYUp
+  FbxUpVector upVector = FbxUpVector::YAxis;
+  FbxFrontVector frontVector = FbxFrontVector::ParityOdd;
+  FbxCoordSystem coordSystem = FbxCoordSystem::RightHanded;
+};
+
+// ============================================================================
+// Unified File Save Options
+// ============================================================================
+
+/// Unified options for saving files in both FBX and GLTF formats.
+///
+/// This struct consolidates save options that were previously scattered across
+/// multiple function parameters. Format-specific options (e.g., FBX coordinate
+/// system, GLTF extensions) are included but only used by their respective formats.
+struct FileSaveOptions {
+  // ---- Common Options (used by both FBX and GLTF) ----
+
+  /// Include mesh geometry in the output (default: true)
+  bool mesh = true;
+
+  /// Include locators in the output (default: true)
+  bool locators = true;
+
+  /// Include collision geometry in the output (default: true)
+  bool collisions = true;
+
+  /// Include blend shapes in the output (default: true)
+  bool blendShapes = true;
+
+  /// Permissive mode: allow saving mesh-only characters without skin weights (default: false)
+  Permissive permissive = Permissive::No;
+
+  // ---- FBX-Specific Options ----
+
+  /// FBX coordinate system configuration (default: Maya Y-up)
+  FbxCoordSystemInfo coordSystemInfo = {};
+
+  /// Optional namespace prefix for FBX node names (e.g., "ns" becomes "ns:")
+  /// Only used for FBX output (default: empty = no namespace)
+  std::string_view fbxNamespace = "";
+
+  // ---- GLTF-Specific Options ----
+
+  /// Enable GLTF extensions (default: true)
+  /// Only used for GLTF output
+  bool extensions = true;
+
+  /// GLTF file format selection (default: Auto)
+  /// Only used for GLTF output
+  GltfFileFormat gltfFileFormat = GltfFileFormat::Auto;
+};
+
+} // namespace momentum