安装PyVista包

依赖项

PyVista 构建在 Visualization Toolkit (VTK) 和 NumPy 之上——因此，以下项目是 PyVista 的必需依赖项：

pooch - 用于我们的示例数据集的数据管理，以便用户可以即时下载教程。

可选依赖项

PyVista 包括几个可选依赖项，用于可视化和读取各种附加文件格式，包括：

PyPI

PyVista 可以使用 pip 从 PyPI 安装：

pip install pyvista

要安装所有扩展 PyVista 的附加包，请使用 pip 安装：

pip install pyvista[all]

Anaconda

要使用 conda 安装此包，请运行：

conda install -c conda-forge pyvista

Pixi

Pixi 是一个现代包管理工具，提供快速、可靠和可复现的软件环境。它可以作为 conda/mamba 的替代方案来管理 PyVista 安装。

要使用 pixi 安装 PyVista，首先确保已安装 pixi（参见 pixi 安装说明），然后运行：

pixi add pyvista

这会将 PyVista 添加到您的 pixi.toml 文件并在您的项目环境中安装它。要在 pixi 环境中使用 PyVista：

pixi shell

python -c 'import pyvista as pv; print(pv.__version__)'

Pixi 自动处理所有依赖项并确保跨不同平台的兼容性。

从 GitHub 安装当前开发分支

可能有些功能或错误修复已在 PyVista 中实现但尚未发布。要从 github 上的最新最新开发分支安装 pyvista，请使用以下方法之一：

pip install -U git+https://github.com/pyvista/pyvista.git@main

或者，您可以使用 git 克隆存储库并使用 pip 安装它。

git clone https://github.com/pyvista/pyvista.git

cd pyvista

pip install -e .

注意开发标志 -e。这允许您就地更改 pyvista，而无需为每个更改重新安装它。

开发轮子（Wheels）

PyVista 文档站点还托管了一个 PEP 503 “简单存储库”，其中包含从 main 最新提交构建的轮子。这些轮子由文档流水线在每次推送到 main 时重新构建并重新发布，因此该索引始终指向最新的 main 构建，无需 GitHub 克隆或检出。

要安装最新的开发轮子：

pip install --upgrade --pre --index-url https://dev.pyvista.org/wheels/simple/ pyvista

要保持 PyPI 作为依赖项的来源，并仅从开发索引拉取 pyvista 本身，请改用 --extra-index-url：

pip install --upgrade --pre --extra-index-url https://dev.pyvista.org/wheels/simple/ pyvista

每个构建都带有形式为 <base>+g<short-sha>（例如 0.48.dev0+g11c36e50）的 PEP 440 本地版本段，因此轮子构建自的具体提交始终可从版本字符串中恢复。针对开发索引运行 pip install --pre -U pyvista 将始终获取最新提交的轮子。

当前构建的可读着陆页可在 dev.pyvista.org/wheels/ 获取。

警告

这些轮子是不受支持的开发构建。它们可能包含尚未发布的不完整更改、回归或破坏性 API 更改。将它们用于测试即将推出的功能或针对 main 复现报告，而非用于生产。对于稳定版本，请照常从 PyPI 安装。

可选依赖项

以下是可选依赖项及其用途的列表：

表格

源代码 / 开发者

或者，您可以通过访问 PyVista 并从 GitHub 安装最新版本来下载源代码（克隆）：

git clone https://github.com/pyvista/pyvista.git

cd pyvista

python -m pip install -e .

main 分支的 PyVista 最新文档可在 dev.pyvista.org 找到。

测试安装

您可以通过运行示例来测试安装：

from pyvista import demos
demos.plot_wave()

查看其他示例和演示：

from pyvista import examples
from pyvista import demos
# 列出所有可用示例。
print(dir(examples))
# 列出所有可用演示。

注意

在克隆源代码存储库后，可使用更全面的测试套件。有关如何克隆和测试 PyVista 源代码的详细信息，请参阅我们的贡献指南，特别是测试部分。

在 CI 服务上运行

请前往 pyvista/setup-headless-display-action 了解有关在 GitHub Actions 工作流中使用 PyVista 设置无头显示的详细信息。

过去，我们也支持 pyvista/gl-ci-helpers 来设置 Travis 和 Azure Pipelines 等 CI 服务以运行 PyVista。

在 MyBinder 上运行

本节适用于希望在 MyBinder 等笔记本托管服务上使用无头显示安装和使用 PyVista 的高级用户。

请参阅此项目以获取方便的 Cookiecutter 以开始在 MyBinder 上使用 PyVista。

Docker 容器只需要 VTK 的运行时 GL 库。对于 MyBinder，在名为 apt.txt 的文件中包含以下内容：

libopengl0

libgl1

libegl1

libxrender1

