OpenCASCADE与Qt实战：JellyCAD三维建模框架构建指南

简介JellyCAD是一款基于OpenCASCADE几何引擎、以QT为UI框架的开源三维建模软件面向需要快速原型设计、教学演示或个人CAD项目的开发者。资源包含完整的C工程源码核心功能支持参数化创建正方体、长方体、圆柱体、圆锥、圆环等基本几何体并具备自由曲线、点线绘制能力同时原生支持IGES格式导入导出可方便地与主流CAD系统交换模型数据适合作为入门OpenCASCADE二次开发和QT桌面应用开发的实战参考。压缩包内共20个文件以C头文件与实现文件.h/.cpp为主体配合Qt界面文件.ui、资源集合.qrc、工程配置.pro以及若干效果预览图.png组织整个压缩包仅76KB结构紧凑清晰便于直接加载和二次修改。资源已经过1129人学习下载使用者可获得一个可运行的三维建模程序框架直观理解几何内核与界面层的协作方式同时掌握从几何体构建、参数调整到模型文件导入导出的完整实现思路对从事CAD软件开发或相关课题研究具有较强参考价值。 JellyCAD-master 这个名字初看像是一个随手起的开源项目等真正把它编译跑起来之后你会发现它其实是“OpenCASCADE Qt”这套经典组合的一份完整脚手架。说白了它是一套用 OpenCASCADE 做三维几何内核、用 Qt 做界面框架的三维建模软件原型。什么人适合看这个项目一类是想学 OpenCASCADE 但不想一上来就啃底层 API 的开发者另一类是 Qt 已经用得很熟、想跨进三维建模领域却不知道从哪下手的同学。这篇文章我会从项目定位、环境搭建、核心代码结构、发布部署这几个维度做完整拆解也把我实际编译和二次开发过程中踩过的坑一并放进来。1. 先搞清楚项目定位1.1 JellyCAD 拆开看是什么样打开 JellyCAD 的源码目录你会发现它的结构并不神秘界面部分全部是 Qt 的 QMainWindow、QToolBar、QDockWidget三维视图区域由一个封装过的 QWidget 承载核心命令则围绕着 OpenCASCADE 的建模算法展开。整体跑起来后你可以创建基本实体、在三维视图中旋转缩放、选中对象并看到高亮效果部分流程里还能完成布尔运算。这些功能听起来不复杂但对于学习 CAD 开发的人来说这个项目的价值不是功能有多齐全而是把“一个三维建模程序到底应该分成哪几层”这件事讲清楚了。几何数据交给 OpenCASCADE 管理UI 状态交给 Qt 管理两者之间通过 AIS 交互选择框架沟通。当你理解这种分层之后后面不管自己写渲染器还是换内核思路都不会乱。反过来说如果一上来就在 Qt 里直接画线画方块那只是画了个带界面的 Demo不是建模软件。1.2 为什么这套组合被大量 CAD 项目采用可能有人会问为什么不用 Unity、Three.js或者干脆用纯 OpenGL 自己画答案在于边界表达模型。CAD 软件里的一张圆柱面不只是一堆三角网格它需要精确的数学表达式才能在后续拉伸、倒角、布尔运算中保持拓扑正确。OpenCASCADE 恰好提供了从解析几何到拓扑实体的完整体系同时还有 STEP、IGES 等格式读写库。而后端的交互与界面用 Qt 可以在桌面端快速搭建出工业软件的质感。这个组合在全球范围内有大量商业案例JellyCAD 的价值就是把这条成熟路线变成一份看得懂、能改得动的开源示例。2. 环境准备与编译避坑2.1 OpenCASCADE 编译从源码到可用状态先说编译 OpenCASCADE。这一步几乎决定了项目后续能不能顺利跑起来。我个人的建议是优先使用官方源码配合 CMake 编译而不是图省事直接拿别人编好的库。原因很简单OCCT 的功能模块很多默认全量编译耗时长生成的库文件也很大而自己做二次开发往往只需要其中的建模、可视化和数据交换模块从源码编译可以按需裁剪后续想调整宏定义也有底。编译前要准备的依赖主要是 FreeType、Tcl/Tk、TBB。如果不想手动管理依赖用 vcpkg 一条命令能装好大部分但要注意 vcpkg 生成的库默认带 Debug 和 Release 两套配置链接时要严格区分。我自己在 Windows 上习惯用 Visual Studio 2022 加 CMake-GUI 来配置编译类型选 Release关闭不必要的测试和示例目录开启 TBB 支持这样出来的库体积和运行性能都比较理想。编译完成后有三组路径必须记清楚include 目录、bin 目录、lib 目录。这三组路径在给 Qt 工程配置库时都要用到建议直接写到一个环境变量或者 CMake 缓存文件里避免每次配置新工程都手动找一遍。另外OCCT 编译输出里通常会有 Draw 相关的可执行文件如果只是做界面集成这个模块用处不大可以在 CMake 配置里直接关掉 BUILD_MODULE_Draw能省不少编译时间。2.2 Qt 环境选择版本、编译器与镜像JellyCAD 这种项目一般基于 Qt 5 编写我实际使用的是 Qt 5.15.2 加 MSVC 2019 64 位套件。其实 Qt 6 也能跑但老项目里很多第三方封装和示例代码是按 Qt 5 的信号槽写法来的升级时会多出一些编译错误。如果没有特别需求建议先用 5.15 系列等把整体逻辑吃透后再考虑迁移。这里有一个特别容易翻车的经验Qt 套件的编译器必须和 OpenCASCADE 的编译器保持一致。如果 OCCT 是用 MSVC 编出来的Qt 也选 MSVC 套件如果 OCCT 是用 MinGW 编出来的Qt 也要选 MinGW。千万不要混用混用的结果就是一堆模板相关的链接错误报错信息还特别难读。我见过不止一个人在这上面折腾了一整天最后只是换成了同一套编译器就通过了。国内下载 Qt 官方组件通常比较慢记得配置镜像源。安装 Qt 时除了核心组件建议把 Sources 也勾上方便调试时直接看 Qt 源码。装完之后打开 Qt Creator检查构建套件里 CMake 和编译器是否已经被自动识别识别不了就手动指定路径。这里的坑往往不是 Qt 本身而是 Qt Creator 用了系统里残留的旧 CMake导致配置出来一堆奇怪问题。2.3 CMake 配置示例与库路径绑定JellyCAD 的 CMakeLists 通常只需要改几处路径就能配置通过。如果你是从零新建工程我贴一个最精简的参考配置cmake_minimum_required(VERSION 3.16) project(JellyCAD) set(OpenCASCADE_DIR D:/OCCT/build/win64) set(CMAKE_PREFIX_PATH D:/Qt/5.15.2/msvc2019_64) find_package(OpenCASCADE REQUIRED) find_package(Qt5 REQUIRED COMPONENTS Widgets OpenGL) add_executable(JellyCAD main.cpp MainWindow.cpp) target_link_libraries(JellyCAD PRIVATE ${OpenCASCADE_LIBRARIES} Qt5::Widgets Qt5::OpenGL )配置过程中最常见的报错是找不到 OpenCASCADE这个就是 OpenCASCADE_DIR 没有指向 OpenCASCADEConfig.cmake 所在的目录。找准路径后CMake 会一次性把 OCCT 的所有库名解析出来。还有个小细节因为 OCCT 的库名很长、文件数量也多建议在 Visual Studio 的属性管理器里统一管理库目录而不是手动一个个添加 lib 文件不然多个工程来回切配置时很容易漏掉某一个依赖。3. 核心实现拆解与二次开发3.1 三维视图区如何桥接 OCCT 与 Qt三维视图区是整个项目里我最推荐精读的部分。它的本质是拿到一个 QWidget 的系统窗口句柄交给 OpenCASCADE 的窗口类去管理然后让 OCCT 自己负责 OpenGL 渲染。整个桥接过程可以用一段伪代码来理解在自定义 QWidget 子类的 showEvent 里调用 winId() 获得窗口句柄构造 WNT_Window再传入 V3d_Viewer 创建视图。此后不需要你在 QWidget 的 paintEvent 里写任何绘制代码OCCT 会通过内部 OpenGL 上下文完成渲染你只需要在 resizeEvent 里通知视图更新尺寸。这段桥接代码容易出错的地方在于执行顺序。窗口必须先显示winId 才是有效的视图创建要在 Viewer 已初始化之后首次 Resize 之前不要去触发任何鼠标交互。如果按这个顺序写模型显示和鼠标操作基本不会出问题。很多人在这一步卡住是因为把 OpenCASCADE 当成了普通渲染库试图在 Qt 的 paint 事件里自己画图实际上窗口句柄交出去之后绘制工作已经完全不在 Qt 的控制范围内了。3.2 建模命令的三层结构JellyCAD 里点击“创建圆柱”这类命令背后是一个值得借鉴的三层设计。第一层是几何构建层调用 BRepPrimAPI_MakeCylinder 之类的类生成 TopoDS_Shape 对象第二层是可视化层把 TopoDS_Shape 包装成 AIS_Shape然后交给 AIS_InteractiveContext 显示第三层是界面层负责把用户输入的半径、高度等参数传给几何构建层同时刷新特征树。举个例子创建一个圆柱体的核心代码大致是TopoDS_Shape cylinder BRepPrimAPI_MakeCylinder(radius, height); Handle(AIS_Shape) aisCylinder new AIS_Shape(cylinder); context-Display(aisCylinder, Standard_True);第一行生成的是精确的几何拓扑数据后面两行才让它显示出来。如果你要做二次开发我建议把“生成实体”和“显示实体”拆成两个独立函数这样后续需要导出 STEP、IGES或者做参数驱动都可以直接复用生成函数不需要动界面代码。布尔运算也是一样的思路BRepAlgoAPI_Fuse、BRepAlgoAPI_Cut、BRepAlgoAPI_Common 分别对应并、差、交运算前最好对参与运算的实体做一次粗略检查避免两个完全没有交集的实体强行做布尔导致异常。3.3 UI 状态机交互逻辑的本质很多读不懂 JellyCAD 交互逻辑的人问题都出在没理解它的状态机。三维建模软件里鼠标点击、按钮按下、参数面板变化这些都是事件但是同一个鼠标左键点击在不同状态下含义完全不同在“预览”状态下是旋转视图在“选择”状态下是选中对象在“绘制草图”状态下是落点。JellyCAD 通常会用枚举变量记录当前命令状态再用 Qt 的信号槽把按钮点击和视图鼠标事件接到一个统一的分发函数里。视图本身不知道某次点击之后该干什么它只负责把事件发给控制层控制层根据当前状态决定行为。这种解耦非常彻底也解释了为什么视图代码里看起来没有直接的建模逻辑但模型却能随着操作发生变化。我自己仿照这个结构加过一个“两点测距”功能最开始直接在视图鼠标事件里写测量逻辑结果加第二个命令时发现到处互相干扰。后来改成状态机写法在进入测量状态后再把鼠标事件路由到测量模块整个流程就顺畅多了。这个经验对任何做 CAD 交互的人都适用先定好状态再写事件处理。4. 打包发布与排错指南4.1 windeployqt 部署流程开发环境能跑只是第一步把程序拷到别的机器上还能跑才是发布。Qt 项目经典的发布问题就是缺 DLL最常见的错误是“no qt platform plugin could be initialized”。这个错误通常是 platforms 目录没带全或者 windeployqt 没有成功执行。我常用的部署步骤是在 Release 模式下编译出 JellyCAD.exe新建一个干净目录把 exe 拷进去打开 Qt 对应套件的命令行工具比如 Qt 5.15.2 MSVC2019 64-bit执行windeployqt JellyCAD.exe工具会自动拷贝 Qt 相关 DLL 和插件手动拷贝 OpenCASCADE 的运行时 DLL包括 TK 系列库、freetype.dll、tbb.dll 等用 Dependencies 工具扫描一遍确认没有遗漏。有一点需要特别提醒OpenCASCADE 的运行时文件可能涉及 plugins、resources 等子目录拷贝时要保留目录结构不能只拉一层 DLL。否则程序可能在启动时不报错等到读取某个格式或加载某个功能时才崩溃那种问题反而更难定位。windeployqt 本身也不是万能的它只处理 Qt 自身的依赖OCCT 和第三方库都得手动跟上。4.2 常见问题速查以下这些问题大多不是 JellyCAD 独有而是整个 OCCT 加 Qt 开发流程的共性问题我把它们整理成一张速查表现象可能原因处理办法编译链接时出现大量未解析符号OCCT 库路径或宏定义不对检查 OpenCASCADE_DIR确认库目录和预处理宏没有缺失启动时提示找不到 Qt platform plugin部署时 platforms 目录缺失重新运行 windeployqt确保 qwindows.dll 存在程序在带中文路径的目录下崩溃OCCT 文件解析或 Qt 字体路径问题工程路径和安装路径全部改为英文视图区黑屏但程序未崩溃winId 获取过早或 OpenGL 上下文初始化失败确认视图初始化顺序更新显卡驱动后再试Debug 下正常、Release 下崩溃Debug 和 Release 第三方库混用统一使用同一个编译模式下的所有依赖库模型能显示但无法选中AIS 选择模式没有设置调用合适的 SetSelectionMode检查 Context 当前状态5. 从项目里带走的经验5.1 学习与二次开发的路径建议如果你刚拿到这个项目我推荐按这样的顺序读代码先看 CMakeLists 和主入口知道整个程序是怎么被组织起来的然后看三维视图类的创建和事件转发接着分析一个完整的建模命令从按钮点击到实体显示完整走一遍最后再看特征树和对象管理。这条路径能让你在半天内建立起整体心智模型比从头到尾盲目翻代码效率高得多。在此基础上做二次开发我建议先加一个“导入 STEP 文件”的功能。这个功能不需要自己写任何解析器OpenCASCADE 的 STEPControl_Reader 已经封装好了你只需要把 Qt 文件对话框返回的路径传进去再把得到的 TopoDS_Shape 显示出来。这个练手任务会逼着你把文件操作、异常捕获、视图刷新、状态更新全部串起来一次能学到很多。5.2 调试与日志习惯最后一个经验也是我和很多做 CAD 开发的同行一致的看法一定要把日志系统分开。OpenCASCADE 侧的消息通过 SetMessage 回调单独记录Qt 侧的事件用 qDebug 输出两边都用时间戳标注。很多崩溃问题其实就出在某一个侧的状态异常有了隔离日志一眼就能定位是几何引擎挂了还是界面状态错了。这个习惯我后来在所有的图形项目里都在用建议你一进项目就把它搭好。本文还有配套的精品资源点击获取