pythonocc-step-editor/README.md

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 文件。
• 打开 STEP 时会先在临时模型里完成读取和显示网格生成；失败时当前模型保持不变。
• 使用 XCAF 读取 STEP 中的 part / assembly 标签。
• 模型结构树会用中文显示 STEP 里的装配、零件和实体层级，并在对应零件下面列出实体子节点。
• 点击模型结构树中的实体子节点，可以直接选中、高亮、查看属性并用于导出该实体。
• 使用 OCCT 读取真实 B-Rep 拓扑。
• 使用 VTK 显示模型，并通过 PySide6/Qt 承载桌面界面。
• 左侧操作面板按功能模块分组显示，并使用四边同色的轻量彩色边框和标题层级区分文件、选择、显示、导出、编辑、候选、历史和属性信息。
• 支持选择模式：
  • Part
  • Solid
  • Face
  • Edge
  • Feature
• 鼠标悬停对象会以红色预高亮，真正选中后会以黄色高亮。
• 鼠标选择会按当前模式做就近映射；例如 Edge 模式点到面时，会自动选择鼠标附近的边界 edge。
• 支持按当前选择模式输入 ID 直接选择 Part / Solid / Face / Edge / Feature。
• 鼠标选择模式 下拉框不会响应鼠标滚轮，避免鼠标经过时误切换模式；需要点击后手动选择。
• 按 ID 选择 会在输入框和 选择 按钮之间同步显示当前鼠标选择模式。
• Feature 模式现在会把点到的 face 解释为局部几何特征候选：
  • 平面会识别为可推拉平面候选。
  • 圆柱面会识别为圆柱孔候选、槽/半孔候选、圆角/倒圆候选、凸台/外圆候选或未明确圆柱特征。
  • 圆柱特征会尝试找出边界 edge、相邻 face、端面 face、开口端相邻 face 和疑似底面 face，并一起高亮相关局部区域。
  • 槽/半孔候选会额外显示槽宽、圆弧长度、槽深估算和槽边界相邻 face。
  • 圆角/倒圆候选会额外显示已有圆角半径估算、圆弧角度、圆弧长度和相邻支撑 face。
• 支持显示选中对象信息，并提供 属性表 / 原始文本 两种查看方式：
  • 零件名称
  • solid 数量
  • face 数量
  • edge 数量
  • 面类型
  • 面面积
  • 平面法向
  • 圆柱面半径/直径
  • 边类型
  • 边长度
  • 圆边半径/直径
• 属性面板现在还会显示更多几何调试信息：
  • part / solid 的包围盒、尺寸、体积、重心、表面积。
  • face 的方向、面积中心、UV 参数范围、边界边数量、包围盒。
  • 平面 face 的几何法向和按拓扑方向修正后的法向。
  • 平面 face 的推拉向外方向、向内方向和方向判断置信度。
  • 圆柱 face 的轴线点、轴方向、半径、直径、角度跨度、估算高度和是否接近完整圆柱。
  • edge 的参数范围、起点、终点、长度中心、包围盒。
  • 直线 edge 的方向，圆弧 edge 的圆心、轴线、半径和直径。
• 属性面板支持复制当前对象 ID、拾取坐标和完整信息。
• 面/边属性查询带缓存；重复选择同一个对象会复用上次计算结果，模型编辑、撤销、重做或重新加载后缓存会自动清空。
• 支持高亮选中的零件、solid、面、边或局部特征候选，并在鼠标悬停时用红色预览当前可选对象。
• 支持只显示当前选中对象、对准当前选中对象，并可一键恢复显示完整模型。
• Feature 模式会在属性表里显示特征来源 face、侧壁 face、端面 face、疑似底面 face、开口端相邻 face、边界 edge 和当前可用操作。
• 支持导出当前完整模型为 STEP。
• 支持导出选中的 part 为 STEP。
• 支持导出选中的 solid 为 STEP。
• 支持导出选中的 face 为 STEP。
• 支持导出选中特征区域为 STEP。
• 支持导出选中的 edge 为 STEP。
• 支持导出质量检查：导出前会检查 B-Rep 有效性、solid / face / edge 数量、体积和包围盒；如果发现风险，会先弹窗确认。
• 导出完整模型、part 或 solid 前，会先尝试执行 ShapeFix 和同域面/边合并，减少外部 CAD 打开时出现碎面、坏体或明显拼接痕迹的概率。
• 实验性编辑按钮会根据当前选中对象自动启用或禁用，并通过悬停提示说明为什么当前操作不可用，减少 face、edge、孔、凸台、盲孔等对象混用导致的误操作。
• 支持扫描第一版可编辑对象：
  • 默认扫描优先保证界面响应速度，会列出一组有代表性的候选。
  • 深度扫描 会尝试列出更多候选，适合默认列表里没有找到目标对象时使用。
  • 可推拉的平面 face。
  • 可调整孔径的圆柱 face 候选。
  • 可调整盲孔深度的圆柱 face 候选。
  • 可添加新圆角的直线 edge 候选。
  • 可添加倒角的直线 edge 候选。
  • 可尝试通过端面推拉调整长度的直线 edge 候选。
  • 表格会显示当前值、状态、风险、置信度和说明。
  • 盲孔深度候选会在列表阶段先确认疑似底面，列表里的深度值优先使用底面 face 轴向位置计算。
  • 点击表格行会直接选中对应 face 或 edge，方便继续执行推拉、孔径调整、盲孔深度调整、边倒圆、边倒角或受限直线边长度调整。