这是完整的系统库集：libegl1 启用 EGL，因此当容器使用 NVIDIA 容器运行时运行时，VTK 会自动选择 GPU 加速，并在仅 CPU 的主机上回退到 Mesa 的 llvmpipe 软件渲染器。从 VTK 9.5 开始，无头离屏渲染与库存 PyPI vtk 轮子开箱即用，因此不需要 Xvfb 或 DISPLAY 设置。

在您的 Python 需求中包含 PyVista，并且 pv.Plotter(off_screen=True) 将进行渲染。如果您在这些类型的服务上设置 PyVista 需要更多帮助，请访问讨论页面与开发人员聊天，或查看此存储库，该存储库当前在 MyBinder 上使用 PyVista。

在远程服务器上运行

在远程服务器上使用 PyVista 需要与上述 Docker 案例类似的设置步骤。例如，以下是在 AWS EC2 Ubuntu 18.04 LTS（us-east-1 中的 ami-0a313d6098716f372）上使用 PyVista 的完整步骤。其他服务器类似。

登录远程服务器后，安装 VTK 的运行时 GL 库并设置 Python：

sudo apt update && sudo apt install -y \

libopengl0 libgl1 libegl1 libxrender1

python -m venv vtk_env

source vtk_env/bin/activate

pip install jupyter 'pyvista[jupyter]'

安装了 libegl1 后，VTK 9.5+ 通过 EGL 开箱即用进行离屏渲染，因此不需要 Xvfb 或 DISPLAY 配置。在 shell 中设置 PYVISTA_OFF_SCREEN=true（或在构造 Plotter 时传递 off_screen=True），并且 pv.Plotter(off_screen=True) 将正常工作。

通过端口转发重新连接到服务器，并启动 Jupyter：

ssh -i "your-ssh-key" your-user-name@your-server-ip -L 8888:localhost:8888

source vtk_env/bin/activate

jupyter lab --NotebookApp.token='' --no-browser --port=8888

在 Web 浏览器中访问 localhost:8888。

在 WSL 上运行

与上面的远程服务器示例类似，Linux 的 Windows 子系统不提供用于可视化的 X 服务器。相反，在 WSL 上快速启动并运行的最快方法是通过 JupyterLab。

首先，安装 VTK 的运行时 GL 库并设置 Python：

sudo apt update && sudo apt install -y \

libopengl0 libgl1 libegl1 libxrender1

python -m venv vtk_env

source vtk_env/bin/activate

pip install jupyter 'pyvista[jupyter]'

VTK 与 Jupyter 的链接

从 VTK 9.5 开始，当安装了 libegl1 时，无头离屏渲染与库存 PyPI vtk 轮子开箱即用。不需要 Xvfb 或 DISPLAY 配置。启动 Jupyter：

jupyter lab --NotebookApp.token='' --no-browser --port=8888

在 Web 浏览器中访问 localhost:8888。

最后添加此示例代码，您的交互式可视化应显示在 JupyterLab 中。

import pyvista as pv
pl = pv.Plotter(shape=(1, 2))
actor = pl.add_mesh(pyvista.Cube())
pl.subplot(0, 1)
actor = pl.add_mesh(pyvista.Sphere())
pl.set_background('orange', all_renderers=False)
pl.show()

您的可视化现在应直接显示在 Jupyter 前端中。

与 Sphinx-Gallery 一起运行

在您的 conf.py 中，添加以下内容：

import pyvista as pv
# 构建 sphinx gallery 时必需
pv.BUILDING_GALLERY = True
pv.OFF_SCREEN = True
# 可选 - 设置参数如主题或窗口大小
pv.set_plot_theme('document')
pv.global_theme.window_size = np.array([1024, 768]) * 2
extensions = [
    ...,
    "sphinx_gallery.gen_gallery",
]
# 将 PyVista 图像抓取器添加到 SG
sphinx_gallery_conf = {
    ...: ...,
    "image_scrapers": ('pyvista', ...),
    ...: ...,
}

我们还有一个 Sphinx-Gallery 抓取器，用于嵌入动态 3D 场景而不是静态屏幕截图。可以通过将上述 image_scrapers 参数传递实例而不是直接传递字符串 'pyvista'，并注册 pyvista.ext.viewer_directive 扩展来启用此抓取器：

import pyvista as pv
from pyvista.plotting.utilities.sphinx_gallery import DynamicScraper
# 构建 sphinx gallery 时必需
pv.BUILDING_GALLERY = True
pv.OFF_SCREEN = True
# 可选 - 设置参数如主题或窗口大小
pv.set_plot_theme('document')
pv.global_theme.window_size = np.array([1024, 768]) * 2
extensions = [
    ...,
    "sphinx_gallery.gen_gallery",
    "pyvista.ext.viewer_directive",
]
# 将 PyVista 图像抓取器添加到 SG
sphinx_gallery_conf = {
    ...: ...,
    "image_scrapers": (DynamicScraper(), ...),
    ...: ...,
}