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

include/momentum/io/marker/c3d_io.h

@@ -0,0 +1,30 @@
+/*
+ * 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/marker.h>
+#include <momentum/io/marker/coordinate_system.h>
+
+namespace momentum {
+
+/// Loads all the subjects from a C3D file into a vector of MarkerSequences.
+///
+/// The function reads the given C3D file and stores the marker data as a MarkerSequence. The unit
+/// of the input file will be read from the file and converted to the momentum unit (i.e., cm). The
+/// UpVector parameter 'up' is the up-vector convention of the input marker file.
+///
+/// @param[in] filename The C3D file to load marker data from.
+/// @param[in] up (Optional) The up-vector convention of the input marker file (default:
+/// UpVector::Y).
+/// @return std::vector<MarkerSequence> A vector containing the marker sequences from the C3D file.
+[[nodiscard]] std::vector<MarkerSequence> loadC3d(
+    const std::string& filename,
+    UpVector up = UpVector::Y,
+    std::span<const std::string> validMarkerNames = {});
+
+} // namespace momentum

include/momentum/io/marker/conversions.h

@@ -0,0 +1,57 @@
+/*
+ * 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/io/marker/coordinate_system.h>
+#include <momentum/math/types.h>
+
+namespace momentum {
+
+/// @brief This function converts a 3D vector in the mocap marker coordinate system to the Momentum
+/// coordinate system.
+///
+/// The mocap marker coordinate system uses a spatial index with a specified up-axis (default Z),
+/// right-handedness, and units specified in the 'unit' parameter (default millimeters). The
+/// Momentum coordinate system uses a spatial index with Y as the up-axis, right-handedness, and
+/// units in centimeters.
+///
+/// @tparam T The numeric type of the input and output 3D vectors.
+/// @param[in] vec The 3D vector in the mocap marker coordinate system to be converted.
+/// @param[in] up (Optional) The up-axis convention of the input marker coordinate system (default:
+/// UpVector::Z).
+/// @param[in] unit (Optional) The units of measurement used in the input marker coordinate system
+/// (default: Unit::MM).
+/// @returns A 3D vector in the Momentum coordinate system.
+///
+/// @note This conversion has only been tested for TRC and C3D formats.
+template <typename T>
+[[nodiscard]] Vector3<T>
+toMomentumVector3(const Vector3<T>& vec, UpVector up = UpVector::Z, Unit unit = Unit::MM);
+
+/// @brief This function converts a 3D vector in the mocap marker coordinate system to the Momentum
+/// coordinate system, using a string to specify the unit.
+///
+/// The mocap marker coordinate system uses a spatial index with a specified up-axis (default Z),
+/// right-handedness, and units specified in the 'unitStr' parameter (e.g., "m", "cm", "mm"). The
+/// Momentum coordinate system uses a spatial index with Y as the up-axis, right-handedness, and
+/// units in centimeters.
+///
+/// @tparam T The numeric type of the input and output 3D vectors.
+/// @param[in] vec The 3D vector in the mocap marker coordinate system to be converted.
+/// @param[in] up (Optional) The up-axis convention of the input marker coordinate system (default:
+/// UpVector::Z).
+/// @param[in] unitStr The string representation of the units of measurement used in the input
+/// marker coordinate system.
+/// @returns A 3D vector in the Momentum coordinate system.
+///
+/// @note This conversion has only been tested for TRC and C3D formats.
+template <typename T>
+[[nodiscard]] Vector3<T>
+toMomentumVector3(const Vector3<T>& vec, UpVector up, const std::string& unitStr);
+
+} // namespace momentum

include/momentum/io/marker/coordinate_system.h

@@ -0,0 +1,30 @@
+/*
+ * 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
+
+namespace momentum {
+
+/// This enumeration is used to define the primary up vector directions for various coordinate
+/// systems and orientations in a 3D environment.
+enum class UpVector {
+  X = 0, ///< X-axis up vector
+  Y, ///< Y-axis up vector
+  Z, ///< Z-axis up vector
+  YNeg, ///< Negative Y-axis up vector
+};
+
+/// An enumeration representing the units of measurement used in marker data files.
+enum class Unit {
+  M, ///< Meters
+  DM, ///< Decimeter
+  CM, ///< Centimeters
+  MM, ///< Millimeters
+  Unknown, ///< Unknown unit of measurement
+};
+
+} // namespace momentum

include/momentum/io/marker/marker_io.h

@@ -0,0 +1,56 @@
+/*
+ * 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/marker.h>
+#include <momentum/io/marker/coordinate_system.h>
+
+#include <optional>
+#include <vector>
+
+namespace momentum {
+
+/// Loads all actor sequences from a marker file (c3d, trc, glb) and converts the positions
+/// to the target coordinate system. Default target coordinate system is: (Y-up, right-handed,
+/// centimeter units).
+///
+/// @param[in] filename The marker file to load data from.
+/// @param[in] up (Optional) The up-vector convention of the input marker file (default:
+/// UpVector::Y).
+/// @return std::vector<MarkerSequence> A vector of MarkerSequences containing the marker data from
+/// the file.
+[[nodiscard]] std::vector<MarkerSequence> loadMarkers(
+    const std::string& filename,
+    UpVector up = UpVector::Y,
+    std::span<const std::string> validMarkerNames = {});
+
+/// Loads the main subject's marker data from a marker file (c3d, trc, glb) and converts the
+/// positions to the target coordinate system. Default target coordinate system is: (Y-up,
+/// right-handed, centimeter units). The main subject is determined as the one with the most number
+/// of visible markers in the first frame.
+///
+/// @param[in] filename The marker file to load data from.
+/// @param[in] up (Optional) The up-vector convention of the input marker file (default:
+/// UpVector::Y).
+/// @return std::optional<MarkerSequence> A MarkerSequence containing the main subject's marker
+/// data, or an empty optional if no main subject is found.
+[[nodiscard]] std::optional<MarkerSequence> loadMarkersForMainSubject(
+    const std::string& filename,
+    UpVector up = UpVector::Y,
+    std::span<const std::string> validMarkerNames = {});
+
+/// Finds the "main subject" from a vector of MarkerSequences. The main subject is currently defined
+/// as a named actor with the maximum number of visible markers in the sequence.
+///
+/// @param[in] markerSequences A vector of MarkerSequences to search for the main subject.
+/// @return int The main subject's index in the input vector. If no main subject found, -1 is
+/// returned.
+/// @note This function is exposed mainly for unit tests.
+[[nodiscard]] int findMainSubjectIndex(gsl::span<const MarkerSequence> markerSequences);
+
+} // namespace momentum

include/momentum/io/marker/trc_io.h

@@ -0,0 +1,27 @@
+/*
+ * 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/marker.h>
+#include <momentum/io/marker/coordinate_system.h>
+
+namespace momentum {
+
+/// Loads marker data from a TRC file into a MarkerSequence.
+///
+/// The function reads the given TRC file and stores the marker data as a MarkerSequence. The unit
+/// of the input file will be read from the file and converted to the momentum unit (i.e., cm). The
+/// UpVector parameter 'up' is the up-vector convention of the input marker file.
+///
+/// @param[in] filename The TRC file to load marker data from.
+/// @param[in] up (Optional) The up-vector convention of the input marker file (default:
+/// UpVector::Y).
+/// @return MarkerSequence A MarkerSequence containing the marker data from the TRC file.
+[[nodiscard]] MarkerSequence loadTrc(const std::string& filename, UpVector up = UpVector::Y);
+
+} // namespace momentum

include/momentum/io/motion/mmo_io.h

@@ -0,0 +1,97 @@
+/*
+ * 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 {
+
+/// Save motion data using character parameter mapping
+///
+/// @param filename Output file path
+/// @param poses Motion poses as span of vectors, each vector represents one frame
+/// @param scale Joint scale parameters
+/// @param character Character definition for parameter mapping
+void saveMmo(
+    const std::string& filename,
+    gsl::span<const VectorXf> poses,
+    const VectorXf& scale,
+    const Character& character);
+
+/// Save motion data with optional additional parameters
+///
+/// @param filename Output file path
+/// @param poses Motion poses matrix (parameters x frames)
+/// @param scale Joint scale parameters
+/// @param character Character definition for parameter mapping
+/// @param additionalParameters Extra parameters to store alongside poses
+/// @param additionalParameterNames Names for additional parameters
+void saveMmo(
+    const std::string& filename,
+    const MatrixXf& poses,
+    const VectorXf& scale,
+    const Character& character,
+    const MatrixXf& additionalParameters = MatrixXf(),
+    gsl::span<const std::string> additionalParameterNames = std::vector<std::string>());
+
+/// Save motion data with explicit parameter and joint names
+///
+/// @param filename Output file path
+/// @param poses Motion poses matrix (parameters x frames)
+/// @param scale Joint scale parameters
+/// @param parameterNames Names of motion parameters
+/// @param jointNames Names of skeleton joints
+void saveMmo(
+    const std::string& filename,
+    const MatrixXf& poses,
+    const VectorXf& scale,
+    gsl::span<const std::string> parameterNames,
+    gsl::span<const std::string> jointNames);
+
+/// Load motion data from file
+///
+/// @param filename Input file path
+/// @return Tuple of (poses, scale, parameter names, joint names)
+std::tuple<MatrixXf, VectorXf, std::vector<std::string>, std::vector<std::string>> loadMmo(
+    const std::string& filename);
+
+/// Load motion data and map to character parameter space
+///
+/// @param filename Input file path
+/// @param character Target character for parameter mapping
+/// @return Tuple of (mapped poses, mapped scale)
+std::tuple<MatrixXf, VectorXf> loadMmo(const std::string& filename, const Character& character);
+
+/// Extract auxiliary data from motion parameters
+///
+/// Auxiliary parameters are identified by names wrapped with double underscores (e.g., "__param__")
+///
+/// @param poses Motion poses matrix
+/// @param parameterNames Names of all parameters
+/// @return Tuple of (auxiliary data matrix, auxiliary parameter names without underscores)
+std::tuple<MatrixXf, std::vector<std::string>> getAuxiliaryDataFromMotion(
+    const MatrixXf& poses,
+    gsl::span<const std::string> parameterNames);
+
+/// Map motion data from one parameter space to character parameter space
+///
+/// @param poses Source motion poses
+/// @param offsets Source joint offsets
+/// @param parameterNames Source parameter names
+/// @param jointNames Source joint names
+/// @param character Target character definition
+/// @return Tuple of (mapped poses, mapped offsets)
+std::tuple<MatrixXf, VectorXf> mapMotionToCharacter(
+    const MatrixXf& poses,
+    const VectorXf& offsets,
+    gsl::span<const std::string> parameterNames,
+    gsl::span<const std::string> jointNames,
+    const Character& character);
+
+} // namespace momentum

include/momentum/io/shape/blend_shape_io.h

@@ -0,0 +1,70 @@
+/*
+ * 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/blend_shape.h>
+#include <momentum/common/filesystem.h>
+
+#include <iosfwd>
+
+namespace momentum {
+
+/// Loads blend shape vectors from a file without base shape.
+///
+/// @param filename Path to the blend shape base data file
+/// @param expectedShapes Limits number of shape vectors loaded if > 0, otherwise loads all
+/// @param expectedVertices Limits number of vertices loaded if > 0, otherwise loads all
+/// @return BlendShapeBase object with loaded shape vectors
+BlendShapeBase loadBlendShapeBase(
+    const filesystem::path& filename,
+    int expectedShapes = -1,
+    int expectedVertices = -1);
+
+/// Loads blend shape vectors from a stream without base shape.
+///
+/// @param data Input stream containing blend shape base data
+/// @param expectedShapes Limits number of shape vectors loaded if > 0, otherwise loads all
+/// @param expectedVertices Limits number of vertices loaded if > 0, otherwise loads all
+/// @return BlendShapeBase object with loaded shape vectors
+BlendShapeBase
+loadBlendShapeBase(std::istream& data, int expectedShapes = -1, int expectedVertices = -1);
+
+/// Loads a blend shape from a file, including base shape and shape vectors.
+///
+/// @param filename Path to the blend shape data file
+/// @param expectedShapes Limits number of shape vectors loaded if > 0, otherwise loads all
+/// @param expectedVertices Limits number of vertices loaded if > 0, otherwise loads all
+/// @return BlendShape object with loaded data
+///
+/// @note Only supports local files. For non-local paths, use the stream version.
+BlendShape loadBlendShape(
+    const filesystem::path& filename,
+    int expectedShapes = -1,
+    int expectedVertices = -1);
+
+/// Loads a blend shape from a stream, including base shape and shape vectors.
+///
+/// @param data Input stream containing blend shape data
+/// @param expectedShapes Limits number of shape vectors loaded if > 0, otherwise loads all
+/// @param expectedVertices Limits number of vertices loaded if > 0, otherwise loads all
+/// @return BlendShape object with loaded data
+BlendShape loadBlendShape(std::istream& data, int expectedShapes = -1, int expectedVertices = -1);
+
+/// Saves a blend shape to a file.
+///
+/// @param filename Output file path for the blend shape data
+/// @param blendShape BlendShape object to save
+void saveBlendShape(const filesystem::path& filename, const BlendShape& blendShape);
+
+/// Saves a blend shape to a stream.
+///
+/// @param os Output stream to write blend shape data
+/// @param blendShape BlendShape object to save
+void saveBlendShape(std::ostream& os, const BlendShape& blendShape);
+
+} // namespace momentum

include/momentum/io/shape/pose_shape_io.h

@@ -0,0 +1,21 @@
+/*
+ * 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/pose_shape.h>
+
+namespace momentum {
+
+/// Loads pose shape data from a binary file.
+///
+/// @param filename Path to the pose shape data file
+/// @param character Character containing skeleton and mesh for validation and joint mapping
+/// @return PoseShape with loaded data, or empty PoseShape if file cannot be opened
+PoseShape loadPoseShape(const std::string& filename, const Character& character);
+
+} // namespace momentum

include/momentum/io/skeleton/locator_io.h

@@ -0,0 +1,41 @@
+/*
+ * 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/common/filesystem.h>
+#include <gsl/span>
+
+namespace momentum {
+
+enum class LocatorSpace {
+  Local = 0, // local offset in the joint space; useful for transferring locators from one model to
+             // another.
+  Global = 1, // global offset in the character's space; useful for authoring in Maya/Blender
+              // without parenting the locators.
+};
+
+LocatorList loadLocators(
+    const filesystem::path& filename,
+    const Skeleton& skeleton,
+    const ParameterTransform& parameterTransform);
+
+LocatorList loadLocatorsFromBuffer(
+    gsl::span<const std::byte> rawData,
+    const Skeleton& skeleton,
+    const ParameterTransform& parameterTransform);
+
+void saveLocators(
+    const filesystem::path& filename,
+    const LocatorList& locators,
+    const Skeleton& skeleton,
+    LocatorSpace space = LocatorSpace::Global);
+
+} // namespace momentum

include/momentum/io/skeleton/mppca_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/math/fwd.h>
+
+#include <gsl/span>
+
+#include <istream>
+
+namespace momentum {
+
+std::shared_ptr<const Mppca> loadMppca(std::istream& inputStream);
+
+std::shared_ptr<const Mppca> loadMppca(const std::string& name);
+
+std::shared_ptr<const Mppca> loadMppca(gsl::span<const unsigned char> posePriorDataRaw);
+
+void saveMppca(const Mppca& mppca, const std::string& name);
+
+} // namespace momentum

include/momentum/io/skeleton/parameter_limits_io.h

@@ -0,0 +1,25 @@
+/*
+ * 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 {
+
+ParameterLimits parseParameterLimits(
+    const std::string& data,
+    const Skeleton& skeleton,
+    const ParameterTransform& parameterTransform);
+
+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,41 @@
+/*
+ * 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 <gsl/span>
+
+#include <string>
+#include <unordered_map>
+
+namespace momentum {
+
+std::unordered_map<std::string, std::string> loadMomentumModel(const filesystem::path& filename);
+
+std::unordered_map<std::string, std::string> loadMomentumModelFromBuffer(
+    gsl::span<const std::byte> buffer);
+
+ParameterTransform parseParameterTransform(const std::string& data, const Skeleton& skeleton);
+
+ParameterSets parseParameterSets(const std::string& data, const ParameterTransform& pt);
+
+PoseConstraints parsePoseConstraints(const std::string& data, const ParameterTransform& pt);
+
+// load transform definition from file
+std::tuple<ParameterTransform, ParameterLimits> loadModelDefinition(
+    const filesystem::path& filename,
+    const Skeleton& skeleton);
+
+std::tuple<ParameterTransform, ParameterLimits> loadModelDefinition(
+    gsl::span<const std::byte> rawData,
+    const Skeleton& skeleton);
+
+} // 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/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 <gsl/span>
+
+namespace momentum {
+
+/// Loads a character from a URDF file.
+template <typename T = float>
+[[nodiscard]] 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(gsl::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 <gsl/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(gsl::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