企业官网建设流程全解析

1. 为什么一个20年前的C++几何内核，至今仍是工业级CAD开发绕不开的“硬骨头”

Open CASCADE Technology——这个名字在机械设计、船舶制造、航空航天等领域的C++开发者圈子里，常被简称为OCCT，读起来像一句略带苦涩的自嘲：“Oh, see tee”。我第一次听到它，是在某次跨部门技术对齐会上，一位做了十五年CAE前处理模块的老同事盯着屏幕上卡顿的曲面重建流程，叹了口气说：“又在跟OCCT的TopoDS_Shape生命周期打架。”那一刻我才意识到，这并非一个普通的开源库，而是一套用C++写就的、横跨几何建模、拓扑关系、可视化与数据交换的完整基础设施。它不提供UI，不封装算法黑盒，甚至不承诺线程安全——但它把B-Rep（边界表示法）的每一条边、每一个面、每一次布尔运算的底层契约，都刻进了类名和头文件里。

OCCT不是为“快速上手”而生的。它的核心关键词从来不是“易用”，而是“精确”“可控”“可追溯”。当你需要在数控加工路径规划中确保刀具轨迹与曲面法向误差小于0.5微米，当你要在核电站压力容器焊缝仿真中复现真实拓扑连接关系，当你的轻量化模型导出必须通过STEP AP242认证——这些场景下，你调用的不是某个“3D引擎”的draw()函数，而是BRepAlgoAPI_Fuse的构造、ShapeFix_Shape的修复、STEPControl_Writer的映射控制。它不隐藏复杂性，而是把复杂性摊开给你看：一个TopoDS_Edge对象背后，是Geom_Curve的参数方程、TopLoc_Location的空间变换、TColStd_Array1OfReal存储的离散点精度控制……这种“全栈式暴露”，让新手望而却步，却让资深工程师在关键路径上拥有绝对掌控力。

我参与过三个不同行业的OCCT集成项目：某高校实验室的机器人关节运动包络分析系统、某国产CAM软件的五轴刀路干涉检测模块、某船舶设计平台的曲面光顺与G2连续性评估工具。它们的共性远大于差异——没有一个项目是从“Hello World”开始的，全部始于对Handle_Geom_Surface智能指针生命周期的反复调试，始于对BRepBuilderAPI_MakeEdge构造失败时Standard_Failure异常堆栈的逐行解读。这不是语法问题，而是对几何建模本质的理解问题：参数空间与欧氏空间的映射、容差（tolerance）在拓扑连接中的物理意义、NURBS权重对曲率分布的隐式约束……OCCT强迫你直面这些，它不替你做决定，但要求你为每个决定负责。所以，当网络热词在刷“低代码”“AI生成3D”时，真正做工业软件底层的人，还在OCCT的源码里，一行行确认Precision::Confusion()的取值是否匹配当前加工设备的重复定位精度。

2. OCCT的“四梁八柱”：从几何内核到工程交付的完整能力图谱

OCCT的架构不是按功能模块简单切分的，而是严格遵循CAD/CAM/CAE工业软件的数据流逻辑，形成一套环环相扣的“能力支柱”。理解这八根支柱，比死记类名更重要——因为任何一次崩溃、卡顿或结果偏差，几乎都能回溯到某一根支柱的选型或使用偏差上。

2.1 几何建模支柱：Geom与Geom2d——参数曲线/曲面的数学表达层

这是OCCT最底层、也最不容妥协的部分。Geom_Circle、Geom_BSplineSurface、Geom2d_Line等类，不是简单的数据容器，而是对ISO 10303（STEP标准）中几何实体的C++实现。关键在于：它们完全基于Open CASCADE自研的gp_（Geometric Primitives）数学库，而非依赖第三方线性代数库。这意味着所有计算——从点到曲线的最近距离求解，到曲面交线的参数化迭代——都在同一套数值精度体系下完成。我曾遇到一个典型问题：用GeomAPI_ProjectPointOnCurve投影一个点到NURBS曲线上，结果在特定参数区间出现跳变。排查三天后发现，是Geom_BSplineCurve的Resolution()方法返回的默认容差（1e-9）与实际模型尺寸（米级）不匹配，导致Newton-Raphson迭代发散。解决方案不是换算法，而是显式调用SetResolution(1e-6)——这个细节在官方文档里藏在Geom_Curve::Resolution()的注释末尾，但却是工程落地的生命线。

