简介这份资源是面向Node.js开发者与CAD/3D建模方向学习者的OpenCascade绑定扩展用于在服务端以JavaScript构建BREP实体模型。它通过V8包装器将OpenCascade的几何内核能力暴露为简洁API支持布尔运算、STEP/IGES等格式读写并附带示例Web应用适合需要将参数化建模、CSG运算接入Node.js工程的中高级开发者。压缩包共105个文件约6.53MB以36个js脚本、22个C头文件、21个cc实现文件为主另有json配置、bat构建脚本、yml流程文件及step/stp模型样例覆盖从源码编译到模型导出的完整链路。目前已有1920人学习下载。借助其中的ShapeFactory、Mesh、Solid、Face等模块实现与构建脚本读者可快速理解OpenCascade在Node环境下的封装方式掌握用代码生成箱体、圆柱并执行切割等实体操作并参考示例应用完成从建模到文件输出的实践为自建CAD工具链或三维服务提供可复用的基础。1. 用 JavaScript 玩转 BREPnode-occ 到底解决了谁的痛点如果你写过 Three.js 的 CSGConstructive Solid Geometry大概率经历过那种“布尔运算一多就崩、模型边缘全是锯齿、导出 STEP 直接报错”的绝望。Three.js 的 CSG 本质是网格级别的多边形裁剪做做视觉演示还行一旦涉及工程级精度——比如要导出能被 SolidWorks、Fusion 360 正常打开的 STEP 或 IGES 文件——它立刻露馅。node-occ 走的是另一条路它把工业界用了三十年的 OpenCascadeOCCT内核通过 Node.js 原生绑定暴露出来让你在 JavaScript 里直接操作 BREPBoundary Representation实体。BREP 用参数化曲面和精确边界描述几何体一个圆柱就是数学意义上的圆柱不是 32 个三角面片拼出来的近似品。这意味着你在 Node.js 里做的布尔运算、倒角、抽壳结果可以直接进 CAD 流水线。适合谁做参数化设计工具的前端工程师、需要服务端批量生成 CAD 模型的后端开发者以及想把 3D 建模能力塞进 Web 应用但不想碰 C 的全栈选手。2. 环境搭建与第一个 BREP 实体从 npm 安装到 STEP 导出2.1 为什么 node-occ 的安装比普通 npm 包麻烦node-occ 不是纯 JavaScript 库它依赖 OpenCascade 的 C 编译产物。npm 上能搜到几个相关包但真正维护活跃、API 相对完整的是node-occ及其衍生分支。安装前你得确认三件事Node.js 版本建议 16 或 18 LTS太新的版本可能遇到 node-gyp 编译兼容问题、系统是否有 C 编译工具链Windows 需要 Visual Studio Build ToolsmacOS 需要 Xcode Command Line ToolsLinux 需要 build-essential、以及 Python 2.7 或 3.xnode-gyp 依赖。如果你在 Windows 上遇到npm : 无法加载文件 ... npm.ps1因为在此系统上禁止运行脚本这是 PowerShell 执行策略问题用管理员权限运行Set-ExecutionPolicy RemoteSigned即可跟 node-occ 本身无关但它是你安装路上第一只拦路虎。# 确认 Node.js 和 npm 版本 node -v # 建议 v16.x 或 v18.x npm -v # Windows 下如果 npm 脚本被禁止先处理执行策略 # 以管理员身份打开 PowerShell Set-ExecutionPolicy RemoteSigned -Scope CurrentUser # 安装 node-occ具体包名以你获取的资源为准 npm install node-occ安装完成后在node_modules/node-occ下应该能看到.node二进制文件和lib目录。如果只有 JS 文件没有二进制说明编译阶段失败了回头检查编译工具链。2.2 用代码创建一个带孔的法兰盘并导出 STEP下面这段代码演示了 node-occ 的核心工作流创建基本体、布尔运算、倒角、导出。我以一个法兰盘为例——圆柱主体加中心通孔边缘做圆角。const occ require(node-occ); // 1. 创建外圆柱半径 50高度 20 const outerCylinder new occ.BRepPrimAPI_MakeCylinder(50, 20).Shape(); // 2. 创建中心通孔圆柱半径 15高度 30比主体高确保完全贯穿 const innerCylinder new occ.BRepPrimAPI_MakeCylinder(15, 30).Shape(); // 3. 布尔减运算外圆柱减去内圆柱 const cutOp new occ.BRepAlgoAPI_Cut(outerCylinder, innerCylinder); cutOp.Build(); const flangeWithHole cutOp.Shape(); // 4. 对上下边缘做圆角半径 2 // 先获取所有边缘 const edgeExplorer new occ.TopExp_Explorer( flangeWithHole, occ.TopAbs_ShapeEnum.TopAbs_EDGE ); const edges []; while (edgeExplorer.More()) { edges.push(occ.TopoDS.Edge(edgeExplorer.Current())); edgeExplorer.Next(); } // 对圆形边缘做倒角实际项目中需要按几何类型筛选边缘 const filletOp new occ.BRepFilletAPI_MakeFillet(flangeWithHole); // 这里简化处理对所有边缘尝试倒角生产环境需判断边缘类型 edges.forEach(edge { try { filletOp.Add(2, edge); // 倒角半径 2 } catch (e) { // 某些边缘可能不支持倒角跳过 } }); filletOp.Build(); const finalShape filletOp.Shape(); // 5. 导出为 STEP 文件 const stepWriter new occ.STEPControl_Writer(); stepWriter.Transfer(finalShape, occ.STEPControl_StepModelType.STEPControl_AsIs); stepWriter.Write(flange.step); console.log(法兰盘已导出为 flange.step);逻辑说明BRepPrimAPI_MakeCylinder是 OpenCascade 创建圆柱的标准 API参数依次为半径和高度。BRepAlgoAPI_Cut执行布尔减Build()触发计算Shape()取出结果。倒角部分我用了简化写法实际项目中你需要通过BRepAdaptor_Curve判断边缘是直线还是圆只对圆边缘倒角。STEP 导出用STEPControl_WriterTransfer的第二个参数STEPControl_AsIs表示保持原样导出不进行额外简化。参数怎么改圆柱半径和高度直接改数字倒角半径改filletOp.Add的第一个参数导出格式如果想换 IGES把STEPControl_Writer换成IGESControl_WriterTransfer方法签名类似。失败时看什么如果Build()后Shape()返回空检查两个实体是否真的相交——布尔运算要求实体有重叠区域。如果倒角报错多半是边缘太短或相邻面夹角太小减小倒角半径试试。3. 布尔运算与倒角BREP 建模的核心操作与参数调优3.1 布尔运算的三种模式与选型逻辑OpenCascade 的布尔运算分三种BRepAlgoAPI_Cut减、BRepAlgoAPI_Fuse并、BRepAlgoAPI_Common交。node-occ 把它们都暴露成了构造函数。选型逻辑很直接你要在实体上挖孔就用 Cut要把两个实体合并成一个就用 Fuse要取重叠部分就用 Common。但这里有个容易被忽略的点——布尔运算的“容差”。OCCT 内部用浮点数表示几何两个面如果距离小于某个阈值可能被判定为相交或不相交导致结果不符合预期。常见做法是在布尔运算前用BRepBuilderAPI_Copy复制实体避免原始形状被修改运算后用BRepCheck_Analyzer检查结果有效性。// 布尔运算后检查结果有效性 const analyzer new occ.BRepCheck_Analyzer(finalShape); if (!analyzer.IsValid()) { console.warn(布尔运算结果无效可能需要调整容差或修复几何); // 尝试修复用 ShapeFix_Shape const fixer new occ.ShapeFix_Shape(finalShape); fixer.Perform(); finalShape fixer.Shape(); }BRepCheck_Analyzer的IsValid()返回布尔值ShapeFix_Shape是 OCCT 的通用修复工具能处理大部分微小几何缺陷。参数方面布尔运算本身没有暴露容差设置但你可以通过BRepAlgoAPI_Cut的SetFuzzyValue方法设置模糊容差如果 node-occ 绑定了这个方法的话默认值通常是1e-7量级。3.2 倒角与圆角BRepFilletAPI 的两个变体倒角Chamfer和圆角Fillet在 OCCT 里是两个不同的 APIBRepFilletAPI_MakeFillet做圆角BRepFilletAPI_MakeChamfer做倒角。圆角需要指定半径倒角需要指定两个距离或者一个距离加角度。实际项目里我一般会先对边缘分类水平边缘、垂直边缘、圆形边缘然后分别处理。因为对所有边缘统一倒角大概率会在某些尖锐角落产生自交或失败。// 只对圆形边缘做圆角 const edgeExplorer new occ.TopExp_Explorer(shape, occ.TopAbs_ShapeEnum.TopAbs_EDGE); const filletOp new occ.BRepFilletAPI_MakeFillet(shape); while (edgeExplorer.More()) { const edge occ.TopoDS.Edge(edgeExplorer.Current()); const curve new occ.BRepAdaptor_Curve(edge); // 判断边缘类型Circle 表示圆 if (curve.GetType() occ.GeomAbs_CurveType.GeomAbs_Circle) { filletOp.Add(2, edge); // 只对圆边缘倒半径 2 的圆角 } edgeExplorer.Next(); } filletOp.Build(); const filletedShape filletOp.Shape();BRepAdaptor_Curve的GetType()返回边缘的几何类型GeomAbs_Circle对应圆GeomAbs_Line对应直线。这个筛选逻辑能避免对直线边缘误倒角导致的失败。参数调优方面圆角半径不能大于相邻面的最小尺寸否则会报错。如果Build()失败先检查半径是否过大再检查边缘是否连续。3.3 从 BREP 到网格三角剖分与 Three.js 集成BREP 实体要显示在 Web 页面上需要先三角剖分。OCCT 提供BRepMesh_IncrementalMesh做网格化node-occ 应该也绑定了这个类。剖分精度由LinearDeflection和AngularDeflection控制前者是线性偏差值越小网格越密后者是角度偏差控制曲面处的细分程度。// 对 BREP 实体进行三角剖分 const meshOp new occ.BRepMesh_IncrementalMesh( finalShape, 0.1, // LinearDeflection线性偏差越小越精细 false, // isRelative是否相对偏差 0.5 // AngularDeflection角度偏差弧度 ); meshOp.Perform(); // 提取三角面片数据伪代码具体 API 名以 node-occ 文档为准 const triangulation occ.BRepTool.Triangulation(finalShape); const vertices []; const indices []; // 遍历面、遍历三角面片填充 vertices 和 indices // 然后传给 Three.js 的 BufferGeometryLinearDeflection设 0.1 意味着网格顶点与真实曲面的最大距离不超过 0.1 个单位。如果你的模型尺寸是毫米级0.1 可能太粗如果是米级0.1 又太细。我一般会按模型包围盒对角线长度的 0.1% 到 0.5% 来估算。AngularDeflection设 0.5 弧度大约对应 28 度曲面细分程度适中。这两个参数直接决定网格数量和渲染性能需要根据实际场景权衡。4. 避坑与排查node-occ 实战中五个血泪教训4.1 现象npm install 卡在 node-gyp 编译报错 “gyp ERR! stack Error: Cant find Python executable”原因node-gyp 需要 Python 来生成编译配置系统里没装 Python 或者 PATH 里找不到。解决安装 Python 3.x 并确保python命令可用。Windows 上如果同时有 Python 2 和 3可能需要用npm config set python python3指定。另外Visual Studio Build Tools 必须包含 “Desktop development with C” 工作负载否则缺少 MSVC 编译器。4.2 现象布尔运算结果为空Shape()返回 null 或空对象原因两个实体没有实际相交或者相交区域小于 OCCT 的默认容差。解决先用BRepBndLib计算两个实体的包围盒确认它们在空间上有重叠。如果重叠区域很小尝试用BRepBuilderAPI_Transform移动实体让重叠区域变大。另外检查实体是否有效——用BRepCheck_Analyzer验证输入实体。4.3 现象倒角操作报错 “BRepFilletAPI_MakeFillet::Add: edge is not suitable for fillet”原因边缘太短、相邻面夹角太小、或者边缘本身有几何缺陷。解决先用ShapeFix_Shape修复实体再尝试倒角。如果还是失败减小倒角半径。对于夹角极小的边缘可以考虑先做一个小距离的倒角再做正常倒角分两步走。4.4 现象导出的 STEP 文件在 SolidWorks 里打开后显示为破面或实体丢失原因BREP 实体的拓扑结构有问题可能是布尔运算产生的微小缝隙或自交。解决导出前用BRepCheck_Analyzer检查用ShapeFix_Shape修复。另外STEP 导出时可以用STEPControl_Writer的SetTolerance方法设置导出容差适当放宽容差能合并微小缝隙。如果还是不行尝试先导出为 IGES 再转 STEP有时能绕过一些拓扑问题。4.5 现象三角剖分后网格数量爆炸Three.js 渲染卡顿原因LinearDeflection和AngularDeflection设得太小导致每个曲面被细分成成千上万个三角面片。解决根据模型尺寸和屏幕显示精度调整参数。一个实用的估算方法是LinearDeflection 模型对角线长度 / 1000AngularDeflection 0.5弧度。如果模型只在屏幕上显示几百像素这个精度足够了。需要高精度导出时再单独用更小的偏差值重新剖分。5. 进阶技巧用 node-occ 做参数化批量生成与 STEP 元数据写入5.1 批量生成把参数表变成一堆 STEP 文件实际工作中我经常遇到“给一张 Excel 参数表生成几百个不同尺寸的零件”这种需求。node-occ 配合 Node.js 的异步能力可以很优雅地做这件事。核心思路是把建模逻辑封装成一个函数参数从 JSON 或 CSV 读入循环调用每个零件导出独立 STEP 文件。const fs require(fs); const occ require(node-occ); // 参数表每个对象是一组零件参数 const parts [ { name: flange_A, outerR: 50, innerR: 15, height: 20, filletR: 2 }, { name: flange_B, outerR: 60, innerR: 20, height: 25, filletR: 3 }, // ... 更多参数 ]; function buildFlange(params) { const outer new occ.BRepPrimAPI_MakeCylinder(params.outerR, params.height).Shape(); const inner new occ.BRepPrimAPI_MakeCylinder(params.innerR, params.height * 1.5).Shape(); const cut new occ.BRepAlgoAPI_Cut(outer, inner); cut.Build(); let shape cut.Shape(); // 倒角逻辑简化 const fillet new occ.BRepFilletAPI_MakeFillet(shape); // ... 筛选边缘并倒角 fillet.Build(); shape fillet.Shape(); return shape; } parts.forEach(params { const shape buildFlange(params); const writer new occ.STEPControl_Writer(); writer.Transfer(shape, occ.STEPControl_StepModelType.STEPControl_AsIs); writer.Write(${params.name}.step); console.log(${params.name}.step 已生成); });这个模式的关键是把所有参数外置建模函数只负责几何运算。批量生成时注意内存管理——OCCT 的实体对象不会自动被 JavaScript 垃圾回收大量生成时可能需要手动释放如果 node-occ 提供了delete方法或类似机制。我一般会分批处理每 50 个零件重启一次 Node.js 进程避免内存泄漏。5.2 写入 STEP 元数据让文件自带“身份证”STEP 文件支持自定义属性比如零件号、材料、作者。OCCT 的STEPControl_Writer可以通过Interface_Static设置一些全局属性但更灵活的方式是在导出前给形状附加XCAF文档结构。node-occ 如果绑定了XCAFDoc相关类可以这样做// 伪代码创建 XCAF 文档并写入元数据 const doc new occ.TDocStd_Document(XmlXCAF); const shapeTool occ.XCAFDoc_DocumentTool.ShapeTool(doc.Main()); const label shapeTool.AddShape(finalShape, false); // 设置属性 occ.TDataStd_Name.Set(label, Flange_Part_001); // 还可以设置材料、公差等如果 node-occ 没有绑定 XCAF退而求其次的方法是在导出后用文本编辑器打开 STEP 文件在FILE_NAME段手动添加描述信息。STEP 是纯文本格式FILE_NAME行里的第二个字段就是作者第三个字段是组织第四个字段是描述。批量处理时可以用 Node.js 的fs模块读写替换。5.3 验证导出结果三个必须做的检查导出 STEP 后别急着交付我一般会做三个检查。第一用BRepCheck_Analyzer在导出前验证实体有效性这是最后一道防线。第二用文本编辑器打开 STEP 文件确认文件头完整、实体数量与预期一致。第三如果条件允许用 FreeCAD 或 CAD Assistant 打开文件肉眼确认几何形状。FreeCAD 是免费开源的支持 STEP 导入适合做快速验证。我吃过亏——有一次导出的 STEP 在 SolidWorks 里打开后倒角全部变成了尖角原因是倒角操作在导出前没有Build()形状还是原始状态。从那以后我每次导出前都强制走一遍BRepCheck_Analyzer和肉眼验证再也不敢偷懒。希望帮到你。本文还有配套的精品资源点击获取