企业官网建设流程全解析

简介：JellyCAD-master压缩包提供了一款基于OpenCASCADE几何引擎、采用QT搭建界面框架的三维建模软件源码，面向机械设计、产品开发和三维图形学习者。软件支持创建正方体、长方体、圆柱体等基础几何体，借助参数化建模只需调整尺寸参数即可快速成形，同时支持点线绘制和IGES格式导入导出，便于与SolidWorks等主流CAD工具交换数据。包内共20个文件，以4个C++源文件、4个头文件以及UI、qrc资源文件为核心，附5张模型效果示例图、工程构建文件与说明文档，整体仅76KB，结构紧凑易读。通过阅读源码可直观理解OpenCASCADE实体造型、曲线曲面构建与QT交互界面如何无缝整合，适合入门级开发者借鉴小型CAD项目的完整架构。目前已有1137人学习下载，对刚接触三维建模库集成或想快速搭建建模工具的用户颇具参考价值。

1. 一个能建出方块的三维建模软件，为什么非要用OpenCASCADE和Qt

第一次见到JellyCAD这个仓库名时，我的第一反应是它又是一款三维建模学习项目。但在"基于opencascade、以QT为ui的三维建模软件"这句描述里，藏着桌面CAD工具最实用的一组技术选型：几何内核交给OpenCASCADE，界面与交互交给Qt。要做内部三维工具、毕业课题或者垂直行业建模软件的人，多数不需要自研几何内核，OCCT把曲面、实体、布尔运算这些最重的活包了；Qt负责窗口、菜单、树形控件与事件循环，省掉大量原生UI工作。两者结合，正好覆盖三维建模软件从"能建模型"到"能交互"的整条链路。下面按一条可以照着复现的路径讲：选型依据、CMake工程与第一个方块、鼠标交互与模型树联动，最后是我实际开发里翻过车的高频坑。新手跟着走能跑通，熟手可以挑参数细节和边界问题看。

2. 先分清职责：OCCT与Qt的边界清楚，后面才不会反复返工

JellyCAD这类项目最容易犯的错，是上来就把OCCT的显示、建模、数据管理一股脑塞进界面代码里。三个月后连自己都分不清一个功能该写在哪个模块。所以动手前先把职责边界定死。

2.1 谁在管几何数据：BRep拓扑与建模接口

OpenCASCADE的几何核心建立在边界表示（BRep）之上。一个实体不是简单的一个网格，而是由一系列拓扑元素组成：Vertex（顶点）、Edge（边）、Wire（轮廓）、Face（面）、Shell（壳）、Solid（实体）、Compound（复合体）。每一层都挂着自己的几何数据，比如Edge上有曲线方程，Face上有曲面方程。这个分层结构是整个软件的地基，显示、选择、布尔运算都要遍历它。

建模接口在OCCT里分得很清晰。基本体用BRepPrimAPI_MakeBox、BRepPrimAPI_MakeCylinder这类类，布尔运算走BRepAlgoAPI_Boolean，倒角用BRepFilletAPI_MakeFillet，扫掠用BRepOffsetAPI_MakePipe。每个类都是"构造器模式"，构造完调用Shape()拿到TopoDS_Shape。TopoDS_Shape本身是一个轻量句柄，真正的数据由内部引用计数管理，赋值和传参都不会发生全量拷贝，这是你可以在信号槽和容器里自由传递模型的前提。

为什么选OCCT而不是商业内核？最现实的原因是授权成本。商业几何内核通常按席位或按部署收费，做开源项目、内部工具和教学Demo几乎不可能承受。OCCT虽然在一些高级曲面操作和超大规模装配性能上不如商业内核，但对JellyCAD这个量级的三维建模软件完全够用。它的另一个隐性优势是自带AIS框架，把"几何数据"和"屏幕上的可交互对象"分开，省去自己写显示清单的工作。

2.2 谁在管窗口与事件：Qt的应用外壳

Qt在JellyCAD里不只是一个外皮，它承担了三件具体的事。第一，主窗口框架：菜单栏、工具栏、左侧模型树dock、右侧属性面板、中央三维视口，这些用QMainWindow加dock布局可以在半天内搭完。第二，事件循环：鼠标点击、滚轮、键盘快捷键、菜单触发都以事件形式进入Qt队列，你再把这些事件翻译成OCCT能理解的坐标和操作。第三，业务数据结构：模型树里的项目、颜色、可见性、图层这类UI状态，应该由Qt模型类管理，不要塞进OCCT的TopoDS_Shape里。

