1. 从 step 文件到会动的三维模型，PythonOcc 这条链路到底卡在哪
如果你正在做三维 CAD 数据处理，大概率会遇到这样的场景：手头有一堆 step 文件，想批量读取里面的零件、转成别的格式，甚至让机构按运动学关系动起来。PythonOcc 就是干这个的——它是 OpenCASCADE 的 Python 封装，能读 step、IGES、STL，能做布尔运算、网格化、格式转换，还能挂到 Qt 里做三维可视化。适合谁？做 CAD 二次开发的、搞机构仿真的、需要把工业模型接进自己程序的工程师。
但真正上手你会发现，卡点不在“读文件”这一步。read_step_file一行就能把 step 读进来，可读进来的是TopoDS_Shape这种拓扑格式，它没法直接扔进三维显示环境里做动画。你得先转成AIS_Shape，再通过Context.Display挂上去，动画还得靠SetLocation一帧一帧刷。中间任何一步搞错，要么模型不显示，要么动了但位置全乱。
我试过把四连杆机构的 step 文件从读取、格式转换到动画展示完整跑一遍，中间踩的坑基本都集中在“格式转换”和“运动坐标系”这两块。下面把整条链路拆开，每一步都给可复制的代码骨架，你照着改文件路径就能跑。
2. 前置准备：PythonOcc 环境与 TaoToken 接入配置
PythonOcc 的安装是第一个门槛。官方推荐用 conda，因为底层依赖 OpenCASCADE 的二进制库，pip 直接装经常缺 DLL。
conda create -n pyocc python=3.10 conda activate pyocc conda install -c conda-forge pythonocc-core=7.7.0 pip install PyQt5 numpy装完验证一下：
from OCC.Core.BRepPrimAPI import BRepPrimAPI_MakeBox from OCC.Display.SimpleGui import init_display box = BRepPrimAPI_MakeBox(10, 20, 30).Shape() display, start_display, _, _ = init_display() display.DisplayShape(box, update=True) start_display()能弹出一个带立方体的窗口，环境就通了。
如果你在开发过程中需要调用大模型来辅助生成 OCC 的 API 调用代码、排查报错，或者做批量脚本的自动化，可以配一个统一的模型接入层。TaoToken 提供 OpenAI 兼容的接口，把 base_url 指过去就行：
from openai import OpenAI client = OpenAI( api_key="你的Key", base_url="https://taotoken.net/api" ) resp = client.chat.completions.create( model="claude-sonnet-4-20250514", messages=[{"role": "user", "content": "PythonOcc 里 AIS_Shape 和 TopoDS_Shape 有什么区别？"}] ) print(resp.choices[0].message.content)Key 在控制台的 API Keys 页面拿，接入文档里有完整的参数说明。这样你在写 OCC 脚本时遇到不熟的类，可以直接问，不用来回翻文档。
3. 可复制配置：step 导入 + 格式转换 + 动画展示完整代码
3.1 step 文件读取与拓扑解析
先解决“读进来”的问题。read_step_file返回的是复合 shape，里面可能包含多个 solid。用TopologyExplorer遍历：
from OCC.Extend.DataExchange import read_step_file from OCC.Extend.TopologyUtils import TopologyExplorer def load_step(path): shape = read_step_file(path) explorer = TopologyExplorer(shape) solids = list(explorer.solids()) print(f"读到 {len(solids)} 个 solid") return solids这里有个细节：step 文件里零件的顺序不一定和你在 CAD 软件里看到的装配顺序一致。四连杆机构里，曲柄、摇杆、连杆三个 solid 的索引需要你自己确认。简单办法是先全部显示出来，用不同颜色区分，肉眼对一下。
3.2 从 TopoDS_Shape 转到 AIS_Shape
这是最关键的一步。TopoDS_Shape是纯几何拓扑数据，没有显示属性；AIS_Shape是 OpenCASCADE 的交互对象，能挂颜色、材质、位置，才能放进Context里。
from OCC.Core.AIS import AIS_Shape from OCC.Core.Quantity import Quantity_Color, Quantity_TOC_RGB import random def to_ais(solids): ais_list = [] for s in solids: ais = AIS_Shape(s) color = Quantity_Color(random.random(), random.random(), random.random(), Quantity_TOC_RGB) ais.SetColor(color) ais_list.append(ais) return ais_list如果你只是想把 step 转成 STL 或 OBJ，不走显示链路，那用BRepMesh_IncrementalMesh做网格化再导出：
from OCC.Core.BRepMesh import BRepMesh_IncrementalMesh from OCC.Core.StlAPI import StlAPI_Writer def step_to_stl(shape, out_path, deflection=0.1): BRepMesh_IncrementalMesh(shape, deflection) writer = StlAPI_Writer() writer.Write(shape, out_path)3.3 挂到 Qt 显示环境并做动画
假设你已经有一个qtViewer3d这样的显示类（基于OCC.Display.OCCViewer封装），核心动画逻辑是：每一帧计算新的gp_Trsf，包成TopLoc_Location，然后Context.SetLocation更新。
四连杆的运动学关系用解析式算角度序列：
import numpy as np def alpha_trace(theta): return np.where( theta / (2 * np.pi) - np.trunc(theta / (2 * np.pi)) <= 0.5, np.arccos((3 * np.cos(theta) - 8) / np.sqrt(73 - 48 * np.cos(theta))) - np.arccos((9 - 8 * np.cos(theta)) / (3 * np.sqrt(73 - 48 * np.cos(theta)))), 2 * np.pi - np.arccos((3 * np.cos(theta) - 8) / np.sqrt(73 - 48 * np.cos(theta))) - np.arccos((9 - 8 * np.cos(theta)) / (3 * np.sqrt(73 - 48 * np.cos(theta)))) ) def gamma_trace(alpha, theta): return np.arccos(0.1 * (9 * np.cos(alpha) + 8 - 3 * np.cos(theta)))然后主循环里逐帧设置位置：
from OCC.Core.gp import gp_Ax1, gp_Pnt, gp_Dir, gp_Trsf, gp_Vec from OCC.Core.TopLoc import TopLoc_Location def animate(ctx, bar_crank, bar_rocker, bar_coupler, theta_seq, alpha_seq, gamma_seq, xx_seq, yy_seq): ax_origin = gp_Ax1(gp_Pnt(0., 0., 0.), gp_Dir(0., 0., 1.)) ax_fixed = gp_Ax1(gp_Pnt(400., 0., 0.), gp_Dir(0., 0., 1.)) for j in range(len(theta_seq)): # 曲柄绕原点转 t1 = gp_Trsf() t1.SetRotation(ax_origin, alpha_seq[j] - alpha_seq[0]) ctx.SetLocation(bar_crank, TopLoc_Location(t1)) # 摇杆绕固定点转 t2 = gp_Trsf() t2.SetRotation(ax_fixed, theta_seq[j] - theta_seq[0]) ctx.SetLocation(bar_rocker, TopLoc_Location(t2)) # 连杆：先转再平移 ax3 = gp_Ax1(gp_Pnt(xx_seq[j], yy_seq[j], 0.), gp_Dir(0., 0., 1.)) t3r = gp_Trsf() t3r.SetRotation(ax3, gamma_seq[j] - gamma_seq[0]) t3t = gp_Trsf() t3t.SetTranslation(gp_Vec(xx_seq[j] - xx_seq[0], yy_seq[j] - yy_seq[0], 0.)) ctx.SetLocation(bar_coupler, TopLoc_Location(t3r * t3t)) ctx.UpdateCurrentViewer()注意t3r * t3t的顺序：先旋转再平移，矩阵乘法是左乘旋转。顺序反了连杆会飞出去。
4. 验证请求：跑通后的成功结果与检查点
跑通之后你应该看到：窗口里三个零件以不同颜色显示，点击菜单触发动画后，曲柄匀速转、摇杆摆动、连杆做平面复合运动，整体构成四连杆的经典轨迹。
验证分三步：
第一步，静态显示。调用load_step后打印 solid 数量，四连杆应该是 3 个。如果读到 1 个，说明 step 里是装配体但被合并了，需要检查导出设置。
第二步，格式转换。对每个 solid 调AIS_Shape后Display，确认颜色生效、模型完整。如果显示成线框，检查Display的第二个参数是不是False（表示不更新，批量显示后再FitAll）。
第三步，动画。把theta_seq的步长设成 0.005，跑一轮大概几秒。观察连杆的端点是否始终和曲柄、摇杆的铰接点重合。如果出现错位，八成是XX2Ani、YY2Ani的计算公式里系数搞反了。
step = 0.005 start_p = 0.5 * np.pi end_p = 2 * np.pi + 0.5 * np.pi theta_seq = np.linspace(start_p, end_p, int((end_p - start_p) / step), endpoint=True) alpha_seq = alpha_trace(theta_seq) gamma_seq = gamma_trace(alpha_seq, theta_seq) xx_seq = 0.5 * (150 * np.cos(theta_seq) + 400 + 450 * np.cos(alpha_seq)) yy_seq = 0.5 * (150 * np.sin(theta_seq) + 450 * np.sin(alpha_seq))5. 本篇常见错排查
报错ModuleNotFoundError: No module named 'OCC.Core.AIS'pythonocc-core 版本不对。7.7 之后 AIS 模块路径没变，但如果你装的是 7.4 以下，部分类名不同。统一用 conda 装 7.7.0。
step 读进来是空的，solid 数量为 0文件路径含中文或空格。read_step_file底层是 C++ 接口，对非 ASCII 路径支持不好。把文件挪到纯英文路径下再试。
模型显示了但动画不动检查Context.UpdateCurrentViewer()有没有在每帧调用。另外SetLocation的第二个参数必须是TopLoc_Location对象，直接传gp_Trsf不会报错但也不生效。
连杆运动时位置偏移gp_Trsf的旋转和平移组合顺序问题。记住：SetRotation和SetTranslation是覆盖操作，不是叠加。要组合变换必须用t_rot * t_trans的方式构造新gp_Trsf。
动画卡顿严重每帧都FitAll会强制重算视图。只在第一帧FitAll，后续帧只调UpdateCurrentViewer。另外把theta_seq的步长从 0.001 放宽到 0.005，帧数少一半，流畅度明显提升。
AIS_Shape 颜色不生效SetColor之后需要Context.Redisplay或者重新Display。如果是在Display之前设的颜色，检查Quantity_Color的第四个参数是不是Quantity_TOC_RGB。
6. 继续深入：从能跑到好用
上面这套流程能让你把 step 导入、格式转换、动画展示跑通，但它有个明显的妥协：运动学关系是硬编码的解析式。真实机构一旦变参数，公式就得重推。OpenCASCADE 的 AIS 其实提供了连接和约束的接口，能让零件之间建立铰接关系，拖动一个另一个跟着动，不用自己算每一帧的变换矩阵。
如果你要长期做这类三维 CAD 数据处理和机构仿真，建议把模型调用和代码生成也纳入工作流。写 OCC 脚本时经常要查某个类的构造参数，用模型对话直接问比翻文档快。批量处理 step 文件、自动生成转换脚本这类任务，可以走 Coding Plan 做长上下文的任务编排。API Key 在控制台的 API Keys 页面创建，接入方式参考接入文档，base_url 统一用https://taotoken.net/api。
先把今天这套骨架跑起来，确认三个 solid 能正确显示、动画能连续播放，再往约束求解的方向走。