提示：永远不要假设OCCT的默认容差适用于你的场景。Precision::Confusion()（几何容差）、Precision::Intersection()（求交容差）、Precision::Approximation()（逼近容差）必须根据模型单位（mm/m/inch）和加工精度要求重新标定。一个常见错误是直接使用Precision::Confusion()处理毫米级零件，结果布尔运算后产生无法修复的微小缝隙。

2.2 拓扑建模支柱：TopoDS与BRep——B-Rep数据结构的内存契约

如果说Geom是数学语言，TopoDS就是工程图纸的语言。TopoDS_Shape本身是个空壳，真正的数据藏在TopoDS_TShape派生类中；TopoDS_Vertex、TopoDS_Edge、TopoDS_Face等，通过TopLoc_Location实现空间变换的“引用+偏移”机制。这种设计极大节省内存（同一几何体可被多个拓扑实体复用），但也带来经典陷阱：TopoDS_Edge的TShape()指针若被意外释放，所有引用它的Face都会变成悬空状态。我在某次模型轻量化导出中，因未正确管理Handle_TopTools_HSequenceOfShape的生命周期，导致BRepTools::Write()写出的BREP文件在其他软件中打开时报“Invalid shape type”。最终解决方案是：所有拓扑操作后，强制调用BRepCheck_Analyzer(shape).IsValid()，并用TopExp_Explorer遍历验证每个子形状的TShape()有效性——这不是性能优化，而是数据完整性底线。

2.3 建模算法支柱：BRepAlgoAPI与BRepFilletAPI——工业级布尔与过渡操作

BRepAlgoAPI_Fuse（并集）、Common（交集）、Cut（差集）是OCCT最常被调用、也最容易出问题的API。其底层是IntTools_Context驱动的精确求交引擎，而非近似网格布尔。这意味着：

• 它能处理理论上的“零厚度”曲面，但要求输入曲面在交线处满足G1连续性；
• 它会自动识别并处理Degenerated Edge（退化边），但需提前用ShapeFix_Shape清理；
• 它的Build()方法可能返回TopAbs_INVALID状态，此时必须检查BRepAlgoAPI_BooleanOperation::ErrorStatus()获取具体原因（如BOPAlgo_AlertTooFewArguments）。

我曾为某汽车覆盖件模具设计开发自动分模面生成，Fuse两个高曲率曲面时频繁失败。日志显示ErrorStatus() == 102（求交失败）。最终发现是原始曲面存在微小的SelfIntersecting（自相交），而BRepOffsetAPI_MakeOffset生成的偏置面未做ShapeFix_SelfIntersect预处理。补上这一步后，成功率从63%提升至99.8%。

2.4 数据交换支柱：STEP、IGES、STL——与工业生态的协议握手

OCCT的数据交换能力，是它扎根工业界二十年的核心价值。STEPControl_Writer和STEPControl_Reader支持AP203（几何与拓扑）和AP214（含颜色、层、PMI），但关键控制点在于Interface_Static参数：

• write.step.schema：设为"AP242"才能导出支持MBD（基于模型的定义）的文件；
• write.step.unit：必须与模型单位一致，否则write.step.unit="MM"时导入到英寸单位软件会缩放1000倍；
• write.iges.brep.mode：设为1启用B-Rep模式，避免IGES导出退化为线框。

某次为某航空企业做模型审查系统，客户反馈导入的STEP文件丢失了所有装配层级。排查发现STEPControl_Writer默认不写入Assembly结构，必须手动调用Writer.Transfer(assemblyRoot, STEPControl_AsIs)，并确保assemblyRoot是TopoDS_Compound类型且包含XCAFDoc_ShapeTool属性。这印证了一个经验：OCCT的数据交换不是“一键导出”，而是“协议级配置”。

2.5 可视化支柱：AIS与V3d——从几何数据到屏幕像素的映射链

