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

include/momentum/io/gltf/gltf_io.h

@@ -0,0 +1,148 @@
+/*
+ * 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/character/types.h>
+#include <momentum/common/filesystem.h>
+#include <momentum/io/gltf/gltf_file_format.h>
+#include <momentum/math/types.h>
+
+#include <fx/gltf.h>
+#include <gsl/span>
+
+#include <tuple>
+#include <vector>
+
+namespace momentum {
+
+struct GltfOptions {
+  bool extensions = true;
+  bool collisions = true;
+  bool locators = true;
+  bool mesh = true;
+  bool blendShapes = true;
+};
+
+Character loadGltfCharacter(const fx::gltf::Document& model);
+
+Character loadGltfCharacter(const filesystem::path& gltfFilename);
+
+Character loadGltfCharacter(gsl::span<const std::byte> byteSpan);
+
+std::tuple<MotionParameters, IdentityParameters, float> loadMotion(
+    const filesystem::path& gltfFilename);
+
+/// Load a glTF character from a local file path.
+///
+/// This function assumes the file format of the given path is glTF without checking the extension,
+/// so please ensure the file is in glTF format.
+///
+/// @param[in] filepath The path to the glTF character file.
+/// @return A tuple containing the loaded Character object, the motion represented in model
+/// parameters, the identity vector represented as joint parameters, and the fps.
+std::tuple<Character, MatrixXf, VectorXf, float> loadCharacterWithMotion(
+    const filesystem::path& gltfFilename);
+
+/// Load a glTF character from a buffer.
+///
+/// @param[in] byteSpan The buffer containing the glTF character data.
+/// @return A tuple containing the loaded Character object, the motion represented in model
+/// parameters, the identity vector represented as joint parameters, and the fps.
+std::tuple<Character, MatrixXf, VectorXf, float> loadCharacterWithMotion(
+    gsl::span<const std::byte> byteSpan);
+
+/// Load a GLTF Character with motion in the form of skeleton states (transform matrices)
+///
+/// Unlike the other loadCharacterWithMotion functions, this function does not require the
+/// file to be saved using momentum's functionality that saves model parameters in a
+/// custom GTLF extension, however the resulting skeleton states may be harder to work with.
+std::tuple<Character, std::vector<SkeletonState>, std::vector<float>>
+loadCharacterWithSkeletonStates(gsl::span<const std::byte> byteSpan);
+
+std::tuple<Character, std::vector<SkeletonState>, std::vector<float>>
+loadCharacterWithSkeletonStates(const filesystem::path& gltfFilename);
+
+/// Maps the loaded motion onto the input character by matching joint names and parameter names.
+///
+/// This function assumes the file format of the given path is glTF without checking the extension,
+/// so please ensure the file is in glTF format.
+///
+/// @param[in] gltfFilename The path to the glTF motion file.
+/// @param[in] character The Character object to map the motion onto.
+/// @return A tuple containing the motion represented in model parameters, the identity vector
+/// represented as joint parameters, and the fps. The model parameters and joint parameters are
+/// mapped to the input character by name matching.
+std::tuple<MatrixXf, VectorXf, float> loadMotionOnCharacter(
+    const filesystem::path& gltfFilename,
+    const Character& character);
+
+/// Buffer version of loadMotionOnCharacter()
+///
+/// @param[in] byteSpan The buffer containing the glTF motion data.
+/// @param[in] character The Character object to map the motion onto.
+/// @return A tuple containing the motion represented in model parameters, the identity vector
+/// represented as joint parameters, and the fps. The model parameters and joint parameters are
+/// mapped to the input character by name matching.
+std::tuple<MatrixXf, VectorXf, float> loadMotionOnCharacter(
+    gsl::span<const std::byte> byteSpan,
+    const Character& character);
+
+/// Loads a MarkerSequence from a file.
+///
+/// @param[in] filename Path to the file containing the MarkerSequence data.
+/// @return A MarkerSequence object containing motion capture marker data.
+MarkerSequence loadMarkerSequence(const filesystem::path& filename);
+
+fx::gltf::Document makeCharacterDocument(
+    const Character& character,
+    float fps = 120.0f,
+    const MotionParameters& motion = {},
+    const IdentityParameters& offsets = {},
+    const std::vector<std::vector<Marker>>& markerSequence = {},
+    bool embedResource = true,
+    const GltfOptions& options = GltfOptions());
+
+/// Saves character motion to a glb file.
+///
+/// @param[in] motion The model parameters representing the motion of the character (numModelParams,
+/// numFrames)
+/// @param[in] offsets Offset values per joint capturing the skeleton bone lengths using translation
+/// and scale offset (7*numJoints, 1)
+void saveCharacter(
+    const filesystem::path& filename,
+    const Character& Character,
+    float fps = 120.0f,
+    const MotionParameters& motion = {},
+    const IdentityParameters& offsets = {},
+    const std::vector<std::vector<Marker>>& markerSequence = {},
+    GltfFileFormat fileFormat = GltfFileFormat::Extension,
+    const GltfOptions& options = GltfOptions());
+
+/// Saves character skeleton states to a glb file.
+///
+/// @param[in] skeletonStates The skeleton states for each frame of the motion sequence (numFrames,
+/// numJoints, 8)
+void saveCharacter(
+    const filesystem::path& filename,
+    const Character& Character,
+    float fps,
+    gsl::span<const SkeletonState> skeletonStates,
+    const std::vector<std::vector<Marker>>& markerSequence = {},
+    GltfFileFormat fileFormat = GltfFileFormat::Extension,
+    const GltfOptions& options = GltfOptions());
+
+std::vector<std::byte> saveCharacterToBytes(
+    const Character& character,
+    float fps = 120.0f,
+    const MotionParameters& motion = {},
+    const IdentityParameters& offsets = {},
+    const std::vector<std::vector<Marker>>& markerSequence = {},
+    const GltfOptions& options = GltfOptions());
+
+} // namespace momentum

include/momentum/io/gltf/utils/accessor_utils.h

@@ -0,0 +1,299 @@
+/*
+ * 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/common/exception.h"
+
+#include <fx/gltf.h>
+#include <gsl/span_ext>
+
+namespace momentum {
+
+static inline int32_t getComponentSize(const fx::gltf::Accessor::ComponentType& componentType) {
+  switch (componentType) {
+    case fx::gltf::Accessor::ComponentType::Byte:
+    case fx::gltf::Accessor::ComponentType::UnsignedByte:
+      return 1;
+    case fx::gltf::Accessor::ComponentType::Short:
+    case fx::gltf::Accessor::ComponentType::UnsignedShort:
+      return 2;
+    // case fx::gltf::Accessor::ComponentType::Int:
+    case fx::gltf::Accessor::ComponentType::UnsignedInt:
+    case fx::gltf::Accessor::ComponentType::Float:
+      return 4;
+    default:
+      return -1;
+  }
+}
+
+static inline int32_t getTypeSize(const fx::gltf::Accessor::Type& ty) {
+  switch (ty) {
+    case fx::gltf::Accessor::Type::Scalar:
+      return 1;
+    case fx::gltf::Accessor::Type::Vec2:
+      return 2;
+    case fx::gltf::Accessor::Type::Vec3:
+      return 3;
+    case fx::gltf::Accessor::Type::Vec4:
+    case fx::gltf::Accessor::Type::Mat2:
+      return 4;
+    case fx::gltf::Accessor::Type::Mat3:
+      return 9;
+    case fx::gltf::Accessor::Type::Mat4:
+      return 16;
+    default:
+      return -1;
+  }
+}
+
+template <typename T>
+std::vector<T> copyAccessorBuffer(const fx::gltf::Document& model, int32_t id) {
+  const auto& accessor = model.accessors[id];
+
+  const auto tsize = getTypeSize(accessor.type);
+  const auto csize = getComponentSize(accessor.componentType);
+  const auto elsize = tsize * csize;
+
+  if (elsize != sizeof(T)) {
+    MT_LOGW(
+        "[{}] Accessor type mismatch. Expect to read {} bytes, but got type of {} bytes with {} components",
+        __func__,
+        sizeof(T),
+        csize,
+        tsize);
+    return {};
+  }
+
+  const auto& view = model.bufferViews[accessor.bufferView];
+  const auto stride = view.byteStride == 0 ? elsize : view.byteStride;
+
+  const auto& buf = model.buffers[view.buffer];
+  auto bytes = gsl::as_bytes(gsl::make_span(buf.data));
+  bytes = bytes.subspan(view.byteOffset, view.byteLength);
+  bytes = bytes.subspan(accessor.byteOffset);
+
+  std::vector<T> r(accessor.count);
+  for (size_t i = 0; i < accessor.count; i++) {
+    std::memcpy(&r[i], &bytes[i * stride], elsize);
+  }
+
+  return r;
+}
+
+template <typename T>
+std::vector<T> copyAlignedAccessorBuffer(const fx::gltf::Document& model, int32_t id) {
+  const auto& accessor = model.accessors[id];
+  if (accessor.count == 0) {
+    MT_LOGW("Accessor count zero.");
+    return {};
+  }
+
+  const auto tsize = getTypeSize(accessor.type);
+  const auto csize = getComponentSize(accessor.componentType);
+  const auto elsize = tsize * csize;
+
+  if (elsize != sizeof(T)) {
+    MT_LOGW(
+        "[{}] Accessor type mismatch. Expect to read {} bytes, but got type of {} bytes with {} components",
+        __func__,
+        sizeof(T),
+        csize,
+        tsize);
+    return {};
+  }
+
+  const auto& view = model.bufferViews[accessor.bufferView];
+  const auto stride = view.byteStride == 0 ? elsize : view.byteStride;
+
+  const auto& buf = model.buffers[view.buffer];
+  auto bytes = gsl::as_bytes(gsl::make_span(buf.data));
+  bytes = bytes.subspan(view.byteOffset, view.byteLength);
+  bytes = bytes.subspan(accessor.byteOffset);
+
+  std::vector<T> r(accessor.count);
+  for (size_t i = 0; i < accessor.count; i++) {
+    std::memcpy(&r[i], &bytes[i * stride], elsize);
+  }
+
+  return r;
+}
+
+// template to set accessor
+template <typename T>
+void setAccessorType(fx::gltf::Accessor& /* accessor */) {
+  MT_THROW("Unsupported data type {}", typeid(T).name());
+}
+
+// create accessor buffer
+template <typename T>
+int32_t createAccessorBuffer(
+    fx::gltf::Document& model,
+    gsl::span<T> data,
+    const bool align = false,
+    const bool normalized = false) {
+  // gltf 2.0 allows multiple buffers, but only the first buffer will be stored in
+  // the binary file, all other ones need to be external files. Because of this we will
+  // only ever store data in the first buffer
+
+  // check if we have a buffer
+  if (model.buffers.empty()) {
+    model.buffers.resize(1);
+  }
+
+  // create buffer for data
+  const size_t bufferIdx = 0;
+  auto& buffer = model.buffers.front();
+
+  // copy data from input buffer to output buffer
+  const size_t bufferDataStart = buffer.data.size();
+  const auto elementSize = sizeof(T);
+  auto alignedElementSize = elementSize;
+  auto dataSize = data.size() * alignedElementSize;
+
+  // check for necessary alignment
+  if (align && alignedElementSize % 4 != 0) {
+    // element is not aligned, need to get bigger element size
+    alignedElementSize = ((elementSize / 4) + 1) * 4;
+    dataSize = data.size() * alignedElementSize;
+    buffer.data.resize(bufferDataStart + dataSize);
+    // need to go over each element one by one to copy
+    for (size_t e = 0; e < data.size(); e++) {
+      std::memcpy(&buffer.data[bufferDataStart + alignedElementSize * e], &data[e], elementSize);
+    }
+    buffer.byteLength = buffer.data.size();
+  } else {
+    // no alignment needed or already aligned, just copy data in
+    buffer.data.resize(bufferDataStart + dataSize);
+    std::memcpy(&buffer.data[bufferDataStart], data.data(), dataSize);
+    buffer.byteLength = buffer.data.size();
+  }
+
+  // create bufferview
+  const size_t bufferViewIdx = model.bufferViews.size();
+  model.bufferViews.emplace_back();
+  auto& bufferView = model.bufferViews.back();
+
+  bufferView.buffer = bufferIdx;
+  bufferView.byteLength = dataSize;
+  bufferView.byteOffset = bufferDataStart;
+  if (align && elementSize % 4 != 0) {
+    bufferView.byteStride = alignedElementSize;
+  } else {
+    bufferView.byteStride = 0;
+  }
+
+  // create accessor
+  const size_t accessorIdx = model.accessors.size();
+  model.accessors.emplace_back();
+  auto& accessor = model.accessors.back();
+
+  // set component type and accessor size depending on the type
+  setAccessorType<T>(accessor);
+  accessor.bufferView = bufferViewIdx;
+  accessor.byteOffset = 0;
+  accessor.count = data.size();
+  accessor.normalized = normalized;
+
+  return accessorIdx;
+}
+
+template <>
+inline void setAccessorType<const int32_t>(fx::gltf::Accessor& accessor) {
+  accessor.componentType = fx::gltf::Accessor::ComponentType::UnsignedInt;
+  accessor.type = fx::gltf::Accessor::Type::Scalar;
+}
+
+template <>
+inline void setAccessorType<const float>(fx::gltf::Accessor& accessor) {
+  accessor.componentType = fx::gltf::Accessor::ComponentType::Float;
+  accessor.type = fx::gltf::Accessor::Type::Scalar;
+}
+
+template <>
+inline void setAccessorType<const Vector2f>(fx::gltf::Accessor& accessor) {
+  accessor.componentType = fx::gltf::Accessor::ComponentType::Float;
+  accessor.type = fx::gltf::Accessor::Type::Vec2;
+}
+
+template <>
+inline void setAccessorType<const Vector3f>(fx::gltf::Accessor& accessor) {
+  accessor.componentType = fx::gltf::Accessor::ComponentType::Float;
+  accessor.type = fx::gltf::Accessor::Type::Vec3;
+}
+
+template <>
+inline void setAccessorType<const Vector4f>(fx::gltf::Accessor& accessor) {
+  accessor.componentType = fx::gltf::Accessor::ComponentType::Float;
+  accessor.type = fx::gltf::Accessor::Type::Vec4;
+}
+
+template <>
+inline void setAccessorType<const Vector3b>(fx::gltf::Accessor& accessor) {
+  accessor.componentType = fx::gltf::Accessor::ComponentType::UnsignedByte;
+  accessor.type = fx::gltf::Accessor::Type::Vec3;
+}
+
+template <>
+inline void setAccessorType<const Vector3i>(fx::gltf::Accessor& accessor) {
+  accessor.componentType = fx::gltf::Accessor::ComponentType::UnsignedInt;
+  accessor.type = fx::gltf::Accessor::Type::Vec3;
+}
+
+template <>
+inline void setAccessorType<const Vector4s>(fx::gltf::Accessor& accessor) {
+  accessor.componentType = fx::gltf::Accessor::ComponentType::UnsignedShort;
+  accessor.type = fx::gltf::Accessor::Type::Vec4;
+}
+
+template <>
+inline void setAccessorType<const Matrix4f>(fx::gltf::Accessor& accessor) {
+  accessor.componentType = fx::gltf::Accessor::ComponentType::Float;
+  accessor.type = fx::gltf::Accessor::Type::Mat4;
+}
+
+// add animation
+template <typename T>
+int32_t createSampler(
+    fx::gltf::Document& model,
+    fx::gltf::Animation& anim,
+    gsl::span<T> data,
+    const gsl::span<float>& timestamps) {
+  MT_CHECK(
+      data.size() == timestamps.size(), "data: {}, timestmaps: {}", data.size(), timestamps.size());
+
+  // create new sampler
+  const int32_t index = anim.samplers.size();
+  anim.samplers.emplace_back();
+  auto& sampler = anim.samplers.back();
+  sampler.interpolation = fx::gltf::Animation::Sampler::Type::Step;
+  sampler.input = createAccessorBuffer(model, timestamps);
+  sampler.output = createAccessorBuffer(model, data);
+
+  // return sampler index
+  return index;
+}
+
+template <typename T>
+int32_t createSampler(
+    fx::gltf::Document& model,
+    fx::gltf::Animation& anim,
+    gsl::span<T> data,
+    const int32_t timestampAccessor) {
+  // create new sampler
+  const int32_t index = anim.samplers.size();
+  anim.samplers.emplace_back();
+  auto& sampler = anim.samplers.back();
+  sampler.interpolation = fx::gltf::Animation::Sampler::Type::Step;
+  sampler.input = timestampAccessor;
+  sampler.output = createAccessorBuffer(model, data);
+
+  // return sampler index
+  return index;
+}
+
+} // namespace momentum

