STEP 零件查看与编辑原型
这是一个基于 Python、pythonocc-core/OCCT、VTK 和 PySide6/Qt 的 STEP 模型查看、选择、局部编辑与导出原型。
当前项目目录下的 geom_extract.step 是默认测试模型。程序入口是 main.py。
最终要实现什么
最终目标是做一个面向 STEP 模型的交互式工具：
- 加载
.step/.stp模型文件。 - 展示三维模型，支持旋转、缩放、平移。
- 读取 STEP 中的零件、装配、solid 等结构。
- 用户可以选择零件、solid、面、边和局部几何特征。
- 程序可以识别孔、圆角、凸台、槽、壳体局部区域等候选特征。
- 用户可以修改可控的局部特征，比如平面推拉、孔径调整、圆角半径调整。
- 用户可以撤销/重做修改，避免实验性编辑一步做坏。
- 用户可以导出修改后的完整模型。
- 如果 STEP 文件里存在多个零件，用户可以只导出选中的某个零件。
需要注意：STEP 文件通常是 B-Rep 几何数据，不是带完整建模历史的参数化 CAD 原文件。所以“随便选一条边改长度”不一定能稳定实现，实际会转化成更可靠的操作，比如移动某个面、重切某个孔、调整某个圆角等。
第一版先实现什么
第一版目标是先把完整工作链路打通：
- 能打开 STEP。
- 能显示模型。
- 能读取 STEP 中的零件/装配标签。
- 能选择 part、solid、face、edge。
- 能显示选中对象的基本属性。
- 能高亮选中对象。
- 能导出整个当前模型。
- 能导出选中的零件。
- 能撤销/重做实验性编辑。
- 先实现少量可控编辑操作，用于验证后续特征编辑路线。
现在已经实现了什么
当前已经实现：
- 默认加载
geom_extract.step。 - 支持打开其他
.step/.stp文件。 - 使用 XCAF 读取 STEP 中的 part / assembly 标签。
- 零件 / 装配树会显示 part / assembly 层级，并在对应 part 下面列出 solid 子节点。
- 点击零件 / 装配树中的 solid 子节点，可以直接选中、高亮、查看属性并用于导出该 solid。
- 使用 OCCT 读取真实 B-Rep 拓扑。
- 使用 VTK 显示模型，并通过 PySide6/Qt 承载桌面界面。
- 支持选择模式：
- Part
- Solid
- Face
- Edge
- Feature
- 支持按 ID 直接选择 Part / Solid / Face / Edge。
- 支持显示选中对象信息，并提供
属性表/原始文本两种查看方式：- 零件名称
- solid 数量
- face 数量
- edge 数量
- 面类型
- 面面积
- 平面法向
- 圆柱面半径/直径
- 边类型
- 边长度
- 圆边半径/直径
- 属性面板现在还会显示更多几何调试信息：
- part / solid 的包围盒、尺寸、体积、重心、表面积。
- face 的方向、面积中心、UV 参数范围、边界边数量、包围盒。
- 平面 face 的几何法向和按拓扑方向修正后的法向。
- 平面 face 的推拉向外方向、向内方向和方向判断置信度。
- 圆柱 face 的轴线点、轴方向、半径、直径、角度跨度、估算高度和是否接近完整圆柱。
- edge 的参数范围、起点、终点、长度中心、包围盒。
- 直线 edge 的方向，圆弧 edge 的圆心、轴线、半径和直径。
- 属性面板支持复制当前对象 ID、拾取坐标和完整信息。
- 支持高亮选中的零件、solid、面或边。
- 支持导出当前完整模型为 STEP。
- 支持导出选中的 part 为 STEP。
- 支持导出选中的 solid 为 STEP。
- 支持导出选中的 face 为 STEP。
- 支持扫描第一版可编辑对象：
- 可推拉的平面 face。
- 可调整孔径的圆柱 face 候选。
- 表格会显示当前值、状态、风险、置信度和说明。
- 点击表格行会直接选中对应 face，方便继续执行推拉或孔径调整。
- 支持列出圆柱面候选特征。
- 圆柱候选会显示在表格中，点击候选行可以直接选中并高亮对应 face。
- 圆柱候选可以按类型筛选：全部、孔/槽候选、圆角候选、凸柱/外圆候选、未明确分类。
- 圆柱候选表格会显示初步分类：
hole/groove candidate：孔/槽一类的凹向圆柱候选。round/fillet candidate：小半径局部圆柱面，可能是圆角/倒圆。boss/outer-round candidate：凸柱/外圆角一类的外向圆柱候选。cylindrical face：暂时无法明确分类的圆柱面。
- 圆柱候选表格会显示直径、角度跨度、估算高度和置信度。
- 圆柱候选表格会显示
risk，用于提示调整圆柱孔径的风险。 - 圆柱候选表默认列出前 100 个候选，以避免打开大模型时刷新过慢。
- 实验性支持平面 face 推拉。
- 平面推拉会自动判断面两侧的 inside / outside，输入正数表示向外加料，输入负数表示向内切削。
- 推拉平面会先显示半透明预览体，表示推拉方向和大致范围，然后在后台执行真实 OCCT 布尔计算。
- 后台编辑计算时会显示进度提示，并暂时阻止选择、扫描、导出或关闭窗口。
- 真实 B-Rep 结果会在布尔计算完成后一次性刷新；半透明预览不等于最终几何结果。
- 实验性支持圆柱孔/圆柱面扩大切削。
- 实验性支持圆柱孔/圆柱面缩小孔径：先补料，再用目标直径重切。
- 圆柱孔/圆柱面孔径调整现在会先生成切削计划：
- 新直径必须大于当前直径，否则直接阻止。
- 候选不是
hole/groove candidate时会标为高风险并要求确认。 - 圆角/倒圆候选会标为高风险，避免误切圆角。
- 选中 face 或实际切削计划会使用多点材料采样，比候选表里的快速分类更谨慎。
- 实际切削优先使用有限长度 cutter，按选中圆柱面的 V 参数范围加少量余量生成，不再默认贯穿整个零件。
- 会沿圆柱轴线采样两端材料状态，初步区分通孔/开口端、盲孔和封闭端。
- 对盲孔/封闭端，有限长度 cutter 会使用更小的端部余量，降低切深变长的风险。
- 支持撤销/重做实验性编辑。
- 支持操作历史面板，显示当前已经成功执行的编辑。
- 操作历史详情会显示编辑类型、目标对象、参数、执行结果和拓扑数量变化。
- 操作历史详情会显示编辑前后的几何差异摘要：
- 体积变化。
- 表面积变化。
- 包围盒尺寸变化。
- 包围盒对角线变化。
- 点击操作历史记录时，会显示三维差异叠加预览：
- 红色半透明表示编辑前模型。
- 绿色半透明表示编辑后模型。
- 编辑后模型上会覆盖距离热力图，蓝色接近无变化，黄色/红色表示变化更大。
- 右下角会显示
distance色带。 - 可以点击
清除差异预览关闭叠加显示。
- 支持导出选中操作历史的差异报告，报告会包含操作参数、拓扑变化、几何变化和热力图统计。
- 鼠标拾取模型时会显示三维拾取点坐标。
- 实验性编辑历史会记录目标对象和当时的拾取点。
- 点击操作历史记录时，程序会尝试重新高亮目标对象，并显示当时的拾取点标记。
- 对非
hole/groove candidate的圆柱切削会先弹出确认，避免误切外圆角或凸柱。 - 提供
--smoke-test启动检查，用于验证 Qt + VTK 窗口组件能正常初始化。
当前 geom_extract.step 的读取结果是：
part: 2001-LOWER_HOUSING
parts: 1
solids: 1
faces: 1800
edges: 4982
vertices: 3262
所以当前测试文件大概率是单个零件，不是多零件装配。但代码已经按“将来可能有多个零件/装配”的方式组织。
还没有实现什么
当前还没有实现：
- 稳定的复杂特征识别。
- 圆角半径修改。
- 稳定的盲孔底面识别和真实 CAD 语义深度恢复。
- 槽、凸台、壳体局部区域的完整识别和编辑。
- 任意边长直接修改。
- 参数化建模历史恢复。
- 工程公差级的局部偏差分析，例如只针对选中区域统计距离并导出区域偏差报告。
- 多零件装配的大规模测试。
- 更完整的错误恢复和模型修复流程。
下一步要实现什么
建议下一步按这个顺序推进：
- 用第一版可编辑对象列表逐项验证当前模型上的平面推拉和孔径调整，记录哪些对象稳定、哪些对象会失败。
- 继续改进孔径修改：降低缩小孔径的布尔失败率，并更准确识别盲孔底面。
- 改进圆角识别，并实现圆角半径修改。
- 增加槽、凸台、局部区域识别。
- 优化导出策略，例如导出时保留更多名称、颜色和层级信息。
- 增强历史记录面板，增加选中局部区域的偏差统计、偏差报告导出和更接近工程公差检查的分析。
怎么运行
先打开 PowerShell，进入项目目录：
cd C:\Users\admin\Desktop\python-occt
激活环境：
conda activate pyocc
如果是在一台新电脑上第一次配置环境，可以使用仓库里的 environment.yml 创建环境：
conda env create -f environment.yml
conda activate pyocc
运行默认模型：
python main.py
打开指定 STEP 文件：
python main.py path\to\model.step
如果当前 PowerShell 没识别 conda，可以直接使用完整路径运行：
C:\Users\admin\miniforge3\Scripts\conda.exe run -n pyocc python main.py
启动烟测，不进入交互窗口：
python main.py --smoke-test
怎么使用
打开程序后，右侧是 3D 模型窗口，左侧是操作面板。
3D 窗口基本操作：
- 鼠标左键拖动：旋转模型。
- 鼠标滚轮：缩放模型。
- 鼠标中键或组合拖动：平移模型，具体取决于 VTK 默认交互方式。
左侧 Selection mode 用来切换选择模式：
Part：选择整个零件。Solid：选择实体。Face：选择面。Edge：选择边。Feature：按特征候选方式选择，目前主要用于圆柱面候选。
左侧 零件 / 装配树 会显示 STEP 里的 part / assembly 层级；如果某个 part 下有 solid，会展开显示 Solid 0、Solid 1 这样的子节点。点击 solid 子节点会自动切换到 Solid 选择，并高亮对应实体。
左侧 按 ID 选择 可以直接输入编号选择对象：
Part的 ID 从 1 开始。Solid、Face、Edge的 ID 从 0 开始。- 这个功能适合配合圆柱候选表格、操作历史和属性面板使用。
左侧 第一版可编辑对象 是当前 MVP 的主要入口：
- 点击
扫描可编辑对象会列出当前第一版能尝试编辑的对象。 - 为了避免打开大模型时界面卡住，程序不会在加载 STEP 时自动扫描；需要编辑时再手动点击扫描。
- 当前默认显示前 40 个可编辑候选，详细几何判断会尽量延后到选中对象或执行编辑前。
推拉平面行表示这个 face 是平面，可以配合面偏移和推拉平面使用。调整圆柱孔径行表示这个 face 是圆柱候选，可以配合孔直径和调整圆柱孔径使用。状态为ready表示比较适合尝试，caution表示可以尝试但风险更高，blocked表示当前参数或对象不适合执行。风险越高越应该谨慎，尤其是圆角、凸柱或未明确圆柱面，不要直接当孔修改。- 点击任意一行会自动选中并高亮对应 face。
选择对象后：
- 被选对象会高亮。
- 下方
Selection info会显示属性。 属性表页签会把属性分成身份、拓扑、测量、位置、方向/轴线、参数、特征判断等分组。原始文本页签会显示同一份信息的纯文本版本，也用于显示候选列表、操作历史详情和普通提示。复制 ID会复制当前选中对象，例如face 2。复制坐标会复制当前拾取点坐标。复制信息会复制当前信息面板里的完整文本。- 用鼠标在模型上选择时，
Selection info和窗口底部状态栏会显示pick_position，也就是拾取点的三维坐标。 - 如果选中圆柱面，会自动给
Hole diameter填一个略大的建议直径。
圆柱候选：
- 点击
列出圆柱候选会刷新候选表格。 - 圆柱候选也是手动扫描，避免加载模型和普通选择操作被候选识别拖慢。
- 可以通过候选表格上方的类型下拉框筛选候选；筛选只过滤已经扫描出的缓存结果，不会重新做几何识别。
- 当前默认显示前 60 个圆柱候选；如果模型很复杂，扫描仍可能需要等待一会儿，但扫描过程中界面会尽量保持响应。
- 表格里的每一行对应一个圆柱面候选。
- 点击候选行会自动切到
Feature模式，并选中对应 face。 guess列是程序通过几何采样得到的初步判断，不是 STEP 文件里自带的 CAD 历史特征。round/fillet candidate只是圆角/倒圆候选，当前还不能直接修改半径。diameter是圆柱直径。span是圆柱面的角度跨度，接近6.283表示接近完整圆柱，接近3.142表示半圆柱。height是根据圆柱面积估算出来的高度。confidence是当前猜测置信度。- 这些候选可能是孔、柱、圆角或其他圆柱面，目前还不是稳定的“孔识别”。
导出：
导出当前完整 STEP：导出当前完整模型。导出选中零件：导出当前选中的零件。导出选中 solid：先选中一个 solid，或选中属于某个 solid 的 face，再导出该 solid。导出选中 face：先切换到Face或Feature选择模式并选中一个 face，再导出该 face。
实验性编辑：
面偏移+推拉平面：- 先选择一个平面 face。
- 输入偏移距离。
- 正数表示沿程序判断的外法向加料。
- 负数表示沿内侧方向切削。
- 点击
推拉平面后，会先出现半透明预览体；绿色表示向外加料方向，红色表示向内切削方向。 - 程序随后在后台执行真实布尔运算，完成后再刷新为真正修改后的模型。
- 选中平面 face 后，可以在
属性表的方向/轴线分组里查看推拉向外方向、推拉向内方向和推拉方向置信度。 - 当前方向判断通过 solid 的 inside / outside 采样得到；如果采样不明确，会退回到拓扑方向法向，并在属性里显示低置信度说明。
- 当前实现仍使用布尔加/减验证推拉路线。
孔直径+调整圆柱孔径：- 先选择一个圆柱面。
- 输入新的直径。
- 目标直径大于当前直径时，会使用有限长度 cutter 扩大切削。
- 目标直径小于当前直径时，会先在原圆柱面范围内补料，再按目标直径重切。
- 程序会先生成切削计划，检查当前直径、目标直径、候选类型、材料投票和风险。
- 切削计划会显示端部类型、深度估算、起点端状态和终点端状态。
- 如果目标直径小于等于 0，或几乎等于当前直径，程序会直接阻止。
- 缩小孔径第一版只对
hole/groove candidate开放；圆角、凸柱或未明确圆柱面会被直接阻止。 - 缩小孔径属于高风险实验功能，因为它依赖“补料 + 重切”的布尔近似，不是 CAD 历史参数修改。
- 如果当前 face 的猜测类型不是
hole/groove candidate，或风险不是低风险，程序会先弹窗确认。 - 切削计划会显示 cutter 策略、高度和余量；当前优先使用有限长度 cutter，减少误切其他区域。
- 缩小孔径时，操作历史会额外记录补料策略、补料半径和补料高度。
- 端部类型是通过轴线端部 inside / outside 采样得到的估算，不等于 CAD 原始建模历史里的“孔深”参数。
- 如果选到的圆柱面不是孔，而是柱或圆角，结果可能不是你想要的，所以它目前仍是实验功能。
撤销：- 撤销上一次成功的实验性编辑。
重做：- 重做刚刚撤销的实验性编辑。
操作历史：- 显示当前模型已经成功执行的实验性编辑。
- 点击某条历史记录，会在
Selection info中显示该次编辑的目标、参数、执行结果和拓扑数量变化。 - 历史详情也会显示几何差异摘要，包括体积、表面积、包围盒尺寸和包围盒对角线的前后变化。
- 点击某条历史记录时，3D 窗口会显示红/绿半透明差异叠加预览：红色表示编辑前，绿色表示编辑后。
- 编辑后模型会覆盖距离热力图：蓝色接近无变化，黄色/红色表示变化更大。
- 历史详情会显示热力图统计，包括最大距离、平均距离和发生明显变化的采样点比例。
清除差异预览可以关闭红/绿叠加显示。导出差异报告会把当前选中的历史记录导出为.txt，里面包含操作详情、拓扑变化、几何变化和热力图统计。- 当前热力图是“编辑后模型顶点到编辑前模型表面”的距离估算，不是完整 CAD 公差报告。
- 点击某条历史记录时，程序也会尝试重新高亮当时编辑的目标 face，并用青色小点标出当时的拾取位置。
- 由于布尔编辑后拓扑 ID 可能重新分配，历史里的 face ID 只能作为定位参考，不能视为稳定的 CAD 建模历史 ID。
- 撤销后对应记录会从列表里退回。
- 重做后对应记录会重新显示。
文件说明
main.py：程序入口和桌面界面。step_model.py：STEP/OCCT 后端逻辑。environment.yml：Conda 环境说明，用于安装 pythonocc-core、VTK、PySide6 等依赖。.gitignore：Git 忽略规则，避免提交 Python 缓存、临时文件和导出的 STEP 文件。geom_extract.step：当前默认测试模型。README.md：项目说明和使用说明。
当前版本边界
这一版重点是验证整体链路，不是最终 CAD 编辑器。
模型显示、选择、属性查看、撤销/重做和导出是当前主要能力。局部编辑已经接入，但仍属于实验性能力。复杂 STEP 几何上的布尔操作可能失败；失败时程序会弹窗提示，不会静默覆盖原始文件。