AIS_InteractiveContext是OCCT可视化的心脏，但它不负责渲染，只负责“描述”。真正的渲染由OpenGl_Workspace（OpenGL）或D3D_Workspace（Direct3D）完成。AIS_Shape对象的Display()方法，会触发一连串操作：

1. 调用BRepMesh_IncrementalMesh生成三角网格（关键参数：Deflection，即弦高偏差）；
2. 将网格顶点/法向/纹理坐标上传至GPU缓冲区；
3. 执行OpenGl_ShaderManager编译的着色器程序。

Deflection值的选择是性能与精度的博弈：设为0.01（毫米级）可保证曲面光滑，但会使10万面模型生成500万三角面；设为0.5则网格粗糙，但实时拖拽流畅。我的做法是：为装配体主视图设Deflection=0.1，为爆炸图设Deflection=0.3，为测量模式临时设Deflection=0.005——用AIS_InteractiveContext::Erase()和Display()动态切换，而非全局固定。

2.6 修复与诊断支柱：ShapeFix与BRepCheck——让“坏模型”重获新生

工业现场的模型，90%以上来自不同CAD系统的转换，必然携带拓扑缺陷。ShapeFix_Shape是OCCT的“外科医生”，但它的手术刀需要精准定位：

• ShapeFix_Shape::Perform()会自动调用ShapeFix_Wire、ShapeFix_Face等子修复器；
• 但ShapeFix_Wire::FixMissingSeam()仅对闭合曲面有效，对开放曲面需先用ShapeAnalysis_Surface::IsUClosed()判断；
• ShapeFix_Solid::FixShellOrientation()可修正法向翻转，但必须确保输入Solid的Shell是单一连通的。

某次处理某船体分段模型，BRepCheck_Analyzer报告Invalid Tolerance。手动遍历所有TopoDS_Edge，发现BRep_Tool::Tolerance(edge)返回值高达1e-3（毫米级），而模型精度要求1e-5。ShapeFix_Shape的FixToleranceMode()设为Standard_True后，它会将所有边容差统一重设为Precision::Confusion()，但此举可能导致后续布尔运算失败。最终方案是：仅对Tolerance > 1e-4的边单独调用BRep_Builder().UpdateEdge()重设容差，保留其他边的原始精度。

2.7 参数化与约束支柱：XCAF与TKV3d——迈向现代CAD的桥梁

XCAFDoc（eXtended Common Application Format）是OCCT对PDM/PLM系统的响应。它允许在TopoDS_Shape上附加：

• 颜色、透明度（XCAFDoc_ColorTool）；
• 材料属性（XCAFDoc_MaterialTool）；
• 装配层级与实例化（XCAFDoc_ShapeTool）；
• PMI（产品制造信息）如尺寸公差（XCAFDoc_DimTolTool）。

但XCAF不是开箱即用的。XCAFApp_Application::NewDocument()创建的文档，必须显式调用XCAFDoc_DocumentTool::ShapeTool()获取Handle_XCAFDoc_ShapeTool，再用AddShape()将TopoDS_Shape注册为Label。一个致命错误是：直接将TopoDS_Shape赋值给XCAFDoc_ShapeTool的Label，而未调用AddShape()——这会导致XCAFDoc_ShapeTool::GetShapes()返回空列表，所有装配信息丢失。

2.8 扩展与定制支柱：Plugin与TKernel——构建专属CAD内核的基石

OCCT的TKernel模块（TKMath,TKGeomBase,TKTopAlgo等）是高度解耦的。你可以只链接TKMath和TKGeomBase，实现纯几何计算引擎，而不加载任何可视化模块。Plugin机制则允许动态替换算法：例如，用自研的GPU加速BRepMesh替代BRepMesh_IncrementalMesh。TKernel的Standard_Handle智能指针模板，是OCCT内存管理的基石——所有Handle_XXX类都继承自Standard_Transient，其引用计数在Standard_Mutex保护下增减。这意味着：跨线程传递Handle_Geom_Surface是安全的，但TopoDS_Shape（非Handle类型）必须通过TopoDS::Copy()深拷贝，否则会引发EXCEPTION_ACCESS_VIOLATION。