• 支持列出圆柱面候选特征。
• 圆柱候选会显示在表格中，点击候选行可以直接选中并高亮对应 face。
• 圆柱候选可以按类型筛选：全部、孔/槽候选、圆角候选、凸柱/外圆候选、未明确分类。
• 圆柱候选的类型下拉框不会响应鼠标滚轮，避免滚动左侧面板时误改筛选条件。
• 圆柱候选表格会显示初步分类：
  • hole/groove candidate：孔/槽一类的凹向圆柱候选。
  • round/fillet candidate：小半径局部圆柱面，可能是圆角/倒圆。
  • boss/outer-round candidate：凸柱/外圆角一类的外向圆柱候选。
  • cylindrical face：暂时无法明确分类的圆柱面。
• 圆柱候选表格会显示直径、角度跨度、估算高度和置信度。
• 圆柱候选表格会显示 risk，用于提示调整圆柱孔径的风险。
• 圆柱候选表默认列出前 60 个候选，以避免打开大模型时刷新过慢。
• 实验性支持平面 face 推拉。
• 平面推拉会自动判断面两侧的 inside / outside，输入正数表示向外加料，输入负数表示向内切削。
• 推拉平面会先显示半透明预览体，表示推拉方向和大致范围，然后在后台执行真实 OCCT 布尔计算。
• 推拉平面现在会从选中 face 出发，自动查找共享边且共面的相邻 face，并把它们作为同一片平面区域一起推拉。
• 这可以减少 STEP 碎面导致的“只推了一小块，导出后像贴上去一块，中间有伤疤”的情况。
• 推拉加料时，工具体会向原实体内部保留一个很小的重叠量，再执行 Fuse，避免只靠两个面贴合导致导出后像“原模型 + 新增块”叠在一起。
• Fuse/Cut 完成后会执行更强的推拉结果清理：按模型尺寸设置小容差，显式禁止保留 internal edges，并多轮执行 OCCT 同域面/边合并，减少第三方 CAD 中出现不必要共面分割线的概率。
• 如果推拉本身产生了真实台阶边界，第三方 CAD 仍会显示这条几何边；清理只能减少不必要的共面残留边，不能消除真实形状边界。
• 推拉平面会先生成操作计划：检查距离是否为 0、方向置信度和相对 face 尺寸的风险；高风险会先弹窗确认。
• 调整圆柱孔径也会先显示半透明预览体：红色表示切削 cutter，绿色表示缩小孔径时的补料范围。
• 支持第一版盲孔/盲槽深度调整：
  • 只对 hole/groove candidate 且端部类型为 blind、并识别到疑似底面 face 的圆柱候选开放。
  • 目标深度大于当前估算深度时，会沿开口到疑似底面方向用有限长度 cutter 加深切削。
  • 目标深度小于当前估算深度时，会从目标新底面到旧底面方向补料，让孔变浅。
  • 调整盲孔深度会先显示半透明预览体：红色表示加深切削范围，绿色表示变浅补料范围。
  • 孔深调整计划会记录当前深度、目标深度、变化比例、疑似底面、开口端和工具参数。
  • 当前深度会优先使用疑似底面 face 在圆柱轴线上的位置计算；如果相邻端面找不到底面，会额外扫描同一 solid 内轴线附近的平面圆盘候选。
• 支持第一版槽/半孔候选结构化识别：
  • 对局部圆柱形 hole/groove candidate，会标记为 partial-cylindrical-groove。
  • 会估算槽宽、圆弧长度和槽深。
  • 会识别槽圆柱 face 和槽边界相邻 face，并在 Feature 模式下一起高亮。
  • 这些仍是 B-Rep 几何估算，不是 CAD 历史里的槽特征参数。
• 支持第一版已有圆角/倒圆候选结构化识别：
  • 对局部小半径圆柱面，会标记为 round/fillet candidate。
  • 会估算已有圆角半径、圆弧角度和圆弧长度。
  • 会识别已有圆角 face 和相邻支撑 face，并在 Feature 模式下一起高亮。
  • 第一版可编辑对象 会把已有圆角候选单独列为 修改已有圆角半径，点击后会选中该圆角 face，并把圆角半径输入框预填为当前估算半径的参考目标值。
  • 选中已有圆角候选时，不会再误把它填入 孔直径，避免把圆角当孔径修改。
  • 第一版已有圆角半径修改会先尝试移除圆角 face，再在恢复出的锐边上重新倒圆；只对较规整的圆柱圆角候选开放，复杂 blend 可能失败并回滚。
