ViewDesignEngine/include/vde/mesh/mesh_parameterize.h

#pragma once
#include "vde/mesh/halfedge_mesh.h"
#include "vde/core/point.h"
#include <vector>

namespace vde::mesh {
using core::Point2D;
using core::Point3D;
using core::Vector3D;

/**
 * @brief Tutte 参数化（调和参数化）
 *
 * 将边界顶点固定映射到单位圆上，内部顶点通过求解 Laplace 方程
 * Δu = 0, Δv = 0 得到 UV 坐标。这是最经典、最稳定的网格参数化方法。
 *
 * 算法：
 * 1. 检测网格边界环
 * 2. 将边界顶点按弧长比例映射到单位圆上
 * 3. 对每个内部顶点求解均匀 Laplace（权重 w_ij = 1）：
 *    v_i = Σ_j v_j / deg(i)
 * 4. 构造稀疏线性系统 LU 求解
 *
 * 优点：极稳定，保证无翻转（对凸边界网格）
 * 缺点：边界固定，内部可能扭曲（非共形）
 *
 * @param mesh 输入三角网格（需含边界）
 * @return 每顶点 UV 坐标（Point2D），顺序与 mesh 顶点一致
 *
 * @note 网格必须有边界（开网格）；闭曲面需先切割为拓扑圆盘
 * @code{.cpp}
 * auto uv = tutte_parameterization(mesh);
 * // uv[i] 为顶点 i 的 (u,v) 坐标，范围大致在 [-1,1]²
 * @endcode
 * @see lscm_parameterization
 * @ingroup mesh
 */
[[nodiscard]] std::vector<Point2D> tutte_parameterization(const HalfedgeMesh& mesh);

/**
 * @brief LSCM（Least Squares Conformal Maps）参数化
 *
 * 基于 Lévy et al. 2002 的最小二乘共形映射。通过最小化共形能量
 * 使参数化尽可能保角（角度畸变小），同时允许边界自由。
 *
 * 与 Tutte 的区别：
 * - 无需固定边界 → 边界自然展开，畸变更小
 * - 需要固定至少 2 个顶点消除刚体自由度（内部处理）
 * - 共形性更好，适合纹理映射
 * - 不保证无翻转（局部极小可能翻转）
 *
 * 能量函数：
 *   E(u,v) = Σ_T || ∇(u+iv) ||² · A_T
 *   对每个三角形 T 最小化梯度扰动平方和
 *
 * @param mesh 输入三角网格
 * @return 每顶点 UV 坐标（Point2D）
 *
 * @note 简化实现，不包含完整 Lévy 论文中所有的退化处理
 * @code{.cpp}
 * auto uv = lscm_parameterization(mesh);
 * // 适合纹理 mapping
 * @endcode
 * @see tutte_parameterization
 * @ingroup mesh
 */
[[nodiscard]] std::vector<Point2D> lscm_parameterization(const HalfedgeMesh& mesh);

}  // namespace vde::mesh