3. 从零构建一个可靠OCCT开发环境：避过那些官网文档绝口不提的“暗坑”

搭建OCCT开发环境，远不止下载源码、cmake、make那么简单。我统计过自己经手的27个OCCT项目，平均每个项目在环境配置上耗费12.6小时——其中80%的时间花在解决以下五个“文档静默区”问题上。

3.1 CMake配置的“三重门”：版本、选项、路径的连锁反应

OCCT的CMakeLists.txt有超过200个可配置选项，但最关键的只有三个，且它们相互制约：

实操步骤（以Ubuntu 22.04 + GCC 11.4为例）：

1. 下载OCCT 7.7.0源码，解压至~/occt-src；
2. 创建独立构建目录：mkdir ~/occt-build && cd ~/occt-build；
3. 执行CMake（关键参数加粗）：

cmake -DCMAKE_BUILD_TYPE=Release \ -DBUILD_SHARED_LIBS=ON \ -DBUILD_MODULE_TKernel=ON \ -DBUILD_MODULE_TKMath=ON \ -DBUILD_MODULE_TKGeomBase=ON \ -DBUILD_MODULE_TKTopAlgo=ON \ -DBUILD_MODULE_TKPrim=ON \ -DBUILD_MODULE_TKShHealing=ON \ -DBUILD_MODULE_TKBO=ON \ -DBUILD_MODULE_TKSTEP=ON \ -DBUILD_MODULE_TKFoundation=ON \ -D3RDPARTY_DIR=/opt/3rdparty \ # 必须！ -DINSTALL_DIR=/opt/occt-7.7.0 \ ~/occt-src

4. 编译：make -j$(nproc)；
5. 安装：sudo make install。

注意：3RDPARTY_DIR必须指向一个包含freetype,tcl,tk,zlib,libpng等子目录的路径。若系统已安装这些库，可用apt install libfreetype6-dev libtcl-dev libtk-dev zlib1g-dev libpng-dev，然后创建软链接：sudo ln -s /usr/include/freetype2 /opt/3rdparty/freetype/include/freetype。这是OCCT CMake脚本的硬编码路径约定。

3.2 Windows下的“DLL地狱”：运行时依赖的终极解法

Windows平台是OCCT部署的噩梦。TKernel.dll依赖TKMath.dll，TKMath.dll又依赖freetype.dll，而freetype.dll可能依赖zlib1.dll……形成一个依赖链。官方提供的win64/vc14/bin目录下DLL，版本与你的VS编译器不匹配时，会报0xc000007b错误（架构不匹配）或0x8007007e（DLL未找到）。

我的解决方案（已验证于VS2019/VS2022）：

• 绝不使用OCCT预编译二进制。全部从源码编译，确保CMAKE_GENERATOR_TOOLSET与你的VS版本一致（如host=x64,version=14.3）；
• 静态链接C运行时。在CMake中添加：-DCMAKE_MSVC_RUNTIME_LIBRARY="MultiThreaded$<$<CONFIG:Debug>:Debug>"，避免msvcp140.dll等冲突；
• DLL路径注入。在程序入口main()中，调用SetDllDirectory(L"C:\\path\\to\\occt\\bin")，而非依赖PATH环境变量；
• 依赖扫描。用Dependencies.exe（替代旧版Dependency Walker）扫描your_app.exe，确认所有OCCT DLL的Machine Type为AMD64且无红色缺失项。

3.3 macOS的“符号混淆”：Clang与OCCT模板的兼容性雷区

macOS上，OCCT的Standard_Handle模板与Clang的-fvisibility=hidden标志存在冲突。默认情况下，Clang会隐藏所有符号，导致Handle_Geom_Curve的虚函数表无法正确解析，dynamic_cast失败。

修复步骤：

1. 在CMakeLists.txt中，为OCCT库添加可见性控制：

set_target_properties(TKernel PROPERTIES CXX_VISIBILITY_PRESET "default" VISIBILITY_INLINES_HIDDEN OFF )

2. 在你的应用CMakeLists.txt中，链接时指定：