• 支持第一版圆柱孔封堵：
  • 只对 hole/groove candidate 且角度跨度接近完整圆柱的孔开放。
  • 不对半孔/槽开放，避免用完整圆柱补料时把不该补的位置也补上。
  • 封堵会用略带半径重叠的圆柱补料体执行 Fuse。
  • 绿色半透明预览表示即将补上的材料范围。
  • 当前默认模型可能不会在默认可编辑对象列表里显示封堵候选；其他包含完整圆柱孔的 STEP 文件可以使用这个能力。
• 支持第一版圆柱凸台直径调整：
  • 只对 boss/outer-round candidate 且角度跨度接近完整圆柱的凸台开放。
  • 不处理局部外圆角、圆角面或未明确圆柱面，避免把圆角当凸台修改。
  • 目标直径变大时，会生成目标直径圆柱并 Fuse。
  • 目标直径变小时，会生成环形 cutter 并 Cut。
  • 会先显示半透明预览：绿色表示扩大补料范围，红色表示缩小切削范围。
  • 当前默认模型可能没有明确凸台候选；包含完整圆柱凸台的 STEP 文件可以使用这个能力。
• 支持第一版直线边添加圆角：
  • 只对直线 edge 开放。
  • 会先检查边长、相邻 face 数量和目标半径相对边长的比例。
  • 蓝色半透明预览表示目标 edge 和输入半径的大致范围。
  • 真实编辑使用 OCCT BRepFilletAPI_MakeFillet 在后台执行。
  • 这一步是“给直线边添加新圆角”，还不是“修改已有圆角半径”。
  • STEP 没有建模历史，某些看起来像直线边的对象仍可能被 OCCT 拒绝；失败时会自动尝试恢复编辑前状态。
• 支持第一版直线边添加倒角：
  • 只对直线 edge 开放。
  • 会先检查边长、相邻 face 数量和倒角距离相对边长的比例。
  • 橙色半透明预览表示目标 edge 和输入倒角距离的大致范围。
  • 真实编辑使用 OCCT BRepFilletAPI_MakeChamfer 在后台执行。
  • STEP 没有建模历史，某些边仍可能被 OCCT 拒绝；失败时会自动尝试恢复编辑前状态。
• 支持第一版受限直线边长度调整：
  • 只对直线 edge 开放。
  • 选中直线 edge 后，边目标长度 会自动填入当前边长。
  • 输入目标长度后，程序会尝试寻找这条边端点附近、方向匹配的平面端面。
  • 找到端面后，会把“改边长”转换成该端面的平面推拉操作，并显示蓝绿色半透明预览。
  • 如果找不到可靠端面，或者目标长度无效，会直接阻止，不会强行修改。
  • 这不是通用参数化边长编辑；复杂拓扑、斜面过渡、圆角链或没有明确端面的边仍可能不能改。
• 支持 part / solid 级平移：
  • 输入 X/Y/Z 平移量后，可以平移当前选中零件。
  • 选中 solid、或选中属于某个 solid 的 face/edge 后，可以平移当前 solid。
  • 单 solid 零件中平移 solid 实际等同于移动整个 part shape，程序会按中风险提示。
  • 平移操作会写入历史记录，并支持撤销/重做。
• 支持 part / solid 级旋转：
  • 选择 X/Y/Z 旋转轴并输入角度后，可以旋转当前选中零件或 solid。
  • 第一版旋转中心取目标对象的包围盒中心。
  • 单 solid 零件中旋转 solid 实际等同于旋转整个 part shape，程序会按中风险提示。
  • 旋转操作会写入历史记录，并支持撤销/重做。
• 后台编辑计算时会显示进度提示，主界面会暂时置灰，并阻止选择、扫描、导出、撤销/重做、历史详情查看或关闭窗口。
• 真实 B-Rep 结果会在布尔计算完成后一次性刷新；半透明预览不等于最终几何结果。
• 如果后台编辑失败，程序会自动尝试恢复到编辑前快照，避免出现“提示失败但模型已经被部分改动”的状态。
• 实验性支持圆柱孔/圆柱面扩大切削。
• 实验性支持圆柱孔/圆柱面缩小孔径：先补料，再用目标直径重切。
• 圆柱孔/圆柱面孔径调整现在会先生成切削计划：
  • 目标直径必须大于 0；如果目标直径与当前直径几乎相同，会直接阻止。
  • 会计算直径变化比例；变化超过当前直径 35% 会提高到中风险，超过 100% 会提高到高风险。
  • 会比较目标直径和圆柱面估算高度；比例异常时会提高风险等级。
  • 候选不是 hole/groove candidate 时会标为高风险并要求确认。
  • 圆角/倒圆候选会标为高风险，避免误切圆角。
  • 缩小孔径第一版只对 hole/groove candidate 开放，其他圆柱面会直接阻止。
  • 选中 face 或实际切削计划会使用多点材料采样，比候选表里的快速分类更谨慎。
  • 实际切削优先使用有限长度 cutter，按选中圆柱面的 V 参数范围加少量余量生成，不再默认贯穿整个零件。
  • 会沿圆柱轴线采样两端材料状态，初步区分通孔/开口端、盲孔和封闭端。
  • 会把圆柱相邻平面按轴线位置分成起点端/终点端，并结合端部采样标记疑似盲孔底面；相邻端面缺失时，会尝试扫描轴线附近的平面圆盘候选作为兜底。
  • 孔径修改计划会记录疑似底面 face、开口端相邻 face 和 cutter 底面保护状态。
  • 对盲孔/封闭端，有限长度 cutter 会使用更小的端部余量，降低切深变长的风险。