这里有一个容易越界的点：很多人试图把OCCT的拓扑结构直接映射成QTreeView的数据源，结果遍历到一万个面时界面卡死。我的习惯是维护一个独立的业务模型层，每个实体分配一个整型ID，ID关联到TopoDS_Shape和AIS对象，QTreeWidgetItem的data里只存ID。这样模型树、视图选择、属性面板三个模块都能以ID为纽带联动，谁也不直接碰别人的内部数据。

2.3 显示链路的核心：AIS_InteractiveContext与V3d_View

OCCT的显示架构是一条从底向上的链路：Graphic3d_GraphicDriver创建渲染驱动，V3d_Viewer管理场景级状态，V3d_View代表一个视口，AIS_InteractiveContext管理所有交互对象，AIS_InteractiveObject是你在屏幕上看到的"可交互形状"。初始化代码通常在自定义的视口控件里做，下面是CADViewport这个QWidget子类的核心初始化逻辑：

#include <Aspect_DisplayConnection.hxx> #include <OpenGl_GraphicDriver.hxx> #include <V3d_Viewer.hxx> #include <V3d_View.hxx> #include <AIS_InteractiveContext.hxx> void CADViewport::init3D() { // 图形驱动是整个渲染栈的底座，OpenGL后端是当前最通用的选择 Handle(Aspect_DisplayConnection) disp = new Aspect_DisplayConnection(); Handle(OpenGl_GraphicDriver) driver = new OpenGl_GraphicDriver(disp); // Viewer负责场景级状态：光源、环境、渲染模式 m_viewer = new V3d_Viewer(driver); m_viewer->SetDefaultLights(); m_viewer->SetLightOn(); // 所有AIS交互对象都注册在这个上下文里，选择、高亮都由它管 m_context = new AIS_InteractiveContext(m_viewer); // View是我们面向的单个视口，后面要把它绑定到Qt控件的原生窗口上 m_view = m_viewer->CreateView(); m_view->SetBackgroundColor(Quantity_Color(Quantity_NOC_WHITE)); m_view->SetWindow(createOcctWindowFromWidget(this)); m_view->MustBeResized(); }

createOcctWindowFromWidget是按平台封装的小函数，Windows上把QWidget的winId包进WNT_Window，X11下包进Xw_Window。这里要注意一个细节：V3d_Viewer创建时必须挂driver，否则后面AIS对象无法显示；SetDefaultLights和SetLightOn两行如果省掉，模型显示出来就是纯黑，这是JellyCAD初始化里第一个高频坑。AIS_InteractiveContext是后面所有选择、高亮、拾取操作的总入口，务必把它保存成成员变量。

3. 从空工程到第一个方块：CMake配置、窗口骨架与建模命令

把架构想清楚之后，下一步是让工程真正跑起来。这一章从上往下给你一套最小可运行的工程配置，跟着做完，点击菜单就能在三维视图里看到第一个方块。

3.1 把OCCT和Qt用CMake接进同一个工程

OCCT官方发布包自带CMake配置，安装后可以通过find_package(OpenCASCADE)引入，省去手写一大堆库路径。注意版本选择：安装时确认是同一个编译器构建出来的包，MSVC版本、Release/Debug类型都不能混。CMakeLists.txt的核心部分如下：

cmake_minimum_required(VERSION 3.16) project(JellyCAD) set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) # OCCT的moc文件需要Qt自动处理，这个必须开 set(CMAKE_AUTOMOC ON) # 指定OCCT安装路径，Windows下通常是安装目录内的lib/cmake/opencascade set(OCCT_DIR "D:/third_party/occt/lib/cmake/opencascade" CACHE PATH "OpenCASCADE config dir") find_package(OpenCASCADE REQUIRED) # Qt5和Qt6都可以，保持与编译OCCT时相同的编译器即可 find_package(Qt5 COMPONENTS Widgets REQUIRED) add_executable(JellyCAD main.cpp MainWindow.cpp MainWindow.h CADViewport.cpp CADViewport.h ) target_include_directories(JellyCAD PRIVATE ${OpenCASCADE_INCLUDE_DIR} ) target_link_libraries(JellyCAD PRIVATE ${OpenCASCADE_LIBRARIES} Qt5::Widgets )

