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

include/momentum/character/joint.h

@@ -0,0 +1,82 @@
+/*
+ * 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/constants.h>
+#include <momentum/math/types.h>
+
+namespace momentum {
+
+/// A simplified version of a Maya joint with pre-rotation only (no post-rotation).
+template <typename T>
+struct JointT {
+  using Scalar = T;
+
+  /// Joint name
+  std::string name{"uninitialized"};
+
+  /// Index of the parent joint in the skeleton hierarchy
+  size_t parent{kInvalidIndex};
+
+  // TODO: does it make sense to save its own index too?
+
+  /// Pre-rotation matrix from its parent's axes to its own axes.
+  /// @note: Braces initialization is avoided due to issues with CUDA 11.
+  Quaternion<T> preRotation = Quaternion<T>::Identity();
+
+  /// The constant translation offset from the parent joint to this joint's origin.
+  Vector3<T> translationOffset = Vector3<T>::Zero();
+
+  /// Checks if the current joint is approximately equal to the provided joint.
+  [[nodiscard]] bool isApprox(
+      const JointT<T>& joint,
+      const T& rotTol = Eps<T>(1e-4, 1e-10),
+      const T& tranTol = Eigen::NumTraits<Scalar>::dummy_precision()) const {
+    if (name != joint.name) {
+      return false;
+    }
+
+    if (parent != joint.parent) {
+      return false;
+    }
+
+    if (!preRotation.toRotationMatrix().isApprox(joint.preRotation.toRotationMatrix(), rotTol)) {
+      return false;
+    }
+
+    if (!translationOffset.isApprox(joint.translationOffset, tranTol)) {
+      return false;
+    }
+
+    return true;
+  }
+
+  /// Casts the current joint to another scalar type.
+  template <typename U>
+  [[nodiscard]] auto cast() const {
+    if constexpr (std::is_same_v<T, U>) {
+      return *this;
+    } else {
+      JointT<U> newJoint;
+      newJoint.name = name;
+      newJoint.parent = parent;
+      newJoint.preRotation = preRotation.template cast<U>();
+      newJoint.translationOffset = translationOffset.template cast<U>();
+      return newJoint;
+    }
+  }
+};
+
+/// A list of joints (e.g., of a skeleton).
+template <typename T>
+using JointListT = std::vector<JointT<T>>;
+using JointList = JointListT<float>;
+using JointListd = JointListT<double>;
+
+} // namespace momentum

include/momentum/character/joint_state.h

@@ -0,0 +1,241 @@
+/*
+ * 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/types.h>
+#include <momentum/math/transform.h>
+#include <momentum/math/types.h>
+
+namespace momentum {
+
+/// Represents the state of a joint with local and global transformations.
+///
+/// Joint transform hierarchy is defined as:
+///     WorldTransform = ParentWorldTransform * Tz * Ty * Tx * Rpre * R * S
+///
+/// Where:
+/// - Tx, Ty, Tz are translations along each axis
+/// - Rpre is the pre-rotation from the joint definition
+/// - R is the joint rotation (applied in order: rz * ry * rx)
+/// - S is the uniform scale factor
+///
+/// Each joint has 7 parameters: 3 translation, 3 rotation, and 1 scale.
+template <typename T>
+struct JointStateT {
+  /// Local transformation relative to parent joint
+  ///
+  /// Defined by the joint parameters (translation, rotation, scale)
+  TransformT<T> localTransform;
+
+  /// Global transformation in world space
+  ///
+  /// Combines parent transformations with local transformation
+  TransformT<T> transform;
+
+  /// Translation axes in global space
+  ///
+  /// Each column represents one translation axis (X, Y, Z) in global coordinates
+  Matrix3<T> translationAxis;
+
+  /// Rotation axes in global space
+  ///
+  /// Each column represents one rotation axis (X, Y, Z) in global coordinates
+  Matrix3<T> rotationAxis;
+
+  /// Indicates if derivative data needs recomputation
+  ///
+  /// When true, derivative methods should not be called as they may return invalid results
+  bool derivDirty = true;
+
+  /// Updates joint state based on joint definition and parameters
+  ///
+  /// Recursively computes all transformations from parent to child, including
+  /// local and global transforms, and optionally derivative information.
+  ///
+  /// @param joint The joint definition containing offset and pre-rotation
+  /// @param parameters The 7 joint parameters [tx, ty, tz, rx, ry, rz, scale]
+  /// @param parentState Optional parent joint state for hierarchical transformations
+  /// @param computeDeriv Whether to compute derivative information (translation/rotation axes)
+  void set(
+      const JointT<T>& joint,
+      const JointVectorT<T>& parameters,
+      const JointStateT<T>* parentState = nullptr,
+      bool computeDeriv = true) noexcept;
+
+  /// Calculates the derivative of a point with respect to rotation around a specific axis
+  ///
+  /// @param index The rotation axis index (0=X, 1=Y, 2=Z)
+  /// @param ref The reference point in global space
+  /// @return The derivative vector
+  [[nodiscard]] Vector3<T> getRotationDerivative(size_t index, const Vector3<T>& ref) const;
+
+  /// Calculates the derivative with respect to translation along a specific axis
+  ///
+  /// @param index The translation axis index (0=X, 1=Y, 2=Z)
+  /// @return The derivative vector
+  [[nodiscard]] Vector3<T> getTranslationDerivative(size_t index) const;
+
+  /// Calculates the derivative of a point with respect to uniform scaling
+  ///
+  /// @param ref The reference point in global space
+  /// @return The derivative vector
+  [[nodiscard]] Vector3<T> getScaleDerivative(const Vector3<T>& ref) const noexcept;
+
+  /// Copies state from another JointState with potentially different scalar type
+  ///
+  /// @tparam T2 Source scalar type
+  /// @param rhs Source joint state to copy from
+  template <typename T2>
+  void set(const JointStateT<T2>& rhs);
+
+  /// Access the joint's local rotation quaternion
+  [[nodiscard]] const Quaternion<T>& localRotation() const {
+    return localTransform.rotation;
+  }
+
+  /// Access the joint's local rotation quaternion (mutable)
+  Quaternion<T>& localRotation() {
+    return localTransform.rotation;
+  }
+
+  /// Access the joint's local translation vector
+  [[nodiscard]] const Vector3<T>& localTranslation() const {
+    return localTransform.translation;
+  }
+
+  /// Access the joint's local translation vector (mutable)
+  Vector3<T>& localTranslation() {
+    return localTransform.translation;
+  }
+
+  /// Access the joint's local scale factor
+  ///
+  /// This scale propagates to all descendant joints
+  [[nodiscard]] const T& localScale() const {
+    return localTransform.scale;
+  }
+
+  /// Access the joint's local scale factor (mutable)
+  T& localScale() {
+    return localTransform.scale;
+  }
+
+  /// Access the joint's global rotation quaternion
+  [[nodiscard]] const Quaternion<T>& rotation() const {
+    return transform.rotation;
+  }
+
+  /// Access the joint's global rotation quaternion (mutable)
+  Quaternion<T>& rotation() {
+    return transform.rotation;
+  }
+
+  /// Access the joint's global position vector
+  [[nodiscard]] const Vector3<T>& translation() const {
+    return transform.translation;
+  }
+
+  /// Access the joint's global position vector (mutable)
+  Vector3<T>& translation() {
+    return transform.translation;
+  }
+
+  /// Access the X component of the global position
+  [[nodiscard]] const T& x() const {
+    return transform.translation.x();
+  }
+
+  /// Access the X component of the global position (mutable)
+  T& x() {
+    return transform.translation.x();
+  }
+
+  /// Access the Y component of the global position
+  [[nodiscard]] const T& y() const {
+    return transform.translation.y();
+  }
+
+  /// Access the Y component of the global position (mutable)
+  T& y() {
+    return transform.translation.y();
+  }
+
+  /// Access the Z component of the global position
+  [[nodiscard]] const T& z() const {
+    return transform.translation.z();
+  }
+
+  /// Access the Z component of the global position (mutable)
+  T& z() {
+    return transform.translation.z();
+  }
+
+  /// Access the W component of the global rotation quaternion
+  [[nodiscard]] const T& quatW() const {
+    return transform.rotation.w();
+  }
+
+  /// Access the W component of the global rotation quaternion (mutable)
+  T& quatW() {
+    return transform.rotation.w();
+  }
+
+  /// Access the X component of the global rotation quaternion
+  [[nodiscard]] const T& quatX() const {
+    return transform.rotation.x();
+  }
+
+  /// Access the X component of the global rotation quaternion (mutable)
+  T& quatX() {
+    return transform.rotation.x();
+  }
+
+  /// Access the Y component of the global rotation quaternion
+  [[nodiscard]] const T& quatY() const {
+    return transform.rotation.y();
+  }
+
+  /// Access the Y component of the global rotation quaternion (mutable)
+  T& quatY() {
+    return transform.rotation.y();
+  }
+
+  /// Access the Z component of the global rotation quaternion
+  [[nodiscard]] const T& quatZ() const {
+    return transform.rotation.z();
+  }
+
+  /// Access the Z component of the global rotation quaternion (mutable)
+  T& quatZ() {
+    return transform.rotation.z();
+  }
+
+  /// Access the joint's global scale factor
+  ///
+  /// This is the cumulative scale from all parent joints
+  [[nodiscard]] const T& scale() const {
+    return transform.scale;
+  }
+
+  /// Access the joint's global scale factor (mutable)
+  T& scale() {
+    return transform.scale;
+  }
+
+  EIGEN_MAKE_ALIGNED_OPERATOR_NEW
+};
+
+/// Structure describing the state of all joints in a skeleton
+template <typename T>
+using JointStateListT = std::vector<JointStateT<T>>;
+
+using JointState = JointStateT<float>;
+using JointStateList = JointStateListT<float>;
+
+} // namespace momentum

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,
+    gsl::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,
+    gsl::span<const Vector3f> points,
+    const SkeletonState& state,
+    Mesh& mesh);
+
+} // namespace momentum

include/momentum/character/locator.h

@@ -0,0 +1,82 @@
+/*
+ * 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;
+
+  /// 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())
+      : name(name),
+        parent(parent),
+        offset(offset),
+        locked(locked),
+        weight(weight),
+        limitOrigin(limitOrigin),
+        limitWeight(limitWeight) {}
+
+  /// 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));
+  }
+};
+
+/// 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