CATIA PMI / 3D 标注 FTA API：基准、GDT、粗糙度自动化指南

一、原理：3D PMI 的语义模型

PMI（Product Manufacturing Information）= 工程图上"基准/GDT/粗糙度/工艺备注"在 3D 模型上的直接表达。CATIA 的 FTA（Functional Tolerancing & Annotation）工作台是它的实现，所有 PMI 对象都挂在 3D Part 里、绑定到 BRep 面/边，跟着几何走。这点是它和 Drawing 标注的本质区别——后者绑在 2D 视图上。

对象	接口	含义
Annotation Set	`CATIFTAAnnotationSet`	视图捕获容器（一个 capture 一组标注）
Datum	`CATIFTADatumFeature` / `DatumTarget`	基准（A/B/C）和基准目标
GDT	`CATIFTAGeometricalTolerance`	形位公差（圆度、平面度、位置度等）
Dimension	`CATIFTADimension`	3D 尺寸（线性/角度/直径）
Surface Finish	`CATIFTASurfaceFinish`	粗糙度
Annotation	`CATIFTAAnnotation`	所有标注的根基类

对象

接口

含义

Annotation Set

CATIFTAAnnotationSet

视图捕获容器（一个 capture 一组标注）

Datum

CATIFTADatumFeature / DatumTarget

基准（A/B/C）和基准目标

GDT

CATIFTAGeometricalTolerance

形位公差（圆度、平面度、位置度等）

Dimension

CATIFTADimension

3D 尺寸（线性/角度/直径）

Surface Finish

CATIFTASurfaceFinish

粗糙度

Annotation

CATIFTAAnnotation

所有标注的根基类

所有 PMI 通过 CATIFTASemantic 接口和它绑定的 BRep 元素（CATIBRepAccess）双向关联。改了几何，标注会自动飘到对应位置；删几何，标注变 isolated。

视图捕获（Capture）是 PMI 特有的概念：每个 capture 锁定一个观察方向 + 一组可见标注。一份零件可以有多个 capture（前视/俯视/局部放大），导出 STEP AP242 / 3D PDF / 工程图时按 capture 切换视角。

二、流程：从 BRep 面创建一条形位公差 5 步

三、避坑：FTA 二开七大坑

坑 1：Datum 字母大小写敏感且不重
"A" / "a" 是两个不同 Datum；批量创建时一个零件里建了第二个"A"会报 E_FTA_DUPLICATE_DATUM。

坑 2：GDT 未关联 Datum 时静默通过校验
位置度公差应该带 |A|B|C|，CAA 里如果忘了 SetDatumReference，会创建一个语义不完整的 GDT，UI 显示正常但 STEP 导出时被忽略。

坑 3：Surface Finish 的符号体系是 ISO 1302:2002
旧版（Ra）和新版（Surface Texture Symbol）字段不通用。CAA 默认建新版，老图纸要切回旧版用 SetSymbolStyle(CATFTAStyleOld)。

坑 4：Capture 不切，标注就看不到
新建 capture 必须 SetActiveCapture，否则即使 AddAnnotation 成功，3D 视图里也是不可见的。批量自动标注完最后要回切 default capture。

坑 5：从 STEP 导入的零件 BRep 引用不稳定
STEP 转 CATPart 后 BRep face 名称重新生成，旧 PMI 的 face reference 可能 dangling。批量补 PMI 前先 CATIFTASemantic::CheckSemantic 校验。

坑 6：3D PDF 导出丢 GDT 框
导出 3D PDF 默认只带可视化图元，要带 GDT 框必须 SetExportPMI(TRUE)，否则下游看到的是空 viewer。

坑 7：FTA 标注的字体大小绑定 Standard
单个标注 SetFontSize 不生效，必须改 CATIFTAStandard 的 GlobalFontSize。批量时改 Standard 一次即可。

实战建议：自动 PMI 的最佳模板是"基准 → 主关键尺寸 → 公差链 → 粗糙度"四级管线。先把零件的 ABC 基准识别清楚（一般是最大平面 + 主轴 + 次轴），然后所有 GDT 和尺寸都引用这三个基准，这样工艺 BOM 工具能直接读 STEP AP242 得到完整可制造数据。

四、完整代码：自动添加基准 A + 平面度公差 + 粗糙度

// AutoFTA.cpp // 输入：CATPart 文档 + 目标平面 BRep 引用 // 输出：在面上挂 Datum A、平面度 0.05、Ra 1.6 #include "CATIFTAFactory.h" #include "CATIFTAAnnotationSet.h" #include "CATIFTADatumFeature.h" #include "CATIFTAGeometricalTolerance.h" #include "CATIFTASurfaceFinish.h" #include "CATIFTASemantic.h" #include "CATIFTACapture.h" HRESULT AutoAnnotate( CATIPartRequest_var spPart, CATISpecObject_var spFaceRef) { HRESULT rc = S_OK; CATIFTAFactory_var spFac = spPart; if (spFac == NULL_var) return E_FAIL; // 1. 拿/建 AnnotationSet CATIFTAAnnotationSet_var spSet; spFac->GetCurrentAnnotationSet(spSet); if (spSet == NULL_var) spFac->CreateAnnotationSet(spSet); // 2. 创建/激活 capture CATIFTACapture_var spCap; spFac->CreateCapture("AutoMfgView", spCap); spSet->SetActiveCapture(spCap); // 3. 建基准 A CATIFTADatumFeature_var spDatum; rc = spFac->CreateDatumFeature(spFaceRef, "A", spDatum); if (FAILED(rc)) return rc; spSet->AddAnnotation(spDatum); // 4. 建平面度公差 0.05 CATIFTAGeometricalTolerance_var spGDT; rc = spFac->CreateGeometricalTolerance( CATFTAFlatness, 0.05, spFaceRef, spGDT); if (FAILED(rc)) return rc; // 平面度无须 datum reference spSet->AddAnnotation(spGDT); // 5. 建粗糙度 Ra 1.6 CATIFTASurfaceFinish_var spSF; rc = spFac->CreateSurfaceFinish(spFaceRef, spSF); if (FAILED(rc)) return rc; spSF->SetRoughness("Ra", 1.6); spSet->AddAnnotation(spSF); // 6. Update CATIUpdate_var spUpd = spPart; if (spUpd != NULL_var) spUpd->Update(); // 7. 校验语义完整性 CATIFTASemantic_var spSem = spGDT; int valid = 0; spSem->CheckSemantic(valid); cout << "GDT semantic valid = " << valid << "\n"; return rc; }