include/momentum/io/gltf/utils/coordinate_utils.h

@@ -0,0 +1,60 @@
+/*
+ * 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/constants.h>
+#include <momentum/math/types.h>
+
+namespace momentum {
+
+// Utility functions to convert gltf coordinate system to momentum coordinate system.
+// #TODO: load coordinates by setting up CoordinateSystems so we don't need to worry about
+// conversion.
+[[nodiscard]] inline Vector3f toMomentumVec3f(const std::array<float, 3>& vec) noexcept {
+  return Vector3f(vec[0], vec[1], vec[2]) * toCm();
+}
+
+[[nodiscard]] inline Vector3f fromMomentumVec3f(const Vector3f& vec) noexcept {
+  return vec * toM();
+}
+
+[[nodiscard]] inline Quaternionf toMomentumQuaternionf(
+    const std::array<float, 4>& gltfQuat) noexcept {
+  return {gltfQuat[3], gltfQuat[0], gltfQuat[1], gltfQuat[2]};
+}
+
+[[nodiscard]] inline std::array<float, 4> fromMomentumQuaternionf(
+    const Quaternionf& quat) noexcept {
+  return {quat.x(), quat.y(), quat.z(), quat.w()};
+}
+
+inline void toMomentumVec3f(std::vector<Vector3f>& vec) {
+  if (vec.empty()) {
+    return;
+  }
+
+  Map<VectorXf>(&vec[0][0], vec.size() * 3) *= toCm();
+}
+
+inline void fromMomentumVec3f(std::vector<Vector3f>& vec) {
+  if (vec.empty()) {
+    return;
+  }
+
+  Map<VectorXf>(&vec[0][0], vec.size() * 3) *= toM();
+}
+
+inline void fromMomentumVec3f(VectorXf& vec) {
+  if (vec.size() == 0) {
+    return;
+  }
+
+  vec *= toM();
+}
+
+} // namespace momentum

include/momentum/io/gltf/utils/json_utils.h

@@ -0,0 +1,102 @@
+/*
+ * 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 <nlohmann/json.hpp>
+#include <Eigen/Core>
+
+namespace momentum {
+
+// Converts Eigen matrix or vector types to nlohmann::json
+//
+// Note: We intentionally avoid defining nlohmann::adl_serializers for type conversion between Eigen
+// types and nlohmann::json to prevent multiple definitions of the same type in different projects
+// that are compiled in a single translation unit. Instead, we recommend using explicit conversion
+// between the types using the toJson() and fromJson() functions provided in this header.
+template <typename Derived>
+void toJson(const Eigen::MatrixBase<Derived>& mat, nlohmann::json& j) {
+  // always save new format that's numpy compatible
+  // this works for both dynamic and statically sized matrices
+  j = nlohmann::json::array();
+  for (int col_i = 0; col_i < mat.cols(); ++col_i) {
+    nlohmann::json jcol = nlohmann::json::array();
+    for (int row_i = 0; row_i < mat.rows(); ++row_i) {
+      jcol.push_back(mat(row_i, col_i));
+    }
+    j.push_back(jcol);
+  }
+}
+
+// Converts nlohmann::json to Eigen matrix or vector types
+template <typename T>
+T fromJson(const nlohmann::json& j) {
+  T result;
+
+  // partially dynamic matrix
+  if constexpr (T::RowsAtCompileTime == Eigen::Dynamic || T::ColsAtCompileTime == Eigen::Dynamic) {
+    // dynamic size matrix
+    // reads dimensions from the json
+    const auto numCols = j.size();
+    if (numCols > 0) {
+      const auto numRows = j.at(0).size();
+      result.resize(numRows, numCols);
+
+      for (int col_i = 0; col_i < numCols; ++col_i) {
+        std::vector<typename T::Scalar> coef = j[col_i];
+        std::copy(coef.begin(), coef.end(), result.col(col_i).begin());
+      }
+    }
+  }
+  // fixed size matrix or vector
+  else {
+    const int Rows = T::RowsAtCompileTime;
+    const int Cols = T::ColsAtCompileTime;
+
+    // vector stored as array
+    if (Rows == 1 && Cols != -1 && j.size() == Cols &&
+        j[0].type() != nlohmann::json::value_t::array) {
+      std::vector<typename T::Scalar> coef = j;
+      std::copy(coef.begin(), coef.end(), result.row(0).begin());
+    } else if (
+        Cols == 1 && Rows != -1 && j.size() == Rows &&
+        j[0].type() != nlohmann::json::value_t::array) {
+      std::vector<typename T::Scalar> coef = j;
+      std::copy(coef.begin(), coef.end(), result.col(0).begin());
+    }
+    // fixed size matrix
+    else {
+      const auto numCols = j.size();
+      if (numCols > 0) {
+        for (int col_i = 0; col_i < Cols; ++col_i) {
+          std::vector<typename T::Scalar> coef = j[col_i];
+          std::copy(coef.begin(), coef.end(), result.col(col_i).begin());
+        }
+      }
+    }
+  }
+
+  return result;
+}
+
+// to json conversion functions
+void parameterLimitsToJson(const Character& character, nlohmann::json& j);
+void parameterSetsToJson(const Character& character, nlohmann::json& j);
+void poseConstraintsToJson(const Character& character, nlohmann::json& j);
+void parameterTransformToJson(const Character& character, nlohmann::json& j);
+void mppcaToJson(const Character& character, nlohmann::json& j);
+
+// from json conversion functions
+ParameterLimits parameterLimitsFromJson(const Character& character, const nlohmann::json& j);
+ParameterSets parameterSetsFromJson(const Character& character, const nlohmann::json& j);
+PoseConstraints poseConstraintsFromJson(const Character& character, const nlohmann::json& j);
+ParameterTransform parameterTransformFromJson(const Character& character, const nlohmann::json& j);
+
+} // namespace momentum

include/momentum/io/legacy_json/legacy_json_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/collision_geometry.h>
+#include <momentum/character/fwd.h>
+#include <momentum/character/locator.h>
+#include <momentum/math/fwd.h>
+
+#include <nlohmann/json.hpp>
+#include <gsl/span>
+#include <string>
+
+namespace momentum {
+
+/// Loads a Character from a legacy JSON format that was previously used by older Python libraries
+/// (and some other tools).
+///
+/// The legacy JSON format contains:
+/// - "skeleton": FBX skeleton structure with joints, hierarchy, and transforms
+/// - "skinnedmodel": Mesh data with skinning weights
+/// - "collision": Optional collision geometry (tapered capsules)
+///
+/// @param[in] jsonPath Path to the legacy JSON file
+/// @return The loaded Character object
+/// @throws std::runtime_error if the file cannot be loaded or parsed
+[[nodiscard]] Character loadCharacterFromLegacyJson(const std::string& jsonPath);
+
+/// Loads a Character from a legacy JSON buffer.
+///
+/// @param[in] jsonBuffer Buffer containing the legacy JSON data
+/// @return The loaded Character object
+/// @throws std::runtime_error if the buffer cannot be parsed
+[[nodiscard]] Character loadCharacterFromLegacyJsonBuffer(gsl::span<const std::byte> jsonBuffer);
+
+/// Loads a Character from a legacy JSON string.
+///
+/// @param[in] jsonString String containing the legacy JSON data
+/// @return The loaded Character object
+/// @throws std::runtime_error if the string cannot be parsed
+[[nodiscard]] Character loadCharacterFromLegacyJsonString(const std::string& jsonString);
+
+/// Saves a Character to legacy JSON format.
+///
+/// This function converts a momentum::Character back to the legacy JSON format
+/// for compatibility with existing tools and workflows.
+///
+/// @param[in] character The Character to save
+/// @param[in] jsonPath Path where to save the legacy JSON file
+/// @throws std::runtime_error if the file cannot be written
+void saveCharacterToLegacyJson(const Character& character, const std::string& jsonPath);
+
+/// Converts a Character to legacy JSON string.
+///
+/// @param[in] character The Character to convert
+/// @return String containing the legacy JSON representation
+[[nodiscard]] std::string characterToLegacyJsonString(const Character& character);
+
+/// Converts a Character to legacy JSON object.
+///
+/// @param[in] character The Character to convert
+/// @return nlohmann::json object containing the legacy JSON representation
+[[nodiscard]] nlohmann::json characterToLegacyJson(const Character& character);
+
+} // namespace momentum