PyVista 中为点标签添加背景边框的方法

背景介绍

在数据可视化领域，PyVista 作为一款强大的 3D 可视化工具，提供了丰富的标注功能。其中 add_point_labels 方法常用于在 3D 场景中添加点标签。然而在实际应用中，当场景复杂或标签较多时，如何提高标签的可读性成为一个重要问题。

问题分析

在 PyVista 0.43.4 及更早版本中，用户只能选择是否填充标签背景（通过 fill_shape 参数），但无法同时实现背景填充和边框效果。这导致在需要白色背景提高可读性的同时，又希望有边框来区分相邻标签的场景下，用户面临两难选择。

解决方案

PyVista 0.44.0 版本对此进行了改进，新增了 background_color 参数，使得用户可以：

1. 通过 fill_shape=True 启用背景填充
2. 通过 background_color 设置背景颜色
3. 通过 fill_shape=False 时自动显示边框效果

实际应用示例

import numpy as np
import pyvista as pv

# 创建绘图器
pl = pv.Plotter()

# 定义点坐标和标签
points = np.array([[0.0, 0.0, 0.0], [1.0, 1.0, 0.0], [2.0, 0.0, 0.0]])
labels = ['点A', '点B', '点C']

# 添加点标签
actor = pl.add_point_labels(
    points,
    labels,
    italic=True,
    font_size=20,
    point_color='red',
    point_size=20,
    render_points_as_spheres=True,
    always_visible=True,
    shape=True,
    fill_shape=True,  # 启用背景填充
    background_color='white'  # 设置背景颜色
)

# 设置相机视角并显示
pl.camera_position = 'xy'
pl.show()

效果对比

1. 无背景填充 (fill_shape=False)：

   • 只有文字和边框
   • 适合简单场景或背景单一的情况

2. 有背景填充 (fill_shape=True 配合 background_color)：

   • 文字带有背景色
   • 提高在复杂背景下的可读性
   • 适合多标签或背景复杂的情况

最佳实践建议

1. 对于密集标签场景，建议使用白色背景配合边框
2. 调整 font_size 和 background_color 以达到最佳对比度
3. 考虑使用 shape=True 增强标签的立体感
4. 在 PyVista 0.44.0 及以上版本中，可以充分利用新的背景颜色设置功能

总结

PyVista 的点标签功能经过版本迭代，已经能够很好地满足各种可视化场景的需求。通过合理配置 fill_shape 和 background_color 参数，用户可以在保持标签可读性的同时，实现美观的视觉效果。对于需要升级版本的用户，建议升级到 PyVista 0.44.0 或更高版本以获得完整功能。