1. 我为什么会碰到 Teigha一个CAD文件解析需求1.1 项目背景要在几千张DWG里批量找数据当时接手的模拟项目X要把某制造企业积累的一千多张DWG图纸接入一个新系统。核心需求有三块第一自动读取图纸标题栏里的图号、图名、日期第二提取指定图层里的坐标数据用于和现场的测量记录做比对第三每个图纸生成一张PNG预览图方便浏览器端展示。这些事听起来零散但放到一套后端服务里就需要一个稳定的库来做统一解析。最早我想着直接遍历文件里的字符串把看起来像坐标的数字抠出来实际跑了两张图就发现完全行不通因为同一个坐标既出现在实体定义里也可能出现在标注文字、扩展数据和图框标题栏里根本没法定边界。最开始尝试让部署了桌面CAD软件的机器来做脚本自动化做法是命令行启动、执行脚本导出DXF再解析。实践下来发现桌面软件启动慢连开几十个进程内存直接爆掉而且机械性脚本很容易在某个文件上卡死整个队列全部堵住。后来我意识到必须在服务端直接内嵌一个能读写DWG的解析层把格式解析变成普通库调用。Teigha 就是在这时候进入视野的。我还试过几款开源解析库它们对DXF支持不错但对DWG普遍不支持即使支持也只覆盖少数版本而且大多只读几何字体、标注、块属性这些一体化能力基本没有。把有限的开发力量投入到补全格式兼容上是划不来的。Teigha 虽然也需要学习成本但它至少把“能打开绝大多数DWG”作为默认能力。1.2 选型时的三条硬条件和最终确认当时列出的硬条件有三条一是格式覆盖要够广必须能读DWG最好连DXF、DWF这类变体也一把梭二是要能脱离桌面软件运行C可以部署在无图形界面的服务器上不依赖GUI三是最好自带渲染能力因为我不仅要读数据还要出预览图。条件明确之后候选方案其实就剩两三条但最后真正把三条同时满足的只有 Teigha。我特意做了个验证Demo写一个最小程序初始化SDK打开一张包含各种实体的测试DWG把图元数量打印出来。Demo跑通之后我又测试了它在不同DWG版本之间的兼容性包括老版本R12、常见的新版本以及一些被第三方软件修改过的文件。结果是只要能正确设置字体映射绝大多数图纸都能打开。这个结论让我决定正式采用。后来复盘这个“先做验证Demo再全量接入”的顺序很有用它让我在真正写业务代码之前先摸清了SDK的边界也避开了很多后续返工。2. 从初始化到打开DWGTeigha 的启动流程没那么随意2.1 环境配置与许可证校验Teigha 不是一个普通的三件套源码库拿过来链接完就能跑。它的运行依赖一套自带的运行时环境启动时要初始化动态链接器、注册模块退出时要反过来释放。首次接入时最容易被忽略的是许可证校验如果许可证没有提前放好后面读文件时会抛出一堆让人摸不着头脑的异常。我记得第一次跑通Demo前配置了License文件路径又在代码里设置了许可类型顺序大抵是先注册许可再调用odInitialize()最后加载必要的模块。环境变量也需要单独处理。在某些服务器上SDK会通过环境变量查找资源文件、字体目录和帮助文件如果把可执行文件直接拷到一个干净系统经常启动后提示缺模块。所以我通常在部署脚本里把以下目录固化SDK的Bin目录、字体目录、许可文件目录。这个细节花了我一个下午排查。在正式接入项目前我还把官方示例程序整个编译了一遍确保环境通。有一个很常见的现象官方示例编译好后在本机正常但部署到服务器上找不到模块多半是环境变量和路径问题而不是代码问题。建议在部署脚本里打印SDK模块路径启动时检查关键模块是否加载成功。// 简化版初始化顺序不同版本类名可能不同 setLicensePath(L/srv/teigha/license); odInitialize(); // 加载核心模块 ::odrxDynamicLinker()-loadModule(LTD_Db); // 后面再创建HostApp、打开文件2.2 readFile 的前前后后初始化之后核心入口是读取文件。我用的版本里通过一个自定义的HostApp实例调用readFile它内部会根据文件扩展名和文件头自动判断DWG还是DXF并选择对应的模块解析。整个过程不是简单地fopen然后解析字节流而是把文件映射到 Teigha 的对象数据库里之后所有操作都是对对象ID和对象指针进行。很多第一次接触的人以为readFile就是“把文件读完”实际上它只是把文件里的对象数据库建立起来真正的实体访问要等你主动去遍历。class MyHostAppServices : public OdDbHostAppServices { public: OdString getFileDirs() override { return L/srv/teigha/fonts; } }; void processFile(const OdString path) { MyHostAppServices host; OdDbDatabasePtr pDb host.readFile(path); // 业务处理... pDb nullptr; }readFile并不是无状态的。同一个进程连续读多个文件时建议每次创建新的OdDbDatabasePtr处理完马上释放如果不释放数据库对象的析构可能延迟到进程退出导致内存峰值异常。还有一个经验文件路径里中文比较常见尽量使用宽字符接口避免在窄字符转换时出乱码。我们后期就遇到过因为某个文件路径里带全角括号导致路径转换异常的情况排查了半天才发现是编码问题。3. 实体遍历与坐标提取把DWG变成业务数据3.1 模型空间、块表记录和实体ID的关系DWG内部结构像一个树根上是数据库数据库里有块表块表里有很多块表记录每个块表记录里又存放一组实体。模型空间其实就是块表里一条特殊的记录图纸上看到的图形基本都在这里。Teigha 的调用方式很典型先通过数据库拿到模型空间ID再打开为块表记录最后用迭代器遍历所有实体。实体ID是逻辑ID不是指针拿到ID后需要openObject才能变成对象。遍历时用只读模式需要修改时才用写模式。如果忘记关闭对象长时间批处理会堆积引用计数导致文件无法释放。OdDbObjectId modelSpaceId pDb-getModelSpaceId(); OdDbBlockTableRecordPtr pModel modelSpaceId.openObject(); OdDbBlockTableRecordIteratorPtr pIter pModel-newIterator(); for (; !pIter-done(); pIter-step()) { OdDbObjectId entId pIter-getEntityId(); OdDbEntityPtr pEnt entId.openObject(OdDb::kForRead); // 判断类型... }但这只是模型空间一层。实际图纸还有大量块引用OdDbBlockReference它们嵌套在模型空间里指向另一个块表记录里面可能还有更多实体。所以正确的遍历是一个递归过程遇到块引用时打开它指向的块表记录继续循环。接近真实业务后你会发现很多坐标问题不是实体本身写错而是遍历时漏掉了块里层提取不到目标图元。我当时的做法是写一个递归函数传入块表记录ID处理完一层实体后再把所有块引用收集起来逐个深入最多见过七八层嵌套。3.2 坐标提取中最容易被忽略的变换对于普通实体坐标就是实体属性里的坐标比如直线startPoint()、圆心center()。但一旦实体在块引用内部它记录的坐标是块定义坐标系下的值显示到模型空间时需要乘上块引用携带的变换矩阵。块引用可能存在多级嵌套所以变换也要逐级乘下去。我当时为了快第一版程序直接读取了嵌套块里圆心的原始坐标导致导出的坐标和图纸实际位置相差几十米查了半天才意识到少了变换这一步。OdGeMatrix3d totalTransform; totalTransform blkRef-blockTransform() * totalTransform; OdGePoint3d pt line-startPoint(); pt.transformBy(totalTransform);这里还有一个小技巧不要每遍历到一个实体就立刻做坐标转换可以先建一个中间结构体把原始坐标、变换矩阵、类型都存进去全部遍历完再批量计算。这样如果坐标系设置有误只需要改转换函数不需要重新跑整个DWG读取。块引用还有统一缩放和非统一缩放的区别有些实体会被拉伸变形如果业务只关心坐标统一缩放情况下blockTransform()就够了非统一缩放时还要额外判断坐标轴方向。4. 容易踩坑的三大区域字体、代理实体和坐标系4.1 字体缺失导致的中文乱码与文本越位第一次在服务器上跑出预览图时所有单行文字里的中文都变成了方框甚至某些多行文字直接消失。原因就是服务器上没有安装图纸使用的SHX字体文件。Teigha 在找不到字体时不会报错而是用一种默认字体替代替代后有些字符没对应字形就成了乱码。这不算SDK的Bug而是运行环境不完整。和桌面版CAD不同桌面版会自带详尽字体库服务端部署却往往只有最小运行环境。解决办法分成三步先把常用CAD字体目录整个拷贝过来放到程序可以访问的字体目录然后配置字体映射文件把 SHX 字体名映射到服务器上已安装的中文字体最后在自定义HostApp里重载findFile让 SDK 优先到自定义目录找字体。这样处理后中文文本、标注样式都能正确渲染。若字体替换仍影响图面至少预览图和原始CAD会略有差异需要跟业务方提前说明。4.2 代理实体第三方对象如何兜底某客户发来的图纸包含第三方对象可能是某种智能管线图元。Teigha 没有对应的专业模块时这些对象会以代理实体形式存在。直接遍历实体时它们的类别是OdDbProxyEntity你不能按普通线、圆来处理很多属性拿不到。常见的表现是实体总数对得上但关键对象全是代理业务数据提不出来。如果你忽略代理实体继续处理导出的坐标数据就会缺漏一大块。有两个倾向要避免一是忽略代理实体继续处理结果导出的坐标数据缺漏二是把所有代理实体都炸开成基本图元虽然视觉上保留了一部分但原始业务语义丢失扩展字典也会丢。稳妥做法是统计代理实体的原始类名和数量把包含代理实体的文件单独标记提示人工复核。你的业务如果只是做预览可以尝试让SDK使用代理体图形进行渲染如果做数据提取遇到代理实体最好如实记录不要硬猜。我在项目里就是定期巡检日志把所有代理实体出现过的DWG列出来交给业务方人工确认。4.3 WCS、OCS与用户坐标系的转换这是我整个项目里理解成本最高的一块。CAD里实体除了普通世界坐标系WCS还有一个对象坐标系OCS比如圆、圆弧、多段线都带有法向向量normal当法向不是Z轴方向时它的坐标需要在法向定义的局部平面上解释。如果你直接拿center()当作WCS坐标在斜板、侧墙这类图纸上就会出错。我们首先接触的是水平布置图所以一开始没注意后来拿到一张倾斜安装的节点图坐标怎么都对不上才回头研究法向向量。我的经验是在遍历阶段不要过早做坐标转换先把实体的类型、原始坐标、法向向量和所在块引用的变换矩阵一起记录最后统一处理。块变换矩阵已经包含了实体所在坐标系的姿态但如果你还要处理 OCS 旋转需要再根据法向构造平面变换。好在我们项目主要处理水平布置图法向基本都是Z轴所以只要把块变换处理好问题就解决了。遇到非水平空间时建议先用一个简单样例构造斜板反复验证转换矩阵再铺开否则很容易在批量数据里混入一批错坐标而不自知。5. 用 Teigha 输出预览图渲染器的正确打开方式5.1 离屏渲染的基本步骤Teigha 自带的图形系统可以把同一个数据库驱动到多种设备上屏幕设备、打印机设备、光栅设备。我们的服务端没有显示器目标是把图纸画成PNG做法就是创建一个离屏光栅设备把数据库绑定上去设置视口让设备执行绘制最后把像素读出来。官方示例里通常有整套绘制调用我这里把它抽象成四步初始化图形系统并创建光栅设备把设备绑定到数据库设置背景色和图纸范围调整视口参数让目标图形范围居中并占满画布触发渲染并读取输出位图。// 伪代码描述流程不针对具体版本 odgsInitialize(); OdGsDevicePtr pDevice createRasterDevice(1024, 768); pDevice-setBackgroundColor(OdCm(255, 255, 255)); pDevice-setDatabase(pDb); setupView(pDevice, databaseExtents(pDb)); pDevice-update(); pDevice-getRasterData(pngPath);离屏渲染比直接解析数据多了一个层面它需要理解线型比例、填充样式、视口配置所以环境里缺任何资源都会在图片上暴露。我建议渲染输出和坐标提取分开跑因为两者关注的东西不同数据解析即使字体缺失也能凑合输出预览图对字体和线型要求严格得多。实际上我们在项目里把渲染任务放到了独立队列只传文件路径和输出路径渲染进程崩溃不会影响数据解析主流程。5.2 预览图输出时我踩过的四个具体问题第一个问题是背景。默认渲染背景是深色而业务方要求白底。这个问题看起来简单但直接改背景色后白色实体在白底上就消失了必须同时做一层颜色映射。后来我在初始化设备时统一把背景设为白色把白色实体替换成黑色或灰色再配合线宽设置预览图的观感才接近桌面软件。这个颜色映射表在服务端和本地渲染客户端必须保持一致否则同一张图在不同环境出图效果会差很多。第二个问题是范围。有的图纸图形只占很小一角但图框边线距离很远如果直接取数据库的统计范围会生成大片的空白业务方反馈“图纸缩着看不清”。后来改成遍历所有实体收集每个实体的包围盒再求并集作为视口范围同时加一个边距比例这样预览图就会自动居中也不会切掉图形。注意要排除掉冻结图层里的不可见实体否则范围会被那些隐藏对象撑得很大。第三个问题是文字。字体没配好时不仅出现4.1里的中文乱码还会出现文字换行错乱。多行文字渲染时字体宽高比发生变化导致文字重叠或跑出框外。这块只能靠字体映射和控制字体替换范围来缓解没有一劳永逸的办法所以我提前把常用字体都放到了字体目录里尽可能避免替换。遇到个别字体实在找不到的我还会在渲染日志里打一条Warn方便人工追踪。第四个问题是分辨率。A0图纸如果按真实尺寸渲染输出像素可能达到数万做网页预览没有必要。我把输出固定在最大边1600像素按图纸范围的长宽比计算另一边。这样缩略图加载快细节也够用。如果之后要支持放大再单独走平铺渲染不必一开始就追求超大原图。这个参数现在只占了我配置表里的一行但它对出图稳定性影响非常大。6. 与手工解析DXF相比为什么最终留下 Teigha6.1 DXF解析的“看起来简单”和“实际很碎”项目最开始团队里有同事建议直接解析DXF理由很朴素DXF是文本文件按行读就可以了。小规模测试时确实能活比如读一个简单DXF文件里的直线和圆代码几十行搞定。可一旦文件变成真实生产图纸段落和组码的结构、嵌套块、扩展数据、代理实体全混在一起手工解析就成了无底洞。我统计过一张完整的生产DXF里实体段落可能只占文件很小一部分前面是大量表段、类段、字典和系统变量而且DXF存在不同版本组码语义会变化。更麻烦的是业界流转的图纸大多是DWG不是每个人都会另存为DXF。所以手工解析只能作为一个临时辅助工具。你如果坚持自研等于是让团队持续维护一个不断变化的格式解析器每遇到一个特殊文件就要打一个补丁这种补丁越积越多最后反而成为项目里最脆弱的模块。至少在模拟项目X里我们早期写的DXF解析代码最后基本都删掉了只保留了一个用于快速预览文本块的函数。6.2 二进制DWG、嵌套块和版本兼容才是深水区DWG是一条更深的深水区它不是简单文件里面有压缩、加密和多种版本历史格式。Teigha 的价值就在于此它本身就是长期跟踪格式演进的产物能够处理从老版本到新版本的各种文件。对我们这种业务系统与其投入人力维护一个永远追不上的格式解析器不如用成熟SDK把风险转嫁出去这不是懒惰而是一个风险收益比很清晰的决定。把格式解析的脏活、累活交给SDK上层业务反而能稳定起来。还有嵌套块。复杂图纸里经常有“块套块”甚至循环引用手工解析遇到这类结构要考虑递归深度、变换矩阵和属性Teigha的对象模型已经把这些封装成了常规操作。另外SDK还提供了版本转换、格式导出、打印布局支持虽然本项目只用到了读取和渲染但后续只要需求扩展也能接得住。这些都是自研方案短期内很难达到的。6.3 成本与维护的最终账本如果把自研解析器也计入维护成本账算下来更清晰。DWG格式本身没有公开规范跟进成本都在第三方更新每遇到一个特殊文件就要写一段兼容代码这些代码会越堆越多。Teigha的授权是按开发者和部署服务器算的初期看起来贵但它是把整个格式兼容和渲染能力外包出去。对我们这种二十人不到的小团队买SDK比招一个专门逆向格式的人划算得多。还有一点SDK提供的不仅仅是解析还带了打印布局、版本转换、导出PDF等能力。这些功能如果都要自己实现每一个都是一条深坑。我甚至在项目里只用了它不到20%的功能但剩下的20%已经覆盖了所有核心需求。做技术选型时不要只看当前最小需求还要考虑需求演进后有没有扩的余地。7. Teigha 使用过程中几个值得记住的心得7.1 内存与生命周期管理Teigha 大量使用引用计数的智能指针。好处是不用手动释放每一个对象坏处是一旦某个引用没有及时释放数据库文件就会一直处于打开状态文件句柄不释放批量跑几个小时内存持续上涨。我的建议是把每个文件的所有局部对象塞进一个明确的代码块里让智能指针在块结束时统一析构。不要图省事把OdDbEntityPtr存到全局容器里除非你确实清楚它应该在什么时候释放。还有一个容易被忽略的事odInitialize和odUninitialize应该在整个进程生命周期里只做一次不要在每次读文件时反复调用。批量任务如果量很大建议按文件数量分片每个进程跑完一批主动退出重新拉起新进程这样可以规避一些潜在的资源碎片问题。我们后来把任务队列改成按目录批量分配给多个独立进程整体吞吐反而比一个长进程更高因为即使某个文件把进程搞崩也不会影响其他任务。7.2 升级版本后的行为变化项目中途我把SDK从旧版升级到了新版本结果同一批预览图的颜色整体偏亮了。这个变更大概来自SDK对颜色校正的调整也可能是渲染管线默认配置变了。还有个别API被替换成新名字旧示例代码直接编译不过。这提醒我如果没有具体诉求不要在大规模业务进行中随意升级SDK如果要升级先跑一遍回归测试集。后来我在本地单独搭了一套升级验证环境升级前后把样例库全部跑一遍对比输出文件和日志确认没有异常才投入使用。回归测试集不用太大覆盖不同版本DWG、含中文标注的文件、含代理实体的文件、含光栅图像的图纸四类基本就够。那次升级让我知道官方示例代码修改日志值得逐条看尤其是渲染、字体映射、坐标系统相关条目。有些行为变化未必写在主文档里可能只是示例代码里的一行注释但影响却很大。7.3 如果重新开始我会先做什么如果让我重新做一遍我会先用三天时间搭一个最小闭环读入DWG、输出实体统计、渲染出PNG拿十张不同类型的真实图纸作为基准数据。这个小闭环一旦跑通后面所有功能都只是往环里填东西。反之如果一开始就急着做完整的业务数据提取很容易被字体、变换、代理实体这些细节耗光时间。另一个动作是把所有在不同批次里出现问题的DWG文件保存成样例库每个样例记录当时的错误日志和解决办法。后面每动一次SDK配置、每换一台部署服务器都先跑一遍样例库。这套东西虽然前期花时间但它能把不确定性挡在正式任务之外。项目跑完我最大的感触是Teigha 的接口确实复杂但只要把格式解析的脏活累活交给它上层业务反而能稳定起来。如果你正准备接这套SDK我的建议很简单先别急着写业务先把环境、许可、字体和最小Demo跑通这些基础工作值得你多花几天。
