ViewDesignEngine/include/vde/brep/brep_heal.h

#pragma once
/**
 * @file brep_heal.h
 * @brief B-Rep 拓扑修复
 *
 * 对 BrepModel 执行拓扑修复操作，处理导入 STEP/IGES 文件时常见的
 * 几何缺陷：重复顶点、冗余边、间隙、退化面和方向不一致。
 *
 * ## 修复流水线（新版）
 *
 * 1. heal_gaps         — BFS 合并距离<tolerance 的顶点（替代旧版 merge + close_gaps）
 * 2. heal_slivers      — 检测并移除面积<sliver_area 的退化面
 * 3. heal_orientation  — 统一面方向（外法线朝外），用欧拉示性数验证
 * 4. heal_topology     — 一站式调用 1→2→3
 * 5. heal_step_import  — STEP 导入后自动修复
 *
 * ## 旧版兼容函数
 *
 * - heal_merge_vertices  — 保留以兼容旧代码，内部委托给 heal_gaps
 * - heal_merge_edges     — 保留以兼容旧代码
 * - heal_close_gaps      — 保留以兼容旧代码，内部委托给 heal_gaps
 *
 * @ingroup brep
 */
#include "vde/brep/brep.h"
#include "vde/brep/brep_validate.h"

namespace vde::brep {

// ═══════════════════════════════════════════════════════════
//  新版修复 API
// ═══════════════════════════════════════════════════════════

/**
 * @brief 使用 BFS 合并距离小于 tolerance 的顶点
 *
 * 构建顶点邻接图：两点距离 < tolerance 则视为连通。
 * 对每个连通分量，以第一个顶点为代表合并该分量中所有顶点。
 * 更新所有边的顶点引用。
 *
 * @param body 待修复的 B-Rep 模型（原地修改）
 * @param tolerance 顶点合并距离容差，默认 1e-6
 * @return 合并的顶点对数（即减少的顶点数）
 */
int heal_gaps(BrepModel& body, double tolerance = 1e-6);

/**
 * @brief 检测并移除退化面（sliver faces）
 *
 * 遍历所有面，计算面的近似面积。面积小于 sliver_area
 * （默认取自 ToleranceConfig::global().sliver_area = 1e-12）的面被移除。
 * 更新壳的面引用并压缩面数组。
 *
 * @param body 待修复的 B-Rep 模型（原地修改）
 * @return 移除的退化面数量
 */
int heal_slivers(BrepModel& body);

/**
 * @brief 统一面方向（全部向外），用欧拉示性数验证
 *
 * 通过符号体积计算确保所有面法向量朝外。
 * 对于方向朝内的面，翻转其 reversed 标志。
 * 修复后计算欧拉示性数 V - E + F（预期 ≈ 2 对封闭流形），
 * 偏差较大时记录但不回滚。
 *
 * @param body 待修复的 B-Rep 模型（原地修改）
 * @return 翻转的面数
 */
int heal_orientation(BrepModel& body);

/**
 * @brief 一站式拓扑修复流水线
 *
 * 按推荐顺序执行：
 * 1. heal_gaps （BFS 顶点合并 + 间隙闭合）
 * 2. heal_slivers （移除退化面）
 * 3. heal_orientation （统一面方向，欧拉验证）
 *
 * 最后调用 validate() 检查修复结果。
 *
 * @param body 待修复的 B-Rep 模型（原地修改）
 * @param tolerance 顶点合并距离容差，默认 1e-6
 * @return true 如果修复后模型通过验证
 */
bool heal_topology(BrepModel& body, double tolerance = 1e-6);

/**
 * @brief STEP 导入后自动修复
 *
 * 使用 auto_tolerance() 根据模型实际尺寸计算自适应容差，
 * 然后执行 heal_topology()。
 *
 * @param body 从 STEP 导入的 B-Rep 模型（原地修改）
 * @return 修复结果
 *   - >0: 修复成功，返回修复项总数
 *   - 0: 无需修复
 *   - <0: 修复失败
 */
int heal_step_import(BrepModel& body);

// ═══════════════════════════════════════════════════════════
//  旧版兼容函数（委托给新版实现）
// ═══════════════════════════════════════════════════════════

/**
 * @brief 合并重合顶点（旧版兼容）
 * @deprecated 请使用 heal_gaps()
 */
int heal_merge_vertices(BrepModel& body, double tolerance = 1e-6);

/**
 * @brief 合并重合边（旧版兼容）
 */
int heal_merge_edges(BrepModel& body, double tolerance = 1e-6);

/**
 * @brief 闭合面之间的微小间隙（旧版兼容）
 * @deprecated 请使用 heal_gaps()
 */
int heal_close_gaps(BrepModel& body, double max_gap = 1e-4);

} // namespace vde::brep