本文详解如何使用pyvista结合空间查询与符号距离原理，准确量化一个三角网格对另一个网格的穿透深度，并将结果以带颜色映射的vtk格式保存，适用于机械装配分析、碰撞检测与cae前处理等工程场景。
本文详解如何使用pyvista结合空间查询与符号距离原理，准确量化一个三角网格对另一个网格的穿透深度，并将结果以带颜色映射的vtk格式保存，适用于机械装配分析、碰撞检测与cae前处理等工程场景。
在三维仿真与几何分析中，“接触穿透”（penetration）并非简单欧氏距离——它是一个有向量：当点位于另一网格内部时，距离应为负值，其绝对值即为穿透深度；外部则为正值（最近距离）。而scipy.spatial.cKDTree.query()仅返回最小正距离，无法区分内外，因此直接使用d_kdtree会导致接触区域全部显示为“零距离”（蓝色），掩盖真实穿透信息。
要实现真正的穿透测量，核心在于判定每个查询点相对于目标网格的内外关系。PyVista 提供了成熟、鲁棒的 mesh.contains_points() 方法（基于射线投射算法），可高效判断点集是否位于封闭网格内部。结合 KD 树距离，即可构建符号距离场（Signed Distance Field, SDF）：
import numpy as np
import pyvista as pv
from 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.points
tree = 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.save(output_path)
print(f"✅ Contact data saved to: {output_path}")
⚠️ 重要注意事项：
- 水密性是前提：contains_points() 要求目标网格（mesh1）为封闭、无孔洞、法向一致的流形网格。建议调用 .clean().triangulate().fill_holes() 预处理，并用 .is_watertight 和 .check_integrity() 验证。
- 性能优化：对百万级点云，contains_points() 可能较慢。如需加速，可先用 tree.query_ball_point(points2, radius=tolerance) 粗筛潜在穿透区域，再仅对候选点执行精确内外判定。
- 物理意义澄清：此处“穿透深度”定义为点到目标网格表面的最短有向距离，非沿特定方向（如法向）的投影穿透。若需法向穿透（如接触力学中的间隙），应结合面片法向与重心坐标插值，或使用 PyVista 的 ray_trace() 进行定向射线检测。
- 单位一致性：确保输入 STL 文件单位统一（如 mm），输出距离单位即为模型单位。
该方法已广泛应用于公差分析、齿轮啮合仿真与3D打印支撑结构干涉检查中。相比手动实现射线投射或依赖商业软件，PyVista 方案兼具精度、可复现性与工程集成能力——只需几行代码，即可将几何接触从“视觉重叠”提升为“量化指标”，真正打通 CAD 到 CAE 的数据闭环。
