ZW3D 二次开发踩坑记录：10 个官方文档没写的失败场景（含实测数据）

先说结论

用 ZW3D 插件 API 建了 37 个零件，过程中遇到十来个「调用返回成功但结果不对」的情况。这些坑官方文档基本没写，整理出来供后来者参考。

最重要的一条：ZW3dRemote 返回 OK、API 返回 0，都不代表操作真的生效。

一、-10000 的真实含义

cvxSkAddPolyline / cvxSkSpline 返回 -10000，这个码不在标准 evxErrors 列表里。实测唯一场景是「没有调用 cvxSkActivate(sk, 0) 进入草图」。

int sk = 0;
cvxPartSkNew(&m, &sk);
cvxSkActivate(sk, 0);        // 这一步不能省

cvxSkAddPolyline(n, pts, 0); // 这时才返回 0

cvxRootExit();
cvxSkActivate(0, 0);         // 这个只是退出

cvxSkActivate(0,0) 是「退出到零件级」，不是「进入草图」。混淆这两个，几何永远画不进去。

二、另外 9 个坑（速览）

2. cvxRootExit() 会弹空草图确认框：草图里没画上几何时，它会弹「是否删除空草图」。自动化流程里会直接阻塞，点「否」则几何被丢弃，后续拉伸返回 -152。

3. 所有草图必须在第一次拉伸前建好：一旦拉伸生成实体，活动根从「零件」变成「实体」，此时再 cvxPartSkNew 会失败。

4. cvxFileClose() 不调会假死：连续建 13 个零件不关文档，内存涨到 1.2 GB，之后 ZW3dRemote 命令不再响应（端口还在监听，但没反应）。加上之后，14 个零件内存只涨 24 MB。

5. 编译必须加 /utf-8：源码有中文注释时，MSVC 默认按 GBK 解析，某些字节被误判成 ASCII 的 { 或 }，报出 C2267 / C2601 / C1075 这类莫名其妙的错误。

6. 闭合样条的两个参数缺一不可：Degree=1（保留尖角，默认 3 会磨圆）、CreateCrvOpen=0（闭合，默认 1 是开放）。另外点数少于 8 时样条会明显外扩（4 点正方形被撑到 1.5 倍），少量点建议用 cvxSkAddPolyline。

7. 带孔的轮廓要用两条独立闭合曲线：一条曲线走「外圈+桥接+内圈」的 8 字形会被判成自交，拉伸体积为 0。正确做法是同一草图里画两条独立闭合曲线，拉伸时 idProfile 传草图 id（不是曲线 id）。

8. 任意平面（含 YZ）不要手填矩阵：这是本项目最大的误判。我曾手填 svxMatrix 的 12 个分量，YZ 平面怎么也建不出来，一度判定为「厂商 API 限制」。正确做法是用官方 zwapi_matrix.h：

#include "zwapi_matrix.h"

szwPoint  origin = {0, 0, 0};
szwVector zAxis  = {1, 0, 0};        /* 法向世界 X，即 YZ 平面 */
szwMatrix m;
ZwMatrixGetByPointAndZAxis(origin, zAxis, &m);

/* szwMatrix 比 svxMatrix 多 4 个字段，显式拷贝更安全 */
svxMatrix sm; memset(&sm, 0, sizeof(sm));
sm.identity = m.identity;
sm.xx = m.xx; sm.yx = m.yx; sm.zx = m.zx; sm.xt = m.xt;
sm.xy = m.xy; sm.yy = m.yy; sm.zy = m.zy; sm.yt = m.yt;
sm.xz = m.xz; sm.yz = m.yz; sm.zz = m.zz; sm.zt = m.zt;

cvxPartSkNew(&sm, &sk);

实测：XY / XZ / YZ 三个平面全部正确，20mm 圆柱拉伸 10 的包围盒分别为 20×20×10、20×10×20、10×20×20。

zwapi_matrix.h 里有 33 个函数（ZwMatrixInitByTranslation、ZwMatrixInitByRotation、ZwMatrixGetByPointAndXYAxis、ZwMatrixCoordinateSystemGet 等），先读这个头文件再动手。

9. cvxPartMoveTransform 已废弃，但会「假成功」：返回 0，但旋转后包围盒完全不变；平移则变成「复制+移动」，原体还在。官方注释：This function will not be updated anymore, please use ZwFeatureMoveCreateByTransform()。建议在目标位置直接建模，不要「建完再转」。

10. 变量：能建、但可能没写进文件：ZwVariableCreate 返回 0，但事后 ZwVariableListGet 读出来 count = 0。另一个坑：ZwVariableDelete 会弹模态对话框，在自动化流程里调用会直接卡死插件，只能强杀进程。

三、参数化：变量绑尺寸是可以做的

关键 API：cvxSkAddConsDim(...) 加约束尺寸，cvxDimValMod(idDim, "D") 把尺寸值设成变量名。缺了这两个，API 建的几何只能是硬编码的 double。

实测数据：

D=80, d=25, t=5，圆画 r=40/12.5，尺寸填 D/d → 体积 22678.372 = π(40²−12.5²)×5
先建 D=100，圆仍画 r=40/12.5，尺寸填 D/d → 几何自动跳到 r=50，体积 36815.539

第二行是关键：说明尺寸框里填变量名确实能驱动几何。

三个限制：事后改变量不会自动重建（ZwVariableListSet 返回 0 但体积不变）、ZwVariableDelete 会卡死插件、变量必须在建几何之前建。

正确做法是每个配置完整重跑一遍：新建零件 → 设变量 → 建几何（尺寸绑变量）→ 拉伸 → 导出 → 关闭。

四、官方资源索引（可能最实用）

ZW3D 安装目录下的 api\ 里有整套资料，很多人（包括我）一开始没注意：

├── ApiExample.zip              官方示例，20 个 VS 工程
├── ApiHelpDoc.chm              英文 API 帮助（22 MB）
├── ApiHelpDoc_chs.chm          中文 API 帮助（23 MB）
├── ZW3D API introduction_Chs.pdf
└── DevelopmentTemplate\        工程模板

20 个示例里与本主题相关的：12.DllRegister（插件注册工具，参数 -n -a -d -l -r，不用手动拷 DLL 再界面加载）、15.EditVariable（变量编辑）、19.MatrixOperations（矩阵操作）、17.ExTrudewithPreview、6.Pattern。