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

include/momentum/character/parameter_transform.h

@@ -0,0 +1,207 @@
+/*
+ * 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;
+
+  bool operator==(const PoseConstraint& poseConstraint) const;
+};
+
+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]] bool isApprox(const ParameterTransformT<T>& parameterTransform) const;
+};
+
+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

include/momentum/character/skeleton_state.h

@@ -0,0 +1,227 @@
+/*
+ * 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_state.h>
+#include <momentum/character/types.h>
+#include <momentum/math/types.h>
+
+namespace momentum {
+
+/// Measures of similarity between two skeleton states
+///
+/// Contains both per-joint error metrics and aggregate statistics
+struct StateSimilarity {
+  /// Position error for each joint (in distance units)
+  VectorXf positionError;
+
+  /// Orientation error for each joint (in radians)
+  VectorXf orientationError;
+
+  /// Root mean square of position errors across all joints
+  float positionRMSE;
+
+  /// Root mean square of orientation errors across all joints
+  float orientationRMSE;
+
+  /// Maximum position error across all joints
+  float positionMax;
+
+  /// Maximum orientation error across all joints
+  float orientationMax;
+};
+
+/// Represents the complete state of a skeleton
+///
+/// Stores joint parameters and computed joint states for an entire skeleton.
+/// Provides methods for updating the state based on new parameters and
+/// comparing different skeleton states.
+template <typename T>
+struct SkeletonStateT {
+  /// Joint parameters for all joints in the skeleton
+  JointParametersT<T> jointParameters;
+
+  /// Computed joint states for all joints in the skeleton
+  JointStateListT<T> jointState;
+
+  /// Creates an empty skeleton state
+  SkeletonStateT() noexcept = default;
+
+  /// Creates a skeleton state from joint parameters and a reference skeleton
+  ///
+  /// @param parameters Joint parameters for all joints in the skeleton
+  /// @param referenceSkeleton The skeleton structure defining joint hierarchy
+  /// @param computeDeriv Whether to compute derivative information for the joints
+  SkeletonStateT(
+      const JointParametersT<T>& parameters,
+      const Skeleton& referenceSkeleton,
+      bool computeDeriv = true);
+
+  /// Creates a skeleton state from rvalue joint parameters and a reference skeleton
+  ///
+  /// @param parameters Joint parameters for all joints in the skeleton (moved from)
+  /// @param referenceSkeleton The skeleton structure defining joint hierarchy
+  /// @param computeDeriv Whether to compute derivative information for the joints
+  SkeletonStateT(
+      JointParametersT<T>&& parameters,
+      const Skeleton& referenceSkeleton,
+      bool computeDeriv = true);
+
+  /// Creates a skeleton state from another skeleton state with a different scalar type
+  ///
+  /// @tparam T2 Source scalar type
+  /// @param rhs Source skeleton state to copy from
+  template <typename T2>
+  explicit SkeletonStateT(const SkeletonStateT<T2>& rhs);
+
+  /// Updates the skeleton state with new joint parameters
+  ///
+  /// @param jointParameters New joint parameters for all joints
+  /// @param referenceSkeleton The skeleton structure defining joint hierarchy
+  /// @param computeDeriv Whether to compute derivative information for the joints
+  void set(
+      const JointParametersT<T>& jointParameters,
+      const Skeleton& referenceSkeleton,
+      bool computeDeriv = true);
+
+  /// Updates the skeleton state with new rvalue joint parameters
+  ///
+  /// @param jointParameters New joint parameters for all joints (moved from)
+  /// @param referenceSkeleton The skeleton structure defining joint hierarchy
+  /// @param computeDeriv Whether to compute derivative information for the joints
+  void set(
+      JointParametersT<T>&& jointParameters,
+      const Skeleton& referenceSkeleton,
+      bool computeDeriv = true);
+
+  /// Updates the skeleton state from another skeleton state with a different scalar type
+  ///
+  /// @tparam T2 Source scalar type
+  /// @param rhs Source skeleton state to copy from
+  template <typename T2>
+  void set(const SkeletonStateT<T2>& rhs);
+
+  /// Compares two skeleton states and returns similarity metrics
+  ///
+  /// @param state1 First skeleton state to compare
+  /// @param state2 Second skeleton state to compare
+  /// @return Similarity metrics between the two states
+  [[nodiscard]] static StateSimilarity compare(
+      const SkeletonStateT<T>& state1,
+      const SkeletonStateT<T>& state2);
+
+  /// Extracts global transforms for all joints in the skeleton
+  ///
+  /// @return List of global transforms for all joints
+  [[nodiscard]] TransformListT<T> toTransforms() const;
+
+  /// Converts the skeleton state to a different scalar type
+  ///
+  /// @tparam T2 Target scalar type
+  /// @return Skeleton state with the target scalar type
+  template <typename T2>
+  [[nodiscard]] SkeletonStateT<T2> cast() const {
+    SkeletonStateT<T2> result;
+    result.set(*this);
+    return result;
+  }
+
+ private:
+  /// Updates the joint states based on the current joint parameters
+  ///
+  /// @param referenceSkeleton The skeleton structure defining joint hierarchy
+  /// @param computeDeriv Whether to compute derivative information for the joints
+  void set(const Skeleton& referenceSkeleton, bool computeDeriv);
+
+  /// Copies joint states from another skeleton state with a different scalar type
+  ///
+  /// @tparam T2 Source scalar type
+  /// @param rhs Source skeleton state to copy from
+  template <typename T2>
+  void copy(const SkeletonStateT<T2>& rhs);
+};
+
+/// Computes the relative transform between two joints in a skeleton
+///
+/// This transform maps points from joint A's local space to joint B's local space.
+/// It is computed by finding the common ancestor of both joints and combining
+/// the transforms along the path, which is more numerically stable than
+/// computing (T_B)^{-1} * T_A directly.
+///
+/// @param jointA Source joint index
+/// @param jointB Target joint index
+/// @param referenceSkeleton The skeleton structure defining joint hierarchy
+/// @param skelState Current state of the skeleton
+/// @return Transform from joint A's local space to joint B's local space
+template <typename T>
+TransformT<T> transformAtoB(
+    size_t jointA,
+    size_t jointB,
+    const Skeleton& referenceSkeleton,
+    const SkeletonStateT<T>& skelState);
+
+/// Invert the skeleton state (global transforms in world space) back to joint parameters (Euler
+/// angles in local space).  Note that this conversion is not unique due to the non-uniqueness of
+/// Euler angle conversion.
+template <typename T>
+[[nodiscard]] JointParametersT<T> skeletonStateToJointParameters(
+    const SkeletonStateT<T>& state,
+    const Skeleton& skeleton);
+
+template <typename T>
+[[nodiscard]] JointParametersT<T> skeletonStateToJointParameters(
+    const TransformListT<T>& state,
+    const Skeleton& skeleton);
+
+/// Converts skeleton state back to joint parameters, respecting active joint parameter constraints.
+///
+/// This function addresses the limitation of the original `skeletonStateToJointParameters` which
+/// always uses 3-axis Euler rotations. Many joints only support 1-axis or 2-axis rotations, so
+/// this function uses the provided `activeJointParams` to determine how many rotation axes are
+/// active for each joint and applies the appropriate conversion method:
+/// - 0 active rotation axes: Sets all rotation parameters to zero
+/// - 1 active rotation axis: Uses `rotationMatrixToOneAxisEuler`
+/// - 2 active rotation axes: Uses `rotationMatrixToTwoAxisEuler`
+/// - 3 active rotation axes: Uses the standard 3-axis Euler conversion
+///
+/// @tparam T The scalar type (float or double)
+/// @param[in] state The skeleton state to convert
+/// @param[in] skeleton The skeleton defining joint hierarchy and properties
+/// @param[in] activeJointParams Boolean array indicating which joint parameters are active.
+///            Size should be skeleton.joints.size() * kParametersPerJoint
+/// @return Joint parameters with rotations respecting the active parameter constraints
+template <typename T>
+[[nodiscard]] JointParametersT<T> skeletonStateToJointParametersRespectingActiveParameters(
+    const SkeletonStateT<T>& state,
+    const Skeleton& skeleton,
+    const VectorX<bool>& activeJointParams);
+
+/// Converts transform list back to joint parameters, respecting active joint parameter constraints.
+///
+/// This function addresses the limitation of the original `skeletonStateToJointParameters` which
+/// always uses 3-axis Euler rotations. Many joints only support 1-axis or 2-axis rotations, so
+/// this function uses the provided `activeJointParams` to determine how many rotation axes are
+/// active for each joint and applies the appropriate conversion method:
+/// - 0 active rotation axes: Sets all rotation parameters to zero
+/// - 1 active rotation axis: Uses `rotationMatrixToOneAxisEuler`
+/// - 2 active rotation axes: Uses `rotationMatrixToTwoAxisEuler`
+/// - 3 active rotation axes: Uses the standard 3-axis Euler conversion
+///
+/// @tparam T The scalar type (float or double)
+/// @param[in] state The transform list to convert
+/// @param[in] skeleton The skeleton defining joint hierarchy and properties
+/// @param[in] activeJointParams Boolean array indicating which joint parameters are active.
+///            Size should be skeleton.joints.size() * kParametersPerJoint
+/// @return Joint parameters with rotations respecting the active parameter constraints
+template <typename T>
+[[nodiscard]] JointParametersT<T> skeletonStateToJointParametersRespectingActiveParameters(
+    const TransformListT<T>& state,
+    const Skeleton& skeleton,
+    const VectorX<bool>& activeJointParams);
+
+} // namespace momentum

include/momentum/character/skeleton_utility.h

@@ -0,0 +1,38 @@
+/*
+ * 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/types.h>
+
+namespace momentum {
+
+inline constexpr float kDefaultExtrapolateFactor = 0.8f;
+inline constexpr float kDefaultExtrapolateMaxDelta = 0.4f; // ~23 degrees
+
+/// Extrapolates model parameters by first clamping the difference between current and previous
+/// parameters to the range [-maxDelta, maxDelta], and then scaling this clamped difference by
+/// `factor`. Returns the current parameters when sizes mismatch.
+[[nodiscard]] ModelParameters extrapolateModelParameters(
+    const ModelParameters& previous,
+    const ModelParameters& current,
+    float factor = kDefaultExtrapolateFactor,
+    float maxDelta = kDefaultExtrapolateMaxDelta);
+
+/// Extrapolates model parameters considering active parameters. The extrapolation is done by first
+/// clamping the difference between current and previous parameters to the range [-maxDelta,
+/// maxDelta] for each active parameter, and then scaling this clamped difference by `factor`.
+/// Returns the current parameters when sizes mismatch.
+[[nodiscard]] ModelParameters extrapolateModelParameters(
+    const ModelParameters& previous,
+    const ModelParameters& current,
+    const ParameterSet& activeParams,
+    float factor = kDefaultExtrapolateFactor,
+    float maxDelta = kDefaultExtrapolateMaxDelta);
+
+} // namespace momentum