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

include/momentum/io/skeleton/parameter_limits_io.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/fwd.h>
+#include <momentum/character/parameter_limits.h>
+
+namespace momentum {
+
+namespace io_detail {
+// Forward declaration
+class SectionContent;
+} // namespace io_detail
+
+// Internal overload for use within momentum parsing
+ParameterLimits parseParameterLimits(
+    const io_detail::SectionContent& content,
+    const Skeleton& skeleton,
+    const ParameterTransform& parameterTransform);
+
+// Public API for external use
+ParameterLimits parseParameterLimits(
+    const std::string& data,
+    const Skeleton& skeleton,
+    const ParameterTransform& parameterTransform,
+    size_t lineOffset = 0);
+
+std::string writeParameterLimits(
+    const ParameterLimits& parameterLimits,
+    const Skeleton& skeleton,
+    const ParameterTransform& parameterTransform);
+
+} // namespace momentum

include/momentum/io/skeleton/parameter_transform_io.h

@@ -0,0 +1,80 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#pragma once
+
+#include <momentum/character/parameter_limits.h>
+#include <momentum/character/parameter_transform.h>
+#include <momentum/common/filesystem.h>
+
+#include <span>
+
+#include <string>
+#include <unordered_map>
+
+namespace momentum {
+
+namespace io_detail {
+// Forward declaration
+class SectionContent;
+} // namespace io_detail
+
+std::unordered_map<std::string, std::string> loadMomentumModel(const filesystem::path& filename);
+
+std::unordered_map<std::string, std::string> loadMomentumModelFromBuffer(
+    std::span<const std::byte> buffer);
+
+// Internal overloads for use within momentum parsing
+ParameterTransform parseParameterTransform(
+    const io_detail::SectionContent& content,
+    const Skeleton& skeleton);
+ParameterSets parseParameterSets(
+    const io_detail::SectionContent& content,
+    const ParameterTransform& pt);
+PoseConstraints parsePoseConstraints(
+    const io_detail::SectionContent& content,
+    const ParameterTransform& pt);
+
+// Public APIs for external use
+ParameterTransform
+parseParameterTransform(const std::string& data, const Skeleton& skeleton, size_t lineOffset = 0);
+
+ParameterSets
+parseParameterSets(const std::string& data, const ParameterTransform& pt, size_t lineOffset = 0);
+
+PoseConstraints
+parsePoseConstraints(const std::string& data, const ParameterTransform& pt, size_t lineOffset = 0);
+
+// load transform definition from file
+std::tuple<ParameterTransform, ParameterLimits> loadModelDefinition(
+    const filesystem::path& filename,
+    const Skeleton& skeleton);
+
+std::tuple<ParameterTransform, ParameterLimits> loadModelDefinition(
+    std::span<const std::byte> rawData,
+    const Skeleton& skeleton);
+
+// Write functions to serialize model definition components
+std::string writeParameterTransform(
+    const ParameterTransform& parameterTransform,
+    const Skeleton& skeleton);
+
+std::string writeParameterSets(const ParameterSets& parameterSets);
+
+std::string writePoseConstraints(const PoseConstraints& poseConstraints);
+
+/// Write complete model definition file
+/// @param skeleton The character's skeletal structure
+/// @param parameterTransform Maps model parameters to joint parameters
+/// @param parameterLimits Constraints on model parameters (can be empty)
+/// @return String containing the complete model definition
+std::string writeModelDefinition(
+    const Skeleton& skeleton,
+    const ParameterTransform& parameterTransform,
+    const ParameterLimits& parameterLimits);
+
+} // namespace momentum

include/momentum/io/skeleton/parameters_io.h