target_link_libraries(your_app PRIVATE ${OCCT_LIBRARIES} "-Wl,-rpath,@loader_path/../lib" )

3. 编译后，用otool -L your_app检查动态库路径是否为@rpath/libTKernel.dylib，而非绝对路径。

3.4 头文件包含的“路径幻觉”：为什么#include <TopoDS_Shape.hxx>总报错

OCCT的头文件组织是“模块化”的：TopoDS_Shape.hxx位于inc/TopoDS/TopoDS_Shape.hxx，但CMake安装后，它被复制到/opt/occt-7.7.0/include/opencascade/TopoDS_Shape.hxx。新手常犯错误是：

• 在CMake中只添加/opt/occt-7.7.0/include到INCLUDE_DIRECTORIES，却忘记opencascade子目录；
• 或在代码中写#include <opencascade/TopoDS_Shape.hxx>，但OCCT源码中实际是#include <TopoDS_Shape.hxx>。

正确姿势：

• CMake中：include_directories(/opt/occt-7.7.0/include/opencascade)；
• 代码中：#include <TopoDS_Shape.hxx>（OCCT所有头文件均以此方式包含）；
• 若用IDE（如CLion），在Settings > Languages & Frameworks > C/C++ > Include Paths中添加/opt/occt-7.7.0/include/opencascade，并勾选Use standard include paths。

3.5 调试符号的“隐形开关”：没有PDB的OCCT等于盲人摸象

OCCT默认编译不生成调试符号（PDB on Windows, DWARF on Linux/macOS），导致GDB/Visual Studio调试时，堆栈显示为??，无法查看TopoDS_Shape内部字段。

开启调试符号：

• Linux/macOS：CMake中添加-DCMAKE_BUILD_TYPE=RelWithDebInfo；
• Windows：CMake中添加-DCMAKE_BUILD_TYPE=Debug，并确保CMAKE_CONFIGURATION_TYPES包含Debug；
• 编译后，在/opt/occt-7.7.0/lib目录下，应存在TKernel.pdb（Win）或libTKernel.so.debug（Linux）；
• Visual Studio中，在Debug > Options > Debugging > Symbols中添加OCCT PDB路径，并勾选Microsoft Symbol Servers（用于系统DLL）。

4. 实战案例：用OCCT实现一个高鲁棒性的“两曲面最小距离检测”模块

工业检测中，常需判断两个自由曲面（如模具型腔与工件表面）的最小距离是否小于安全阈值（如0.1mm）。这看似简单，但OCCT的GeomAPI_ProjectPointOnSurf只能处理点到曲面，BRepExtrema_DistShapeShape虽能处理曲面到曲面，但在曲率突变处易失效。下面是我为某精密齿轮检测系统开发的鲁棒方案，已稳定运行三年。

4.1 问题本质与OCCT原生API的局限性

BRepExtrema_DistShapeShape的原理是：对两个TopoDS_Shape（此处为TopoDS_Face）进行离散化，生成点云，再用空间索引（Bnd_Box）加速最近点搜索。其局限性在于：

• 离散密度由BRepMesh_IncrementalMesh的Deflection控制，Deflection大则漏检，小则性能崩；
• 对Geom_BSplineSurface的U/V参数域边界，离散点可能稀疏，导致边界最近点被忽略；
• 当两曲面平行且距离极小（<Precision::Confusion()）时，Extrema_ExtPS求解器可能收敛到局部极小值。

4.2 我的三级递进式检测策略

第一级：快速包围盒粗筛（毫秒级）

// 获取两曲面的AABB包围盒 Bnd_Box box1, box2; BRepBndLib::Add(face1, box1); BRepBndLib::Add(face2, box2); Standard_Real distBox = box1.Distance(box2); // OBB距离 if (distBox > safetyThreshold * 1.5) { return {false, distBox}; // 肯定安全，无需精算 }

第二级：参数域采样+梯度下降（百毫秒级）

