ViewDesignEngine/include/vde/core/convex_hull.h

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

namespace vde::core {

/**
 * @brief 二维凸包计算（Graham Scan 算法）
 *
 * 使用 Graham 扫描算法计算点集的凸包，时间复杂度 O(n log n)。
 * 以极角排序点为预处理，然后用栈维护凸包边界。
 *
 * @param points 输入点集（至少 3 个不共线点）
 * @return 凸包顶点序列（逆时针排列），不含共线的中间点
 *
 * @note 自动过滤共线点，返回严格的凸包顶点
 * @note 若所有点共线，返回两个端点
 *
 * @code{.cpp}
 * std::vector<Point2D> pts = {{0,0}, {1,0}, {1,1}, {0,1}, {0.5,0.5}};
 * auto hull = convex_hull_2d(pts);
 * // hull = [(0,0), (1,0), (1,1), (0,1)]
 * @endcode
 *
 * @see convex_hull_3d, Polygon2D::convex_hull_2d
 * @ingroup core
 */
std::vector<Point2D> convex_hull_2d(const std::vector<Point2D>& points);

/**
 * @brief 三维凸包计算（QuickHull 算法）
 *
 * 使用 QuickHull 算法计算三维点集的凸包。
 * 先构造初始四面体，然后递归地将外部点添加到凸包上。
 * 平均复杂度 O(n log n)，最坏情况 O(n²)。
 *
 * @param points 输入点集（至少 4 个不共面点）
 * @return 凸包三角形列表，每个三角形三顶点按逆时针排列（从外部观察）
 *
 * @note 返回的三角形法线方向朝外
 * @note 共面/退化点被自动丢弃
 *
 * @code{.cpp}
 * std::vector<Point3D> pts = 3D 点云;
 * auto hull_tris = convex_hull_3d(pts);
 * for (auto& tri : hull_tris) {
 *     // tri = {p0, p1, p2} — CCW when viewed from outside
 * }
 * @endcode
 *
 * @see convex_hull_2d
 * @ingroup core
 */
std::vector<std::array<Point3D, 3>> convex_hull_3d(const std::vector<Point3D>& points);

}  // namespace vde::core