• 支持撤销/重做实验性编辑。
• 撤销/重做会先确认模型恢复成功，再移动历史栈；如果恢复失败，会尽量回到操作前状态。
• 支持操作历史面板，显示当前已经成功执行的编辑。
• 操作历史详情会显示编辑类型、目标对象、参数、执行结果和拓扑数量变化。
• 操作历史详情会额外显示目标零件自身的 solid / face / edge 数量变化。
• 如果一次局部编辑导致目标零件 solid 数异常变化，历史详情会显示质量警告，状态栏也会提示先检查结果。
• 操作历史详情会显示编辑前后的几何差异摘要：
  • 体积变化。
  • 表面积变化。
  • 包围盒尺寸变化。
  • 包围盒对角线变化。
• 点击操作历史记录时，会显示三维差异叠加预览：
  • 红色半透明表示编辑前模型。
  • 绿色半透明表示编辑后模型。
  • 编辑后模型上会覆盖距离热力图，蓝色接近无变化，黄色/红色表示变化更大。
  • 右下角会显示 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 语义级识别。
• 盲孔/盲槽深度：已经能对部分可识别候选做深度估算和编辑，并会优先使用疑似底面 face 的轴向位置计算当前深度；但还不能保证所有模型都能恢复真实 CAD 语义深度。
• 槽、凸台、壳体局部区域：已经有圆柱孔、槽/半孔候选结构化识别、完整圆柱凸台直径修改，复杂槽、复杂凸台和壳体局部区域仍需要继续做。
• 已有圆角/倒圆面半径：已经有第一版受限修改实现，使用 defeature + refillet 路线，但复杂 blend、支撑面不明确或恢复锐边失败时仍会阻止或回滚。
• 局部偏差分析：已经有编辑前后体积、面积、包围盒、距离热力图和差异报告，但还不是工程公差级的局部区域偏差报告。
• 错误恢复和模型修复：已经有编辑前快照、失败回滚、基础 B-Rep 校验、同域面合并和布尔结果自动修复，但还不是完整的模型修复流水线。
• 多零件装配：已经有装配/零件树和单独导出入口，但还没有做大规模、多来源 STEP 装配测试。

仍基本没有实现，或者 STEP 本身不一定能可靠支持：

• 通用任意边长直接修改。当前只有第一版受限直线边长度调整，会尝试通过端面推拉来改变长度；没有明确可推拉端面的边仍不能改。
• 参数化建模历史恢复。STEP 通常只保存结果几何/拓扑，不能稳定还原原 CAD 软件里的建模历史，只能在本程序里记录后续编辑历史，或做近似的特征语义识别。
• 所有场景都稳定的复杂特征识别。

下一步要实现什么

建议下一步按这个顺序推进：

1. 继续加固最小可用编辑闭环：选择、预览、执行、校验、修复、回滚、导出。
2. 继续验证平面推拉、孔径调整、盲孔/盲槽深度调整和圆柱凸台直径调整，记录哪些对象稳定、哪些对象会失败。
3. 改进盲孔/槽底面识别，减少“看起来像 blind 但找不到可靠底面 face”的候选。
4. 继续加固已有圆角半径修改：扩大可成功场景，记录哪些圆角能 defeature + refillet，哪些需要更复杂的重建策略。
5. 继续增加复杂槽、复杂凸台、局部区域识别。
6. 优化导出策略，例如导出时保留更多名称、颜色和层级信息。

怎么运行

先打开 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 默认交互方式。

左侧操作面板按功能分区排列，每个模块都有四边同色的独立边框和颜色提示，方便快速区分文件、模型结构树、选择、显示、导出、编辑、候选列表、历史记录和对象信息。

左侧 鼠标选择模式 用来切换选择模式：

• Part：选择整个零件。
• Solid：选择实体。
• Face：选择面。
• Edge：选择边。
• Feature：按局部特征候选方式选择。平面会识别为可推拉平面候选；圆柱面会进一步识别为圆柱孔、槽/半孔、圆角/倒圆、凸台/外圆等候选。 圆柱候选会额外显示侧壁 face、端面 face、疑似底面 face、开口端相邻 face 和边界 edge。
• 鼠标悬停时，当前模式下将要选中的对象会显示为红色；真正选中后会显示为黄色。
• 如果当前模式是 Edge，即使鼠标点到的是面，程序也会从这个面的边界里选取距离鼠标拾取点最近的 edge。
• 鼠标选择模式 下拉框不响应鼠标滚轮，鼠标停在上面滚动时不会自动切换选项；需要点击下拉框后手动选择。

