ViewDesignEngine/include/vde/core/transform.h

#pragma once
#include "vde/core/point.h"
#include <Eigen/Geometry>

namespace vde::core {

/**
 * @brief 三维仿射变换类型
 *
 * 基于 Eigen::Transform，支持平移、旋转、缩放和它们的组合。
 * 使用 4×4 齐次矩阵表示。
 *
 * @ingroup core
 */
using Transform3D = Eigen::Transform<double, 3, Eigen::Affine>;

/**
 * @brief 创建平移变换
 *
 * @param v 平移向量
 * @return 平移变换矩阵
 *
 * @code{.cpp}
 * auto T = translate(Vector3D(1, 2, 3));
 * Point3D p2 = T * Point3D(0,0,0); // p2 == (1,2,3)
 * @endcode
 *
 * @ingroup core
 */
inline Transform3D translate(const Vector3D& v) {
    return Transform3D(Eigen::Translation<double, 3>(v));
}

/**
 * @brief 创建平移变换（分量形式）
 *
 * @param x X 方向位移
 * @param y Y 方向位移
 * @param z Z 方向位移
 * @return 平移变换矩阵
 *
 * @ingroup core
 */
inline Transform3D translate(double x, double y, double z) {
    return translate(Vector3D(x, y, z));
}

/**
 * @brief 创建旋转变换（轴-角表示）
 *
 * @param axis 旋转轴（自动归一化）
 * @param angle_rad 旋转角度（弧度）
 * @return 旋转变换矩阵
 *
 * @code{.cpp}
 * // 绕 Z 轴旋转 90°
 * auto R = rotate(Vector3D::UnitZ(), M_PI / 2);
 * @endcode
 *
 * @ingroup core
 */
inline Transform3D rotate(const Vector3D& axis, double angle_rad) {
    return Transform3D(Eigen::AngleAxis<double>(angle_rad, axis.normalized()));
}

/**
 * @brief 绕 X 轴旋转
 *
 * @param rad 旋转角度（弧度）
 * @return 旋转变换矩阵
 *
 * @ingroup core
 */
inline Transform3D rotate_x(double rad) { return rotate(Vector3D::UnitX(), rad); }

/**
 * @brief 绕 Y 轴旋转
 *
 * @param rad 旋转角度（弧度）
 * @return 旋转变换矩阵
 *
 * @ingroup core
 */
inline Transform3D rotate_y(double rad) { return rotate(Vector3D::UnitY(), rad); }

/**
 * @brief 绕 Z 轴旋转
 *
 * @param rad 旋转角度（弧度）
 * @return 旋转变换矩阵
 *
 * @ingroup core
 */
inline Transform3D rotate_z(double rad) { return rotate(Vector3D::UnitZ(), rad); }

/**
 * @brief 创建非均匀缩放变换
 *
 * @param sx X 方向缩放因子
 * @param sy Y 方向缩放因子
 * @param sz Z 方向缩放因子
 * @return 缩放变换矩阵
 *
 * @note 非均匀缩放可能导致法线方向不准确；使用场景中应考虑法线变换 = (M^{-1})^T
 *
 * @ingroup core
 */
inline Transform3D scale(double sx, double sy, double sz) {
    return Transform3D(Eigen::Scaling(sx, sy, sz));
}

/**
 * @brief 创建均匀缩放变换
 *
 * @param s 各方向统一的缩放因子
 * @return 缩放变换矩阵
 *
 * @ingroup core
 */
inline Transform3D scale(double s) { return scale(s, s, s); }

}  // namespace vde::core