pyvista

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PyVista - 3D Visualization

PyVista - 3D可视化

Quick Reference

快速参考

python

import pyvista as pv

mesh = pv.read('model.vtk')
plotter = pv.Plotter()
plotter.add_mesh(mesh, scalars='property', cmap='viridis')
plotter.show()

python

import pyvista as pv

mesh = pv.read('model.vtk')
plotter = pv.Plotter()
plotter.add_mesh(mesh, scalars='property', cmap='viridis')
plotter.show()

Key Classes

核心类

Class	Purpose
`pv.Plotter`	Main visualization window
`pv.PolyData`	Surface meshes, point clouds
`pv.StructuredGrid`	Regular 3D grids
`pv.UnstructuredGrid`	Irregular meshes
`pv.ImageData`	3D voxel data (seismic)

类	用途
`pv.Plotter`	主可视化窗口
`pv.PolyData`	曲面网格、点云
`pv.StructuredGrid`	规则3D网格
`pv.UnstructuredGrid`	不规则网格
`pv.ImageData`	3D体素数据（地震数据）

Essential Operations

核心操作

Load and Display Mesh

加载并显示网格

python

mesh = pv.read('model.vtk')
plotter = pv.Plotter()
plotter.add_mesh(mesh, scalars='lithology', cmap='Set1')
plotter.show()

python

mesh = pv.read('model.vtk')
plotter = pv.Plotter()
plotter.add_mesh(mesh, scalars='lithology', cmap='Set1')
plotter.show()

Create Structured Grid (Surface)

创建结构化网格（曲面）

python

x, y = np.meshgrid(np.arange(-10, 10, 0.5), np.arange(-10, 10, 0.5))
z = np.sin(np.sqrt(x**2 + y**2))
grid = pv.StructuredGrid(x, y, z)
pv.Plotter().add_mesh(grid, scalars=z.ravel(), cmap='terrain').show()

python

x, y = np.meshgrid(np.arange(-10, 10, 0.5), np.arange(-10, 10, 0.5))
z = np.sin(np.sqrt(x**2 + y**2))
grid = pv.StructuredGrid(x, y, z)
pv.Plotter().add_mesh(grid, scalars=z.ravel(), cmap='terrain').show()

Visualize Point Cloud

可视化点云

python

cloud = pv.PolyData(np.random.rand(1000, 3) * 100)
cloud['depth'] = cloud.points[:, 2]
pv.Plotter().add_mesh(cloud, scalars='depth', point_size=5,
                      render_points_as_spheres=True).show()

python

cloud = pv.PolyData(np.random.rand(1000, 3) * 100)
cloud['depth'] = cloud.points[:, 2]
pv.Plotter().add_mesh(cloud, scalars='depth', point_size=5,
                      render_points_as_spheres=True).show()

Volume Rendering (Seismic)

体渲染（地震数据）

python

grid = pv.ImageData(dimensions=(nx+1, ny+1, nz+1), spacing=(25, 25, 10))
grid.cell_data['amplitude'] = data.ravel(order='F')
pv.Plotter().add_volume(grid, cmap='seismic', opacity='sigmoid').show()

python

grid = pv.ImageData(dimensions=(nx+1, ny+1, nz+1), spacing=(25, 25, 10))
grid.cell_data['amplitude'] = data.ravel(order='F')
pv.Plotter().add_volume(grid, cmap='seismic', opacity='sigmoid').show()

Slice Through Volume

体数据切片

python

volume = pv.read('seismic.vti')
slice_x = volume.slice(normal='x', origin=volume.center)
pv.Plotter().add_mesh(slice_x, cmap='seismic').show()

python

volume = pv.read('seismic.vti')
slice_x = volume.slice(normal='x', origin=volume.center)
pv.Plotter().add_mesh(slice_x, cmap='seismic').show()

Well Path Visualization

井轨迹可视化

python

points = np.column_stack([x, y, z])  # Well trajectory
tube = pv.Spline(points, 500).tube(radius=5)
pv.Plotter().add_mesh(tube, color='brown', label='Well').add_legend().show()

python

points = np.column_stack([x, y, z])  # 井轨迹数据
tube = pv.Spline(points, 500).tube(radius=5)
pv.Plotter().add_mesh(tube, color='brown', label='Well').add_legend().show()

Combine Multiple Surfaces

多曲面组合显示

python

plotter = pv.Plotter()
plotter.add_mesh(horizon1, color='gold', opacity=0.7, label='Top')
plotter.add_mesh(horizon2, color='blue', opacity=0.7, label='Base')
plotter.add_mesh(fault, color='red', opacity=0.5, label='Fault')
plotter.add_legend().show()

python

plotter = pv.Plotter()
plotter.add_mesh(horizon1, color='gold', opacity=0.7, label='Top')
plotter.add_mesh(horizon2, color='blue', opacity=0.7, label='Base')
plotter.add_mesh(fault, color='red', opacity=0.5, label='Fault')
plotter.add_legend().show()