左侧 模型结构树 会显示 STEP 里的装配、零件和实体层级；如果某个零件下有实体，会展开显示 实体 0、实体 1 这样的子节点。点击实体子节点会自动切换到 Solid 选择，并高亮对应实体。

普通单零件 STEP 通常会显示成类似：

零件 1：2001-LOWER_HOUSING    零件 | 实体 1 个 | 面 1800 个 | 边 4982 条
  实体 0                     面 1800 个 | 边 4982 条

如果 STEP 是多零件装配，树里可能会先出现 装配 节点，下面再挂多个 零件 节点；装配可以理解为“多个零件组成的一组结构”。

左侧 按 ID 选择 可以直接输入编号选择对象：

• 按 ID 选择会复用上方 鼠标选择模式 的当前类型；先切换模式，再输入 ID，点击 选择。
• 输入框右侧会同步显示当前类型，例如 Face、Edge 或 Solid，用于确认这个 ID 会按哪类对象解释。
• Part 的 ID 从 1 开始。
• Solid、Face、Edge、Feature 的 ID 从 0 开始；Feature 使用来源 face 的 ID。
• 这个功能适合配合圆柱候选表格、操作历史和属性面板使用。

左侧 显示 用来临时缩小三维视图范围：

• 只显示选中：只显示当前选中的 part、solid、face、edge 或 feature 区域。
• 对准选中：不改变显示范围，只把相机对准当前选中的 part、solid、face、edge 或 feature，适合快速查看小孔、小边和局部特征。
• 显示全部：恢复显示完整模型。
• solid / edge 的显示查询已经使用拓扑索引，避免每次隔离或高亮时反复全模型查找。
• 这是视图操作，不会修改 STEP 几何，也不会写入操作历史。

左侧 第一版可编辑对象 是当前 MVP 的主要入口：

• 点击 扫描可编辑对象 会列出当前第一版能尝试编辑的对象。
• 点击 深度扫描 会用更高上限重新扫描，可能需要等待更久。
• 为了避免打开大模型时界面卡住，程序不会在加载 STEP 时自动扫描；需要编辑时再手动点击扫描。
• 当前默认显示一批代表性的可编辑候选，详细几何判断会尽量延后到选中对象或执行编辑前，避免扫描过慢。
• 推拉平面 行表示这个 face 是平面，可以配合 面偏移 和 推拉平面 使用。
• 调整圆柱孔径 行表示这个 face 是圆柱候选，可以配合 孔直径 和 调整圆柱孔径 使用。
• 调整圆柱凸台直径 行表示这个 face 是较明确的完整圆柱凸台候选，可以配合 凸台直径 和 调整圆柱凸台直径 使用。
• 封堵圆柱孔 行表示这个 face 是接近完整圆柱的孔候选，可以点击后直接使用 封堵圆柱孔。
• 调整盲孔深度 行表示这个 face 是较明确的盲孔/盲槽候选，可以配合 孔深度 和 调整盲孔深度 使用。
• 给边添加圆角 行表示这个对象是直线 edge，可以配合 圆角半径 和 给边添加圆角 使用。
• 给边添加倒角 行表示这个对象是直线 edge，可以配合 倒角距离 和 给边添加倒角 使用。
• 修改已有圆角半径 行表示这个 face 是已有圆角/倒圆候选，点击后会切到 Feature 模式并预填圆角半径参考值；真正执行需要再点击编辑区里的 修改已有圆角半径 按钮并确认。
• 状态 为 ready 表示比较适合尝试，caution 表示可以尝试但风险更高，blocked 表示当前参数或对象不适合执行。
• 风险 越高越应该谨慎，尤其是圆角、凸柱或未明确圆柱面，不要直接当孔修改。
• 点击任意一行会自动选中并高亮对应 face 或 edge。

选择对象后：

• 鼠标经过对象时会出现红色预高亮；被选对象会显示为黄色高亮。
• 如果处于 Feature 模式，程序会尽量高亮这个特征相关的局部区域，例如圆柱侧壁、相邻端面和槽边界相邻面。
• 对槽/半孔候选，属性表会显示 槽宽估算、槽圆弧长度估算、槽深估算 和 槽边界相邻 Face。
• 对圆角/倒圆候选，属性表会显示 已有圆角半径估算、已有圆角圆弧角度、已有圆角圆弧长度估算 和 已有圆角支撑 Face。
• 对盲孔/槽候选，属性表中的 疑似底面 Face 是根据圆柱端部 inside / outside 采样和相邻平面位置推断的，不等于 CAD 原始建模历史里的孔深参数。
• 下方 选中对象信息 会显示属性。
• 属性表 页签会把属性分成身份、拓扑、测量、位置、方向/轴线、参数、特征判断等分组。
• 原始文本 页签会显示同一份信息的纯文本版本，也用于显示候选列表、操作历史详情和普通提示。
• 复制 ID 会复制当前选中对象，例如 face 2。
• 复制坐标 会复制当前拾取点坐标。
• 复制信息 会复制当前信息面板里的完整文本。
• 用鼠标在模型上选择时，选中对象信息 和窗口底部状态栏会显示 pick_position，也就是拾取点的三维坐标。
• 如果选中圆柱面，会自动给 Hole diameter 填一个略大的建议直径。
• 如果选中直线 edge，会自动给 圆角半径 和 倒角距离 填一个保守的建议值，并把 边目标长度 填成当前边长。