OCCT的CMake包通常已经聚合了所有TK模块，直接链接OpenCASCADE_LIBRARIES是最省事的做法。但如果你的OCCT安装包里没有提供聚合变量，可以手动选模块链接。下面这张表是JellyCAD最常用到的模块，链接报错时对着它检查：

手动链接时顺序也有讲究，静态库依赖要放在后面，比如TKernel最后链，否则MSVC下会报一堆无法解析的外部符号。我一般习惯把TKMesh和TKOpenGl都列上，显示相关的符号经常在你意想不到的地方被引用。

提示：OCCT的Debug库和Release库不能混用，Qt也要对应匹配。构建类型不统一，运行时会撞出一堆看似随机的崩溃。

3.2 MainWindow骨架：中心区域挂三维视口

主窗口用QMainWindow搭建，中心区域放CADViewport，左侧放模型树dock。这是最常见的CAD布局，代码量不大：

#include <QMainWindow> #include <QDockWidget> #include <QTreeWidget> #include <QMenuBar> MainWindow::MainWindow(QWidget *parent) : QMainWindow(parent) { // 中心区域就是三维视口，必须让它占满大部分空间 m_viewport = new CADViewport(this); setCentralWidget(m_viewport); // 左侧模型树，用QTreeWidget存业务节点 m_treeWidget = new QTreeWidget(this); m_treeWidget->setHeaderLabel(QStringLiteral("模型")); QDockWidget *dock = new QDockWidget(QStringLiteral("模型树"), this); dock->setWidget(m_treeWidget); addDockWidget(Qt::LeftDockWidgetArea, dock); // 菜单栏挂建模动作，触发后走MainWindow的建模槽函数 QMenu *modelMenu = menuBar()->addMenu(QStringLiteral("建模")); QAction *newBoxAct = modelMenu->addAction(QStringLiteral("新建方块")); connect(newBoxAct, &QAction::triggered, this, &MainWindow::onCreateBox); }

CADViewport需要提供context()访问器，让MainWindow把AIS对象注册进去。这样分层的好处是，视口只管显示和鼠标事件，建模命令全部集中在MainWindow或独立命令类里，后续添加新命令不用改动视口代码。

3.3 创建第一个立方体：BRepPrimAPI_MakeBox与AIS_Shape的配合

现在进入建模命令。一个立方体从几何数据到屏幕显示，走的是"TopoDS_Shape -> AIS_Shape -> AIS_InteractiveContext->Display"这条路：

#include <BRepPrimAPI_MakeBox.hxx> #include <AIS_Shape.hxx> void MainWindow::onCreateBox() { // 单位默认是毫米，这里创建一个40x40x40的立方体 TopoDS_Shape box = BRepPrimAPI_MakeBox(40.0, 40.0, 40.0).Shape(); // 把纯拓扑对象包装成AIS交互对象，它才有颜色、高亮、选中这些能力 Handle(AIS_Shape) aisBox = new AIS_Shape(box); aisBox->SetColor(Quantity_NOC_ORANGE); aisBox->SetDisplayMode(AIS_Shaded); // 注册进上下文，第二个参数true表示立即刷新视图 m_viewport->context()->Display(aisBox, Standard_True); }

BRepPrimAPI_MakeBox的三个参数对应X、Y、Z方向的边长，OCCT内部没有IMPERIAL_UNIT这类概念，数值直接解释为当前场景的长度单位。米还是毫米由你的业务层统一约定，JellyCAD这类桌面软件通常直接用毫米。AIS_Shape把拓扑对象和显示状态绑在一起，SetColor控制颜色，SetDisplayMode控制线框还是带光照的着色模式。最后Display把对象注册进场景并触发重绘。这个三步链路是后续所有建模命令的模板：生成几何、包装AIS、注册显示。

4. 把视图变成建模环境：鼠标旋转平移、点选高亮与模型树联动