@@ -0,0 +1,20 @@
+/*
+ * 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 <string>
+#include <unordered_map>
+
+namespace momentum {
+
+// Load the input parameters onto the character
+void loadParameters(std::unordered_map<std::string, std::string>& param, Character& character);
+
+} // namespace momentum

include/momentum/io/skeleton/utility.h

@@ -0,0 +1,67 @@
+/*
+ * 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 <sstream>
+#include <string>
+#include <string_view>
+#include <vector>
+
+namespace momentum {
+namespace io_detail {
+
+/// Represents a single segment of a section (when sections are split across the file)
+struct SectionSegment {
+  std::string content;
+  size_t startLine;
+};
+
+/// Holds all segments of a section and provides line-aware iteration
+/// This is used internally to track line numbers across potentially duplicate sections
+class SectionContent {
+ public:
+  void addSegment(std::string_view content, size_t startLine) {
+    segments_.push_back({std::string(content), startLine});
+  }
+
+  [[nodiscard]] bool empty() const {
+    return segments_.empty();
+  }
+
+  /// Iterator that walks through all segments while tracking line numbers
+  class LineIterator {
+   public:
+    explicit LineIterator(const std::vector<SectionSegment>& segments);
+
+    /// Get the next line from the sections
+    /// @return true if a line was read, false if end of all segments reached
+    bool getline(std::string& line);
+
+    /// Get the current line number in the original file
+    [[nodiscard]] size_t currentLine() const;
+
+   private:
+    const std::vector<SectionSegment>& segments_;
+    size_t segmentIndex_;
+    size_t lineInSegment_;
+    std::istringstream currentStream_;
+  };
+
+  [[nodiscard]] LineIterator begin() const {
+    return LineIterator(segments_);
+  }
+
+  /// Get all content as a single concatenated string (for backward compatibility)
+  [[nodiscard]] std::string toString() const;
+
+ private:
+  std::vector<SectionSegment> segments_;
+};
+
+} // namespace io_detail
+} // namespace momentum

include/momentum/io/urdf/urdf_io.h

@@ -0,0 +1,26 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#pragma once
+
+#include <momentum/character/character.h>
+#include <momentum/common/filesystem.h>
+#include <momentum/math/types.h>
+
+#include <span>
+
+namespace momentum {
+
+/// Loads a character from a URDF file.
+template <typename T = float>
+CharacterT<T> loadUrdfCharacter(const filesystem::path& filepath);
+
+/// Loads a character from a URDF file using the provided byte data.
+template <typename T = float>
+[[nodiscard]] CharacterT<T> loadUrdfCharacter(std::span<const std::byte> bytes);
+
+} // namespace momentum

include/momentum/io/usd/usd_io.h

@@ -0,0 +1,36 @@
+/*
+ * 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/common/filesystem.h>
+#include <momentum/math/types.h>
+
+#include <span>
+
+namespace momentum {
+
+/// Load a USD character from a local file path.
+///
+/// @param[in] inputPath The path to the USD character file.
+/// @return The loaded Character object.
+Character loadUsdCharacter(const filesystem::path& inputPath);
+
+/// Load a USD character from a buffer.
+///
+/// @param[in] inputSpan The buffer containing the USD character data.
+/// @return The loaded Character object.
+Character loadUsdCharacter(std::span<const std::byte> inputSpan);
+
+/// Save a character to a USD file.
+///
+/// @param[in] filename The path to save the USD file.
+/// @param[in] character The Character object to save.
+void saveUsd(const filesystem::path& filename, const Character& character);
+
+} // namespace momentum

include/momentum/marker_tracking/app_utils.h

@@ -0,0 +1,64 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#pragma once
+
+#include <momentum/character/character.h>
+#include <momentum/character/marker.h>
+#include <momentum/marker_tracking/marker_tracker.h>
+
+#include <CLI/CLI.hpp>
+
+namespace momentum {
+
+struct IOOptions {
+  std::string inputFile;
+  std::string outputFile;
+};
+
+struct ModelOptions {
+  std::string model;
+  std::string parameters;
+  std::string locators;
+};
+
+void addIOOptions(CLI::App& app, std::shared_ptr<IOOptions> ioOptions);
+void addModelOptions(CLI::App& app, std::shared_ptr<ModelOptions> modelOptions);
+void addCalibrationOptions(CLI::App& app, std::shared_ptr<CalibrationConfig> config);
+void addTrackingOptions(CLI::App& app, std::shared_ptr<TrackingConfig> config);
+void addRefineOptions(CLI::App& app, std::shared_ptr<RefineConfig> config);
+
+std::tuple<momentum::Character, momentum::ModelParameters> loadCalibratedModel(
+    const std::string& modelFile);
+
+std::tuple<momentum::Character, momentum::ModelParameters> loadCharacterWithIdentity(
+    const ModelOptions& modelFiles);
+
+/// Save the given character and motion to a GLB or FBX file.
+///
+/// @param[in] outFile The GLB/FBX file to save to
+/// @param[in] character The GLB/FBX file to save to
+/// @param[in] identity The identity parameters used for the character
+/// @param[in] finalMotion The motion save to the file. (Note: this may be modified to remove
+/// scaling parameters if saveScaleToMotion is false)
+/// @param[in] markerData Marker data to save to the file
+/// @param[in] fps Framerate of the motion
+/// @param[in] saveMarkerMesh (optional) Whether to save a visible cube mesh for the markers
+/// @param[in] saveScaleToMotion (optional) Whether to save the scale parameters to the motion or
+/// identity parameter vectors (saving to motion is preferred)
+/// @param[in] timestamps Per-frame timestamps. Size should match motion columns.
+void saveMotion(
+    const std::string& outFile,
+    const momentum::Character& character,
+    const momentum::ModelParameters& identity,
+    Eigen::MatrixXf& finalMotion,
+    std::span<const std::vector<momentum::Marker>> markerData,
+    double fps,
+    bool saveMarkerMesh = true,
+    std::span<const int64_t> timestamps = {});
+
+} // namespace momentum

include/momentum/marker_tracking/marker_tracker.h

@@ -0,0 +1,221 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#pragma once
+
+#include <momentum/character/character.h>
+#include <momentum/character/marker.h>
+
+namespace momentum {
+
+/// Common configuration for a tracking problem
+struct BaseConfig {
+  /// Minimum percentage of visible markers in a frame to consider for tracking. We will skip frames
+  /// with too few visible markers as they may be better filled in through a smoothing pass.
+  float minVisPercent = 0.f;
+  /// Parameter to control what loss function to use. Refer to comments in GeneralizedLoss class for
+  /// details. Use a smaller alpha when data is noisy; otherwise L2 is good.
+  float lossAlpha = 2.0;
+  /// Max number of solver iterations to run.
+  size_t maxIter = 30;
+  /// Regularization parameter (lambda) for Levenberg-Marquardt solver.
+  float regularization = 0.05f;
+  /// True to print and save debug information.
+  bool debug = false;
+};
+
+/// Configuration for running body and/or locator calibration
+struct CalibrationConfig : public BaseConfig {
+  /// Number of frames used in calibration. It will be a uniform sample from the input.
+  size_t calibFrames = 100;
+  /// Number of iterations to run the main calibration loop. It could be larger if calibrating for
+  /// locators only.
+  size_t majorIter = 3;
+  /// True to only solve for a global body scale without changing individual bone length.
+  bool globalScaleOnly = false;
+  /// True to calibrate only the locators and not the body.
+  bool locatorsOnly = false;
+  /// Sample uniformly or do a greedy importance sampling
+  size_t greedySampling = 0;
+  /// True to lock the floor constraints to the floor in the first frame
+  bool enforceFloorInFirstFrame = false;
+  /// Name of a pose constraint set to use for the first frame
+  std::string firstFramePoseConstraintSet;
+  /// Calibrate the character's shape
+  bool calibShape = false;
+};
+
+/// Configuration for pose tracking given a calibrated body and locators
+struct TrackingConfig : public BaseConfig {
+  /// The weight for the smoothness error function.
+  float smoothing = 0;
+  /// The weight for the collision error function.
+  float collisionErrorWeight = 0.0;
+  /// Smoothing weights per model parameter. The size of this vector should be equal to number of
+  /// model parameters and this overrides the value specific in smoothing
+  Eigen::VectorXf smoothingWeights{};
+};
+
+/// Configuration for refining an already tracked motion, eg. add smoothing and/or collision
+/// handling; improve residuals with extra dofs etc.
+struct RefineConfig : public TrackingConfig {
+  /// Minimize changes to calibration parameters when in calibration mode, by regularizing towards
+  /// the input value with this regularizer weight.
+  float regularizer = 0.0;
+  /// Calibrate identity parameters when refining the motion.
+  bool calibId = false;
+  /// Calibrate locators when refining the motion.
+  bool calibLocators = false;
+};
+
+/// Use multiple frames to solve for global parameters such as body proportions and/or marker
+/// offsets together with the motion. It can also be used to smooth out a motion with or without
+/// solving for global parameters, for example to fill gaps when there are missing markers.
+///
+/// @param[in] markerData Marker data.
+/// @param[in] character Character definition.
+/// @param[in] globalParams Bitset to indicate global parameters to solve for; could be all zeros
+/// for post-process a motion.
+/// @param[in] initialMotion Initial values of all parameters. It should be the same length as
+/// markerData, but only frames used in solving are used. Values in unused frames do not matter.
+/// Number of parameters should be the same as defined in character.
+/// @param[in] config Solving options.
+/// @param[in] frameStride Frame stride to select solver frames (ie. uniform sample).
+/// @param[in] enforceFloorInFirstFrame Flag to enforce the floor contact constraints in first frame
+/// @param[in] firstFramePoseConstraintSet Name of a pose constraint set to use for the first frame
+///
+/// @return The solved motion. It has the same length as markerData. It repeats the same solved pose
+/// within a frame stride.
+Eigen::MatrixXf trackSequence(
+    std::span<const std::vector<momentum::Marker>> markerData,
+    const momentum::Character& character,
+    const momentum::ParameterSet& globalParams,
+    const Eigen::MatrixXf& initialMotion,
+    const TrackingConfig& config,
+    float regularizer = 0.0,
+    size_t frameStride = 1,
+    bool enforceFloorInFirstFrame = false,
+    const std::string& firstFramePoseConstraintSet = "");
+
+/// Use multiple frames to solve for global parameters such as body proportions and/or marker
+/// offsets together with the motion.
+///
+/// @param[in] markerData Marker data.
+/// @param[in] character Character definition.
+/// @param[in] globalParams Bitset to indicate global parameters to solve for; could be all zeros
+/// for post-process a motion.
+/// @param[in] initialMotion Initial values of all parameters. It should be the same length as
+/// markerData, but only frames used in solving are used. Values in unused frames do not matter.
+/// Number of parameters should be the same as defined in character.
+/// @param[in] config Solving options.
+/// @param[in] frames List of frames to solve for.
+/// @param[in] enforceFloorInFirstFrame Flag to enforce the floor contact constraints in first frame
+/// @param[in] firstFramePoseConstraintSet Name of a pose constraint set to use for the first frame
+///
+/// @return The solved motion. It has the same length as markerData. It repeats the same solved pose
+/// within a frame stride.
+Eigen::MatrixXf trackSequence(
+    std::span<const std::vector<momentum::Marker>> markerData,
+    const momentum::Character& character,
+    const momentum::ParameterSet& globalParams,
+    const Eigen::MatrixXf& initialMotion,
+    const TrackingConfig& config,
+    const std::vector<size_t>& frames,
+    float regularizer = 0.0,
+    bool enforceFloorInFirstFrame = false,
+    const std::string& firstFramePoseConstraintSet = "");
+
+/// Track poses per-frame given a calibrated character.
+///
+/// @param[in] markerData Input marker data.
+/// @param[in] character Character definition.
+/// @param[in] globalParams Calibrated identity info; could be repurposed to pass in an initial pose
+/// too.
+/// @param[in] config Solving options.
+/// @param[in] frameStride Frame stride to select solver frames (ie. uniform sample).
+///
+/// @return The solved motion. It has the same length as markerData. It repeats the same solved pose
+/// within a frame stride.
+Eigen::MatrixXf trackPosesPerframe(
+    std::span<const std::vector<momentum::Marker>> markerData,
+    const momentum::Character& character,
+    const momentum::ModelParameters& globalParams,
+    const TrackingConfig& config,
+    size_t frameStride = 1);
+
+/// Track poses for given frames.
+///
+/// @param[in] markerData Input marker data.
+/// @param[in] character Character definition.
+/// @param[in] globalParams Calibrated identity info; could be repurposed to pass in an initial pose
+/// too.
+/// @param[in] config Solving options.
+/// @param[in] frameIndices Frame indices of the frames to be solved.
+/// @param[in] isContinuous Whether to use temporal coherence between frames.
+///
+/// @return The solved motion. It has the same length as markerData. It repeats the same solved pose
+/// within a frame stride.
+Eigen::MatrixXf trackPosesForFrames(
+    std::span<const std::vector<momentum::Marker>> markerData,
+    const momentum::Character& character,
+    const Eigen::MatrixXf& initialMotion,
+    const TrackingConfig& config,
+    const std::vector<size_t>& frameIndices,
+    bool isContinuous = false);
+
+/// Calibrate body proportions and locator offsets of a character from input marker data.
+///
+/// @param[in] markerData Input marker data.
+/// @param[in] config Solving options.
+/// @param[in,out] character Character definition. It provides input locators offsets which will get
+/// updated in return.
+/// @param[in,out] identity Initial identity parameters that get updated in return. It could also
+/// hold the pose of the first frame for better initialization for tracking later.
+/// @param[in] regularizerWeights Regularizer weights used for global parameters, at each different
+/// stage (3 in total) of the calibration. Ideally these weights would increase over stages: in
+/// stage 0, 0 or low regularization weight to allow a large change; in stage 1, a small
+/// regularization weight to prevent too large of a change; in stage 2, a higher regularization
+/// weight to prevent large changes.
+void calibrateModel(
+    std::span<const std::vector<momentum::Marker>> markerData,
+    const CalibrationConfig& config,
+    momentum::Character& character,
+    momentum::ModelParameters& identity,
+    const std::array<float, 3>& regularizerWeights = {0.0f, 0.0f, 0.0f});
+
+/// Calibrate locator offsets of a character from input identity and marker data.
+///
+/// @param[in] markerData Input marker data.
+/// @param[in] config Solving options.
+/// @param[in] identity Identity parameters of the input character.
+/// @param[in,out] character Character definition. It provides input locators offsets which will get
+/// updated in return. We overwrite the locators in the input character so we don't have to
+/// duplicate the character object inside the function.
+void calibrateLocators(
+    std::span<const std::vector<momentum::Marker>> markerData,
+    const CalibrationConfig& config,
+    const momentum::ModelParameters& identity,
+    momentum::Character& character);
+
+Eigen::MatrixXf refineMotion(
+    std::span<const std::vector<momentum::Marker>> markerData,
+    const Eigen::MatrixXf& motion,
+    const RefineConfig& config,
+    momentum::Character& character);
+
+/// Get the error of the locator motion vs the markers
+///
+/// @param[in] markerData Input marker data.
+/// @param[in] motion Motion to compare against.
+/// @param[in] character Character definition
+/// @return average per frame error and max marker error
+std::pair<float, float> getLocatorError(
+    std::span<const std::vector<momentum::Marker>> markerData,
+    const Eigen::MatrixXf& motion,
+    momentum::Character& character);
+
+} // namespace momentum

include/momentum/marker_tracking/process_markers.h

@@ -0,0 +1,58 @@
+/*
+ * 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/marker_tracking/app_utils.h>
+#include <momentum/marker_tracking/marker_tracker.h>
+
+#include <string>
+
+namespace momentum {
+
+/// Processes marker data for a character model.
+///
+/// It can calibrate the model and locators based on the calibrationConfig, and track the motion of
+/// the markers.
+///
+/// @param[in,out] character The input character definition with locators. It also holds the output
+/// locators if locators are to be calibrated from the calibrationConfig.
+/// @param[in,out] identity The input identity used for tracking. It also holds the solved identify
+/// if identity is to be calibrated from the calibrationConfig.
+/// @param[in] markerData The per-frame position targets to be tracked.
+/// @param[in] trackingConfig The config for per-frame tracking after the correct identity and
+/// locators are solved for (or from input).
+/// @param[in] calibrationConfig The config for running calibration if calibrate is set to true.
+/// @param[in] calibrate True to run calibration according to calibrationConfig.
+/// @param[in] firstFrame The first frame to start solving. We pass in the first frame instead of
+/// triming markerData to avoid data copy.
+/// @param[in] maxFrames The maximum number of frames to process starting from firstFrame.
+/// @returns The final motion matrix after tracking.
+Eigen::MatrixXf processMarkers(
+    momentum::Character& character,
+    momentum::ModelParameters& identity,
+    const std::vector<std::vector<momentum::Marker>>& markerData,
+    const TrackingConfig& trackingConfig,
+    const CalibrationConfig& calibrationConfig,
+    bool calibrate = true,
+    size_t firstFrame = 0,
+    size_t maxFrames = 0);
+
+/// Runs marker tracking on an input marker file (e.g. c3d) and writes the output motion (e.g. glb)
+/// to outputFile
+void processMarkerFile(
+    const std::string& inputMarkerFile,
+    const std::string& outputFile,
+    const TrackingConfig& trackingConfig,
+    const CalibrationConfig& calibrationConfig,
+    const ModelOptions& modelOptions,
+    bool calibrate,
+    size_t firstFrame = 0,
+    size_t maxFrames = 0);
+
+} // namespace momentum