圆柱候选：

• 点击 列出圆柱候选 会刷新候选表格。
• 圆柱候选也是手动扫描，避免加载模型和普通选择操作被候选识别拖慢。
• 可以通过候选表格上方的类型下拉框筛选候选；筛选只过滤已经扫描出的缓存结果，不会重新做几何识别。
• 类型下拉框不响应鼠标滚轮，避免鼠标经过时误切换筛选条件。
• 当前默认显示前 60 个圆柱候选；如果模型很复杂，扫描仍可能需要等待一会儿，但扫描过程中界面会尽量保持响应。
• 表格里的每一行对应一个圆柱面候选。
• 点击候选行会自动切到 Feature 模式，并选中对应 face。
• guess 列是程序通过几何采样得到的初步判断，不是 STEP 文件里自带的 CAD 历史特征。
• round/fillet candidate 是圆角/倒圆候选；部分规整圆柱圆角可以通过 修改已有圆角半径 进行第一版受限修改。
• diameter 是圆柱直径。
• span 是圆柱面的角度跨度，接近 6.283 表示接近完整圆柱，接近 3.142 表示半圆柱。
• height 是根据圆柱面积估算出来的高度。
• confidence 是当前猜测置信度。
• 这些候选可能是孔、柱、圆角或其他圆柱面，目前还不是稳定的“孔识别”。

导出：

• 导出当前完整 STEP：导出当前完整模型。
• 导出选中零件：导出当前选中的零件。
• 导出选中 solid：先选中一个 solid，再导出该 solid。
• 导出选中 face：先切换到 Face 选择模式并选中一个 face，再导出该 face。
• 导出选中特征区域：先切换到 Feature 选择模式并选中局部特征，再导出当前特征高亮的 face 集合。
• 导出选中 edge：先切换到 Edge 选择模式并选中一个 edge，再导出该 edge。
• 检查导出质量：检查当前选中对象；如果没有选中对象，就检查当前完整模型。
• 导出按钮会根据当前选中对象自动启用或禁用，避免选中 face 时误点 导出选中 edge 这类不匹配的操作。
• 所有导出按钮都会先做质量检查。发现 B-Rep 无效、没有 solid、零件包含多个 solid、体积接近 0 等风险时，会先弹窗确认是否继续导出。

实验性编辑：

• 编辑按钮会根据当前选择自动启用或禁用。例如未选中平面时不能点击 推拉平面，未选中直线 edge 时不能点击 给边添加圆角 / 给边添加倒角，未选中明确孔/凸台/盲孔候选时对应圆柱编辑按钮会禁用。
• 面偏移 + 推拉平面：
  • 先选择一个平面 face。
  • 输入偏移距离。
  • 正数表示沿程序判断的外法向加料。
  • 负数表示沿内侧方向切削。
  • 点击 推拉平面 后，会先出现半透明预览体；绿色表示向外加料方向，红色表示向内切削方向。
  • 如果距离为 0 会直接阻止；如果方向置信度低或距离相对 face 尺寸偏大，会先弹窗确认。
  • 如果选中 face 周围有共享边且共面的碎面，程序会自动把这些 face 合成同一片推拉区域，属性表和历史记录会显示 推拉共面区域 Face 数。
  • 加料时程序会让拉伸体和原实体产生极小重叠，并在布尔后尝试合并同域面/边，使导出的 STEP 更像一个整体实体。
  • 程序随后在后台执行真实布尔运算，完成后再刷新为真正修改后的模型。
  • 选中平面 face 后，可以在 属性表 的方向/轴线分组里查看 推拉向外方向、推拉向内方向 和 推拉方向置信度。
  • 当前方向判断通过 solid 的 inside / outside 采样得到；如果采样不明确，会退回到拓扑方向法向，并在属性里显示低置信度说明。
  • 当前实现仍使用布尔加/减验证推拉路线。