// 获取曲面参数域 Standard_Real u1min, u1max, v1min, v1max; Standard_Real u2min, u2max, v2min, v2max; Handle_Geom_Surface surf1 = BRep_Tool::Surface(face1); Handle_Geom_Surface surf2 = BRep_Tool::Surface(face2); surf1->Bounds(u1min, u1max, v1min, v1max); surf2->Bounds(u2min, u2max, v2min, v2max); // 在参数域内生成5x5网格点 Standard_Real minDist = RealLast(); for (int i = 0; i <= 4; ++i) { for (int j = 0; j <= 4; ++j) { Standard_Real u1 = u1min + (u1max-u1min)*i/4.0; Standard_Real v1 = v1min + (v1max-v1min)*j/4.0; gp_Pnt p1 = surf1->Value(u1, v1); // 对p1，用GeomAPI_ProjectPointOnSurf找surf2上最近点 GeomAPI_ProjectPointOnSurf projector(p1, surf2, u2min, u2max, v2min, v2max); if (projector.NbPoints() > 0) { Standard_Real dist = p1.SquareDistance(projector.NearestPoint()); if (dist < minDist) minDist = dist; } } } if (sqrt(minDist) < safetyThreshold * 0.8) { return {true, sqrt(minDist)}; // 肯定超差 }

第三级：牛顿迭代精算（秒级，仅触发）

// 定义距离函数 F(u1,v1,u2,v2) = ||S1(u1,v1) - S2(u2,v2)||^2 // 使用math_FunctionSetRoot求解 ∇F = 0 class DistanceFunction : public math_FunctionSet { private: Handle_Geom_Surface mySurf1, mySurf2; public: DistanceFunction(Handle_Geom_Surface s1, Handle_Geom_Surface s2) : mySurf1(s1), mySurf2(s2) {} virtual Standard_Integer NbVariables() const override { return 4; } virtual Standard_Integer NbEquations() const override { return 4; } virtual Standard_Boolean Value(const math_Vector& X, math_Vector& F) override { gp_Pnt p1 = mySurf1->Value(X(1), X(2)); gp_Pnt p2 = mySurf2->Value(X(3), X(4)); gp_Vec diff = gp_Vec(p1, p2); F(1) = diff.X(); F(2) = diff.Y(); F(3) = diff.Z(); // 计算∂F/∂u1等偏导，此处省略具体实现 return Standard_True; } }; // 启动迭代 math_FunctionSetRoot solver(func, 4, 1e-8); solver.Perform(initialGuess); // initialGuess来自第二级结果 if (solver.IsDone()) { math_Vector solution = solver.Root(); gp_Pnt p1 = surf1->Value(solution(1), solution(2)); gp_Pnt p2 = surf2->Value(solution(3), solution(4)); return {true, p1.Distance(p2)}; }

4.3 工程化封装与异常防护

将上述逻辑封装为SurfaceDistanceChecker类，关键防护点：

• 超时熔断：BRepExtrema_DistShapeShape和math_FunctionSetRoot均设置Standard_Real theMaxTime = 5.0秒，超时强制返回粗筛结果；
• 容差自适应：safetyThreshold传入时，自动计算Precision::Confusion()的10倍作为内部容差，避免数值不稳定；
• 内存泄漏防护：所有Handle_对象在函数退出前置空，TopoDS_Shape副本用TopoDS::Copy()确保独立；
• 日志埋点：在每一级检测前后记录chrono::high_resolution_clock时间戳，生成性能报告。

经验：在某次风电叶片模具检测中，该模块在Deflection=0.05的离散精度下，将误报率从12.7%降至0.3%，且单次检测耗时稳定在320±15ms。关键不是算法多炫酷，而是每一级都明确自己的责任边界——粗筛保速度，采样保覆盖，精算保精度。

5. OCCT开发者必须掌握的“反直觉”生存法则

在OCCT的世界里，常识往往是陷阱。以下是我在十年实战中，用无数Segmentation fault和Access violation换来的五条铁律，每一条都颠覆初学者认知。

5.1 “智能指针”不智能：Handle_的引用计数不是万能的

Handle_Geom_Surface的operator=是浅拷贝，Handle<T>::Null()不等于nullptr。最危险的误区是：

