本文详解如何使用pyvista结合空间查询与符号距离原理，准确量化一个三角网格对另一个网格的穿透深度，并将结果以带颜色映射的vtk格式保存，适用于机械装配分析、碰撞检测与cae前处理等工程场景。
在三维仿真与几何分析中，接触穿透的计算是个绕不开的坎儿。我常遇到的一个问题是：两个网格“叠”在一起了，到底穿进去多深？很多人第一反应就是算欧氏距离，但严格来说，穿透深度是个有向量——点跑到了目标网格内部，距离就成了负值，绝对值才是真正的深度；如果还在外面，那就是正的最短距离。这里面的坑，是从最基础的数学理解开始的。
用KD-tree去查最近点行不行？行的。但它有个致命短板：scipy.spatial.cKDTree.query()只告诉你最近距离，不管你是里面还是外面。结果就是，明明穿进去了，距离显示却是个零值——在可视化里全成了蓝色，等于没穿。
那么，要判断内外，就需要一个思路的转变。
真正的难点在于判定每个查询点相对于目标网格的内外关系。PyVista 的 mesh.contains_points() 就是为此而生的——基于射线投射算法，高效且鲁棒。结合 KD-tree 距离，就能构建一个符号距离场：
import numpy as npimport pyvista as pvfrom scipy.spatial import cKDTree# 1. 加载并预处理网格（确保水密性）mesh1 = pv.read("mesh1.stl").clean().triangulate() # 目标网格（被穿透者）mesh2 = pv.read("mesh2.stl").clean().triangulate() # 探针网格（施加穿透者）# ✅ 关键：验证网格封闭性（否则 contains_points 不可靠）if not mesh1.is_watertight: raise ValueError("mesh1 must be watertight for inside/outside query")# 2. 构建符号距离：正=外部距离，负=内部穿透深度points2 = mesh2.pointstree = cKDTree(mesh1.points)# 查询最近距离与最近点索引distances, idx_closest = tree.query(points2)# 判定点是否在 mesh1 内部（True 表示 inside → penetration）inside_flags = mesh1.contains_points(points2)# 构建符号距离数组：内部点取负距离，外部点保持正距离signed_distances = np.where(inside_flags, -distances, distances)# 3. 将结果绑定到 mesh2 的点数据中mesh2.point_data["penetration_depth"] = signed_distances# 4. 可视化：穿透区域（负值）用暖色突出，外部用冷色plotter = pv.Plotter()plotter.add_mesh( mesh2, scalars="penetration_depth", clim=[np.min(signed_distances), 0], # 重点关注穿透（≤0） cmap="coolwarm", show_edges=False, opacity=0.95)plotter.add_mesh(mesh1, color="lightgray", opacity=0.3, show_edges=True)plotter.add_text("Penetration Depth (mm)", font_size=12, position="upper_left")plotter.show()# 5. 保存含穿透数据的 VTK 文件（支持 ParaView/VisIt 直接读取）output_path = "contact_analysis.vtk"mesh2.sa ve(output_path)print(f"✅ Contact data sa ved to: {output_path}")写代码前，有几件事要先说清楚。
水密性是前提。contains_points() 依赖网格封闭，mesh1 绝不能有孔洞或者法向不一致。建议先用 .clean().triangulate().fill_holes() 预处理，再用 .is_watertight 和 .check_integrity() 验一下身。
性能优化也别忽略。对上百万的点云，contains_points() 可能会慢到让人想砸键盘。一个常见策略：先用 KD-tree 的 query_ball_point() 粗筛潜在穿透区域，只对候选点做精确判定。
物理意义这里得说清楚——我们定义的“穿透深度”是点到目标网格表面的最短有向距离，而不是沿某个法向方向的投影距离。如果要做接触力学里的法向间隙分析，就得结合面片法向与重心坐标插值，或者用 ray_trace() 做定向射线检测。
单位也得盯紧。STL 文件统一用 mm 输入，输出距离自然就是 mm，否则一换算就会跑偏。
这套方法在公差分析、齿轮啮合仿真、3D打印支撑结构干涉检查中已经跑得很稳了。对比手动实现射线投射或依赖商业软件，PyVista 的方案精度可控、可复现，而且工程集成能力强——几行代码，就能把几何接触从“视觉重叠”升级为“量化指标”，让 CAD 到 CAE 的数据闭环真正跑通。