• 孔直径 + 调整圆柱孔径：
  • 先选择一个圆柱面。
  • 输入新的直径。
  • 目标直径大于当前直径时，会使用有限长度 cutter 扩大切削。
  • 目标直径小于当前直径时，会先在原圆柱面范围内补料，再按目标直径重切。
  • 点击 调整圆柱孔径 后，会先显示半透明预览；红色是切削范围，绿色是缩小孔径时的补料范围。
  • 程序会先生成切削计划，检查当前直径、目标直径、候选类型、材料投票和风险。
  • 切削计划会显示直径变化量、直径变化比例，以及目标直径相对圆柱面估算高度的比例。
  • 切削计划会显示端部类型、深度估算、起点端状态和终点端状态。
  • 切削计划会显示疑似底面 face、开口端相邻 face 和底面保护说明；这些信息会写入操作历史。
  • 如果目标直径小于等于 0，或几乎等于当前直径，程序会直接阻止。
  • 如果目标直径变化过大，或者目标直径相对圆柱估算高度明显异常，程序会提高风险并要求确认。
  • 缩小孔径第一版只对 hole/groove candidate 开放；圆角、凸柱或未明确圆柱面会被直接阻止。
  • 缩小孔径属于高风险实验功能，因为它依赖“补料 + 重切”的布尔近似，不是 CAD 历史参数修改。
  • 如果当前 face 的猜测类型不是 hole/groove candidate，或风险不是低风险，程序会先弹窗确认。
  • 切削计划会显示 cutter 策略、高度和余量；当前优先使用有限长度 cutter，减少误切其他区域。
  • 缩小孔径时，操作历史会额外记录补料策略、补料半径和补料高度。
  • 端部类型是通过轴线端部 inside / outside 采样得到的估算，不等于 CAD 原始建模历史里的“孔深”参数。
  • 如果选到的圆柱面不是孔，而是柱或圆角，结果可能不是你想要的，所以它目前仍是实验功能。
• 凸台直径 + 调整圆柱凸台直径：
  • 先选择一个完整圆柱凸台 face，建议从 第一版可编辑对象 中点击 调整圆柱凸台直径 行进入。
  • 只有接近完整圆柱的 boss/outer-round candidate 会放行；局部外圆角、圆角面、孔/槽和未明确圆柱面会被阻止。
  • 目标直径大于当前直径时，会在选中圆柱面的轴向范围内生成目标直径圆柱并 Fuse。
  • 目标直径小于当前直径时，会生成环形 cutter，把目标直径外侧到原直径附近的材料 Cut 掉。
  • 点击后会显示半透明预览：绿色表示扩大补料范围，红色表示缩小切削范围。
  • 这不是 CAD 历史里的“修改凸台特征参数”，而是基于当前 B-Rep 的受限几何布尔编辑。
• 封堵圆柱孔：
  • 先选择一个完整圆柱孔 face，建议从 第一版可编辑对象 中点击 封堵圆柱孔 行进入。
  • 点击 封堵圆柱孔 后，程序会先生成补料计划。
  • 只有接近完整圆柱的 hole/groove candidate 会放行；半孔/槽、圆角、凸柱、未明确圆柱面会被阻止。
  • 通过检查后，会显示绿色半透明补料体预览。
  • 真实编辑会把补料体和当前零件 Fuse，并尝试合并同域面/边。
  • 这个功能适合封堵通孔或盲孔，但仍是基于 B-Rep 几何的实验性补料，不是 CAD 历史里的“删除孔特征”。
• 孔深度 + 调整盲孔深度：
  • 先选择一个盲孔或盲槽的圆柱面，建议从 第一版可编辑对象 中点击 调整盲孔深度 行进入。
  • 选中符合条件的盲孔/盲槽后，孔深度 会自动填入一个比当前估算深度略大的建议值。
  • 输入目标深度后点击 调整盲孔深度。
  • 目标深度大于当前估算深度时，程序会用有限长度 cutter 沿孔方向加深切削，预览显示为红色。
  • 目标深度小于当前估算深度时，程序会在旧底面方向补料，让孔变浅，预览显示为绿色。
  • 目标深度必须大于 0；如果和当前估算深度几乎相同，会直接阻止。
  • 当前只支持 hole/groove candidate、端部类型为 blind、并且已经识别到 疑似底面 Face 的对象。
  • 通孔、封闭内腔、圆角、凸柱和未明确圆柱面会被阻止，避免误切。
  • 这个深度来自圆柱面 V 参数范围和端部 inside / outside 采样，是几何估算，不是 CAD 历史参数。
  • 操作历史会记录当前深度、目标深度、深度变化比例、底面 face、开口端 face 和工具参数。
• 圆角半径 + 给边添加圆角：
  • 先切换到 Edge 选择模式并选择一条直线 edge，或从 第一版可编辑对象 中点击 给边添加圆角 行进入。
  • 选中直线 edge 后，圆角半径 会自动填入一个较小的建议半径。
  • 输入目标圆角半径后点击 给边添加圆角。
  • 程序会先检查半径是否大于 0、是否相对边长过大，以及该 edge 是否检测到至少两个相邻 face。
  • 点击后会显示蓝色半透明圆管预览，用于提示目标边和半径范围。
  • 真实编辑会在后台调用 OCCT 倒圆 API，完成后刷新模型。
  • 这是“给直线边添加新圆角”，不是修改已有圆角面。
  • 由于 STEP 不带建模历史，某些边会被 OCCT 判断为不适合倒圆；失败时程序会提示并尝试恢复编辑前状态。