能显示方块只是第一步，三维建模软件之所以是"软件"而不是"图片查看器"，关键在于交互。这一章解决最核心的交互链路：鼠标控制视角、点选模型、选中的结果同步到模型树。

4.1 中键旋转、右键平移、滚轮缩放的事件落法

在CADViewport里重写Qt的鼠标事件，把坐标和操作翻译给V3d_View。三个操作分别对应StartRotation/Rotation、Pan、SetZoom：

void CADViewport::mousePressEvent(QMouseEvent *ev) { if (ev->button() == Qt::MiddleButton) { // 中键按下时记录旋转起始点 m_view->StartRotation(ev->pos().x(), ev->pos().y()); } m_lastPos = ev->pos(); } void CADViewport::mouseMoveEvent(QMouseEvent *ev) { if (ev->buttons() & Qt::MiddleButton) { // 拖动中键，视图根据鼠标轨迹计算旋转角度 m_view->Rotation(ev->pos().x(), ev->pos().y()); } else if (ev->buttons() & Qt::RightButton) { // 右键平移，这里已经把y轴方向翻转了 double dx = ev->pos().x() - m_lastPos.x(); double dy = m_lastPos.y() - ev->pos().y(); m_view->Pan(dx, dy); } m_lastPos = ev->pos(); } void CADViewport::wheelEvent(QWheelEvent *ev) { // angleDelta().y()是滚轮步进，120是一个标准刻度 double factor = ev->angleDelta().y() / 120.0 * 30.0; m_view->SetZoom(ev->position().x(), ev->position().y(), factor); }

这几个接口里最坑的是坐标方向。OCCT的窗口坐标原点在左下角，y轴向上；Qt的坐标原点在左上角，y轴向下。所以Pan的dy我做了符号翻转。高DPI屏幕上还要把event->pos()除以devicePixelRatio，否则4K屏下点击位置和实际拾取位置会错位。血泪经验是：早点封装一个从QPoint到OCCT窗口坐标的转换函数，后面所有鼠标功能统一走它，不要每个事件里各写一遍换算。

4.2 点选与高亮：MoveTo与Select的拾取链路

点击模型表面然后让它高亮，是CAD最基础的能力。AIS_InteractiveContext提供了基于像素坐标的拾取接口：

void CADViewport::pickAt(const QPoint &pos) { // MoveTo只做拾取探测，Select才会真正改变选择状态 m_context->MoveTo(pos.x(), pos.y(), m_view, Standard_True); m_context->Select(); // 遍历当前选中的AIS交互对象，转成业务能识别的拓扑 for (m_context->InitSelected(); m_context->MoreSelected(); m_context->NextSelected()) { Handle(AIS_InteractiveObject) obj = m_context->SelectedInteractive(); if (obj->DynamicType(STANDARD_TYPE(AIS_Shape))) { Handle(AIS_Shape) ais = Handle(AIS_Shape)::DownCast(obj); emit shapePicked(ais->Shape()); } } }

在鼠标左键点击事件里调用pickAt即可。MoveTo把鼠标位置传给上下文做探测，Select触发选择算法，默认会在上下文里维护一个"当前选中集合"。高亮不用你手动做，Context会自动改变选中对象的高亮状态，颜色由默认选择样式控制。这里需要知道类型判断的正确姿势：AIS_InteractiveObject是基类，必须用DynamicType加STANDARD_TYPE判断是否是AIS_Shape，再DownCast，直接static_cast在RTTI下可能拿到不完整对象。

4.3 把选中结果推给模型树：信号槽打通场景与UI

拾取到的TopoDS_Shape要通过信号发给MainWindow，由它决定如何更新模型树。由于TopoDS_Shape不能直接放进QVariant，常见的做法是维护一张ID到Shape的映射，模型树节点只存ID：

void MainWindow::onShapePicked(const TopoDS_Shape &shape) { // 分配一个自增ID，把拓扑对象存进容器 int id = m_nextShapeId++; m_shapeMap.insert(id, shape); // QHash<int, TopoDS_Shape> QString typeName; switch (shape.ShapeType()) { case TopAbs_SOLID: typeName = QStringLiteral("实体"); break; case TopAbs_FACE: typeName = QStringLiteral("面"); break; case TopAbs_EDGE: typeName = QStringLiteral("边"); break; default: typeName = QStringLiteral("几何"); break; } // 树节点只存ID，不存Shape，避免生命周期纠缠 QTreeWidgetItem *item = new QTreeWidgetItem(m_treeWidget); item->setText(0, QStringLiteral("%1 #%2").arg(typeName).arg(id)); item->setData(0, Qt::UserRole, id); m_treeWidget->addTopLevelItem(item); }

这个设计把模型树和场景的关系完全理顺了：点击树节点时，从item的UserRole取出ID，在m_shapeMap里找到Shape，再通过AIS定位到对应对象做选中或删除。后续要加属性面板、图层管理、显隐控制，都在这个ID映射上扩展。

5. JellyCAD避坑手册：显示、坐标、选择与拓扑的五处翻车现场

到这一章，工程能跑、方块能建、鼠标能转、点选能亮。但真正让一个CAD项目从"能演示"变成"能交出给别人用"的，是那些藏在边界里的坑。下面五条是我实际做类似项目时踩过、也帮别人排查过的现场记录。

5.1 模型一上来是纯黑色：光源和背景参数的默认状态

现象：新创建的V3d_Viewer里显示AIS_Shape，模型不是橙色的，而是黑乎乎一片，转动视角后稍微亮一点，但整体像被关在小黑屋里。

原因：V3d_Viewer创建后并没有默认光源。没有光源，OpenGL渲染的面就没有散射光，整个物体落在黑暗里。这不是玄学，是OCCT把"开灯"这个决定权交给了开发者。

解决：初始化时补上三行：m_viewer->SetDefaultLights()、m_viewer->SetLightOn()、m_viewer->SetLightOn前先确保光源类型正确。SetDefaultLights会创建默认的无限光源，SetLightOn才会真正激活。如果自定义光源，注意要调用AddLight再SetLightOn，只AddLight不点亮，效果一样是黑的。

5.2 鼠标旋转方向反了：OCCT右手系与Qt屏幕坐标系的换算

现象：按住中键往上拖，模型反而往下翻；往右拖，模型绕Z轴的旋转方向跟预期相反。单独写代码时没觉得有问题，合到一起越转越晕。

原因：OCCT使用右手坐标系，Z轴朝上，窗口坐标原点在左下角，y轴向上；Qt的事件坐标原点在左上角，y轴向下。直接拿Qt的y值传给OCCT的旋转接口，等于把垂直方向完全颠倒了。

解决：给CADViewport加一个统一的坐标映射函数，所有传给OCCT的鼠标坐标都过一遍：

QPoint CADViewport::toOcctPos(const QPoint &qtPos) const { // OCCT把窗口左下角当作原点，这里做一次y轴翻转 return QPoint(qtPos.x(), height() - qtPos.y()); }

把mousePressEvent、mouseMoveEvent、wheelEvent里的原始坐标全部替换成toOcctPos的结果。高DPI屏幕再把x、y除以devicePixelRatio，两件事一起做干净。一个项目里只在一处写坐标换算，是最省心的习惯。

5.3 嵌入QWidget后视图不刷新：窗口句柄与MustBeResized时机

现象：CADViewport作为centralWidget放进主窗口后，窗口能打开，菜单点了"新建方块"也没报错，但三维视图区域一片空白，或者只在拖动窗口边缘时偶尔闪出画面。

原因：QWidget的winId()在窗口还没显示出来时可能返回无效值，此时用这个句柄创建OCCT窗口，渲染目标就不对。另外控件尺寸变化后没有通知V3d_View更新视口，导致视图在错误的尺寸下渲染。

解决：不要在构造函数里调用createOcctWindowFromWidget和SetWindow，改到showEvent之后初始化，并在resizeEvent里调用m_view->MustBeResized()。稳妥的做法是加一个延时初始化标记，第一次showEvent里执行init3D，后面每次resize就更新视口。这样句柄有效、视口大小同步，画面才会跟着窗口走。

5.4 关闭窗口时崩溃或闪退：handle引用计数与析构顺序

现象：程序跑得好好的，点击关闭按钮，主窗口销毁时偶发崩溃，Debug版本报HEAP CORRUPTION，Release版本直接闪退。有时需要带命令行才能抓到异常。

原因：OCCT对象的生命周期靠handle的引用计数管理。窗口退出时，Qt先析构centralWidget，CADViewport析构会释放V3d_View和AIS_InteractiveContext，但如果AIS对象还在上下文里注册着，释放顺序不对就会访问已经失效的图形驱动。

解决：CADViewport的析构函数里，先遍历上下文移除所有已显示的AIS对象，再依次释放View、Context、Viewer，最后才让基类析构。另外注意别在Qt对象树销毁之后再操作OCCT对象，尤其是在closeEvent里手动清理业务模型时，要保证清理动作发生在centralWidget析构之前。释放顺序写成"先清AIS，再清View，最后清Context和Viewer"，能稳定复现的问题就不再随机。

5.5 导入STEP后布尔/倒角失败：先修复拓扑再进入建模流程

现象：自己用基本体建的模型，布尔运算、倒角都正常。但从STEP文件导入的模型，一执行BRepAlgoAPI_Boolean就报错，或者倒角后出现破面。

原因：STEP文件里的几何质量参差不齐，相邻面可能存在微小间隙、重叠边、退化边。OCCT导入时虽然会尽力复现，但不会自动帮你把几何修好。拓扑修复是在体内：不加装补丁的数据，来到布尔阶段就翻车。

解决：导入模型后先做一次形状检查与修复。用BRepCheck_Analyzer检查形状合法性，不通过就进入修复流程，常见的修复工具是ShapeUpgrade_UnifySameDomain合并共面小面，再用BRepBuilderAPI_Copy做一次深拷贝把历史依赖去掉。修复通过后再进布尔，失败率会低很多。这条经验在JellyCAD这类要对接外部数据的软件里几乎是必踩的。

6. 让JellyCAD从Demo变成可用工具：参数化驱动与增量刷新

模型能建、能选、能存，距离"可用工具"还差一步：参数调整。建模软件里的参数化不是加一个属性框就完事，而是"改一个尺寸，几何跟着变，视图同步刷新"的完整闭环。

参数化重建的核心思路是保留AIS对象，更新它内部的Shape而不是销毁重建。比如把方块边长改成变量控制后，尺寸变更只需要重新生成拓扑，再调用AIS_Shape的SetShape和上下文的Redisplay：

void MainWindow::onBoxSizeChanged(double side) { // BRepPrimAPI_MakeBox每次构造都会生成新的TopoDS_Shape TopoDS_Shape newShape = BRepPrimAPI_MakeBox(side, side, side).Shape(); // 不新建AIS对象，复用已有的aisBox，替换内部几何 m_aisBox->SetShape(newShape); m_viewport->context()->Redisplay(m_aisBox, Standard_True); }

SetShape会保留AIS对象的颜色、材质、显隐状态，Redisplay触发生效。这套模式的性能比"移除旧对象再插入新对象"好很多，尤其在场景里有几百个对象时，复现一次就知道差距。要提醒的是：能这么干的场景有限，圆角、布尔这类依赖中间拓扑的操作，参数变化后不能保证拓扑结果稳定，所以在参数化命令里最好加一个形状合法性检查，失败时回退到上一次成功的结果，给用户一个明确的错误提示而不是留下一半未完成的几何。

另一件值得投入的事是增量刷新。AIS_InteractiveContext加了很多对象后，每次Display第二个参数写true都会触发全场景重绘，在大型STEP模型上能明显感到卡顿。把高频操作里的刷新参数改成false，积累一批变更后统一调用一次m_view->RedrawImmediate()，交互流畅度会有质的提升。JellyCAD这类基于OCCT的项目，模型量通常不会小，性能优化早晚要做，晚做不如早做。

我自己的习惯是：拿到这类三维建模工程，先不急着堆功能，而是反复验证"创建形状、修改形状、删除形状"这三个基础动作在高频操作下的稳定性。基础链路稳了，布尔运算、扫掠、放样这些复杂命令才有可信的地基。把坐标映射统一封装、把生命周期释放顺序写对、把STEP修复流程固化下来，这三点做扎实，JellyCAD才能从仓库里的一个demo壳变成真正能交付使用的三维建模软件。希望帮到你。

本文还有配套的精品资源，点击获取