pymomentum-cpu 0.1.78.post11__cp312-cp312-win_amd64.whl

include/momentum/io/character_io.h

@@ -0,0 +1,56 @@
+/*
+ * 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/math/fwd.h>
+#include <momentum/math/types.h>
+
+#include <string>
+
+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,
+    gsl::span<const std::byte> characterBuffer,
+    gsl::span<const std::byte> paramBuffer = gsl::span<const std::byte>(),
+    gsl::span<const std::byte> locBuffer = gsl::span<const std::byte>());
+
+} // 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]] gsl::span<T> cast_span(gsl::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]] gsl::span<const T> cast_span(gsl::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 gsl::span of const std::byte (default: empty span).
+  spanstreambuf(gsl::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 gsl::span of const std::byte.
+  explicit ispanstream(gsl::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,109 @@
+/*
+ * 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/common/filesystem.h>
+#include <momentum/math/types.h>
+
+#include <gsl/span>
+
+namespace momentum {
+
+// UpVector 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 };
+
+// FrontVector  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. The EPreDefinedAxisSystem list the
+// up-vector, parity and coordinate system values for the predefined systems.
+// Maps to fbxsdk::FbxAxisSystem::EFrontVector
+enum class FBXFrontVector { ParityEven = 1, ParityOdd = 2 };
+
+// CoordSystem Specifies the third vector of the system.
+// Maps to fbxsdk::FbxAxisSystem::ECoordSystem
+enum class FBXCoordSystem { RightHanded, LeftHanded };
+
+// 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 };
+
+// A struct containing the up, front vectors and coordinate system
+struct FBXCoordSystemInfo {
+  // Default to the same orientations as FbxAxisSystem::eMayaYUp
+  FBXUpVector upVector = FBXUpVector::YAxis;
+  FBXFrontVector frontVector = FBXFrontVector::ParityOdd;
+  FBXCoordSystem coordSystem = FBXCoordSystem::RightHanded;
+};
+
+// 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,
+    bool permissive = false,
+    LoadBlendShapes loadBlendShapes = LoadBlendShapes::No);
+
+// 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(
+    gsl::span<const std::byte> inputSpan,
+    KeepLocators keepLocators = KeepLocators::No,
+    bool permissive = false,
+    LoadBlendShapes loadBlendShapes = LoadBlendShapes::No);
+
+// 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,
+    bool permissive = false,
+    LoadBlendShapes loadBlendShapes = LoadBlendShapes::No);
+
+// Permissive mode allows loading mesh-only characters (without skin weights).
+std::tuple<Character, std::vector<MatrixXf>, float> loadFbxCharacterWithMotion(
+    gsl::span<const std::byte> inputSpan,
+    KeepLocators keepLocatorss = KeepLocators::No,
+    bool permissive = false,
+    LoadBlendShapes loadBlendShape = LoadBlendShapes::No);
+
+// Permissive mode allows saving mesh-only characters (without skin weights).
+void saveFbx(
+    const filesystem::path& filename,
+    const Character& character,
+    const MatrixXf& poses = MatrixXf(),
+    const VectorXf& identity = VectorXf(),
+    double framerate = 120.0,
+    bool saveMesh = false,
+    const FBXCoordSystemInfo& coordSystemInfo = FBXCoordSystemInfo(),
+    bool permissive = false);
+
+// Permissive mode allows saving mesh-only characters (without skin weights).
+void saveFbxWithJointParams(
+    const filesystem::path& filename,
+    const Character& character,
+    const MatrixXf& jointParams = MatrixXf(),
+    double framerate = 120.0,
+    bool saveMesh = false,
+    const FBXCoordSystemInfo& coordSystemInfo = FBXCoordSystemInfo(),
+    bool permissive = false);
+
+// A shorthand of saveFbx() to save both the skeleton and mesh as a model but without any animation
+// Permissive mode allows saving mesh-only characters (without skin weights).
+void saveFbxModel(
+    const filesystem::path& filename,
+    const Character& character,
+    const FBXCoordSystemInfo& coordSystemInfo = FBXCoordSystemInfo(),
+    bool permissive = false);
+
+} // namespace momentum

include/momentum/io/fbx/fbx_memory_stream.h

@@ -0,0 +1,66 @@
+/*
+ * 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 <fbxsdk.h>
+#include <fbxsdk/core/fbxstream.h>
+#include <gsl/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(gsl::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:
+  gsl::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

include/momentum/io/fbx/openfbx_loader.h

@@ -0,0 +1,49 @@
+/*
+ * 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/common/filesystem.h>
+#include <momentum/io/fbx/fbx_io.h>
+#include <momentum/math/types.h>
+
+#include <gsl/span>
+
+namespace momentum {
+
+// 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,
+    bool permissive = false,
+    LoadBlendShapes loadBlendShapes = LoadBlendShapes::No);
+
+// Permissive mode allows loading mesh-only characters (without skin weights).
+Character loadOpenFbxCharacter(
+    gsl::span<const std::byte> inputData,
+    KeepLocators keepLocators = KeepLocators::No,
+    bool permissive = false,
+    LoadBlendShapes loadBlendShapes = LoadBlendShapes::No);
+
+// 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,
+    bool permissive = false,
+    LoadBlendShapes loadBlendShapes = LoadBlendShapes::No);
+
+// Permissive mode allows loading mesh-only characters (without skin weights).
+std::tuple<Character, std::vector<MatrixXf>, float> loadOpenFbxCharacterWithMotion(
+    gsl::span<const std::byte> inputData,
+    KeepLocators keepLocators = KeepLocators::No,
+    bool permissive = false,
+    LoadBlendShapes loadBlendShapes = LoadBlendShapes::No);
+
+} // 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 <gsl/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(
+    gsl::span<const uint32_t> indices,
+    gsl::span<const uint32_t> offsets);
+
+} // namespace momentum

include/momentum/io/gltf/gltf_builder.h

@@ -0,0 +1,132 @@
+/*
+ * 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/marker.h>
+#include <momentum/character/skeleton.h>
+#include <momentum/common/filesystem.h>
+#include <momentum/io/gltf/gltf_file_format.h>
+#include <momentum/io/gltf/gltf_io.h>
+#include <momentum/math/mesh.h>
+#include <momentum/math/types.h>
+
+#include <fx/gltf.h>
+
+namespace fx::gltf {
+struct Document;
+} // namespace fx::gltf
+
+namespace momentum {
+
+using MotionParameters = std::tuple<std::vector<std::string>, MatrixXf>;
+using IdentityParameters = std::tuple<std::vector<std::string>, VectorXf>;
+
+/// Helper class to build a glb scene. It supports adding multiple characters
+/// and motions for each character.
+/// By default, momentum extension is added to the glb nodes. This is required if you
+/// want to correctly load the exported character back.
+class GltfBuilder final {
+ public:
+  GltfBuilder();
+
+  ~GltfBuilder();
+
+  GltfBuilder(GltfBuilder const&) = delete;
+
+  void operator=(GltfBuilder const&) = delete;
+
+  /// Specify how marker mesh is represented in the glb file
+  enum class MarkerMesh : uint8_t { None, UnitCube };
+
+  /// Add a character to the scene. Each character will have a root node with the character's
+  /// name as the parent of the skeleton root and the character mesh.
+  /// positionOffset and rotationOffset can be provided as an initial offset to the character.
+  void addCharacter(
+      const Character& character,
+      const Vector3f& positionOffset = Vector3f::Zero(),
+      const Quaternionf& rotationOffset = Quaternionf::Identity(),
+      const GltfOptions& options = GltfOptions());
+
+  /// Add a static mesh, such as an environment or a target scan
+  void addMesh(const Mesh& mesh, const std::string& name, bool addColor = false);
+
+  void setFps(float fps);
+
+  /// Add a motion to the provided character. If addCharacter is not called before adding
+  /// the motion, the character will be automatically added with the default settings.
+  void addMotion(
+      const Character& character,
+      float fps = 120.0f,
+      const MotionParameters& motion = {},
+      const IdentityParameters& offsets = {},
+      bool addExtensions = true,
+      const std::string& customName = "default");
+
+  /// Add a skeleton states to the provided character. If addCharacter is not called before adding
+  /// the skeleton states, the character will be automatically added with the default settings.
+  void addSkeletonStates(
+      const Character& character,
+      float fps,
+      gsl::span<const SkeletonState> skeletonStates,
+      const std::string& customName = "default");
+
+  /// Add marker data to the file
+  ///
+  /// @param[in] fps The frame rate of the motion capture data in frames per second.
+  /// @param[in] markerSequence A 2D vector specifying the Marker data (name/position/occlusion) for
+  /// all markers across all captured frames. Size: [numFrames][numMarkers]
+  /// @param[in] markerMesh Optional parameter specifying the MarkerMesh type (default is
+  /// MarkerMesh::None).
+  /// @param[in] animName Optional parameter specifying the animation name (default is "default").
+  void addMarkerSequence(
+      float fps,
+      gsl::span<const std::vector<momentum::Marker>> markerSequence,
+      MarkerMesh markerMesh = MarkerMesh::None,
+      const std::string& animName = "default");
+
+  // Save the file with the provided filename. If the fileFormat is 'GltfFileFormat::Extension',
+  // will deduct the file format by filename.
+  // When embedResources is true, it will set all the existing buffers to embed the data.
+  void save(
+      const filesystem::path& filename,
+      GltfFileFormat fileFormat = GltfFileFormat::Extension,
+      bool embedResources = false);
+
+  static void save(
+      fx::gltf::Document& document,
+      const filesystem::path& filename,
+      GltfFileFormat fileFormat = GltfFileFormat::Extension,
+      bool embedResources = false);
+
+  /// Set all existing buffers to embed resources.
+  void forceEmbedResources();
+
+  static void forceEmbedResources(fx::gltf::Document& document);
+
+  /// Allow copy the document, but do not allow modify the file
+  /// outside of the builder to keep metadata consistent
+  const fx::gltf::Document& getDocument();
+
+  size_t getNumCharacters();
+
+  size_t getCharacterRootIndex(const std::string& name);
+
+  size_t getNumJoints(const std::string& name);
+
+  size_t getNumMotions();
+
+  float getFps();
+
+  std::vector<size_t> getCharacterMotions(const std::string& characterName);
+
+ private:
+  struct Impl;
+  std::unique_ptr<Impl> impl_;
+};
+
+} // namespace momentum

include/momentum/io/gltf/gltf_file_format.h

@@ -0,0 +1,19 @@
+/*
+ * 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
+
+namespace momentum {
+
+// File format in which the character is saved
+enum class GltfFileFormat {
+  Extension = 0, // The file extension is used for deduction (e.g. ".gltf" --> ASCII)
+  GltfBinary = 1, // Binary format (generally .glb)
+  GltfAscii = 2, // ASCII format (generally .gltf)
+};
+
+} // namespace momentum