PyVista设置show_edges=True后模型整体变黑如何解决

问题复现 #

在WSL Ubuntu环境运行PyVista代码，调用add_mesh时传入show_edges=True参数，预期显示带边线的三维模型，实际模型整体渲染为纯黑色，无正常面颜色显示。
以渲染带边线的球体为例，异常效果如下：

最小复现代码：

import pyvista as pv

sphere = pv.Sphere()

pl = pv.Plotter()
pl.add_mesh(sphere, show_edges=True)

pl.show()

故障原因 #

该问题属于WSL环境下OpenGL渲染栈与PyVista默认边线渲染逻辑的兼容缺陷：WSL默认GPU加速渲染对边线、模型面的深度测试支持异常，开启边线渲染后，黑色边线会完全覆盖模型面的颜色输出，最终呈现全黑效果。

修复方案 #

按优先级从高到低可选择以下方案：

• 优先使用深度剥离配置，无需修改系统设置，兼容性最高。直接在add_mesh时显式指定颜色参数并开启深度剥离即可，修改后代码如下：

import pyvista as pv

sphere = pv.Sphere()

pl = pv.Plotter()
pl.add_mesh(
    sphere,
    show_edges=True,
    color="#ffffff",  # 显式指定模型面颜色
    edge_color="#000000",  # 显式指定边线颜色
    line_width=1,
    depth_peeling=True  # 开启深度剥离解决层级渲染冲突
)
pl.show()

• 如果上述方案无效，可强制PyVista使用适配WSL的osmesa软渲染后端，在导入pyvista后先设置全局渲染配置：

import pyvista as pv
pv.global_theme.rendering_backend = "osmesa"

# 后续原有渲染逻辑不变
sphere = pv.Sphere()
pl = pv.Plotter()
pl.add_mesh(sphere, show_edges=True)
pl.show()

• 若不需要在WSL中使用GPU加速，可关闭WSL2的GPU支持从根源规避渲染兼容问题：在Windows用户目录下创建/编辑.wslconfig文件，写入如下配置：

[wsl2]
gpuSupport = false

保存后在Windows终端执行wsl --shutdown，重启WSL后再运行代码即可正常渲染。

内容的提问来源于stack exchange，提问作者Jasonczx