首页 / 技术文章 / Catalog 标准件库

CATIA Catalog 标准件库 API：Chapter / Family / Component 完整指南

琛兴科技 · CATIA 二次开发系列 · 适用 V5R19~R32 · 含 GB / DIN / ISO 紧固件库实战

一、原理：Catalog 的三层组织模型

CATIA 的标准件库（Catalog）是一种特殊的 .catalog 文档，专门用来管理可参数化、可大量复用的零件。它的组织结构是清晰的三层：

层级接口含义
Catalog 文档CATICatalogDocument整个 .catalog 文件
Chapter（章节）CATICatalogChapter分类节点，可嵌套（GB/DIN/ISO）
Family（族）CATICatalogFamily同一种零件的参数族（如 GB5782 六角螺栓）
Component（实例条目）CATICatalogDescription族里的一行规格（M10×100）

Family 内部维护一张关键字段表（Keywords）：每行是一个具体规格，每列是一个参数（M、L、Length、Pitch等）。Family 还绑定一个参考 CATPart（带参数化建模特征），实例化时按选中行的参数值代入参数表，重新计算 CATPart 得到一个具体零件。

这个机制的工业价值：100 万种紧固件不需要 100 万个 CATPart 文件，一个参数化模板 + 一张 100 万行的 Excel 表即可。

二、流程：从 Excel 批量灌库 6 步

  1. 建参数化模板 CATPart：用 KBE 公式把所有可变尺寸（M、L、Pitch、HeadHeight）暴露为 CATIParm。
  2. 新建 .catalog：CATDocumentServices::New("catalog", pDoc)。
  3. 建 Chapter 树：用 CATICatalogFactory::CreateChapter 嵌套出"GB → 紧固件 → 螺栓"路径。
  4. 建 Family 并绑模板：CreateComponentFamily 传入 Chapter 和模板 CATPart 路径。
  5. 读 Excel 灌行：每行调 AddDescription，把规格名和参数值塞进去。
  6. Save .catalog：保存即可在 Product 工作台用 Catalog Browser 打开拖入。

三、避坑：Catalog 七大坑

坑 1：模板 CATPart 必须有 Publication
仅参数 KBE 不够，安装点 / 配合面也得做成 Publication，否则下游做 Routing / 装配自动连接时找不到接口。
坑 2：Catalog 路径里有中文 → Browser 打不开
.catalog 文件路径含中文字符在某些版本的 Windows + V5 组合下 Browser 显示空白。把库放在英文路径（如 D:\CatalogLib\GB\）最稳。
坑 3：Family 行数过万 → Catalog 加载慢
单 Family 超过 5000 行时 Browser 加载肉眼可见的卡。批量建库分多个 Family（如 GB5782_M3, GB5782_M4, ...）。
坑 4：参数类型不一致导致整族静默失败
模板里螺距是 Length 类型，Catalog 里写"1.5"（数字），实例化时认作 mm 没问题；但写"1.5mm"（带单位字符串）会报"keyword type mismatch"，整个 Family 全失败。
坑 5：Component 引用 Family 的相对路径会丢
模板 .CATPart 跟 .catalog 必须在同一上级目录，否则 .catalog 里存的是相对路径，移动后实例化报"link broken"。
坑 6：实例化后 Product 出现"未定义关键字"
模板里有 KBE 公式但没暴露成 Family Keyword，实例化后这些公式仍按模板值计算，导致每个实例 M10×100 都是同一个值。
坑 7：批量实例化做 Save 内存暴涨
每实例化一个螺栓 CATIA 都生成完整的 CATPart 子树。1000 个螺栓 × 50KB 一台 8GB 机就 OOM。批量时务必每 100 个 Save+Close 一次。
实战建议（GB 标准件库）：建议按"国标编号 + 规格"两级 Family——Chapter "GB5782 六角螺栓" → Family "GB5782_M10" → 100+ 行不同长度。这样浏览效率高，且每个 Family 独立维护，新增长度规格时不动整库。

四、完整代码：从 Excel 自动建 GB5782 螺栓库

// BuildGB5782Catalog.cpp
// 输入：参数化模板 CATPart 路径 + Excel 规格表（M, L, Pitch, HeadHeight, Width）
// 输出：GB5782_Bolts.catalog

#include "CATICatalogFactory.h"
#include "CATICatalogDocument.h"
#include "CATICatalogChapter.h"
#include "CATICatalogFamily.h"
#include "CATICatalogDescription.h"
#include "CATDocumentServices.h"

struct BoltSpec {
    CATUnicodeString name;   // "GB5782_M10x100"
    double M;                // mm
    double L;
    double pitch;
    double headHeight;
    double headWidth;
};

HRESULT BuildBoltCatalog(
    const CATUnicodeString& templatePart,
    const std::vector<BoltSpec>& specs,
    const CATUnicodeString& outCatalog)
{
    HRESULT rc = S_OK;
    CATDocument* pDoc = NULL;
    rc = CATDocumentServices::New("CatalogDocument", pDoc);
    if (FAILED(rc) || !pDoc) return rc;

    CATICatalogDocument_var spCat = pDoc;
    if (spCat == NULL_var) return E_FAIL;

    CATICatalogFactory_var spFac = pDoc;

    // 1. 建 Chapter 树
    CATICatalogChapter_var spRootChap, spGBChap, spBoltChap;
    spCat->GetRootChapter(spRootChap);
    spFac->CreateChapter(spRootChap, "GB", spGBChap);
    spFac->CreateChapter(spGBChap,   "Hex_Bolts_GB5782", spBoltChap);

    // 2. 建 Family，绑模板
    CATICatalogFamily_var spFam;
    rc = spFac->CreateComponentFamily(
            spBoltChap, "GB5782_AllSizes",
            templatePart, spFam);
    if (FAILED(rc)) return rc;

    // 3. 声明 Keywords（必须和模板里 KBE 参数名一致）
    spFam->AddKeyword("M",          CATCatalogKeywordReal);
    spFam->AddKeyword("L",          CATCatalogKeywordReal);
    spFam->AddKeyword("pitch",     CATCatalogKeywordReal);
    spFam->AddKeyword("headHeight", CATCatalogKeywordReal);
    spFam->AddKeyword("headWidth",  CATCatalogKeywordReal);

    // 4. 灌行
    int n = 0;
    for (const auto& s : specs) {
        CATICatalogDescription_var spDesc;
        spFam->AddDescription(s.name, spDesc);
        spDesc->SetRealValue("M",          s.M);
        spDesc->SetRealValue("L",          s.L);
        spDesc->SetRealValue("pitch",      s.pitch);
        spDesc->SetRealValue("headHeight", s.headHeight);
        spDesc->SetRealValue("headWidth",  s.headWidth);
        ++n;
    }
    cout << "Inserted " << n << " bolt specs.\n";

    // 5. Save
    rc = CATDocumentServices::SaveAs(*pDoc, outCatalog);
    CATDocumentServices::Remove(*pDoc);
    return rc;
}

© 上海琛兴科技发展有限公司 · 转载请注明出处 · CATIA 是 Dassault Systèmes 注册商标