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

include/momentum/character/linear_skinning.h

@@ -0,0 +1,139 @@
+/*
+ * 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/fwd.h>
+#include <momentum/math/types.h>
+
+namespace momentum {
+
+/// @file linear_skinning.h
+/// Functions for linear blend skinning (Skeletal Subspace Deformation)
+///
+/// Linear blend skinning (LBS), also known as Skeletal Subspace Deformation (SSD),
+/// is a technique used in character animation to deform a mesh based on an underlying
+/// skeleton. Each vertex in the mesh is influenced by one or more joints, with weights
+/// determining how much influence each joint has on the vertex's final position.
+///
+/// This file provides functions to:
+/// - Apply forward skinning (transform vertices from bind pose to animated pose)
+/// - Apply inverse skinning (transform vertices from animated pose back to bind pose)
+/// - Compute inverse skinning transformations for specific vertices
+///
+/// Key concepts:
+/// - Bind pose: The reference pose of the character, where skin weights are defined
+/// - Skin weights: Per-vertex weights defining how much influence each joint has
+/// - Joint transformations: Current transformations of the skeleton's joints
+/// - Forward skinning: Applying joint transformations to deform the mesh
+/// - Inverse skinning: Reversing the deformation to return to bind pose
+
+/// Applies forward SSD (linear blend skinning) to points, returning new points
+///
+/// This overload transforms individual points and returns a new vector of transformed points.
+/// Use this when you need to transform arbitrary points without modifying a mesh.
+///
+/// @param inverseBindPose Inverse bind pose transformations for each joint
+/// @param skin Skin weights defining influence of each joint on vertices
+/// @param points Input points to transform
+/// @param state Current skeleton state containing joint transformations
+/// @return Vector of transformed points
+template <typename T>
+std::vector<Vector3<T>> applySSD(
+    const TransformationListT<T>& inverseBindPose,
+    const SkinWeights& skin,
+    typename DeduceSpanType<const Vector3<T>>::type points,
+    const SkeletonStateT<T>& state);
+
+/// Applies forward SSD to a mesh using skeleton state, modifying output mesh
+///
+/// This overload transforms both vertices and normals of the mesh, writing results to outputMesh.
+/// Use this when working with complete meshes and full skeleton state.
+///
+/// @param inverseBindPose Inverse bind pose transformations for each joint
+/// @param skin Skin weights defining influence of each joint on vertices
+/// @param mesh Input mesh to transform
+/// @param state Current skeleton state containing joint transformations
+/// @param outputMesh Output mesh to store the transformed result
+template <typename T>
+void applySSD(
+    const TransformationListT<T>& inverseBindPose,
+    const SkinWeights& skin,
+    const MeshT<T>& mesh,
+    const SkeletonStateT<T>& state,
+    MeshT<T>& outputMesh);
+
+/// Applies forward SSD to a mesh using raw joint state list, modifying output mesh
+///
+/// This overload accepts a JointStateList directly instead of a full SkeletonState.
+/// Use this when you have joint transformations but not a complete skeleton state.
+///
+/// @param inverseBindPose Inverse bind pose transformations for each joint
+/// @param skin Skin weights defining influence of each joint on vertices
+/// @param mesh Input mesh to transform
+/// @param state List of joint states containing transformations
+/// @param outputMesh Output mesh to store the transformed result
+template <typename T>
+void applySSD(
+    const TransformationListT<T>& inverseBindPose,
+    const SkinWeights& skin,
+    const MeshT<T>& mesh,
+    const JointStateListT<T>& state,
+    MeshT<T>& outputMesh);
+
+/// Computes the inverse SSD transformation for a specific vertex
+///
+/// Returns a transformation matrix that converts from skinned space back to bind pose space.
+/// This is useful for operations that need to work in the original bind pose space.
+///
+/// @param inverseBindPose Inverse bind pose transformations for each joint
+/// @param skin Skin weights defining influence of each joint on vertices
+/// @param state Current skeleton state containing joint transformations
+/// @param index Index of the vertex to compute inverse transformation for
+/// @return Inverse transformation matrix for the specified vertex
+Affine3f getInverseSSDTransformation(
+    const TransformationList& inverseBindPose,
+    const SkinWeights& skin,
+    const SkeletonState& state,
+    size_t index);
+
+/// Applies inverse SSD to points, returning new points in bind pose space
+///
+/// This overload transforms points from skinned space back to bind pose space,
+/// returning a new vector of transformed points.
+///
+/// @param inverseBindPose Inverse bind pose transformations for each joint
+/// @param skin Skin weights defining influence of each joint on vertices
+/// @param points Input points to transform (in skinned space)
+/// @param state Current skeleton state containing joint transformations
+/// @return Vector of transformed points in bind pose space
+std::vector<Vector3f> applyInverseSSD(
+    const TransformationList& inverseBindPose,
+    const SkinWeights& skin,
+    std::span<const Vector3f> points,
+    const SkeletonState& state);
+
+/// Applies inverse SSD to points, storing results in a mesh
+///
+/// This overload transforms points from skinned space back to bind pose space,
+/// writing the results directly to the provided mesh's vertices.
+///
+/// @param inverseBindPose Inverse bind pose transformations for each joint
+/// @param skin Skin weights defining influence of each joint on vertices
+/// @param points Input points to transform (in skinned space)
+/// @param state Current skeleton state containing joint transformations
+/// @param mesh Output mesh to store the transformed vertices
+void applyInverseSSD(
+    const TransformationList& inverseBindPose,
+    const SkinWeights& skin,
+    std::span<const Vector3f> points,
+    const SkeletonState& state,
+    Mesh& mesh);
+
+} // namespace momentum

include/momentum/character/locator.h

@@ -0,0 +1,94 @@
+/*
+ * 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/math/utility.h>
+
+namespace momentum {
+
+/// Represents a point attached to a joint in a skeleton.
+///
+/// Locators can be used for various purposes such as tracking specific points
+/// on a character, defining constraints, or serving as targets for inverse kinematics.
+struct Locator {
+  /// Name identifier for the locator
+  std::string name;
+
+  /// Index of the parent joint in the skeleton
+  size_t parent;
+
+  /// Position relative to the parent joint's coordinate system
+  Vector3f offset;
+
+  /// Specifies which axes (x,y,z) are locked (1) or free (0)
+  Vector3i locked;
+
+  /// Influence weight of this locator when used in constraints
+  float weight;
+
+  /// Reference position for limit constraints, typically equal to offset when loaded
+  Vector3f limitOrigin;
+
+  /// Controls how strongly the locator should maintain its original position
+  /// Higher values create stronger constraints, zero means completely free
+  Vector3f limitWeight;
+
+  /// Indicates whether the locator is attached to the skin of a person (e.g. as in mocap tracking),
+  /// used to determine whether the locator can safely be converted to a skinned locator.
+  bool attachedToSkin = false;
+
+  /// Offset from the skin surface, used when trying to solve for body shape using locators.
+  float skinOffset = 0.0f;
+
+  /// Creates a locator with the specified properties
+  ///
+  /// @param name Identifier for the locator
+  /// @param parent Index of the parent joint
+  /// @param offset Position relative to the parent joint
+  /// @param locked Axes that are locked (1) or free (0)
+  /// @param weight Influence weight in constraints
+  /// @param limitOrigin Reference position for limit constraints
+  /// @param limitWeight Strength of position maintenance constraints
+  Locator(
+      const std::string& name = "uninitialized",
+      const size_t parent = kInvalidIndex,
+      const Vector3f& offset = Vector3f::Zero(),
+      const Vector3i& locked = Vector3i::Zero(),
+      const float weight = 1.0f,
+      const Vector3f& limitOrigin = Vector3f::Zero(),
+      const Vector3f& limitWeight = Vector3f::Zero(),
+      bool attachedToSkin = false,
+      float skinOffset = 0.0f)
+      : name(name),
+        parent(parent),
+        offset(offset),
+        locked(locked),
+        weight(weight),
+        limitOrigin(limitOrigin),
+        limitWeight(limitWeight),
+        attachedToSkin(attachedToSkin),
+        skinOffset(skinOffset) {}
+
+  /// Compares two locators for equality, using approximate comparison for floating-point values
+  ///
+  /// @param locator The locator to compare with
+  /// @return True if all properties are equal (or approximately equal for floating-point values)
+  inline bool operator==(const Locator& locator) const {
+    return (
+        (name == locator.name) && (parent == locator.parent) && offset.isApprox(locator.offset) &&
+        locked.isApprox(locator.locked) && isApprox(weight, locator.weight) &&
+        limitOrigin.isApprox(locator.limitOrigin) && limitWeight.isApprox(locator.limitWeight) &&
+        attachedToSkin == locator.attachedToSkin && isApprox(skinOffset, locator.skinOffset));
+  }
+};
+
+/// A collection of locators attached to a skeleton
+using LocatorList = std::vector<Locator>;
+
+} // namespace momentum

include/momentum/character/locator_state.h

@@ -0,0 +1,43 @@
+/*
+ * 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/locator.h>
+#include <momentum/character/types.h>
+
+namespace momentum {
+
+/// Tracks the current world positions of locators in a skeleton.
+///
+/// This class maintains the transformed positions of locators based on the current
+/// state of the skeleton they're attached to.
+struct LocatorState {
+  /// World-space positions of all locators, updated when the skeleton moves
+  std::vector<Vector3f> position;
+
+ public:
+  /// Creates an empty locator state with no positions
+  LocatorState() noexcept = default;
+
+  /// Creates a locator state and immediately updates positions based on the given skeleton state
+  ///
+  /// @param skeletonState Current pose of the skeleton
+  /// @param referenceLocators List of locators to track
+  LocatorState(const SkeletonState& skeletonState, const LocatorList& referenceLocators) noexcept {
+    update(skeletonState, referenceLocators);
+  }
+
+  /// Updates the world positions of all locators based on the current skeleton pose
+  ///
+  /// @param skeletonState Current pose of the skeleton
+  /// @param referenceLocators List of locators to update positions for
+  void update(const SkeletonState& skeletonState, const LocatorList& referenceLocators) noexcept;
+};
+
+} // namespace momentum

include/momentum/character/marker.h

@@ -0,0 +1,48 @@
+/*
+ * 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 <string>
+#include <vector>
+
+namespace momentum {
+
+/// Marker represents a motion capture marker that defines an active marker during motion capture.
+struct Marker {
+  /// The name of the marker, default is "Undefined"
+  std::string name = "Undefined";
+
+  /// The 3D position of the marker as a Vector3d object, where the unit is assumed to be in
+  /// centimeters.
+  Vector3d pos = {0.0, 0.0, 0.0};
+
+  /// The occlusion status of the marker, true if occluded, false otherwise
+  bool occluded = true;
+};
+
+/// MarkerSequence stores all the frames from a single capture sequence for one subject (motion
+/// capture actor).
+///
+/// Each frame is a std::vector<Marker> containing the position and occlusion status of
+/// all the markers placed on the subject.
+/// The size of the std::vector<Marker> must be consistent for all frames.
+struct MarkerSequence {
+  /// Name of the actor sequence (typically a unique subject name or ID)
+  std::string name;
+
+  /// A 2D vector that specifies the Marker (name/position/occlusion) for all markers
+  /// throughout all captured frames. Size: [numFrames][numMarkers]
+  std::vector<std::vector<Marker>> frames;
+
+  /// The frame rate of the motion capture sequence in frames per second (default is 30.0)
+  float fps = 30.0f;
+};
+
+} // namespace momentum

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