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

include/momentum/io/gltf/gltf_builder.h

@@ -0,0 +1,141 @@
+/*
+ * 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/file_save_options.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 FileSaveOptions& options = FileSaveOptions());
+
+  /// 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.
+  ///
+  /// @param[in] character The character to add motion for.
+  /// @param[in] fps Frame rate of the motion in frames per second.
+  /// @param[in] motion Motion parameters (parameter names and poses matrix).
+  /// @param[in] offsets Identity/offset parameters (joint names and offsets vector).
+  /// @param[in] addExtensions Whether to add momentum extensions to the document.
+  /// @param[in] customName Custom name for the animation (default is "default").
+  /// @param[in] timestamps Per-frame timestamps. Size should match motion columns.
+  void addMotion(
+      const Character& character,
+      float fps = 120.0f,
+      const MotionParameters& motion = {},
+      const IdentityParameters& offsets = {},
+      bool addExtensions = true,
+      const std::string& customName = "default",
+      std::span<const int64_t> timestamps = {});
+
+  /// 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,
+      std::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,
+      std::span<const std::vector<momentum::Marker>> markerSequence,
+      MarkerMesh markerMesh = MarkerMesh::UnitCube,
+      const std::string& animName = "default");
+
+  // Save the file with the provided filename. If the fileFormat is 'GltfFileFormat::Auto',
+  // 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::Auto,
+      bool embedResources = false);
+
+  static void save(
+      fx::gltf::Document& document,
+      const filesystem::path& filename,
+      GltfFileFormat fileFormat = GltfFileFormat::Auto,
+      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_io.h

@@ -0,0 +1,149 @@
+/*
+ * 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/types.h>
+#include <momentum/common/filesystem.h>
+#include <momentum/io/file_save_options.h>
+#include <momentum/math/types.h>
+
+#include <fx/gltf.h>
+#include <span>
+
+#include <tuple>
+#include <vector>
+
+namespace momentum {
+
+Character loadGltfCharacter(const fx::gltf::Document& model);
+
+Character loadGltfCharacter(const filesystem::path& gltfFilename);
+
+Character loadGltfCharacter(std::span<const std::byte> byteSpan);
+
+std::tuple<MotionParameters, IdentityParameters, float> loadMotion(
+    const filesystem::path& gltfFilename);
+
+/// Load per-frame timestamps from a glTF file.
+/// This function loads timestamps that were saved using GltfBuilder::addMotion
+///
+/// @param[in] gltfFilename The path to the glTF file.
+/// @return A vector of per-frame timestamps (usually in microsecond).
+std::vector<int64_t> loadMotionTimestamps(const filesystem::path& gltfFilename);
+
+/// Load a glTF character from a local file path.
+///
+/// This function assumes the file format of the given path is glTF without checking the extension,
+/// so please ensure the file is in glTF format.
+///
+/// @param[in] filepath The path to the glTF character file.
+/// @return A tuple containing the loaded Character object, the motion represented in model
+/// parameters, the identity vector represented as joint parameters, and the fps.
+std::tuple<Character, MatrixXf, VectorXf, float> loadCharacterWithMotion(
+    const filesystem::path& gltfFilename);
+
+/// Load a glTF character from a buffer.
+///
+/// @param[in] byteSpan The buffer containing the glTF character data.
+/// @return A tuple containing the loaded Character object, the motion represented in model
+/// parameters, the identity vector represented as joint parameters, and the fps.
+std::tuple<Character, MatrixXf, VectorXf, float> loadCharacterWithMotion(
+    std::span<const std::byte> byteSpan);
+
+/// Load a GLTF Character with motion in the form of skeleton states (transform matrices)
+///
+/// Unlike the other loadCharacterWithMotion functions, this function does not require the
+/// file to be saved using momentum's functionality that saves model parameters in a
+/// custom GTLF extension, however the resulting skeleton states may be harder to work with.
+std::tuple<Character, std::vector<SkeletonState>, std::vector<float>>
+loadCharacterWithSkeletonStates(std::span<const std::byte> byteSpan);
+
+std::tuple<Character, std::vector<SkeletonState>, std::vector<float>>
+loadCharacterWithSkeletonStates(const filesystem::path& gltfFilename);
+
+/// Maps the loaded motion onto the input character by matching joint names and parameter names.
+///
+/// This function assumes the file format of the given path is glTF without checking the extension,
+/// so please ensure the file is in glTF format.
+///
+/// @param[in] gltfFilename The path to the glTF motion file.
+/// @param[in] character The Character object to map the motion onto.
+/// @return A tuple containing the motion represented in model parameters, the identity vector
+/// represented as joint parameters, and the fps. The model parameters and joint parameters are
+/// mapped to the input character by name matching.
+std::tuple<MatrixXf, VectorXf, float> loadMotionOnCharacter(
+    const filesystem::path& gltfFilename,
+    const Character& character);
+
+/// Buffer version of loadMotionOnCharacter()
+///
+/// @param[in] byteSpan The buffer containing the glTF motion data.
+/// @param[in] character The Character object to map the motion onto.
+/// @return A tuple containing the motion represented in model parameters, the identity vector
+/// represented as joint parameters, and the fps. The model parameters and joint parameters are
+/// mapped to the input character by name matching.
+std::tuple<MatrixXf, VectorXf, float> loadMotionOnCharacter(
+    std::span<const std::byte> byteSpan,
+    const Character& character);
+
+/// Loads a MarkerSequence from a file.
+///
+/// @param[in] filename Path to the file containing the MarkerSequence data.
+/// @return A MarkerSequence object containing motion capture marker data.
+MarkerSequence loadMarkerSequence(const filesystem::path& filename);
+
+fx::gltf::Document makeCharacterDocument(
+    const Character& character,
+    float fps = 120.0f,
+    const MotionParameters& motion = {},
+    const IdentityParameters& offsets = {},
+    std::span<const std::vector<Marker>> markerSequence = {},
+    bool embedResource = true,
+    const FileSaveOptions& options = FileSaveOptions());
+
+/// 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)
+/// @param[in] options Optional file save options for controlling output (default:
+/// FileSaveOptions{}).
+void saveGltfCharacter(
+    const filesystem::path& filename,
+    const Character& character,
+    float fps = 120.0f,
+    const MotionParameters& motion = {},
+    const IdentityParameters& offsets = {},
+    std::span<const std::vector<Marker>> markerSequence = {},
+    const FileSaveOptions& options = FileSaveOptions());
+
+/// Saves character skeleton states to a glb file.
+///
+/// @param[in] skeletonStates The skeleton states for each frame of the motion sequence (numFrames,
+/// numJoints, 8)
+/// @param[in] options Optional file save options for controlling output (default:
+/// FileSaveOptions{}).
+void saveGltfCharacter(
+    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());
+
+std::vector<std::byte> saveCharacterToBytes(
+    const Character& character,
+    float fps = 120.0f,
+    const MotionParameters& motion = {},
+    const IdentityParameters& offsets = {},
+    std::span<const std::vector<Marker>> markerSequence = {},
+    const FileSaveOptions& options = FileSaveOptions());
+
+} // namespace momentum

include/momentum/io/gltf/utils/accessor_utils.h

@@ -0,0 +1,299 @@
+/*
+ * 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/common/exception.h"
+
+#include <fx/gltf.h>
+#include <gsl/span_ext>
+
+namespace momentum {
+
+static inline int32_t getComponentSize(const fx::gltf::Accessor::ComponentType& componentType) {
+  switch (componentType) {
+    case fx::gltf::Accessor::ComponentType::Byte:
+    case fx::gltf::Accessor::ComponentType::UnsignedByte:
+      return 1;
+    case fx::gltf::Accessor::ComponentType::Short:
+    case fx::gltf::Accessor::ComponentType::UnsignedShort:
+      return 2;
+    // case fx::gltf::Accessor::ComponentType::Int:
+    case fx::gltf::Accessor::ComponentType::UnsignedInt:
+    case fx::gltf::Accessor::ComponentType::Float:
+      return 4;
+    default:
+      return -1;
+  }
+}
+
+static inline int32_t getTypeSize(const fx::gltf::Accessor::Type& ty) {
+  switch (ty) {
+    case fx::gltf::Accessor::Type::Scalar:
+      return 1;
+    case fx::gltf::Accessor::Type::Vec2:
+      return 2;
+    case fx::gltf::Accessor::Type::Vec3:
+      return 3;
+    case fx::gltf::Accessor::Type::Vec4:
+    case fx::gltf::Accessor::Type::Mat2:
+      return 4;
+    case fx::gltf::Accessor::Type::Mat3:
+      return 9;
+    case fx::gltf::Accessor::Type::Mat4:
+      return 16;
+    default:
+      return -1;
+  }
+}
+
+template <typename T>
+std::vector<T> copyAccessorBuffer(const fx::gltf::Document& model, int32_t id) {
+  const auto& accessor = model.accessors[id];
+
+  const auto tsize = getTypeSize(accessor.type);
+  const auto csize = getComponentSize(accessor.componentType);
+  const auto elsize = tsize * csize;
+
+  if (elsize != sizeof(T)) {
+    MT_LOGW(
+        "[{}] Accessor type mismatch. Expect to read {} bytes, but got type of {} bytes with {} components",
+        __func__,
+        sizeof(T),
+        csize,
+        tsize);
+    return {};
+  }
+
+  const auto& view = model.bufferViews[accessor.bufferView];
+  const auto stride = view.byteStride == 0 ? elsize : view.byteStride;
+
+  const auto& buf = model.buffers[view.buffer];
+  auto bytes = std::as_bytes(std::span<const uint8_t>(buf.data));
+  bytes = bytes.subspan(view.byteOffset, view.byteLength);
+  bytes = bytes.subspan(accessor.byteOffset);
+
+  std::vector<T> r(accessor.count);
+  for (size_t i = 0; i < accessor.count; i++) {
+    std::memcpy(&r[i], &bytes[i * stride], elsize);
+  }
+
+  return r;
+}
+
+template <typename T>
+std::vector<T> copyAlignedAccessorBuffer(const fx::gltf::Document& model, int32_t id) {
+  const auto& accessor = model.accessors[id];
+  if (accessor.count == 0) {
+    MT_LOGW("Accessor count zero.");
+    return {};
+  }
+
+  const auto tsize = getTypeSize(accessor.type);
+  const auto csize = getComponentSize(accessor.componentType);
+  const auto elsize = tsize * csize;
+
+  if (elsize != sizeof(T)) {
+    MT_LOGW(
+        "[{}] Accessor type mismatch. Expect to read {} bytes, but got type of {} bytes with {} components",
+        __func__,
+        sizeof(T),
+        csize,
+        tsize);
+    return {};
+  }
+
+  const auto& view = model.bufferViews[accessor.bufferView];
+  const auto stride = view.byteStride == 0 ? elsize : view.byteStride;
+
+  const auto& buf = model.buffers[view.buffer];
+  auto bytes = std::as_bytes(std::span<const uint8_t>(buf.data));
+  bytes = bytes.subspan(view.byteOffset, view.byteLength);
+  bytes = bytes.subspan(accessor.byteOffset);
+
+  std::vector<T> r(accessor.count);
+  for (size_t i = 0; i < accessor.count; i++) {
+    std::memcpy(&r[i], &bytes[i * stride], elsize);
+  }
+
+  return r;
+}
+
+// template to set accessor
+template <typename T>
+void setAccessorType(fx::gltf::Accessor& /* accessor */) {
+  MT_THROW("Unsupported data type {}", typeid(T).name());
+}
+
+// create accessor buffer
+template <typename T>
+int32_t createAccessorBuffer(
+    fx::gltf::Document& model,
+    std::span<T> data,
+    const bool align = false,
+    const bool normalized = false) {
+  // gltf 2.0 allows multiple buffers, but only the first buffer will be stored in
+  // the binary file, all other ones need to be external files. Because of this we will
+  // only ever store data in the first buffer
+
+  // check if we have a buffer
+  if (model.buffers.empty()) {
+    model.buffers.resize(1);
+  }
+
+  // create buffer for data
+  const size_t bufferIdx = 0;
+  auto& buffer = model.buffers.front();
+
+  // copy data from input buffer to output buffer
+  const size_t bufferDataStart = buffer.data.size();
+  const auto elementSize = sizeof(T);
+  auto alignedElementSize = elementSize;
+  auto dataSize = data.size() * alignedElementSize;
+
+  // check for necessary alignment
+  if (align && alignedElementSize % 4 != 0) {
+    // element is not aligned, need to get bigger element size
+    alignedElementSize = ((elementSize / 4) + 1) * 4;
+    dataSize = data.size() * alignedElementSize;
+    buffer.data.resize(bufferDataStart + dataSize);
+    // need to go over each element one by one to copy
+    for (size_t e = 0; e < data.size(); e++) {
+      std::memcpy(&buffer.data[bufferDataStart + alignedElementSize * e], &data[e], elementSize);
+    }
+    buffer.byteLength = buffer.data.size();
+  } else {
+    // no alignment needed or already aligned, just copy data in
+    buffer.data.resize(bufferDataStart + dataSize);
+    std::memcpy(&buffer.data[bufferDataStart], data.data(), dataSize);
+    buffer.byteLength = buffer.data.size();
+  }
+
+  // create bufferview
+  const size_t bufferViewIdx = model.bufferViews.size();
+  model.bufferViews.emplace_back();
+  auto& bufferView = model.bufferViews.back();
+
+  bufferView.buffer = bufferIdx;
+  bufferView.byteLength = dataSize;
+  bufferView.byteOffset = bufferDataStart;
+  if (align && elementSize % 4 != 0) {
+    bufferView.byteStride = alignedElementSize;
+  } else {
+    bufferView.byteStride = 0;
+  }
+
+  // create accessor
+  const size_t accessorIdx = model.accessors.size();
+  model.accessors.emplace_back();
+  auto& accessor = model.accessors.back();
+
+  // set component type and accessor size depending on the type
+  setAccessorType<T>(accessor);
+  accessor.bufferView = bufferViewIdx;
+  accessor.byteOffset = 0;
+  accessor.count = data.size();
+  accessor.normalized = normalized;
+
+  return accessorIdx;
+}
+
+template <>
+inline void setAccessorType<const int32_t>(fx::gltf::Accessor& accessor) {
+  accessor.componentType = fx::gltf::Accessor::ComponentType::UnsignedInt;
+  accessor.type = fx::gltf::Accessor::Type::Scalar;
+}
+
+template <>
+inline void setAccessorType<const float>(fx::gltf::Accessor& accessor) {
+  accessor.componentType = fx::gltf::Accessor::ComponentType::Float;
+  accessor.type = fx::gltf::Accessor::Type::Scalar;
+}
+
+template <>
+inline void setAccessorType<const Vector2f>(fx::gltf::Accessor& accessor) {
+  accessor.componentType = fx::gltf::Accessor::ComponentType::Float;
+  accessor.type = fx::gltf::Accessor::Type::Vec2;
+}
+
+template <>
+inline void setAccessorType<const Vector3f>(fx::gltf::Accessor& accessor) {
+  accessor.componentType = fx::gltf::Accessor::ComponentType::Float;
+  accessor.type = fx::gltf::Accessor::Type::Vec3;
+}
+
+template <>
+inline void setAccessorType<const Vector4f>(fx::gltf::Accessor& accessor) {
+  accessor.componentType = fx::gltf::Accessor::ComponentType::Float;
+  accessor.type = fx::gltf::Accessor::Type::Vec4;
+}
+
+template <>
+inline void setAccessorType<const Vector3b>(fx::gltf::Accessor& accessor) {
+  accessor.componentType = fx::gltf::Accessor::ComponentType::UnsignedByte;
+  accessor.type = fx::gltf::Accessor::Type::Vec3;
+}
+
+template <>
+inline void setAccessorType<const Vector3i>(fx::gltf::Accessor& accessor) {
+  accessor.componentType = fx::gltf::Accessor::ComponentType::UnsignedInt;
+  accessor.type = fx::gltf::Accessor::Type::Vec3;
+}
+
+template <>
+inline void setAccessorType<const Vector4s>(fx::gltf::Accessor& accessor) {
+  accessor.componentType = fx::gltf::Accessor::ComponentType::UnsignedShort;
+  accessor.type = fx::gltf::Accessor::Type::Vec4;
+}
+
+template <>
+inline void setAccessorType<const Matrix4f>(fx::gltf::Accessor& accessor) {
+  accessor.componentType = fx::gltf::Accessor::ComponentType::Float;
+  accessor.type = fx::gltf::Accessor::Type::Mat4;
+}
+
+// add animation
+template <typename T>
+int32_t createSampler(
+    fx::gltf::Document& model,
+    fx::gltf::Animation& anim,
+    std::span<T> data,
+    const std::span<float>& timestamps) {
+  MT_CHECK(
+      data.size() == timestamps.size(), "data: {}, timestmaps: {}", data.size(), timestamps.size());
+
+  // create new sampler
+  const int32_t index = anim.samplers.size();
+  anim.samplers.emplace_back();
+  auto& sampler = anim.samplers.back();
+  sampler.interpolation = fx::gltf::Animation::Sampler::Type::Step;
+  sampler.input = createAccessorBuffer(model, timestamps);
+  sampler.output = createAccessorBuffer(model, data);
+
+  // return sampler index
+  return index;
+}
+
+template <typename T>
+int32_t createSampler(
+    fx::gltf::Document& model,
+    fx::gltf::Animation& anim,
+    std::span<T> data,
+    const int32_t timestampAccessor) {
+  // create new sampler
+  const int32_t index = anim.samplers.size();
+  anim.samplers.emplace_back();
+  auto& sampler = anim.samplers.back();
+  sampler.interpolation = fx::gltf::Animation::Sampler::Type::Step;
+  sampler.input = timestampAccessor;
+  sampler.output = createAccessorBuffer(model, data);
+
+  // return sampler index
+  return index;
+}
+
+} // namespace momentum

