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

include/momentum/character/character_state.h

@@ -0,0 +1,108 @@
+/*
+ * 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/character.h>
+#include <momentum/character/locator_state.h>
+#include <momentum/character/skeleton_state.h>
+#include <momentum/math/fwd.h>
+
+namespace momentum {
+
+/// Represents the complete state of a character at a specific point in time.
+///
+/// Stores the character's parameters, skeleton state, locator positions,
+/// skinned mesh, and collision geometry state. This class is used for
+/// character animation and rendering.
+template <typename T>
+struct CharacterStateT {
+  /// Model parameters and joint offsets
+  CharacterParameters parameters;
+
+  /// Joint transformations
+  SkeletonState skeletonState;
+
+  /// Locator positions and orientations
+  LocatorState locatorState;
+
+  /// Skinned mesh (may be null if updateMesh=false)
+  Mesh_u meshState;
+
+  /// Collision geometry state (may be null if updateCollision=false)
+  CollisionGeometryState_u collisionState;
+
+  /// Creates an empty character state
+  CharacterStateT();
+
+  /// Creates a deep copy of another character state
+  explicit CharacterStateT(const CharacterStateT& other);
+
+  /// Move constructor
+  CharacterStateT(CharacterStateT&& c) noexcept;
+
+  /// Copy assignment is disabled
+  CharacterStateT& operator=(const CharacterStateT& rhs) = delete;
+
+  /// Move assignment operator
+  CharacterStateT& operator=(CharacterStateT&& rhs) noexcept;
+
+  /// Destructor
+  ~CharacterStateT();
+
+  /// Creates a character state in bind pose
+  ///
+  /// @param referenceCharacter The character to use as reference
+  /// @param updateMesh Whether to compute the skinned mesh
+  /// @param updateCollision Whether to update collision geometry
+  explicit CharacterStateT(
+      const CharacterT<T>& referenceCharacter,
+      bool updateMesh = true,
+      bool updateCollision = true);
+
+  /// Creates a character state with specific parameters
+  ///
+  /// @param parameters The character parameters to use
+  /// @param referenceCharacter The character to use as reference
+  /// @param updateMesh Whether to compute the skinned mesh
+  /// @param updateCollision Whether to update collision geometry
+  /// @param applyLimits Whether to apply joint parameter limits
+  CharacterStateT(
+      const CharacterParameters& parameters,
+      const CharacterT<T>& referenceCharacter,
+      bool updateMesh = true,
+      bool updateCollision = true,
+      bool applyLimits = true);
+
+  /// Updates the character state with specific parameters
+  ///
+  /// If parameters.offsets is empty, it will be initialized with zeros.
+  ///
+  /// @param parameters The character parameters to use
+  /// @param referenceCharacter The character to use as reference
+  /// @param updateMesh Whether to compute the skinned mesh
+  /// @param updateCollision Whether to update collision geometry
+  /// @param applyLimits Whether to apply joint parameter limits
+  void set(
+      const CharacterParameters& parameters,
+      const CharacterT<T>& referenceCharacter,
+      bool updateMesh = true,
+      bool updateCollision = true,
+      bool applyLimits = true);
+
+  /// Sets the character state to the bind pose
+  ///
+  /// @param referenceCharacter The character to use as reference
+  /// @param updateMesh Whether to compute the skinned mesh
+  /// @param updateCollision Whether to update collision geometry
+  void setBindPose(
+      const CharacterT<T>& referenceCharacter,
+      bool updateMesh = true,
+      bool updateCollision = true);
+};
+
+} // namespace momentum

include/momentum/character/character_utility.h

@@ -0,0 +1,128 @@
+/*
+ * 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/character.h>
+
+namespace momentum {
+
+/// Scales the character (mesh and skeleton) by the desired amount.
+///
+/// Note that this should primarily be used when transforming the character into different units. If
+/// you simply want to apply an identity-specific scale to the character, you should use the
+/// 'scale_global' parameter in the ParameterTransform class.
+///
+/// @param[in] character Character to be scaled
+/// @param[in] scale Scale factor to apply
+/// @return A new Character object that has been scaled
+[[nodiscard]] Character scaleCharacter(const Character& character, float scale);
+
+/// Transforms the character (mesh and skeleton) by the desired transformation matrix.  The
+/// transformation matrix should not have any scale or shear.
+///
+/// Note that this should primarily be used for transforming models between different coordinate
+/// spaces (e.g. y-up vs. z-up). If you want to move a character around the scene, you should
+/// preferably use the model parameters.
+///
+/// @param[in] character Character to be transformed
+/// @param[in] xform Transformation to apply
+/// @return A new Character object that has been transformed
+[[nodiscard]] Character transformCharacter(const Character& character, const Affine3f& xform);
+
+/// Replaces the part of target_character's skeleton rooted at target_root with the part of
+/// source_character's skeleton rooted at source_root.
+///
+/// This function is typically used to swap one character's hand skeleton with another, for example.
+///
+/// @param[in] srcCharacter The source character whose skeleton will be copied.
+/// @param[in] tgtCharacter The target character whose skeleton will be replaced.
+/// @param[in] srcRootJoint Root of the source skeleton hierarchy to be copied.
+/// @param[in] tgtRootJoint Root of the target skeleton hierarchy to be replaced.
+/// @return A new Character that is identical to tgtCharacter except that the skeleton under
+/// tgtRootJoint has been replaced by the part of srcCharacter's skeleton rooted at srcRootJoint.
+[[nodiscard]] Character replaceSkeletonHierarchy(
+    const Character& srcCharacter,
+    const Character& tgtCharacter,
+    const std::string& srcRootJoint,
+    const std::string& tgtRootJoint);
+
+/// Removes the specified joints and any joints parented beneath them from the character.
+///
+/// Currently, it is necessary to remove child joints to prevent dangling joints. Mesh points
+/// skinned to the removed joints are re-skinned to their parent joint in the hierarchy.
+///
+/// @param[in] character The character from which joints will be removed.
+/// @param[in] jointsToRemove A vector of joint indices to be removed.
+/// @return A new Character object that is identical to the original except for the removal of
+/// specified joints.
+[[nodiscard]] Character removeJoints(
+    const Character& character,
+    std::span<const size_t> jointsToRemove);
+
+/// Maps the input ModelParameter motion to a target character by matching model parameter names.
+/// Mismatched names will be discarded (source) or set to zero (target).
+///
+/// @param[in] inputMotion Input ModelParameter motion with names.
+/// @param[in] targetCharacter Target character that defines its own ModelParameters.
+/// @return A matrix of model parameters for the target character.
+MatrixXf mapMotionToCharacter(
+    const MotionParameters& inputMotion,
+    const Character& targetCharacter);
+
+/// Maps the input JointParameter vector to a target character by matching joint names. Mismatched
+/// names will be discarded (source) or set to zero (target). For every matched joint, all 7
+/// parameters will be copied over.
+///
+/// @param[in] inputIdentity Input JointParameter vector with joint names.
+/// @param[in] targetCharacter Target character that defines its own Joints.
+/// @return A vector of joint parameters for the target character.
+VectorXf mapIdentityToCharacter(
+    const IdentityParameters& inputIdentity,
+    const Character& targetCharacter);
+
+/// Reduces the mesh to only include the specified vertices and associated faces
+///
+/// @param[in] character Character to be reduced
+/// @param[in] activeVertices Boolean vector indicating which vertices to keep
+/// @return A new character with mesh reduced to the specified vertices
+template <typename T>
+[[nodiscard]] CharacterT<T> reduceMeshByVertices(
+    const CharacterT<T>& character,
+    const std::vector<bool>& activeVertices);
+
+/// Reduces the mesh to only include the specified faces and associated vertices
+///
+/// @param[in] character Character to be reduced
+/// @param[in] activeFaces Boolean vector indicating which faces to keep
+/// @return A new character with mesh reduced to the specified faces
+template <typename T>
+[[nodiscard]] CharacterT<T> reduceMeshByFaces(
+    const CharacterT<T>& character,
+    const std::vector<bool>& activeFaces);
+
+/// Converts vertex selection to face selection
+///
+/// @param[in] character Character containing the mesh
+/// @param[in] activeVertices Boolean vector indicating which vertices are active
+/// @return Boolean vector indicating which faces only contain active vertices
+template <typename T>
+[[nodiscard]] std::vector<bool> verticesToFaces(
+    const MeshT<T>& mesh,
+    const std::vector<bool>& activeVertices);
+
+/// Converts face selection to vertex selection
+///
+/// @param[in] character Character containing the mesh
+/// @param[in] activeFaces Boolean vector indicating which faces are active
+/// @return Boolean vector indicating which vertices are used by active faces
+template <typename T>
+[[nodiscard]] std::vector<bool> facesToVertices(
+    const MeshT<T>& mesh,
+    const std::vector<bool>& activeFaces);
+
+} // namespace momentum

include/momentum/character/collision_geometry.h

@@ -0,0 +1,80 @@
+/*
+ * 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/types.h>
+#include <momentum/common/memory.h>
+#include <momentum/math/constants.h>
+#include <momentum/math/transform.h>
+#include <momentum/math/utility.h>
+
+namespace momentum {
+
+/// Tapered capsule collision geometry for character collision detection.
+///
+/// Defined by a transformation, length, and two radii at the endpoints, creating
+/// a capsule with potentially different radii at each end.
+template <typename S>
+struct TaperedCapsuleT {
+  using Scalar = S;
+
+  /// Transformation defining the orientation and starting point relative to the parent coordinate
+  /// system.
+  TransformT<S> transformation;
+
+  /// Radii at the two endpoints of the capsule.
+  Vector2<S> radius;
+
+  /// Parent joint to which the geometry is attached.
+  size_t parent;
+
+  /// Length of the collision geometry along the x-axis.
+  S length;
+
+  TaperedCapsuleT()
+      : transformation(TransformT<S>()),
+        radius(Vector2<S>::Zero()),
+        parent(kInvalidIndex),
+        length(S(0)) {
+    // Empty
+  }
+
+  /// Checks if the current capsule is approximately equal to another.
+  [[nodiscard]] bool isApprox(const TaperedCapsuleT& other, const S& tol = Eps<S>(1e-4f, 1e-10))
+      const {
+    if (!transformation.isApprox(other.transformation, tol)) {
+      return false;
+    }
+
+    if (!radius.isApprox(other.radius)) {
+      return false;
+    }
+
+    if (parent != other.parent) {
+      return false;
+    }
+
+    if (!::momentum::isApprox(length, other.length)) {
+      return false;
+    }
+
+    return true;
+  }
+};
+
+/// Collection of tapered capsules representing a character's collision geometry.
+template <typename S>
+using CollisionGeometryT = std::vector<TaperedCapsuleT<S>>;
+
+using CollisionGeometry = CollisionGeometryT<float>;
+using CollisionGeometryd = CollisionGeometryT<double>;
+
+MOMENTUM_DEFINE_POINTERS(CollisionGeometry)
+MOMENTUM_DEFINE_POINTERS(CollisionGeometryd)
+
+} // namespace momentum

include/momentum/character/collision_geometry_state.h

@@ -0,0 +1,130 @@
+/*
+ * 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/collision_geometry.h>
+#include <momentum/character/fwd.h>
+
+#include <axel/BoundingBox.h>
+
+namespace momentum {
+
+/// Represents collision geometry states using a Structure of Arrays (SoA) format.
+template <typename T>
+struct CollisionGeometryStateT {
+  // ASCII Art to visualize the capsule:
+  //
+  //           ^
+  //           :
+  //           :________________________________________
+  //          /:                                        :\
+  //        /  :                                        : \
+  //       |   :(origin)                                :  |
+  //       |   O-------------(direction)--------------->:--|------------------> X-axis
+  //       |   :                                        :  |
+  //        \  : (radius[0])                            : /  (radius[1])
+  //          \:________________________________________:/
+  //
+  //
+  // Note: radius[0] and radius[1] can be different.
+
+  /// Capsule's origin in global coordinates.
+  std::vector<Vector3<T>> origin;
+
+  /// Capsule's direction vector (representing the X-axis) in global coordinates.
+  std::vector<Vector3<T>> direction;
+
+  /// Scaled radii of the capsule's endpoints.
+  std::vector<Vector2<T>> radius;
+
+  /// Signed difference between the capsule's radii (radius[1] - radius[0]).
+  std::vector<T> delta;
+
+  /// Updates the state based on a given skeleton state and collision geometry.
+  void update(const SkeletonStateT<T>& skeletonState, const CollisionGeometry& collisionGeometry);
+};
+
+/// Determines if two tapered capsules overlap.
+///
+/// @param originA Origin of the first capsule
+/// @param directionA Direction vector of the first capsule
+/// @param radiiA Radii at the endpoints of the first capsule
+/// @param deltaA Difference between radii of the first capsule
+/// @param originB Origin of the second capsule
+/// @param directionB Direction vector of the second capsule
+/// @param radiiB Radii at the endpoints of the second capsule
+/// @param deltaB Difference between radii of the second capsule
+/// @param outDistance Output parameter for the distance between the closest points
+/// (normalized). No modification on return false.
+/// @param outOverlap Output parameter for the overlap amount (positive if overlapping)
+/// @return True if the capsules overlap, false otherwise
+template <typename T>
+bool overlaps(
+    const Vector3<T>& originA,
+    const Vector3<T>& directionA,
+    const Vector2<T>& radiiA,
+    T deltaA,
+    const Vector3<T>& originB,
+    const Vector3<T>& directionB,
+    const Vector2<T>& radiiB,
+    T deltaB,
+    T& outDistance,
+    Vector2<T>& outClosestPoints,
+    T& outOverlap) {
+  // Sum of the maximum radii of the tapered capsules
+  const T maxRadiiSum = radiiA.maxCoeff() + radiiB.maxCoeff();
+
+  // Determine the closest points on the segments of the tapered capsules
+  auto [success, closestDist, closestPoints] =
+      closestPointsOnSegments<T>(originA, directionA, originB, directionB, maxRadiiSum);
+
+  if (!success) {
+    return false;
+  }
+
+  // Store the closest points to the output argument
+  outClosestPoints = closestPoints;
+
+  // Calculate the radii at the closest points
+  const T radiusAtClosestPoints =
+      radiiA[0] + closestPoints[0] * deltaA + radiiB[0] + closestPoints[1] * deltaB;
+
+  // Determine the overlap and distance between the closest points
+  outOverlap = radiusAtClosestPoints - closestDist;
+  outDistance = closestDist;
+
+  // Check for overlap and sufficient proximity
+  return (outOverlap > T(0)) && (closestDist >= Eps<T>(1e-8, 1e-17));
+}
+
+/// Updates an axis-aligned bounding box to encompass a tapered capsule.
+///
+/// @param aabb The bounding box to update
+/// @param originA Origin of the capsule
+/// @param direction Direction vector of the capsule
+/// @param radii Radii at the endpoints of the capsule
+template <typename T>
+void updateAabb(
+    axel::BoundingBox<T>& aabb,
+    const Vector3<T>& originA,
+    const Vector3<T>& direction,
+    const Vector2<T>& radii) {
+  const Vector3<T> radius0 = Vector3<T>::Constant(radii[0]);
+  const Vector3<T> radius1 = Vector3<T>::Constant(radii[1]);
+  const Vector3<T> originB = originA + direction;
+
+  const Vector3<T> minA = originA - radius0;
+  const Vector3<T> maxA = originA + radius0;
+  const Vector3<T> minB = originB - radius1;
+  const Vector3<T> maxB = originB + radius1;
+
+  aabb.aabb.min() = minA.cwiseMin(minB);
+  aabb.aabb.max() = maxA.cwiseMax(maxB);
+}
+
+} // namespace momentum