ViewDesignEngine/include/vde/brep/iges_import.h

#pragma once
/**
 * @file iges_import.h
 * @brief IGES 文件导入（ANSI Y14.26M）
 *
 * 解析 IGES 格式文件（.igs / .iges）并转换为 B-Rep 模型。
 *
 * ## IGES 格式概述
 *
 * IGES (Initial Graphics Exchange Specification) 是一种旧式但广泛使用的 CAD 数据交换格式。
 * 采用 80 字符固定宽度记录格式，分为 5 个区域：
 *
 * - **S (Start)**: 自由格式注释
 * - **G (Global)**: 参数分隔符、单位、精度等全局设置
 * - **D (Directory)**: 实体目录（类型、线型、颜色等属性）
 * - **P (Parameter)**: 实体参数数据
 * - **T (Terminate)**: 文件结束标记
 *
 * ## 支持的实体类型
 *
 * 主要支持几何和拓扑实体：
 * - Type 100: Circular Arc
 * - Type 110: Line
 * - Type 116: Point
 * - Type 126: Rational B-Spline Curve
 * - Type 128: Rational B-Spline Surface
 * - Type 108: Plane
 * - Type 186: Manifold Solid B-Rep Object
 * - Type 502/504/508/510/514: B-Rep 拓扑（顶点/边/环/面/壳）
 *
 * @ingroup brep
 */
#include "vde/brep/brep.h"
#include <string>
#include <vector>

namespace vde::brep {

/**
 * @brief IGES 导入错误码
 */
enum class IgesError {
    Ok = 0,               ///< 导入成功
    FileNotFound,          ///< 文件不存在或无法读取
    ParseError,            ///< IGES 语法错误（固定宽度格式异常）
    InvalidSection,        ///< 段标记无效或缺失
    UnsupportedEntity,     ///< 遇到了不支持但合法的实体类型
    MissingEntity,         ///< 引用了未定义的实体
    EntityTypeError,       ///< 实体类型解析失败
};

/**
 * @brief 从文件导入 IGES
 *
 * 解析 .igs 或 .iges 文件并返回其中的 B-Rep 体。
 *
 * **算法概要:**
 * 1. 读取文件并按 80 字符行分割
 * 2. 解析 Start, Global, Directory, Parameter 各段
 * 3. 根据 Directory Entry 识别实体类型和参数位置
 * 4. 构建 B-Rep 拓扑结构（B-Rep Object 或独立几何实体）
 *
 * @param filepath .igs 或 .iges 文件路径
 * @return B-Rep 体列表
 *
 * @note IGES 格式较为宽松，不同 CAD 系统的实现差异很大。
 *       对于非常规实体或自定义类型，可能会返回 IgesError::UnsupportedEntity。
 *
 * @code{.cpp}
 * auto bodies = import_iges("part.igs");
 * for (auto& body : bodies) {
 *     auto mesh = body.to_mesh(0.01);
 *     // 处理 mesh
 * }
 * @endcode
 *
 * @see import_iges_from_string 从字符串导入
 * @see iges_last_error 获取错误码
 */
[[nodiscard]] std::vector<BrepModel> import_iges(const std::string& filepath);

/**
 * @brief 从字符串导入 IGES（用于测试）
 *
 * @param data IGES 文件完整内容（字符串形式）
 * @return B-Rep 体列表
 *
 * @see import_iges 从文件导入
 */
[[nodiscard]] std::vector<BrepModel> import_iges_from_string(const std::string& data);

/**
 * @brief 获取最近一次 IGES 导入的错误码
 * @return IgesError 枚举值
 *
 * @see iges_last_error_message 获取可读描述
 */
[[nodiscard]] IgesError iges_last_error();

/**
 * @brief 获取最近一次 IGES 导入的可读错误描述
 * @return 错误描述字符串
 *
 * @see iges_last_error 获取枚举错误码
 */
[[nodiscard]] const std::string& iges_last_error_message();

} // namespace vde::brep