简介这是一份面向C开发者的Qt与OpenCASCADE三维建模平台资源适合需要在Qt界面内集成OCC内核、快速实现常规三维建模功能的工程师、学生或研究者。资源解决了OCC原生视图与Qt窗口体系融合不便的问题作者将三维视图封装为可直接复用的控件并提供建模类封装调用即可创建立方体、圆柱、圆锥、球体、圆环、管道等基础几何体界面中还带有对应图元的按钮工具方便交互操作与二次扩展也可在此基础上按需添加新的几何类型。压缩包共94个文件体积约18.05MB其中66个dll为OCC运行时功能库5个cpp与4个h为源码实现ui文件定义界面布局pro和vcxproj/sln分别对应Qt Creator与Visual Studio工程另有11张png作为图标资源Release目录下还提供exe可执行程序便于直接体验运行效果。已有3218人学习下载目录结构较为清晰读者可对照源码研究OCC与Qt的嵌入方式、控件封装思路及建模接口设计也可作为项目起步框架继续完善功能。1. QtOpenCASCADE三维建模平台一套能落地的桌面CAD组合拳QtOpenCASCADE三维建模平台说白了就是用Qt解决界面、交互和业务流用OpenCASCADEOCCT解决几何建模、拓扑运算和渲染显示。很多团队一开始都想自研几何内核结果往往半年过去了连一个能拖动旋转的方块都交不出来。与其在数学库里耗尽预算不如把OCCT当成黑匣子用起来把人力集中在行业逻辑上。这个方向适合要做CAD/CAM工具、参数化建模软件、装配仿真或测量软件的开发者。这篇笔记会把架构选型、最小工程、交互接入和最容易卡住项目的坑一次性讲清楚目标是让你照着做两周内跑起一个能交互的三维建模原型。2. 用CMake把Qt和OpenCASCADE跑通最小工程配置与V3d_View初始化2.1 工具链对齐是第一道坎MSVC还是MinGW网上绝大多数“跑不起来”的问题根源不在代码而在工具链。OCCT编译出来是一堆DLL和一个庞大的头文件树Qt 5.15.2也有MSVC和MinGW两种主流构建。两者C ABI不同混用轻则链接报错重则运行期直接崩。我的经验是新项目优先选MSVC配合Visual Studio调试器成熟OCCT的预编译成果多半也是MSVC只有在需要跨平台到Linux嵌入式或偏好MinGW工作流时才选MinGW而且必须用Qt安装包自带的MinGW不能用系统里另装的MinGW否则标准库和异常机制不一致进构造函数就崩。Qt版本上5.15.2 LTS仍然是很多商用项目的稳妥底子离线安装包齐全发布生态成熟。Qt 6的分包方式变了OCCT官方对Qt 6的适配也早已跟上新项目可以直接上。但有一点必须记住find_package找到的必须是同一个Qt根目录不能在CMake里写一个路径运行时PATH里又放着另一个版本这类矛盾会让编译过、运行崩的戏码反复上演。2.2 CMakeLists.txt最小工程两个find_package和一组链接库一个能跑通的最简CMake配置如下我一般不手写-l参数而是让CMake把OCCT的库列表取出来。cmake_minimum_required(VERSION 3.16) project(OCCQtDemo) set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) find_package(Qt5 5.15 REQUIRED COMPONENTS Widgets) find_package(OpenCASCADE REQUIRED) add_executable(OCCQtDemo main.cpp occviewer.cpp ) target_link_libraries(OCCQtDemo PRIVATE Qt5::Widgets ${OpenCASCADE_LIBRARIES} )这里的逻辑是Qt用Qt5::Widgets导入目标OCCT用${OpenCASCADE_LIBRARIES}变量展开。OCCT的CMake配置装好后会生成OpenCASCADEConfig.cmake里面已经把所有依赖的toolkit库按顺序列好不需要你自己挑TKernel、TKMath、TKBRep、TKV3d挑漏了反而浪费时间。个别版本还会提供OpenCASCADE::TKernel这种导入目标如果你只用少量模块可以把变量换成按需目标但首次跑通不推荐精简。配置时注意CMAKE_PREFIX_PATH要把Qt和OCCT两个根目录都写进去分号分隔。比如Windows下cmake -S . -B build -DCMAKE_PREFIX_PATHD:/Qt/5.15.2/msvc2019_64;D:/occt/lib/cmake cmake --build build --config Release找不到OpenCASCADEConfig.cmake时第一反应不是怀疑安装而是看D:/occt/lib/cmake里有没有这个文件以及CMAKE_PREFIX_PATH是否写到了lib/cmake的上一层。2.3 在QOpenGLWidget里初始化V3d_ViewerOCCT的显示栈是四层关系OpenGl_GraphicDriver负责OpenGL底层V3d_Viewer是场景V3d_View是相机视角AIS_InteractiveContext管对象显示与拾取。在Qt里最顺的做法是让窗口继承QOpenGLWidget在initializeGL里初始化这四件套。#include QOpenGLWidget #include OpenGl_GraphicDriver.hxx #include V3d_Viewer.hxx #include V3d_View.hxx #include AIS_InteractiveContext.hxx #include AIS_Shape.hxx #include BRepPrimAPI_MakeBox.hxx class OCCViewer : public QOpenGLWidget { Q_OBJECT public: Handle(V3d_Viewer) m_viewer; Handle(V3d_View) m_view; Handle(AIS_InteractiveContext) m_context; protected: void initializeGL() override; void paintGL() override; void resizeGL(int w, int h) override; }; void OCCViewer::initializeGL() { // GraphicDriver 必须比 viewer 活得久用静态对象挂住 static Handle(OpenGl_GraphicDriver) aDriver; if (aDriver.IsNull()) { aDriver new OpenGl_GraphicDriver(new Aspect_DisplayConnection()); } if (m_viewer.IsNull()) { m_viewer new V3d_Viewer(aDriver); m_viewer-SetDefaultLights(); m_viewer-SetLightOn(); } m_context new AIS_InteractiveContext(m_viewer); m_view m_viewer-CreateView(); // 把 Qt 的窗口句柄交给 OCCT 的视图 Handle(Aspect_Window) aWin new Aspect_NeutralWindow((Aspect_Drawable)winId()); m_view-SetWindow(aWin); m_view-SetBackgroundColor(Quantity_NOC_BLACK); m_view-SetImmediateUpdate(false); m_view-MustBeResized(); // 放一个测试立方体 TopoDS_Shape box BRepPrimAPI_MakeBox(100.0, 80.0, 60.0); Handle(AIS_Shape) aisBox new AIS_Shape(box); m_context-Display(aisBox, Standard_True); } void OCCViewer::paintGL() { if (m_view.IsNull() || !m_view-IsDefined()) return; m_view-Redraw(); } void OCCViewer::resizeGL(int w, int h) { m_view-MustBeResized(); m_view-Redraw(); }这段代码里几个参数值得留意。SetImmediateUpdate(false)表示拾取高亮、显示属性变化时不立刻重绘由paintGL统一驱动能显著降低高频鼠标移动时的重绘次数。Aspect_NeutralWindow是我在Windows和X11上常用的简化窗口封装直接传Qt的winId()就能让OCCT拿到原生句柄如果你在Wayland下跑需要换成OCCT官方Qt样例里的专用窗口实现否则视图绑定会失败。paintGL里的IsDefined()是护身符窗口还没完成绑定就执行Redraw是黑屏的常见原因之一。3. 把三维建模操作接到界面上拾取、视图控制与参数化建模代码骨架3.1 鼠标事件坐标映射Qt的窗口像素坐标可以直接喂给OCCTOCCT的选择接口按窗口像素坐标工作原点在左上角和Qt的QMouseEvent::pos()方向一致所以不需要做y轴翻转。真正要处理的是高DPI缩放Qt在高分屏下pos()返回的仍是逻辑像素而OCCT吃的是物理像素需要在传给MoveTo之前乘上devicePixelRatioF()。void OCCViewer::mousePressEvent(QMouseEvent* e) { const qreal dpr devicePixelRatioF(); const int x int(e-pos().x() * dpr); const int y int(e-pos().y() * dpr); if (e-button() Qt::LeftButton) { // 先 MoveTo 再 Select否则拾取状态停留在上一次位置 m_context-MoveTo(x, y, m_view, Standard_True); m_context-Select(x, y, m_view, Standard_True); update(); } }MoveTo负责把鼠标位置同步给OCCT的动态高亮机制Select执行拾取。很多刚上手的人只写Select不写MoveTo结果第一次点击总是选不中这就是原因。Select的最后一个布尔参数控制是否立刻刷新视图交互频繁时改传Standard_False等鼠标松开或空闲时统一update()。视图旋转用中键拖拽OCCT里做旋转的标准做法是先StartRotation再Rotationvoid OCCViewer::mouseMoveEvent(QMouseEvent* e) { const qreal dpr devicePixelRatioF(); const int x int(e-pos().x() * dpr); const int y int(e-pos().y() * dpr); if (e-buttons() Qt::MiddleButton) { if (!m_rotating) { m_view-StartRotation(x, y); m_rotating true; } else { m_view-Rotation(x, y); } update(); } else { m_context-MoveTo(x, y, m_view, Standard_True); update(); } }旋转的另一个做法是V3d_View::Rotate(a, b, c)指定欧拉角但会丢失拖拽的跟手手感。StartRotation/Rotation内部按视角把平面位移折算成球面旋转是OCCT原生手感最好的方式。3.2 拾取与高亮双击改颜色为什么必须Redisplay拾取之后拿到的对象是Handle(AIS_InteractiveObject)。想改它的显示属性很多人直接调SetColor然后发现视图纹丝不动这不是没生效而是OCCT的显示属性更新不在即时刷新路径上。下面这段双击改色的代码是常用模版void OCCViewer::mouseDoubleClickEvent(QMouseEvent* e) { const qreal dpr devicePixelRatioF(); const int x int(e-pos().x() * dpr); const int y int(e-pos().y() * dpr); m_context-Select(x, y, m_view, Standard_False); if (m_context-HasSelected()) { Handle(AIS_InteractiveObject) obj m_context-SelectedInteractive(); m_context-SetColor(obj, Quantity_NOC_RED, Standard_False); m_context-Redisplay(obj, Standard_True); update(); } }最后一行Redisplay是关键。SetColor只是改了对象属性里的颜色值OCCT不会自动重建显示对象Redisplay才重新生成presentation。顺带一提如果你要取回底层几何体做后续计算要把对象向下转型Handle(AIS_Shape) aisShape Handle(AIS_Shape)::DownCast(obj); if (!aisShape.IsNull()) { TopoDS_Shape shape aisShape-Shape(); // 拿去做 BRepTools::Dump、布尔运算等 }DownCast之后一定要判空因为拾取到的可能是AIS_Point、AIS_Line等非Shape类型直接取Shape会崩。3.3 参数化建模对话框输入生成立方体并安全替换旧实体建模命令的落点是把用户参数变成TopoDS_Shape。OCCT的BRepPrimAPI提供了一组现成的构造器最常见的立方体有两种写法void MainWindow::createBox(double xLen, double yLen, double zLen) { // 第一种以原点为中心展开的尺寸构造 TopoDS_Shape box1 BRepPrimAPI_MakeBox(xLen, yLen, zLen); // 第二种指定角点位置 gp_Pnt corner(10.0, 20.0, 30.0); TopoDS_Shape box2 BRepPrimAPI_MakeBox(corner, gp_Pnt(10.0 xLen, 20.0 yLen, 30.0 zLen)); Handle(AIS_Shape) ais new AIS_Shape(box2); m_viewer-m_context-Display(ais, Standard_True); m_viewer-update(); }第二种写法更符合“用户指定左下角坐标”的直觉工程上用得多。圆柱、球、圆环分别对应BRepPrimAPI_MakeCylinder、MakeSphere、MakeTorus参数都是半径、长度这类几何量接口风格一致。如果场景里已经有一个旧模型用户改完参数要原地替换最忌讳的做法是直接Display新的旧的那份会叠在场景里。安全流程是三步先Remove旧的AIS对象再创建新AIS对象最后Display。旧AIS对象的Handle如果不在你手里可以用拾取拿m_context-Remove(selectedObj, Standard_False); m_context-Display(newAisObj, Standard_True); m_context-Redisplay(newAisObj, Standard_True);Remove的第二个布尔参数同样控制是否立即刷新连续做多个操作时传false能避免中间帧闪烁这是三维平台里“不闪”的关键技巧。4. 渲染与交互框架选型QWidget、QML和Qt MVVM的取舍4.1 QOpenGLWidget默认方案但有两个初始化参数要设置OCCT官方Qt样例走的是QWidget加QOpenGLWidget这条路我推荐新项目也默认用这套。QOpenGLWidget把OpenGL上下文和窗口生命周期绑在一起OCCT只需要拿到窗口句柄就能渲染事件处理用原生QMouseEvent调试直观。初始化时两个细节值得特意写上setAutoFillBackground(false); // 防止 QWidget 默认清屏把 OCCT 的渲染结果擦掉 setUpdateBehavior(QOpenGLWidget::NoPartialUpdate); // 每次重绘都更新整个视口setAutoFillBackground(false)是黑屏的高频元凶尤其当你把OCCViewer塞进布局里的DockWidget时。NoPartialUpdate则告诉Qt不要只更新脏区域OCCT内部自己管理重绘区域Qt的局部更新优化反而会导致残影。QML方案不是不行OCCT渲染需要一个原生的GL上下文QML里通常通过QQuickFramebufferObject把OCCT的OpenGL渲染重定向到FBO上再在场景图里合成。问题是多了一层FBO拷贝事件坐标还要自己从QML坐标映射到窗口像素拖拽旋转的跟手性调试起来成本更高。如果你的团队已经是QML技术栈且对渲染节点插入有信心可以挑战否则我劝你用QWidget。4.2 MVVM框架与OCCT的边界控制层独立几何层别套Qt生态里确实有非官方的qt mvvm框架也有Qt自带的Model/View架构。很多团队一上来就想把三维平台做成MVVM把AIS对象塞进ViewModel很快会发现OCCT的AIS_InteractiveContext本身就是一个搞状态管理的大家伙选择集、高亮、显示模式全在里面你做另一套ViewModel来镜像它等于维护两份状态同步起来就是灾难。我常用的做法是只做一层命令封装不碰OCCT内部状态class CreateBoxCommand { public: CreateBoxCommand(AIS_InteractiveContext* ctx) : m_ctx(ctx) {} void execute(double l, double w, double h) { TopoDS_Shape shape BRepPrimAPI_MakeBox(l, w, h); Handle(AIS_Shape) ais new AIS_Shape(shape); m_ctx-Display(ais, Standard_True); } private: AIS_InteractiveContext* m_ctx; };这样ViewModel只管Qt侧的输入框、参数校验和按钮状态几何操作收敛到Command里。要支持撤销重做可以用QUndoCommand把execute和undo分别写成Display和RemoveOCCT在这里拿回一个AIS_Shape的Handle不需要反向同步。记住一条边界规则凡是OCCT里已经有状态的东西不镜像凡是你想让它进入业务流的东西用命令包一层。4.3 多视图联动一个GraphicDriver多个V3d_View三维平台常需要“主视口加三视图”或“局部放大镜”这类多视图布局。OCCT允许一个V3d_Viewer下创建多个V3d_View它们共享同一个场景和AIS上下文只要为每个View挂接不同的窗口句柄就行。对应到Qt里放两个QOpenGLWidget分别绑定各自的句柄与View。但OpenGl_GraphicDriver必须保持单例如果两个Widget各自new一个GraphicDriver第一个的OpenGL上下文就会和第二个互相踩表现是其中一个窗口黑屏或闪退。多视图联动的常用做法是让次视图跟随主视图的投影方向void LinkView::syncView(const Handle(V3d_View) master) { if (m_view master) return; m_view-SetProj(master-ProjVx(), master-ProjVy(), master-ProjVz()); m_view-Redraw(); }ProjVx等接口返回当前视图的投影方向向量分量把它推到次视图后再Redraw就能实现“主视图转侧视图跟着转”的效果。注意别在鼠标事件里同步调用最好改成定时器或空闲时同步否则两个视图互相触发刷新会画成鬼影。5. QtOpenCASCADE避坑记录从闪退到黑屏的五个现实问题5.1 退出程序崩溃报错停在0000005现象程序关闭时弹窗显示内存访问异常调试器里栈顶往往在AIS_InteractiveContext或V3d_Viewer析构附近断点都抓不住纯随机。原因QOpenGLWidget析构时会先销毁OpenGL上下文而OCCT的GraphicDriver还引用着这个上下文里的GL资源析构顺序反了。更隐蔽的是OCCT的Handle引用计数由旧编译器生成和Qt对象跨DLL析构时谁先释放那一下的时序完全不可控。解决在OCCViewer析构里手动按顺序清空不要等编译器自动析构。OCCViewer::~OCCViewer() { makeCurrent(); if (!m_context.IsNull()) { m_context-RemoveAll(Standard_False); m_context.Nullify(); } if (!m_view.IsNull()) { m_view-Remove(); m_view.Nullify(); } if (!m_viewer.IsNull()) { m_viewer.Nullify(); } doneCurrent(); }RemoveAll把场景里所有对象先摘掉再逐个Nullify Handle。顺序不能乱先上下文再视图最后场景。GraphicDriver那个静态Handle留到进程退出时析构不主动清。5.2 窗口能显示但只有背景色模型不见现象程序能启动QOpenGLWidget也占了一块区域背景色正确就是没有几何模型控制台也没有报错。原因分三类。一是OpenGL版本不满足OCCT新版默认按OpenGL 3.3起渲染虚拟机、远程桌面和部分旧显卡只有2.1虽然能创建窗口但画不出东西。二是窗口句柄没绑成功SetWindow在Wayland或特殊窗口环境下拿到无效句柄模型其实加载了但显示不到当前窗口上。三是paintGL里没有调用Redraw或者被Qt的部分更新优化吞掉了。解决先单独创建一个纯色QOpenGLWidget测底子用glGetString(GL_VERSION)打印版本再确认SetWindow之前winId()不是0最后把setUpdateBehavior(QOpenGLWidget::NoPartialUpdate)加上。如果确定是OpenGL版本问题换更早的OCCT版本或换显示环境不要浪费时间在代码层面找。5.3 报“cannot mix incompatible qt library (version ex50601)”这类版本错乱现象程序跑起来直接弹fatal error说Qt库版本不兼容版本号跟你实际用的对不上甚至出现0x50601这种非常老的数字。原因运行路径PATH里的Qt DLL和编译时用的不是同一套典型情况是系统里装了多个Qt或者Qt安装包的bin目录还残留在PATH里程序启动时优先加载了错误的Qt5Core.dll。OCCT节点里如果也带着Qt依赖更容易把版本搅浑。解决编译和运行都指向同一个Qt根目录。项目里不要依赖PATH统一用CMAKE_PREFIX_PATH指定发布时用同版本Qt自带的windeployqt生成运行依赖部署目录里严格放一套Qt DLL。调试时可以打印QLibraryInfo::location(QLibraryInfo::LibrariesPath)和::bin确认加载路径两个不一致就清理PATH重来。5.4 链接时报“cannot find -lpublic”但库明明都在现象CMake配置通过编译也通过链接阶段报cannot find -lpublic网上搜不出所以然。原因这个public不是你的代码是CMake或Makefile里某个变量展开成了空字符串后面的库名被推进了-l参数末位。常见于手写了一长串target_link_libraries中间某个${OpenCASCADE_LIBRARIES}没被正确解析或者变量里带了分号、空格被shell拆分成两个链接项。解决先用一行打印排查变量实际内容。message(STATUS OCC_LIBS[${OpenCASCADE_LIBRARIES}])方括号是为了看清首尾有没有空格。正确做法是不手拼链接项直接用find_package展开。真要手写OCCT库名时注意对齐TKernel、TKMath、TKBRep、TKV3d这些准确拼写少一个字母拼成TKBRepx之类的链接器也会给你报一个莫名其妙的cannot find。5.5 板子上报“could not find the qt platform plugin linuxfb”现象交叉编译好的Qt程序拷到ARM板子上运行时提示找不到qt.qpa.plugin里的linuxfb平台插件程序直接退出。树莓派和国产板卡上特别常见。原因Qt的QPA插件是可加载模块libqlinuxfb.so必须和可执行文件放在一起并且位于可执行文件相对路径的platforms/子目录下。交叉编译时如果只拷了可执行文件和Qt核心库漏了插件目录就会这样。另一个原因是编译Qt时没启用linuxfb插件整个库从源头就没有它。解决确认目标机的Qt库版本和编译机一致在可执行文件旁边放一个qt.conf[Paths] Plugins ./plugins然后把libqlinuxfb.so放到plugins/platforms/目录下。如果还不行运行前显式指定export QT_QPA_PLATFORMlinuxfb。这种方法能诊断出插件存在但没加载的问题。交叉编译Qt时建议同时把linuxfb和eglfs两个平台插件都编进去一个做纯软件渲染兜底一个做GPU加速。6. 进阶思路大模型加载不卡交互的一个异步方案建模平台免不了要打开几十兆的STEP文件。直接在UI线程里读文件加TransferRoots模型一大界面就冻住几秒旋转操作像放PPT。我的做法是把加载丢到后台线程用信号把TopoDS_Shape传回主线程显示前再控制一下网格精度。class LoadModelWorker : public QObject { Q_OBJECT public slots: void loadStep(const QString file) { STEPControl_Reader reader; reader.ReadFile(file.toLocal8Bit().constData()); reader.TransferRoots(); emit loaded(reader.OneShape()); } signals: void loaded(TopoDS_Shape shape); };主线程里连接时要注意两点。第一TopoDS_Shape跨线程传递需要注册元类型否则QueuedConnection的拷贝会失败qRegisterMetaTypeTopoDS_Shape(TopoDS_Shape);第二Handle内部引用计数是原子的形状对象在后台线程创建的句柄跨线程共享没有崩溃风险但不要让后台线程再去操作AIS_InteractiveContext所有显示操作必须回到主线程的GL上下文里执行connect(worker, LoadModelWorker::loaded, this, [this](const TopoDS_Shape shape) { Handle(AIS_Shape) ais new AIS_Shape(shape); m_context-Display(ais, Standard_True); }, Qt::QueuedConnection);显示之前还可以压一下网格密度。OCCT在首次显示时会自动做网格划分默认精度对超大模型生成海量三角形。用BRepMesh_IncrementalMesh预设一个0.5的偏置值让曲面离散得粗一点视觉上差别不大帧率却能翻倍。等到用户真正需要特写时再局部加密网格这就是“先用低精度保住交互后台再精化”的做法。我最早做这类平台时第一次打开一个两百兆的STEP文件直接卡死到系统弹出无响应窗口。后来才明白渲染层永远不应该等几何加载这是三维建模平台里最不值得走的弯路。希望帮到你。本文还有配套的精品资源点击获取