• 圆角半径 + 修改已有圆角半径：
  • 先切换到 Feature 选择模式并选择一个已有圆角/倒圆候选 face，或从 第一版可编辑对象 中点击 修改已有圆角半径 行进入。
  • 选中已有圆角候选后，圆角半径 会自动填入一个基于当前估算半径的参考目标值。
  • 输入目标半径后点击 修改已有圆角半径。
  • 程序会先检查该 face 是否为 round/fillet candidate、是否识别到至少两个支撑 face、目标半径是否有效，以及当前零件是否为单 solid。
  • 通过检查后，会显示蓝色半透明预览，表示将尝试移除并重建的已有圆角面。
  • 真实编辑会先用 OCCT defeaturing 移除已有圆角面，再从恢复出的候选锐边中寻找可重新倒圆的边并调用 OCCT 倒圆 API。
  • 这是 B-Rep 几何重建，不是 CAD 历史圆角参数编辑；复杂 blend、支撑面不明确或恢复锐边失败时会失败并回滚。
• 倒角距离 + 给边添加倒角：
  • 先切换到 Edge 选择模式并选择一条直线 edge，或从 第一版可编辑对象 中点击 给边添加倒角 行进入。
  • 选中直线 edge 后，倒角距离 会自动填入一个较小的建议距离。
  • 输入目标倒角距离后点击 给边添加倒角。
  • 程序会先检查倒角距离是否大于 0、是否相对边长过大，以及该 edge 是否检测到至少两个相邻 face。
  • 点击后会显示橙色半透明圆管预览，用于提示目标边和倒角距离范围。
  • 真实编辑会在后台调用 OCCT 倒角 API，完成后刷新模型。
  • 当前只支持对称距离倒角，不支持两侧不同距离或距离+角度倒角。
  • 由于 STEP 不带建模历史，某些边会被 OCCT 判断为不适合倒角；失败时程序会提示并尝试恢复编辑前状态。
• 边目标长度 + 调整直线边长度：
  • 先切换到 Edge 选择模式并选择一条直线 edge，或从 第一版可编辑对象 中点击 调整直线边长度 行进入。
  • 选中直线 edge 后，边目标长度 会自动填入当前边长。
  • 把它改成目标长度后点击 调整直线边长度。
  • 程序会先查找该边端点附近是否有可推拉的平面端面，并计算需要移动的端面 face 和推拉距离。
  • 通过检查后，会显示蓝绿色半透明预览，表示将要移动的端面推拉范围。
  • 真实编辑复用平面推拉的布尔流程，执行失败时会回滚到编辑前状态。
  • 如果这条边没有明确端面，或端面方向与边长变化不匹配，会被阻止。这是受限功能，不是任意边参数化改长。
• 平移 X/Y/Z + 平移选中零件 / 平移选中 solid：
  • 输入 X、Y、Z 三个方向的平移量。
  • 选择 Part 后点击 平移选中零件，会移动整个 part。
  • 选择 Solid，或选择属于某个 solid 的 face/edge 后，点击 平移选中 solid，会移动当前 solid。
  • 如果当前 part 只有一个 solid，平移 solid 实际会移动整个 part shape，程序会提示中风险。
  • 平移向量为 0 会直接阻止。
  • 如果平移距离相对对象包围盒过大，程序会提高风险并要求确认。
  • 平移属于真实 B-Rep 变换，会写入操作历史，可以撤销/重做。
• 旋转轴/角度 + 旋转选中零件 / 旋转选中 solid：
  • 选择 X、Y 或 Z 旋转轴。
  • 输入旋转角度，单位是度。
  • 选择 Part 后点击 旋转选中零件，会绕该 part 的包围盒中心旋转整个 part。
  • 选择 Solid，或选择属于某个 solid 的 face/edge 后，点击 旋转选中 solid，会绕该 solid 的包围盒中心旋转当前 solid。
  • 如果当前 part 只有一个 solid，旋转 solid 实际会旋转整个 part shape，程序会提示中风险。
  • 旋转角度为 0 会直接阻止；角度超过 360 度会提高风险并要求确认。
  • 旋转属于真实 B-Rep 变换，会写入操作历史，可以撤销/重做。
• 撤销：
  • 撤销上一次成功的实验性编辑。
• 重做：
  • 重做刚刚撤销的实验性编辑。
• 操作历史：
  • 显示当前模型已经成功执行的实验性编辑。
  • 点击某条历史记录，会在 选中对象信息 中显示该次编辑的目标、参数、执行结果和拓扑数量变化。
  • 历史详情也会显示几何差异摘要，包括体积、表面积、包围盒尺寸和包围盒对角线的前后变化。
  • 点击某条历史记录时，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 几何上的布尔操作可能失败；失败时程序会弹窗提示，不会静默覆盖原始文件。