Export for Publication

导出出版级文件

python

plotter = pv.Plotter(off_screen=True)
plotter.add_mesh(mesh, cmap='terrain')
plotter.screenshot('figure.png', scale=3)   # High-res image
plotter.export_html('model.html')           # Interactive HTML

python

plotter = pv.Plotter(off_screen=True)
plotter.add_mesh(mesh, cmap='terrain')
plotter.screenshot('figure.png', scale=3)   # 高分辨率图片
plotter.export_html('model.html')           # 交互式HTML文件

Color Maps

颜色映射

Map	Use Case
`terrain`	Topography, elevation
`seismic`	Seismic amplitudes (diverging)
`viridis`	General scientific
`Set1` , `Set2`	Categorical (lithology)

映射名称	使用场景
`terrain`	地形、海拔
`seismic`	地震振幅（发散型）
`viridis`	通用科学可视化
`Set1` , `Set2`	分类数据（岩性）

Supported Formats

支持的格式

.vtk

.vtu

.vti

.vtp

.stl

.obj

.ply

(read/write)

.vtk

.vtu

.vti

.vtp

.stl

.obj

.ply

（支持读写）

When to Use vs Alternatives

适用场景与替代工具对比

Tool	Best For	Limitations
pyvista	Pythonic 3D viz, VTK wrapper, mesh operations, scripting	Requires display or off-screen backend
Mayavi	Scientific 3D visualization, volume rendering	Heavier dependency, less active development
ParaView	Interactive GUI exploration of large 3D datasets	GUI-focused, scripting is secondary
matplotlib 3D	Simple 3D scatter/surface plots	Limited interactivity, not true 3D engine

Use pyvista when you need programmatic 3D visualization of geological models, meshes, or point clouds with VTK power but a Pythonic API.

Consider alternatives when you need a full GUI for exploring large models (use ParaView), legacy scientific visualization (use Mayavi), or only need simple 3D scatter plots (use matplotlib 3D).

工具	最佳适用场景	局限性
pyvista	Python风格的3D可视化、VTK封装、网格操作、脚本编写	需要显示设备或离线渲染后端
Mayavi	科学3D可视化、体渲染	依赖更重、开发活跃度较低
ParaView	大型3D数据集的交互式GUI探索	以GUI为核心，脚本编写为次要功能
matplotlib 3D	简单3D散点/曲面图	交互性有限，并非真正的3D引擎

当你需要利用VTK的强大功能，同时通过Python风格的API对地质模型、网格或点云进行程序化3D可视化时，选择pyvista。

考虑替代工具的场景：当你需要完整的GUI来探索大型模型时（使用ParaView），需要传统科学可视化工具时（使用Mayavi），或者仅需简单的3D散点图时（使用matplotlib 3D）。

Common Workflows

常见工作流程

Visualize 3D geological model with multiple surfaces

多曲面3D地质模型可视化

Load mesh files with
```
pv.read()
```
for each surface/horizon
Create plotter with
```
pv.Plotter()
```
(use
```
off_screen=True
```
for scripts)
Add each surface with
```
plotter.add_mesh()
```
and distinct colors/opacity
Add well paths as tubes with
```
pv.Spline().tube()
```
Add axes and legend with
```
plotter.add_axes()
```
and
```
plotter.add_legend()
```
Set camera position for desired view angle

Export screenshot with

plotter.screenshot()

or HTML with

plotter.export_html()

使用
```
pv.read()
```
加载每个曲面/层位的网格文件
使用
```
pv.Plotter()
```
创建绘图器（脚本中使用
```
off_screen=True
```
）
使用
```
plotter.add_mesh()
```
添加每个曲面，并设置不同的颜色/透明度
使用
```
pv.Spline().tube()
```
将井轨迹生成为管状模型并添加
使用
```
plotter.add_axes()
```
和
```
plotter.add_legend()
```
添加坐标轴和图例
设置相机位置以获得所需视角
使用
```
plotter.screenshot()
```
导出截图，或使用
```
plotter.export_html()
```
导出HTML文件

Tips

小贴士

Use
```
off_screen=True
```
for batch processing
Add axes with
```
plotter.add_axes()
```
for publication
Export to HTML for interactive sharing
Use opacity to show internal structure

批量处理时使用
```
off_screen=True
```
用于出版时使用
```
plotter.add_axes()
```
添加坐标轴
导出为HTML以实现交互式分享
使用透明度展示内部结构

References

参考资料

Mesh Types - PyVista mesh classes and when to use each
Plotting Options - Plotter settings and rendering options

网格类型 - PyVista网格类及其适用场景
绘图选项 - 绘图器设置与渲染选项

Scripts

脚本示例

scripts/visualize_surface.py - Visualize geological surfaces from file

scripts/visualize_surface.py - 从文件可视化地质曲面