pymomentum-cpu 0.1.84.post0__cp313-cp313-macosx_14_0_arm64.whl

include/momentum/character/mesh_state.h

@@ -0,0 +1,71 @@
+/*
+ * 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/types.h>
+#include <momentum/math/mesh.h>
+#include <momentum/math/types.h>
+
+namespace momentum {
+
+/// Represents the complete state of a model's mesh
+///
+/// Stores the mesh in its various states throughout the deformation pipeline:
+/// - neutralMesh: Base mesh before any deformations
+/// - restMesh: Mesh after blend shapes/expressions are applied
+/// - posedMesh: Final mesh after skinning is applied
+template <typename T>
+struct MeshStateT {
+  std::unique_ptr<MeshT<T>>
+      neutralMesh_; // Rest mesh without facial expression basis,
+                    // used to restore the neutral shape after facial expressions are applied.
+                    // Not used with there is a shape basis.
+  std::unique_ptr<MeshT<T>> restMesh_; // The rest positions of the mesh after shape basis
+                                       // (and potentially facial expression) has been applied
+  std::unique_ptr<MeshT<T>>
+      posedMesh_; // The posed mesh after the skeleton transforms have been applied.
+
+  /// Creates an empty mesh state
+  MeshStateT() noexcept = default;
+  MeshStateT(
+      const ModelParametersT<T>& parameters,
+      const SkeletonStateT<T>& state,
+      const Character& character) noexcept;
+  ~MeshStateT() noexcept;
+
+  /// Copy constructor
+  MeshStateT(const MeshStateT& other);
+
+  /// Copy assignment operator
+  MeshStateT& operator=(const MeshStateT& other);
+
+  /// Move constructor
+  MeshStateT(MeshStateT&& other) noexcept = default;
+
+  /// Move assignment operator
+  MeshStateT& operator=(MeshStateT&& other) noexcept = default;
+
+  /// Updates the mesh state based on model parameters and skeleton state
+  ///
+  /// This applies the full deformation pipeline:
+  /// 1. Apply blend shapes to create rest mesh
+  /// 2. Apply face expression blend shapes
+  /// 3. Update normals
+  /// 4. Apply skinning to create posed mesh
+  ///
+  /// @param parameters Model parameters containing blend weights
+  /// @param state Current skeleton state for skinning
+  /// @param character Character containing mesh, blend shapes, and skinning data
+  void update(
+      const ModelParametersT<T>& parameters,
+      const SkeletonStateT<T>& state,
+      const Character& character);
+};
+
+} // namespace momentum

include/momentum/character/parameter_limits.h

@@ -0,0 +1,144 @@
+/*
+ * 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/types.h>
+#include <momentum/common/memory.h>
+#include <momentum/math/utility.h>
+
+#include <array>
+#include <cstring>
+
+namespace momentum {
+
+enum LimitType {
+  MinMax,
+  MinMaxJoint,
+  MinMaxJointPassive,
+  Linear,
+  LinearJoint,
+  Ellipsoid,
+  HalfPlane,
+
+  // Keep this as the last entry to track the number of enum values
+  LimitTypeCount
+};
+
+[[nodiscard]] std::string_view toString(LimitType type);
+
+struct LimitMinMax {
+  size_t parameterIndex;
+  Vector2f limits; ///< [min, max]
+};
+
+struct LimitMinMaxJoint {
+  size_t jointIndex;
+  size_t jointParameter; ///< One of [tx, ty, tz, rx, ry, rz, sc]
+  Vector2f limits; ///< [min, max]
+};
+
+/// Linear relationship between parameters: p_0 = s * p_1 - o
+struct LimitLinear {
+  size_t referenceIndex; ///< p_0
+  size_t targetIndex; ///< p_1
+  float scale; ///< s
+  float offset; ///< o
+
+  /// Range where limit applies (in target parameter values)
+  ///
+  /// For piecewise linear limits without double-counting
+  float rangeMin; ///< Inclusive
+  float rangeMax; ///< Non-inclusive
+};
+
+struct LimitLinearJoint {
+  size_t referenceJointIndex;
+  size_t referenceJointParameter;
+  size_t targetJointIndex;
+  size_t targetJointParameter;
+  float scale;
+  float offset;
+
+  /// Range where limit applies (in target parameter values)
+  ///
+  /// For piecewise linear limits without double-counting
+  float rangeMin; ///< Inclusive
+  float rangeMax; ///< Non-inclusive
+};
+
+struct LimitEllipsoid {
+  alignas(32) Affine3f ellipsoid;
+  alignas(32) Affine3f ellipsoidInv;
+  alignas(32) Vector3f offset;
+  size_t ellipsoidParent;
+  size_t parent;
+};
+
+/// Constraint: (p1, p2) · (normal) - offset >= 0
+struct LimitHalfPlane {
+  size_t param1;
+  size_t param2;
+  Vector2f normal;
+  float offset;
+};
+
+union LimitData {
+  LimitMinMax minMax;
+  LimitMinMaxJoint minMaxJoint;
+  LimitLinear linear;
+  LimitLinearJoint linearJoint;
+  LimitEllipsoid ellipsoid;
+  LimitHalfPlane halfPlane;
+  std::array<unsigned char, 512> rawData; ///< For memory operations
+
+  /// Initializes all data to zero
+  LimitData();
+
+  /// Raw memory copy (compiler can't determine which member's constructor to call)
+  LimitData(const LimitData& rhs);
+
+  LimitData& operator=(const LimitData& rhs);
+
+  /// Compares raw memory
+  bool operator==(const LimitData& limitData) const;
+};
+
+struct ParameterLimit {
+  LimitData data;
+  LimitType type = LimitType::MinMax;
+  float weight = 1.0f;
+
+  inline bool operator==(const ParameterLimit& parameterLimit) const {
+    return (
+        (data == parameterLimit.data) && (type == parameterLimit.type) &&
+        isApprox(weight, parameterLimit.weight));
+  }
+};
+
+using ParameterLimits = std::vector<ParameterLimit>;
+
+/// Only processes MinMaxJointPassive limits, clamping parameters to their ranges
+JointParameters applyPassiveJointParameterLimits(
+    const ParameterLimits& limits,
+    const JointParameters& jointParams);
+
+/// Creates MinMax limits from a pose constraint
+ParameterLimits getPoseConstraintParameterLimits(
+    const std::string& name,
+    const ParameterTransform& pt,
+    float weight = 1.0f);
+
+/// If rangeMin and rangeMax are both 0, the limit applies to all values
+bool isInRange(const LimitLinear& limit, float value);
+
+/// If rangeMin and rangeMax are both 0, the limit applies to all values
+bool isInRange(const LimitLinearJoint& limit, float value);
+
+MOMENTUM_DEFINE_POINTERS(ParameterLimits)
+} // namespace momentum

include/momentum/character/parameter_transform.h

@@ -0,0 +1,250 @@
+/*
+ * 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/parameter_limits.h>
+#include <momentum/character/types.h>
+#include <momentum/math/utility.h>
+
+#include <span>
+
+#include <string>
+#include <unordered_map>
+
+namespace momentum {
+
+struct PoseConstraint {
+  /// A vector of tuple of type: (model parameter index, parameter value).
+  /// The model parameter index must be in [0, numModelParameters.size()).
+  /// The value of the model parameters specified here are kept constant (= parameter value) during
+  /// optimization. The ordering of elements in the vector doesn't matter (making it an unordered
+  /// map would be more semantically correct) since it stores an index to the model parameters
+  std::vector<std::pair<size_t, float>> parameterIdValue;
+
+  inline bool operator==(const PoseConstraint& poseConstraint) const {
+    // Compare the parameterIdValue as sets
+    std::map<size_t, float> paramIdToValue1;
+    std::copy(
+        parameterIdValue.begin(),
+        parameterIdValue.end(),
+        std::inserter(paramIdToValue1, paramIdToValue1.begin()));
+
+    std::map<size_t, float> paramIdToValue2;
+    std::copy(
+        poseConstraint.parameterIdValue.begin(),
+        poseConstraint.parameterIdValue.end(),
+        std::inserter(paramIdToValue2, paramIdToValue2.begin()));
+
+    if (paramIdToValue1.size() != paramIdToValue2.size()) {
+      return false;
+    }
+
+    auto pred = [](const auto& l, const auto& r) {
+      return ((l.first == r.first) && isApprox(l.second, r.second));
+    };
+    return std::equal(
+        paramIdToValue1.begin(), paramIdToValue1.end(), paramIdToValue2.begin(), pred);
+  }
+};
+
+using ParameterSets = std::unordered_map<std::string, ParameterSet>;
+using PoseConstraints = std::unordered_map<std::string, PoseConstraint>;
+
+/// A parameter transform is an abstraction of the joint parameters that maps a model_parameter
+/// vector to a joint_parameter vector. It allows mapping a single model_parameter to multiple
+/// joints, and a single joint being influenced by multiple model_parameters joint parameters are
+/// calculated from parameters in the following way : <joint_parameters> = <transform> *
+/// <model_parameters> + <offsets>
+template <typename T>
+struct ParameterTransformT {
+  /// The list of model parameter names.
+  std::vector<std::string> name;
+
+  /// The sparse mapping matrix that maps model parameters to joint parameters.
+  SparseRowMatrix<T> transform;
+
+  /// @deprecated Constant offset factor for each joint.
+  Eigen::VectorX<T> offsets;
+
+  /// The list of joint *parameters* that are actually active and influenced from the transform.
+  VectorX<bool> activeJointParams;
+
+  /// Convenience grouping of model parameters.
+  ParameterSets parameterSets;
+
+  /// A set of predefined poses.
+  PoseConstraints poseConstraints;
+
+  /// The indices of the parameters that influence blend shapes; blendShapeParameters(0) is the
+  /// parameter that controls the 0th blend shape, etc.
+  VectorXi blendShapeParameters;
+
+  /// The indices of the parameters that influence face expressions; faceExpressionParameters(0) is
+  /// the parameter that controls the 0th face expression parameter, etc.
+  VectorXi faceExpressionParameters;
+
+  /// Parameters that control the rest-space positions of the skinned locators.
+  /// This array will be either empty or have the same size as the number of
+  /// skinned locators.  Each entry maps from a skinned locator index to the
+  /// first of the three (x,y,z) parameters that control its position.  Skinned
+  /// locators that aren't controlled by the paramete transform will have
+  /// skinnedLocatorParameters[i] = -1.
+  VectorXi skinnedLocatorParameters;
+
+  /// Return a ParameterTransform object with no model parameters. The model can still perform FK
+  /// with JointParameters, but it does not have any degrees of freedom for IK.
+  [[nodiscard]] static ParameterTransformT<T> empty(size_t nJointParameters);
+
+  /// Return a ParameterTransform object where the model parameters are identical to the joint
+  /// parameters.
+  [[nodiscard]] static ParameterTransformT<T> identity(std::span<const std::string> jointNames);
+
+  /// Compute activeJointParams based on the transform and the input ParameterSet.
+  [[nodiscard]] VectorX<bool> computeActiveJointParams(const ParameterSet& ps = allParams()) const;
+
+  /// Return the index of a model parameter from its name.
+  [[nodiscard]] size_t getParameterIdByName(const std::string& nm) const;
+
+  /// Map model parameters to joint parameters using a linear transformation.
+  [[nodiscard]] JointParametersT<T> apply(const ModelParametersT<T>& parameters) const;
+
+  /// Map model parameters to joint parameters using a linear transformation.
+  [[nodiscard]] JointParametersT<T> apply(const CharacterParametersT<T>& parameters) const;
+
+  /// Return rest pose joint parameters.
+  [[nodiscard]] JointParametersT<T> zero() const;
+
+  /// Return bind pose joint parameters (same as the rest pose here).
+  [[nodiscard]] JointParametersT<T> bindPose() const;
+
+  /// Get a list of scaling parameters (with prefix "scale_").
+  [[nodiscard]] ParameterSet getScalingParameters() const;
+
+  /// Get a list of root parameters (with prefix "root_")
+  [[nodiscard]] ParameterSet getRigidParameters() const;
+
+  /// Return all parameters used for posing the body (excludes scaling parameters, blend shape
+  /// parameters, or any parameters used for physics).
+  [[nodiscard]] ParameterSet getPoseParameters() const;
+
+  /// Get a list of blend shape parameters.
+  [[nodiscard]] ParameterSet getBlendShapeParameters() const;
+
+  /// Get a list of face expression parameters.
+  [[nodiscard]] ParameterSet getFaceExpressionParameters() const;
+
+  /// Get a list of skinned locator parameters
+  [[nodiscard]] ParameterSet getSkinnedLocatorParameters() const;
+
+  /// Get a parameter set, if allowMissing is set then it will return an empty parameter set if no
+  /// such parameterset is found in the file.
+  [[nodiscard]] ParameterSet getParameterSet(
+      const std::string& parameterSetName,
+      bool allowMissing = false) const;
+
+  template <typename T2>
+  [[nodiscard]] ParameterTransformT<T2> cast() const;
+
+  /// Create a simplified transform given the enabled parameters.
+  [[nodiscard]] ParameterTransformT<T> simplify(const ParameterSet& enabledParameters) const;
+
+  /// Dimension of all model parameters, including pose, scaling, marker joints, and blendshape
+  /// parameters for id and expressions.
+  [[nodiscard]] Eigen::Index numAllModelParameters() const {
+    return transform.cols();
+  }
+
+  /// Dimension of the output jointParameters vector.
+  [[nodiscard]] Eigen::Index numJointParameters() const {
+    return transform.rows();
+  }
+
+  /// Dimension of identity blendshape parameters.
+  [[nodiscard]] Eigen::Index numBlendShapeParameters() const;
+
+  /// Dimension of facial expression parameters.
+  [[nodiscard]] Eigen::Index numFaceExpressionParameters() const;
+
+  /// Dimension of facial expression parameters.
+  [[nodiscard]] Eigen::Index numSkinnedLocatorParameters() const;
+
+  /// Dimension of skeletal model parameters, including pose parameters,
+  /// scaling parameters, locator joint parameters etc. basically everything
+  /// but blendshapes (ids and expressions).
+  [[nodiscard]] Eigen::Index numSkeletonParameters() const {
+    return numAllModelParameters() - numBlendShapeParameters() - numFaceExpressionParameters() -
+        numSkinnedLocatorParameters();
+  }
+
+  [[nodiscard]] inline bool isApprox(const ParameterTransformT<T>& parameterTransform) const {
+    // special handling of zero sparse matrix
+    bool isTransformEqual = false;
+    if (transform.cols() > 0 && transform.rows() > 0 && parameterTransform.transform.cols() > 0 &&
+        parameterTransform.transform.rows() > 0) {
+      isTransformEqual = transform.isApprox(parameterTransform.transform);
+    } else {
+      isTransformEqual = (transform.cols() == parameterTransform.transform.cols()) &&
+          (transform.rows() == parameterTransform.transform.rows());
+    }
+    if (!isTransformEqual) {
+      return false;
+    }
+
+    return (
+        (name == parameterTransform.name) &&
+        activeJointParams.isApprox(parameterTransform.activeJointParams) &&
+        (parameterSets == parameterTransform.parameterSets) &&
+        (poseConstraints == parameterTransform.poseConstraints) &&
+        (blendShapeParameters == parameterTransform.blendShapeParameters));
+  }
+};
+
+using ParameterTransform = ParameterTransformT<float>;
+using ParameterTransformd = ParameterTransformT<double>;
+
+/// Return a parameter mapping that only includes the listed parameters.
+template <typename T>
+[[nodiscard]] std::tuple<ParameterTransformT<T>, ParameterLimits> subsetParameterTransform(
+    const ParameterTransformT<T>& paramTransform,
+    const ParameterLimits& paramLimitsOld,
+    const ParameterSet& paramSet);
+
+/// Construct a new parameter transform where the joints have been mapped to a
+/// new skeleton.  Joints that are mapped to kInvalidIndex will be simply skipped.
+/// Note that this does _not_ delete any parameters so it's possible if you remove
+/// enough joints to have "orphan" parameters still kicking around; to avoid this
+/// consider also applying an appropriate subsetParameterTransform() operation.
+template <typename T>
+[[nodiscard]] ParameterTransformT<T> mapParameterTransformJoints(
+    const ParameterTransformT<T>& parameterTransform,
+    size_t numTargetJoints,
+    const std::vector<size_t>& jointMapping);
+
+[[nodiscard]] std::tuple<ParameterTransform, ParameterLimits> addBlendShapeParameters(
+    ParameterTransform paramTransform,
+    ParameterLimits paramLimits,
+    Eigen::Index nBlendShapes);
+
+[[nodiscard]] std::tuple<ParameterTransform, ParameterLimits> addFaceExpressionParameters(
+    ParameterTransform paramTransform,
+    ParameterLimits paramLimits,
+    Eigen::Index nFaceExpressionBlendShapes);
+
+/// Add a set of parameters that control the rest-space positions of the skinned locators.
+/// This function will add 3 parameters for each locator, one for each of the x, y, and z
+/// components of the locator position.  The parameters are added to the end of the
+/// parameter transform.  The parameter transform is returned along with the updated
+/// list of parameter limits.  Note that you pass in the locator names rather than the
+/// actual SkinnedLocator objects because this avoids a circular dependency.
+[[nodiscard]] std::tuple<ParameterTransform, ParameterLimits> addSkinnedLocatorParameters(
+    ParameterTransform paramTransform,
+    ParameterLimits paramLimits,
+    const std::vector<bool>& activeLocators,
+    const std::vector<std::string>& locatorNames = {});
+
+} // namespace momentum

include/momentum/character/pose_shape.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 <momentum/character/fwd.h>
+#include <momentum/math/types.h>
+
+namespace momentum {
+
+/// Computes shape deformations based on joint rotations.
+///
+/// PoseShape implements a linear blend shape system where shape deformations
+/// are driven by joint rotations. This is useful for modeling effects like
+/// muscle bulging or skin sliding that occur during animation.
+struct PoseShape {
+  /// Index of the joint used as reference for computing relative rotations.
+  size_t baseJoint;
+
+  /// Base rotation used as reference for computing rotation differences.
+  ///
+  /// The effective rotation used for deformation is baseRot * joint.rotation().inverse()
+  Quaternionf baseRot;
+
+  /// Indices of joints whose rotations drive the shape deformation.
+  std::vector<size_t> jointMap;
+
+  /// Base shape vertices stored as a flat vector [x1,y1,z1,x2,y2,z2,...].
+  ///
+  /// The size must be a multiple of 3 (3 coordinates per vertex).
+  VectorXf baseShape;
+
+  /// Shape deformation vectors for each quaternion component of each joint.
+  ///
+  /// Matrix dimensions are [baseShape.size() × (jointMap.size() * 4)].
+  /// Each column corresponds to a quaternion component (x,y,z,w) of a joint.
+  MatrixXf shapeVectors;
+
+  /// Computes the deformed shape based on the current skeleton state.
+  ///
+  /// @param state Current state of the skeleton containing joint rotations
+  /// @return Vector of 3D vertex positions representing the deformed shape
+  /// @throws If baseShape.size() != shapeVectors.rows()
+  [[nodiscard]] std::vector<Vector3f> compute(const SkeletonState& state) const;
+
+  /// Checks if this PoseShape is approximately equal to another.
+  ///
+  /// Two PoseShape objects are considered approximately equal if all their
+  /// corresponding members are approximately equal.
+  ///
+  /// @param poseShape The PoseShape to compare with
+  /// @return True if the PoseShape objects are approximately equal
+  [[nodiscard]] inline bool isApprox(const PoseShape& poseShape) const {
+    return (
+        (baseJoint == poseShape.baseJoint) && baseRot.isApprox(poseShape.baseRot) &&
+        (jointMap == poseShape.jointMap) && baseShape.isApprox(poseShape.baseShape) &&
+        shapeVectors.isApprox(poseShape.shapeVectors));
+  }
+};
+
+} // namespace momentum

include/momentum/character/skeleton.h

@@ -0,0 +1,85 @@
+/*
+ * 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/joint.h>
+#include <momentum/character/parameter_transform.h>
+#include <momentum/character/types.h>
+#include <momentum/common/exception.h>
+
+#include <string>
+#include <string_view>
+
+namespace momentum {
+
+/// The skeletal structure of a momentum Character.
+template <typename T>
+struct SkeletonT {
+  /// The list of joints in this skeleton.
+  JointList joints;
+
+  /// Default constructor
+  SkeletonT() = default;
+
+  /// Constructor that validates joint hierarchy.
+  /// Ensures parent indices are valid (parent < child index or kInvalidIndex).
+  explicit SkeletonT(JointList joints);
+
+  /// Copy constructor
+  SkeletonT(const SkeletonT& other) = default;
+
+  /// Move constructor
+  SkeletonT(SkeletonT&& other) noexcept = default;
+
+  /// Copy assignment operator
+  SkeletonT& operator=(const SkeletonT& other) = default;
+
+  /// Move assignment operator
+  SkeletonT& operator=(SkeletonT&& other) noexcept = default;
+
+  /// Returns the index of a joint with the given name, or kInvalidIndex if not found.
+  [[nodiscard]] size_t getJointIdByName(std::string_view name) const;
+
+  /// Returns a vector containing all joint names in the skeleton.
+  [[nodiscard]] std::vector<std::string> getJointNames() const;
+
+  /// Returns indices of child joints for the specified joint.
+  ///
+  /// @param jointId Index of the joint to find children for
+  /// @param recursive If true, returns all descendants; if false, only direct children
+  /// @throws std::out_of_range if jointId is invalid
+  [[nodiscard]] std::vector<size_t> getChildrenJoints(size_t jointId, bool recursive = true) const;
+
+  /// Determines if one joint is an ancestor of another in the hierarchy.
+  ///
+  /// Returns true if ancestorJointId is an ancestor of jointId.
+  /// A joint is considered to be its own ancestor (isAncestor(id, id) returns true).
+  [[nodiscard]] bool isAncestor(size_t jointId, size_t ancestorJointId) const;
+
+  /// Finds the closest common ancestor of two joints in the hierarchy.
+  ///
+  /// Returns the index of the joint that is the lowest common ancestor
+  /// in the hierarchy for the two specified joints.
+  [[nodiscard]] size_t commonAncestor(size_t joint1, size_t joint2) const;
+
+  /// Converts the skeleton to use a different scalar type.
+  ///
+  /// Returns a copy of this skeleton with all numeric values converted to type U.
+  template <typename U>
+  [[nodiscard]] SkeletonT<U> cast() const {
+    if constexpr (std::is_same_v<T, U>) {
+      return *this;
+    } else {
+      SkeletonT<U> newSkeleton;
+      newSkeleton.joints = ::momentum::cast<U>(joints);
+      return newSkeleton;
+    }
+  }
+};
+
+} // namespace momentum