include/momentum/io/gltf/utils/coordinate_utils.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/constants.h>
+#include <momentum/math/types.h>
+
+namespace momentum {
+
+// Utility functions to convert gltf coordinate system to momentum coordinate system.
+// #TODO: load coordinates by setting up CoordinateSystems so we don't need to worry about
+// conversion.
+[[nodiscard]] inline Vector3f toMomentumVec3f(const std::array<float, 3>& vec) noexcept {
+  return Vector3f(vec[0], vec[1], vec[2]) * toCm();
+}
+
+[[nodiscard]] inline Vector3f fromMomentumVec3f(const Vector3f& vec) noexcept {
+  return vec * toM();
+}
+
+[[nodiscard]] inline Quaternionf toMomentumQuaternionf(
+    const std::array<float, 4>& gltfQuat) noexcept {
+  return {gltfQuat[3], gltfQuat[0], gltfQuat[1], gltfQuat[2]};
+}
+
+[[nodiscard]] inline std::array<float, 4> fromMomentumQuaternionf(
+    const Quaternionf& quat) noexcept {
+  return {quat.x(), quat.y(), quat.z(), quat.w()};
+}
+
+inline void toMomentumVec3f(std::vector<Vector3f>& vec) {
+  if (vec.empty()) {
+    return;
+  }
+
+  Map<VectorXf>(&vec[0][0], vec.size() * 3) *= toCm();
+}
+
+inline void fromMomentumVec3f(std::vector<Vector3f>& vec) {
+  if (vec.empty()) {
+    return;
+  }
+
+  Map<VectorXf>(&vec[0][0], vec.size() * 3) *= toM();
+}
+
+inline void fromMomentumVec3f(VectorXf& vec) {
+  if (vec.size() == 0) {
+    return;
+  }
+
+  vec *= toM();
+}
+
+} // namespace momentum