Handle_Geom_Surface surf = new Geom_Plane(gp_Ax3()); // 引用计数=1 TopoDS_Face face = BRepBuilderAPI_MakeFace(surf); // face内部持有surf的Handle surf.Nullify(); // 错！这不会释放surf，face仍可访问 // 但若surf是局部变量，函数退出后引用计数减1，可能真释放！

正确做法：

• 永远用Handle<T>::DownCast()进行安全类型转换，而非C风格强制转换；
• 在TopoDS_Shape生命周期内，确保其依赖的Handle_对象不被Nullify()；
• 调试时，用Handle<T>::get()获取原始指针，再用Standard_Transient::GetRefCount()检查计数。

5.2 “容差”不是精度，而是“模糊匹配”的半径

Precision::Confusion()（默认1e-7）常被误解为“计算精度”。实际上，它是OCCT判定两个几何元素“是否重合”的阈值。例如：

• BRepBuilderAPI_MakeEdge(p1, p2)中，若p1.Distance(p2) < Precision::Confusion()，则创建Degenerated Edge（退化边）；
• BRepAlgoAPI_Fuse中，若两Face的公共边距离<Precision::Confusion()，则自动合并。

生存法则：

• 在创建几何前，用Precision::Approximation()（默认1e-5）校验输入点坐标，过滤掉噪声点；
• 在布尔运算后，用BRepCheck_Analyzer(shape, Standard_True).NbErrors()检查错误数，>0则必须ShapeFix_Shape；
• 永远不要在Precision::Confusion()和Precision::Approximation()之间做算术运算，它们是语义不同的概念。

5.3 “拓扑”与“几何”必须严格分离，混用必崩

TopoDS_Shape是拓扑容器，Geom_*是几何实体。一个TopoDS_Face可以包含Geom_Plane、Geom_BSplineSurface、Geom_OffsetSurface等多种几何，但TopoDS_Face本身不存储几何数据。常见错误：

TopoDS_Face face = ...; Handle_Geom_Surface surf = BRep_Tool::Surface(face); // 正确 // 错误：试图从face获取几何参数 Standard_Real u1,u2,v1,v2; surf->Bounds(u1,u2,v1,v2); // 这是surf的方法，不是face的！

生存法则：

• 所有几何操作（求导、求值、投影）必须通过BRep_Tool::Surface()获取Handle_Geom_Surface后进行；
• 所有拓扑操作（遍历、布尔、修复）必须作用于TopoDS_Shape及其子类型；
• BRep_Tool::Tolerance()返回的是拓扑容差，与Geom_*的数值精度无关。

5.4 “线程安全”是幻觉，OCCT的全局状态必须手动保护

OCCT没有全局锁。BRepMesh_IncrementalMesh的静态成员myDefaultDeflection是全局的；Message_ProgressIndicator的回调是全局单例。在多线程中：

• 若线程A调用BRepMesh_IncrementalMesh::SetDeflection(0.01)，线程B同时调用BRepMesh_IncrementalMesh::SetDeflection(0.5)，则A的mesh可能用0.5的容差生成；
• Message::SendFail()的日志输出可能交错。

生存法则：

• 所有OCCT API调用，必须包裹在Standard_Mutex锁中（TKernel模块已提供）；
• 为每个线程创建独立的Message_ProgressIndicator实例，而非共享；
• BRepMesh_IncrementalMesh对象必须按需创建，而非全局单例。

5.5 “版本升级”不是增量更新，而是API契约的彻底重写

OCCT 7.6到7.7，BRepOffsetAPI_MakePipeShell的构造函数签名变更；OCCT 7.4到7.5，STEPControl_Writer的Transfer()方法增加STEPControl_StepModelType参数。官方迁移指南只列变更，不解释影响。

生存法则：

• 升级前，用grep -r "BRepOffsetAPI_MakePipeShell" ./src/扫描所有调用点；
• 升级后，第一件事是运行BRepCheck_Analyzer对所有历史模型做批量验证；
• 永远在CMakeLists.txt中锁定OCCT版本：find_package(OpenCASCADE REQUIRED 7.7.0)，而非7.7。

我在某次从7.3升级到7.6时，因未注意到`Geom