PyVista

https://docs.pyvista.org/
Admin
PyVista is a foundational Python library for 3D visualization and mesh analysis in scientific...
Tokens:23,421
Snippets:284
Trust Score:8.9
Update:3 months ago
Show doc for...
Tokens:
Raw
### Get PyVista Examples Cache Path

Source: https://docs.pyvista.org/api/examples

Retrieves the local path where PyVista stores downloaded example files. This is useful for managing or inspecting the cache.

```python
>>> from pyvista import examples
>>> # Get the local examples path on Linux
>>> examples.PATH
'/home/user/.cache/pyvista_3'
```

--------------------------------

### Compare Cell Types from Different Generators (Examples)

Source: https://docs.pyvista.org/api/examples/_autosummary/pyvista.examples.cells.generate_cell_blocks

Generates and plots the first 25 cell types using the 'examples' generator. This allows comparison with other generators and highlights expected gaps due to undefined cell types.

```python
>>> kwargs = dict(
...     cell_types=range(1, 26),
...     block_dimensions=(5, 5, 1),
...     unsupported_action='skip',
... )
>>> cell_blocks = generate_cell_blocks(generator='examples', **kwargs)
>>> plot_cell(cell_blocks, cpos='xy', **size_kwargs)
```

--------------------------------

### Initialize UnstructuredGrid from File

Source: https://docs.pyvista.org/api/core/_autosummary/pyvista.unstructuredgrid

Load an UnstructuredGrid from a file path. The example uses a predefined file path from pyvista.examples. Plotting is shown with edges displayed.

```python
>>> import pyvista as pv
>>> from pyvista import examples
>>> grid = pv.UnstructuredGrid(examples.hexbeamfile)
>>> grid.plot(show_edges=True)
```

--------------------------------

### Initialize UnstructuredGrid from Arrays

Source: https://docs.pyvista.org/api/core/_autosummary/pyvista.unstructuredgrid

Construct an UnstructuredGrid from cell connectivity, cell types, and point coordinates. This example creates a single tetrahedron. Ensure PyVista and its examples are imported.

```python
>>> import pyvista as pv
>>> cells = [4, 0, 1, 2, 3]
>>> celltypes = [pv.CellType.TETRA]
>>> points = [
...     [1.0, 1.0, 1.0],
...     [1.0, -1.0, -1.0],
...     [-1.0, 1.0, -1.0],
...     [-1.0, -1.0, 1.0],
... ]
>>> grid = pv.UnstructuredGrid(cells, celltypes, points)
>>> grid.plot(show_edges=True)
```

--------------------------------

### Create an Empty MultiBlock Dataset

Source: https://docs.pyvista.org/api/core/composite

Initialize an empty MultiBlock object to start collecting datasets. This is the first step before adding any data.

```python
import pyvista as pv
from pyvista import examples
blocks = pv.MultiBlock()
blocks
```

--------------------------------

### Create and Visualize Camera Frustum

Source: https://docs.pyvista.org/api/core/camera

This example demonstrates creating a camera frustum and visualizing it within a scene. It sets up a plotter, adds a mesh, the frustum, and lines indicating camera position and focal point. It also labels key camera points and adjusts the camera's view.

```python
import pyvista as pv
import numpy as np
import vtk
from pyvista import examples

pv.set_plot_theme("document")

camera = pv.Camera()
near_range = 0.3
far_range = 0.8
camera.clipping_range = (near_range, far_range)
unit_vector = np.array(camera.direction) / np.linalg.norm(
    np.array([camera.focal_point]) - np.array([camera.position])
)

frustum = camera.view_frustum(1.0)

position = camera.position
focal_point = camera.focal_point
line = pv.Line(position, focal_point)

bunny = examples.download_bunny()
xyz = camera.position + unit_vector * 0.6 - np.mean(bunny.points, axis=0)
bunny.translate(xyz, inplace=True)

pl = pv.Plotter(shape=(2, 1))
pl.subplot(0, 0)
pl.add_text("Camera Position")
pl.add_mesh(bunny)
pl.add_mesh(frustum, style="wireframe")
pl.add_mesh(bunny)
pl.add_mesh(line, color="b")
pl.add_point_labels(
    [
        position,
        camera.position + unit_vector * near_range,
        camera.position + unit_vector * far_range,
        focal_point,
    ],
    ["Camera Position", "Near Clipping Plane", "Far Clipping Plane", "Focal Point"],
    margin=0,
    fill_shape=False,
    font_size=14,
    shape_color="white",
    point_color="red",
    text_color="black",
)
pl.camera.position = (1.1, 1.5, 0.0)
pl.camera.focal_point = (0.2, 0.3, 0.3)
pl.camera.up = (0.0, 1.0, 0.0)
pl.camera.zoom(1.4)

pl.subplot(1, 0)
pl.add_text("Camera View")
pl.add_mesh(bunny)
pl.camera = camera
pl.show()

```

--------------------------------

### get_gpu_info

Source: https://docs.pyvista.org/api/core/misc

Get all information about the GPU.

```APIDOC
## get_gpu_info

### Description
Get all information about the GPU.
```

--------------------------------

### Generate Cell Blocks with Default Settings

Source: https://docs.pyvista.org/api/examples/_autosummary/pyvista.examples.cells.generate_cell_blocks

Generates cell blocks using the default settings and plots them. This is a basic example to visualize the output of `generate_cell_blocks`.

```python
>>> cell_blocks = generate_cell_blocks()
>>> plot_cell(cell_blocks, cpos='xy')
```

--------------------------------

### Download and Plot Saddle Surface

Source: https://docs.pyvista.org/api/examples/_autosummary/pyvista.examples.vrml

Demonstrates how to download the saddle surface dataset and visualize it using PyVista. This is a common starting point for exploring PyVista's plotting capabilities.

```python
from pyvista import examples
mesh = examples.download_saddle_surface()
mesh.plot()
```

--------------------------------

### Set Camera Position to 'yz'

Source: https://docs.pyvista.org/api/core/camera

This example shows how to set the camera's position to view the 'yz' plane of an orientation plotter. It initializes the plotter and then directly sets the camera position.

```python
from pyvista import demos
pl = demos.orientation_plotter()
pl.camera_position = 'yz'
pl.show()

```

--------------------------------

### Set Camera Elevation

Source: https://docs.pyvista.org/api/core/camera

This example moves the camera upward by setting the elevation to 45 degrees, allowing a view of the X+ and Z+ faces. The camera position is initially set to 'yz' before applying the elevation.

```python
from pyvista import demos
pl = demos.orientation_plotter()
pl.camera_position = 'yz'
pl.camera.elevation = 45
pl.show()

```

--------------------------------

### Offset Camera Azimuth

Source: https://docs.pyvista.org/api/core/camera

This example offsets the camera's azimuth by 45 degrees to view the X+ and Y+ faces. It sets the initial camera position to 'yz' and then applies the azimuth offset.

```python
from pyvista import demos
pl = demos.orientation_plotter()
pl.camera_position = 'yz'
pl.camera.azimuth = 45
pl.show()

```

--------------------------------

### generate_cell_blocks

Source: https://docs.pyvista.org/api/examples/_autosummary/pyvista.examples.cells.generate_cell_blocks

This function generates cell blocks for PyVista examples.

```APIDOC
## generate_cell_blocks()

### Description
Generates cell blocks for PyVista examples.

### Parameters
None

### Returns
None
```

--------------------------------

### Reverse and Get MultiBlock Keys

Source: https://docs.pyvista.org/api/core/composite

Shows how to reverse the order of blocks in a MultiBlock object and retrieve the current list of block names. Note that MultiBlock does not enforce unique keys and keys can be None.

```python
blocks.reverse()
blocks.keys()
```

--------------------------------

### Get Number of Partitions using len()

Source: https://docs.pyvista.org/api/core/partitioned

Determine the total number of partitions currently stored in the PartitionedDataSet using the built-in len() function.

```python
len(partitions)
```

--------------------------------

### Compare Cell Types from Different Generators (Parametric)

Source: https://docs.pyvista.org/api/examples/_autosummary/pyvista.examples.cells.generate_cell_blocks

Generates and plots the first 25 cell types using the 'parametric' generator. This serves as a comparison to the 'examples' and 'source' generators, showing variations in cell type representation.

```python
>>> cell_blocks = generate_cell_blocks(generator='parametric', **kwargs)
>>> plot_cell(cell_blocks, cpos='xy', **size_kwargs)
```

--------------------------------

### Plotting Volumetric Data (Hydrogen Orbital)

Source: https://docs.pyvista.org/index.html

Plots the 3Dxy orbital of a hydrogen atom as volumetric data. This example requires the 'sympy' library and uses a 'magma' colormap with custom opacity settings.

```python
from pyvista import examples
grid = examples.load_hydrogen_orbital(3, 2, -2)
grid.plot(volume=True, opacity=[1, 0, 1], cmap='magma')
```

--------------------------------

### Modify Camera Roll

Source: https://docs.pyvista.org/api/core/camera

This example demonstrates modifying the camera's roll by adding 10 degrees. It first sets the camera position to 'yz' and then adjusts the roll in-place before showing the plot.

```python
from pyvista import demos
pl = demos.orientation_plotter()
pl.camera_position = 'yz'
pl.camera.roll += 10
pl.show()

```

--------------------------------

### Download and Load Bunny Dataset

Source: https://docs.pyvista.org/api

Shows how to download the bunny dataset using `pyvista.examples.download_bunny()`. This provides a common mesh for testing and demonstration.

```python
>>> from pyvista import examples
>>> examples.download_bunny()
```

```text
PolyData (0x7f38c359b580)
  N Cells:    69451
  N Points:   35947
  N Strips:   0
  X Bounds:   -9.469e-02, 6.101e-02
  Y Bounds:   3.299e-02, 1.873e-01
  Z Bounds:   -6.187e-02, 5.880e-02
  N Arrays:   0
```

--------------------------------

### UnstructuredGrid Initialization

Source: https://docs.pyvista.org/api/core/_autosummary/pyvista.unstructuredgrid

Demonstrates various ways to initialize an UnstructuredGrid object.

```APIDOC
## UnstructuredGrid()

### Description
Creates an empty UnstructuredGrid.

### Parameters

#### Args
- **args** (str, vtkUnstructuredGrid, iterable) - See examples below.
- **deep** (bool, optional) - Whether to deep copy a vtkUnstructuredGrid object. Defaults to `False`. Keyword only.
- **validate** (bool | MeshValidationFields | sequence[MeshValidationFields], optional) - Validate the mesh using `validate_mesh()` after initialization. Set this to `True` to validate all fields, or specify any combination of fields allowed by `validate_mesh`. Added in version 0.47. Defaults to `False`.

### Request Example
```python
>>> import pyvista as pv
>>> grid = pv.UnstructuredGrid()
```

## UnstructuredGrid(vtk_grid)

### Description
Copies a vtkUnstructuredGrid object.

### Parameters

#### Args
- **args** (vtkUnstructuredGrid) - The vtkUnstructuredGrid object to copy.
- **deep** (bool, optional) - Whether to deep copy the vtkUnstructuredGrid object. Defaults to `False`. Keyword only.
- **validate** (bool | MeshValidationFields | sequence[MeshValidationFields], optional) - Validate the mesh using `validate_mesh()` after initialization. Set this to `True` to validate all fields, or specify any combination of fields allowed by `validate_mesh`. Added in version 0.47. Defaults to `False`.

### Request Example
```python
>>> import pyvista as pv
>>> import vtk
>>> vtkgrid = vtk.vtkUnstructuredGrid()
>>> grid = pv.UnstructuredGrid(vtkgrid)
```

## UnstructuredGrid(filename)

### Description
Initializes an UnstructuredGrid from a file.

### Parameters

#### Args
- **args** (str) - The path to the file.
- **deep** (bool, optional) - Whether to deep copy data from the file. Defaults to `False`. Keyword only.
- **validate** (bool | MeshValidationFields | sequence[MeshValidationFields], optional) - Validate the mesh using `validate_mesh()` after initialization. Set this to `True` to validate all fields, or specify any combination of fields allowed by `validate_mesh`. Added in version 0.47. Defaults to `False`.

### Request Example
```python
>>> import pyvista as pv
>>> grid = pv.UnstructuredGrid('path/to/your/file.vtk')
```

## UnstructuredGrid(cells, celltypes, points)

### Description
Initializes an UnstructuredGrid from cell connectivity, cell types, and point coordinates.

### Parameters

#### Args
- **args** (list, numpy.ndarray) - A list or numpy array representing the cell connectivity.
- **celltypes** (list, numpy.ndarray) - A list or numpy array of cell types.
- **points** (list, numpy.ndarray) - A list or numpy array of point coordinates.
- **deep** (bool, optional) - Whether to deep copy the input arrays. Defaults to `False`. Keyword only.
- **validate** (bool | MeshValidationFields | sequence[MeshValidationFields], optional) - Validate the mesh using `validate_mesh()` after initialization. Set this to `True` to validate all fields, or specify any combination of fields allowed by `validate_mesh`. Added in version 0.47. Defaults to `False`.

### Request Example
```python
>>> import pyvista as pv
>>> cells = [4, 0, 1, 2, 3]
>>> celltypes = [pv.CellType.TETRA]
>>> points = [
...     [1.0, 1.0, 1.0],
...     [1.0, -1.0, -1.0],
...     [-1.0, 1.0, -1.0],
...     [-1.0, -1.0, 1.0],
... ]
>>> grid = pv.UnstructuredGrid(cells, celltypes, points)
```
```

--------------------------------

### Load and Inspect OpenFoam Data Keys

Source: https://docs.pyvista.org/api/core/composite

Illustrates loading an OpenFoam dataset using `pyvista.examples.download_cavity()` and accessing its top-level keys. This highlights the utility of dictionary-like features for understanding complex data structures.

```python
data = examples.download_cavity()
data.keys()
```

--------------------------------

### Get Number of Partitions using n_partitions attribute

Source: https://docs.pyvista.org/api/core/partitioned

Access the number of partitions directly via the 'n_partitions' attribute of the PartitionedDataSet object.

```python
partitions.n_partitions
```

--------------------------------

### Create and Add a Custom Light

Source: https://docs.pyvista.org/api/core/lights

Demonstrates creating a red spotlight and adding it to a plotter with lighting disabled initially. Useful for fine-grained control over scene illumination.

```python
import pyvista as pv
from pyvista import examples
light = pv.Light(position=(-1, 1, 1), color='red')
light.positional = True

import pyvista as pv
from pyvista import examples
pl = pv.Plotter(lighting='none')
pl.background_color = 'white'
mesh = examples.download_bunny()
mesh.rotate_x(90, inplace=True)
mesh.rotate_z(180, inplace=True)
pl.add_mesh(mesh, specular=1.0, diffuse=0.7, smooth_shading=True)
pl.add_light(light)
pl.show()
```

--------------------------------

### Create an Empty PartitionedDataSet

Source: https://docs.pyvista.org/api/core/partitioned

Initialize an empty PartitionedDataSet to later add data partitions.

```python
import pyvista as pv
partitions = pv.PartitionedDataSet()
partitions
```

--------------------------------

### Initialize UnstructuredGrid from VTK Object

Source: https://docs.pyvista.org/api/core/_autosummary/pyvista.unstructuredgrid

Create an UnstructuredGrid by copying an existing vtkUnstructuredGrid object. Ensure the vtk library is imported.

```python
>>> import pyvista as pv
>>> import vtk
>>> vtkgrid = vtk.vtkUnstructuredGrid()
>>> grid = pv.UnstructuredGrid(vtkgrid)
```

--------------------------------

### Get the Number of Blocks

Source: https://docs.pyvista.org/api/core/composite

Determine the total number of datasets currently stored in the MultiBlock object using either the len() function or the n_blocks attribute.

```python
len(blocks)
```

```python
blocks.n_blocks
```

--------------------------------

### Show Orientation Cube Plotter Demo

Source: https://docs.pyvista.org/api/examples

Creates and displays a demo plotter, specifically the orientation cube. Use this to quickly visualize orientation information.

```python
>>> from pyvista import demos
>>> plotter = demos.orientation_plotter()
>>> plotter.show()
```

--------------------------------

### Download and Import 3DS File

Source: https://docs.pyvista.org/api/examples/_autosummary/pyvista.examples.download_3ds.download_iflamigm

Download a 3DS file using `examples.download_3ds.download_iflamigm()` and import it into a PyVista plotter. This is useful for visualizing 3D models in the 3DS format.

```python
import pyvista as pv
from pyvista import examples
download_3ds_file = examples.download_3ds.download_iflamigm()
pl = pv.Plotter()
pl.import_3ds(download_3ds_file)
pl.show()
```

--------------------------------

### pyvista.InteractionEventType

Source: https://docs.pyvista.org/api/core/typing

Defines the types of interaction events used primarily for widgets. This includes string literals like 'end', 'start', 'always', and VTK Command EventIds.

```APIDOC
## pyvista.InteractionEventType#

Interaction event mostly used for widgets.
Includes both strings such as `'end'`, `'start'` and `'always'` and vtkCommand.EventIds. 

InteractionEventType _ = typing.Literal['end', 'start', 'always'] | vtkmodules.vtkCommonCore.vtkCommand.EventIds_#
    
Represent a union type
E.g. for int | str
```

--------------------------------

### Create a Shadow Effect with a Spotlight

Source: https://docs.pyvista.org/api/core/lights

Illustrates how to create a shadow effect below an actor using a positional light with specific cone angle and exponent values. Useful for enhancing depth and realism in scenes. Note potential VTK issues with shadows on certain window sizes.

```python
import pyvista as pv

pl = pv.Plotter(lighting=None, window_size=(800, 800))

# create a top down light
light = pv.Light(position=(0, 0, 3), show_actor=True, positional=True,
                 cone_angle=30, exponent=20, intensity=1.5)
pl.add_light(light)

# add a sphere to the plotter
sphere = pv.Sphere(radius=0.3, center=(0, 0, 1))
pl.add_mesh(sphere, ambient=0.2, diffuse=0.5, specular=0.8,
                 specular_power=30, smooth_shading=True,
                 color='dodgerblue')

# add the grid
grid = pv.Plane(i_size=4, j_size=4)
pl.add_mesh(grid, ambient=0, diffuse=0.5, specular=0.8, color='white')

# set up and show the plotter
pl.enable_shadows()
pl.set_background('darkgrey')
pl.show()
```

--------------------------------

### Get Keys from Nested MultiBlock

Source: https://docs.pyvista.org/api/core/composite

Retrieves the names of the blocks within a nested `pyvista.MultiBlock` object obtained from a dataset. This provides human-readable identifiers for the different parts of the boundary data.

```python
data["boundary"].keys()
```

--------------------------------

### Initialize Empty UnstructuredGrid

Source: https://docs.pyvista.org/api/core/_autosummary/pyvista.unstructuredgrid

Create an empty UnstructuredGrid object. This is useful for building a grid from scratch.

```python
>>> import pyvista as pv
>>> grid = pv.UnstructuredGrid()
```

--------------------------------

### Download and Visualize Head 2 Dataset

Source: https://docs.pyvista.org/api/examples/_autosummary/pyvista.examples.downloads.file_from_files

Downloads the Head 2 dataset and visualizes it using a PyVista plotter. Set `load=False` to only retrieve the filename.

```python
>>> import pyvista as pv
>>> from pyvista import examples
>>> dataset = examples.download_head_2()
>>> pl = pv.Plotter()
>>> _ = pl.add_volume(dataset, cmap='cool', opacity='sigmoid_6')
>>> pl.show()
```

--------------------------------

### Create and Slice a Sphere Mesh

Source: https://docs.pyvista.org/api

Demonstrates creating a sphere mesh and slicing it using PyVista. This is a fundamental operation for mesh manipulation.

```python
>>> import pyvista as pv
>>> mesh = pv.Sphere()
>>> sliced = mesh.slice()
>>> sliced.length
```

```text
1.409317132047406
```

--------------------------------

### Creating and Plotting a Point Cloud with Glyphs

Source: https://docs.pyvista.org/index.html

Integrates with NumPy to create a random point cloud and visualizes it by placing spheres at each point using PyVista's glyphing capabilities. Suitable for visualizing point data or creating complex geometries.

```python
import numpy as np
import pyvista as pv

rng = np.random.default_rng(seed=0)
point_cloud = rng.random((100, 3))
pdata = pv.PolyData(point_cloud)
pdata['orig_sphere'] = np.arange(100)

# create many spheres from the point cloud
sphere = pv.Sphere(radius=0.02, phi_resolution=10, theta_resolution=10)
pc = pdata.glyph(scale=False, geom=sphere, orient=False)
pc.plot(cmap='Reds')
```

--------------------------------

### Append and Reverse PartitionedDataSet

Source: https://docs.pyvista.org/api/core/partitioned

Demonstrates appending another partition and reversing the order of partitions within the PartitionedDataSet. Note that 'pop' is not supported.

```python
partitions.append(pv.Cone())
partitions.reverse()
```

--------------------------------

### Create a Parametric Superellipsoid Mesh

Source: https://docs.pyvista.org/api

Illustrates the creation of a parametric superellipsoid mesh using PyVista. This is useful for generating complex geometric shapes.

```python
>>> import pyvista as pv
>>> mesh = pv.ParametricSuperEllipsoid(xradius=0.1)
>>> mesh
```

```text
PolyData (0x7f38c359ae60)
  N Cells:    19602
  N Points:   10000
  N Strips:   0
  X Bounds:   -9.997e-02, 9.997e-02
  Y Bounds:   -9.999e-01, 9.994e-01
  Z Bounds:   -1.000e+00, 1.000e+00
  N Arrays:   1
```

--------------------------------

### Read Data File with PyVista

Source: https://docs.pyvista.org/api

Demonstrates using `pyvista.get_reader()` to read a data file. This is essential for loading external datasets into PyVista.

```python
>>> import pyvista as pv
>>> from pyvista import examples
>>> reader = pv.get_reader(examples.hexbeamfile)
>>> reader
```

```text
VTKDataSetReader('/home/runner/_work/pyvista/pyvista/.tox/docs-build/lib/python3.14/site-packages/pyvista/examples/hexbeam.vtk')
```

--------------------------------

### Mesh Creation Helpers

Source: https://docs.pyvista.org/api/core/helpers

Functions for creating new mesh objects or wrapping existing VTK data.

```APIDOC
## wrap

### Description
Wrap any given VTK data object to its appropriate PyVista data object.

### Method
`wrap(dataset, *[, validate])`
```

```APIDOC
## make_tri_mesh

### Description
Construct a `pyvista.PolyData` mesh using points and faces arrays.

### Method
`make_tri_mesh(points, faces)`
```

```APIDOC
## lines_from_points

### Description
Make a connected line set given an array of points.

### Method
`lines_from_points(points[, close])`
```

```APIDOC
## line_segments_from_points

### Description
Generate non-connected line segments from points.

### Method
`line_segments_from_points(points)`
```

```APIDOC
## vector_poly_data

### Description
Create a pyvista.PolyData object composed of vectors.

### Method
`vector_poly_data(orig, vec)`
```

```APIDOC
## vtk_points

### Description
Convert numpy array or array-like to a vtkPoints object.

### Method
`vtk_points(points[, deep, force_float, ...])`
```

--------------------------------

### PyVista Light Class

Source: https://docs.pyvista.org/api/core/lights

The `pyvista.Light` class provides a Pythonic interface to VTK's lighting features. It allows for detailed control over light properties such as position, color, intensity, and type (headlight, camera light, scene light).

```APIDOC
## `Light` Class

### Description

Represents a light source in the scene. This class extends `vtkLight` with additional Pythonic features.

### Class Signature

`Light(*args, **kwargs)`

### Properties

- **position** (tuple or list): The position of the light source in the scene.
- **focal_point** (tuple or list): The point the light is directed towards.
- **color** (str or tuple): The color of the light (ambient, diffuse, specular components).
- **intensity** (float): The brightness of the light.
- **on** (bool): Whether the light is currently active.
- **directional** (bool): If True, the light is directional (infinitely distant).
- **positional** (bool): If True, the light is positional (has a specific location).
- **cone_angle** (float): The angle of the light beam for spotlights.
- **exponent** (float): Controls the angular distribution of light intensity within the beam.
- **attenuation_values** (tuple): Controls the fading of light with distance.
- **show_actor** (bool): If True, an actor representing the light source is displayed.

### Methods

(No specific methods are detailed in the provided text beyond instantiation and property access.)

### Examples

```python
import pyvista as pv

# Create a red spotlight shining on the origin
light = pv.Light(position=(-1, 1, 1), color='red')
light.positional = True

# Add the light to a plotter
pl = pv.Plotter(lighting='none')
pl.add_light(light)
pl.show()
```

```python
import pyvista as pv

# Create a positional light with shadow casting properties
light = pv.Light(position=(0, 0, 3), show_actor=True, positional=True,
                 cone_angle=30, exponent=20, intensity=1.5)

# Enable shadows in the plotter
pl = pv.Plotter(lighting=None, window_size=(800, 800))
pl.add_light(light)
pl.enable_shadows()
pl.show()
```
```

--------------------------------

### download_iflamigm

Source: https://docs.pyvista.org/api/examples/_autosummary/pyvista.examples.download_3ds.download_iflamigm

Downloads a 3DS file. This function is part of the `pyvista.examples.download_3ds` module and returns the filename of the downloaded 3DS file.

```APIDOC
## download_iflamigm()

### Description

Download a iflamigm image.

Added in version 0.44.0.

### Returns

* `str` - Filename of the 3DS file.

### Examples

```python
>>> import pyvista as pv
>>> from pyvista import examples
>>> download_3ds_file = examples.download_3ds.download_iflamigm()
>>> pl = pv.Plotter()
>>> pl.import_3ds(download_3ds_file)
>>> pl.show()
```
```

--------------------------------

### Access UnstructuredGrid Data by Key

Source: https://docs.pyvista.org/api/core/composite

Demonstrates accessing a specific `pyvista.UnstructuredGrid` from a loaded dataset using its key. This allows for direct manipulation or inspection of the grid data.

```python
data["internalMesh"]
```

--------------------------------

### sample_function

Source: https://docs.pyvista.org/api/core/misc

Sample an implicit function over a structured point set.

```APIDOC
## sample_function

### Description
Sample an implicit function over a structured point set.

### Parameters
- **function**: The implicit function to sample.
- **bounds**: The bounds of the sampling region.
- **dim**: The dimension of the sampling grid.
```

--------------------------------

### Plot a 3D Moving Wave

Source: https://docs.pyvista.org/api/examples/_autosummary/pyvista.demos.demos.plot_wave

Demonstrates the basic usage of the `plot_wave` function to generate and display a 3D moving wave. This function is useful for visualizing dynamic wave phenomena.

```python
from pyvista import demos
out = demos.plot_wave()
```

--------------------------------

### Compare Cell Types from Different Generators (Source)

Source: https://docs.pyvista.org/api/examples/_autosummary/pyvista.examples.cells.generate_cell_blocks

Generates and plots the first 25 cell types using the 'source' generator. This provides a baseline for comparison with other generators, illustrating how the 'source' generator handles cell type generation.

```python
>>> cell_blocks = generate_cell_blocks(generator='source', **kwargs)
>>> plot_cell(cell_blocks, cpos='xy', **size_kwargs)
```

--------------------------------

### Global Configuration Object

Source: https://docs.pyvista.org/api/core/helpers

The `pyvista.global_config` object provides access to process-wide settings that influence the behavior of `pyvista.core`. It is a singleton instance that allows for centralized control over PyVista's operations.

```APIDOC
## Global Configuration

_class _Config[source]#
    
PyVista core configuration. Holds process-wide settings that affect `pyvista.core` behavior. The singleton instance is exposed as `pyvista.global_config`.

Examples
```python
>>> import pyvista as pv
>>> pv.global_config.validate_on_wrap = False
>>> pv.global_config.validate_on_wrap = True  # restore default
```
```

--------------------------------

### Set and Access MultiBlock Names

Source: https://docs.pyvista.org/api/core/composite

Demonstrates how to assign names to blocks within a MultiBlock object and access them using these names. This is useful for organizing and retrieving specific data blocks.

```python
blocks = pv.MultiBlock([pv.Sphere(), pv.Cube()])
blocks.set_block_name(0, "sphere")
blocks.set_block_name(1, "cube")
blocks["sphere"]  # Sphere
```

--------------------------------

### Generate 3D Cell Grid with Squeeze and Cycle

Source: https://docs.pyvista.org/api/examples/_autosummary/pyvista.examples.cells.generate_cell_blocks

Generates a 5x5x5 grid of all 3D cell types using the 'source' generator, with unsupported types squeezed and the grid filled by cycling cell types. This creates a dense, complete 3D grid.

```python
>>> cell_types = [ctype for ctype in pv.CellType if ctype.dimension == 3]
>>> cell_blocks = generate_cell_blocks(
...     cell_types,
...     'source',
...     block_dimensions=(5, 5, 5),
...     unsupported_action='squeeze',
...     fill_mode='cycle',
... )
>>> cell_blocks.plot(show_edges=True, opacity=0.5, line_width=3)
```

--------------------------------

### download_head_2

Source: https://docs.pyvista.org/api/examples/_autosummary/pyvista.examples.downloads.file_from_files

Downloads the Head 2 dataset. This function can either return the dataset directly or just the filename, depending on the `load` parameter.

```APIDOC
## download_head_2

### Description
Downloads the Head 2 dataset. This function can either return the dataset directly or just the filename, depending on the `load` parameter.

### Method
`download_head_2(load=True)`

### Parameters
#### Keyword Arguments
- **load** (bool, optional) - Defaults to `True`. If `True`, the dataset is loaded and returned. If `False`, only the filename is returned.

### Returns
- **output** (`pyvista.ImageData` | `str`) - The downloaded dataset if `load` is `True`, otherwise the filename of the downloaded dataset.

### Example
```python
import pyvista as pv
from pyvista import examples

dataset = examples.download_head_2()
pl = pv.Plotter()
_ = pl.add_volume(dataset, cmap='cool', opacity='sigmoid_6')
pl.show()
```
```

--------------------------------

### Report

Source: https://docs.pyvista.org/api/core/misc

Generate a PyVista software environment report.

```APIDOC
## Report

### Description
Generate a PyVista software environment report.

### Parameters
- **additional**: Additional information to include in the report.
- **ncol**: Number of columns for the report.
- **text_width**: Text width for the report.
- **sort**: Whether to sort the report.
```

--------------------------------

### pyvista.JupyterBackendOptions

Source: https://docs.pyvista.org/api/core/typing

Defines the available Jupyter backends that can be used for plotting and interaction within a Jupyter environment.

```APIDOC
## pyvista.JupyterBackendOptions#

Jupyter backend to use. 

JupyterBackendOptions#
    
alias of `Literal`[‘static’, ‘client’, ‘server’, ‘trame’, ‘html’, ‘none’]
```

--------------------------------

### Download Turbine Blade Dataset

Source: https://docs.pyvista.org/api/examples

Downloads and caches a large dataset, such as the turbine blade mesh. This is useful for working with complex geometries that are too large to include with the library.

```python
>>> from pyvista import examples
>>> blade_mesh = examples.download_turbine_blade()
>>> blade_mesh.plot()
```

--------------------------------

### pyvista.CameraPositionOptions

Source: https://docs.pyvista.org/api/core/typing

Specifies acceptable options for setting a camera's position and orientation. This includes predefined string literals, NumPy arrays, and various sequence types representing camera viewpoints.

```APIDOC
## pyvista.CameraPositionOptions#

Any object used to set a `Camera`. 

CameraPositionOptions _ = typing.Literal['xy', 'xz', 'yz', 'yx', 'zx', 'zy', 'iso'] | numpy.ndarray[tuple[typing.Any, ...], numpy.dtype[float]] | collections.abc.Sequence[float] | collections.abc.Sequence[numpy.ndarray[tuple[typing.Any, ...], numpy.dtype[float]]] | collections.abc.Sequence[collections.abc.Sequence[float]] | collections.abc.Sequence[collections.abc.Sequence[numpy.ndarray[tuple[typing.Any, ...], numpy.dtype[float]]]] | pyvista.plotting.renderer.CameraPosition_#
    
Represent a union type
E.g. for int | str
```

--------------------------------

### Load Built-In Random Hills Dataset

Source: https://docs.pyvista.org/api/examples

Loads a built-in dataset for demonstration purposes. Use this when you need a quick, readily available mesh.

```python
>>> from pyvista import examples
>>> hills = examples.load_random_hills()
>>> hills.plot()
```

--------------------------------

### show_vtk_api

Source: https://docs.pyvista.org/api/core/helpers

Controls whether VTK-inherited attributes are visible in `dir()` and tab-completion. When `False` (default), VTK attributes are hidden to provide a cleaner interface. When `True`, the full VTK API is enumerated.

```APIDOC
_property _show_vtk_api _: bool_[source]#
    
Return or set whether VTK-inherited attributes appear in `dir()`.

When `False` (the default), attributes inherited from VTK base classes are hidden from `dir()` and tab-completion on PyVista objects that wrap VTK types (data objects, `Renderer`, `Actor`, `Property`, etc.). This keeps the public surface curated for data-science IDEs such as Positron’s Variables pane and VS Code’s Jupyter extension, and for IPython / Jupyter tab-completion. VTK methods remain fully callable regardless of this setting.

When `True`, the full VTK API is enumerated alongside the PyVista API, which is useful for VTK developers who want to discover the raw VTK method surface via introspection.

Warning
This option requires runtime inspection and does not work with all developer tools, e.g. it has no effect when using PyCharm. This is because it relies on calling the object’s `__dir__` method for generating auto-completion suggestions. Tools like PyCharm that only use static analysis for auto-completion are therefore unaffected.

Notes
The snake_case VTK aliases (`number_of_points`, `deep_copy`, …) are controlled separately by `pyvista.vtk_snake_case()`. When snake_case is not `'allow'` (the default), those names are hidden from `dir()` regardless of this setting, because accessing them would already raise `PyVistaAttributeError`. Enabling snake_case surfaces the snake_case names in `dir()`; `show_vtk_api` only controls the CamelCase VTK API.

Added in version 0.48.

Examples
```python
>>> import pyvista as pv
>>> pv.global_config.show_vtk_api
False
>>> pv.global_config.show_vtk_api = True
>>> pv.global_config.show_vtk_api = False  # restore default
```
```

--------------------------------

### plot_wave()

Source: https://docs.pyvista.org/api/examples/_autosummary/pyvista.demos.demos.plot_wave

Plots a 3D moving wave in a render window. This function can be used to visualize wave dynamics over time.

```APIDOC
## plot_wave()

### Description
Plots a 3D moving wave in a render window. This function can be used to visualize wave dynamics over time.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Method
None (Python function)

### Endpoint
None (Python function)

### Request Example
```python
from pyvista import demos
out = demos.plot_wave()
```

### Response
#### Success Response
`numpy.ndarray`: Position of points at the last frame.

#### Response Example
```json
{
  "example": "numpy.ndarray representing point positions"
}
```
```

--------------------------------

### Control VTK API Visibility

Source: https://docs.pyvista.org/api/core/helpers

Manage whether VTK-inherited attributes appear in `dir()` by setting `pv.global_config.show_vtk_api`. When `False` (default), VTK attributes are hidden for a cleaner interface. Set to `True` to expose the full VTK API.

```python
>>> import pyvista as pv
>>> pv.global_config.show_vtk_api
False
>>> pv.global_config.show_vtk_api = True
>>> pv.global_config.show_vtk_api = False  # restore default
```

--------------------------------

### UnstructuredGrid Methods

Source: https://docs.pyvista.org/api/core/_autosummary/pyvista.unstructuredgrid

Methods available for the UnstructuredGrid class.

```APIDOC
## UnstructuredGrid.cast_to_explicit_structured_grid()

### Description
Cast to an explicit structured grid.

### Method
`cast_to_explicit_structured_grid`

### Endpoint
N/A (Method call)

### Parameters
None

### Request Example
```python
>>> grid.cast_to_explicit_structured_grid()
```

## UnstructuredGrid.linear_copy([deep])

### Description
Return a copy of the unstructured grid containing only linear cells.

### Method
`linear_copy`

### Endpoint
N/A (Method call)

### Parameters
- **deep** (bool, optional) - Whether to deep copy the grid. Defaults to `False`.

### Request Example
```python
>>> linear_grid = grid.linear_copy()
```
```

--------------------------------

### Array Utilities Helpers

Source: https://docs.pyvista.org/api/core/helpers

Functions for converting and manipulating arrays, and sampling functions.

```APIDOC
## convert_array

### Description
Convert a NumPy array to a vtkDataArray or vice versa.

### Method
`convert_array(arr[, name, deep, array_type])`
```

```APIDOC
## sample_function

### Description
Sample an implicit function over a structured point set.

### Method
`sample_function(function[, bounds, dim, ...])`
```

```APIDOC
## perlin_noise

### Description
Return the implicit function that implements Perlin noise.

### Method
`perlin_noise(amplitude, freq, phase)`
```

--------------------------------

### set_error_output_file

Source: https://docs.pyvista.org/api/core/misc

Set a file to write out the VTK errors.

```APIDOC
## set_error_output_file

### Description
Set a file to write out the VTK errors.

### Parameters
- **filename**: The name of the file to write errors to.
```

--------------------------------

### Generate Cell Blocks with Source Generator

Source: https://docs.pyvista.org/api/examples/_autosummary/pyvista.examples.cells.generate_cell_blocks

Generates cell blocks using the 'source' generator, squeezing unsupported cell types to create a continuous grid. This method is suitable for generating dense cell arrangements.

```python
>>> cell_blocks = generate_cell_blocks(
...     cell_types, 'source', unsupported_action='squeeze'
... )
>>> plot_cell(cell_blocks, cpos='xy')
```

--------------------------------

### Set PyVista Data Path

Source: https://docs.pyvista.org/api/examples

Clone the PyVista data repository and set the VTK_DATA_PATH environment variable to point to the local data directory. This is useful for offline use or when using a custom data location.

```bash
git clone https://github.com/pyvista/data.git
export VTK_DATA_PATH=/home/alex/python/pyvista/data/Data

```

--------------------------------

### Plot All Meshes in MultiBlock

Source: https://docs.pyvista.org/api/core/composite

Visualize all the datasets contained within the MultiBlock object by calling the plot method. This renders all appended meshes.

```python
blocks.plot(smooth_shading=True)
```

--------------------------------

### Plot a PyVista Cell

Source: https://docs.pyvista.org/api/core/cells

Demonstrates how to plot an individual PyVista cell directly. This is useful for visualizing the geometry of a single cell, including its edges.

```python
cell.plot(show_edges=True, line_width=3)
```

--------------------------------

### Generate Cell Blocks with Parametric Generator

Source: https://docs.pyvista.org/api/examples/_autosummary/pyvista.examples.cells.generate_cell_blocks

Generates cell blocks using the 'parametric' generator, skipping unsupported cell types. This is useful when you need to generate cells that are compatible with the parametric approach.

```python
>>> cell_blocks = generate_cell_blocks(
...     cell_types, 'parametric', shrink_factor=0.8, unsupported_action='skip'
... )
>>> plot_cell(cell_blocks, cpos='xy')
```

--------------------------------

### Access Partition by Index

Source: https://docs.pyvista.org/api/core/partitioned

Retrieve a specific partition from the PartitionedDataSet using its index. The returned object is a PyVista dataset.

```python
partitions[0]  # Sphere
```

--------------------------------

### Accessor Registration

Source: https://docs.pyvista.org/api/core/accessors

Describes a single registered dataset accessor.

```APIDOC
## AccessorRegistration

### Description
Describes one registered dataset accessor.

### Parameters
- **name** (str) - The name of the accessor.
- **target** (type) - The target dataset class.
- **accessor** (type) - The accessor class.
- **\*** - Additional details about the accessor.

### Usage
```python
AccessorRegistration(name, target, accessor, ...)
```
```

--------------------------------

### Access Nested MultiBlock Data by Key

Source: https://docs.pyvista.org/api/core/composite

Shows how to access a nested `pyvista.MultiBlock` object within a loaded dataset using its key. This is useful for exploring hierarchical data structures.

```python
data["boundary"]
```

--------------------------------

### Generate Cell Blocks with 'cycle' Fill Mode

Source: https://docs.pyvista.org/api/examples/_autosummary/pyvista.examples.cells.generate_cell_blocks

Generates cell blocks using the 'cycle' fill mode, which reuses cell types to fill the grid dimensions completely. This ensures a full grid even with fewer cell types than grid slots.

```python
>>> cell_blocks = generate_cell_blocks(
...     cell_types[:-2], block_dimensions=(3, 4, 1), fill_mode='cycle'
... )
>>> plot_cell(cell_blocks, cpos='xy', **size_kwargs)
```

--------------------------------

### send_errors_to_logging

Source: https://docs.pyvista.org/api/core/misc

Send all VTK error/warning messages to Python's logging module.

```APIDOC
## send_errors_to_logging

### Description
Send all VTK error/warning messages to Python's logging module.
```

--------------------------------

### DataSet Accessor Protocol

Source: https://docs.pyvista.org/api/core/accessors

Defines the structural protocol for third-party accessor classes.

```APIDOC
## DataSetAccessor

### Description
Structural protocol for third-party accessor classes.

### Parameters
- **dataset** (vtk.vtkDataObject) - The dataset instance the accessor is attached to.

### Usage
```python
class MyAccessor(DataSetAccessor):
    def __init__(self, dataset):
        super().__init__(dataset)
        # ... accessor logic ...
```
```

--------------------------------

### pyvista.DataSet

Source: https://docs.pyvista.org/api/core/dataset

The `pyvista.DataSet` class is the base class for all spatially referenced datasets in PyVista, analogous to VTK's `vtkDataSet`.

```APIDOC
## pyvista.DataSet

### Description
Methods in common to spatially referenced objects.

### Class Signature
`pyvista.DataSet(*args, **kwargs)`
```

--------------------------------

### StructuredGrid Class

Source: https://docs.pyvista.org/api/core/pointsets

Dataset used for topologically regular arrays of data, forming a regular lattice of points. It extends the vtkStructuredGrid class.

```APIDOC
## StructuredGrid

### Description
Dataset used for topologically regular arrays of data.

### Class Signature
`StructuredGrid(*args, **kwargs)`
```

--------------------------------

### Combine and Show Distinct Cell Types

Source: https://docs.pyvista.org/api/examples/_autosummary/pyvista.examples.cells.generate_cell_blocks

Combines generated cell blocks and displays the set of distinct cell types present. This is useful for verifying the cell types included in a complex generation.

```python
>>> cell_blocks.combine().distinct_cell_types
```

--------------------------------

### Texture

Source: https://docs.pyvista.org/api/core/objects

The pyvista.Texture class is used for loading and representing images. These images can then be applied to the surfaces of pyvista.DataSet objects that possess texture coordinates.

```APIDOC
## pyvista.Texture

### Description
Used to load and represent images that can be placed on the surface of `pyvista.DataSet` that have texture coordinates. This is a wrapper for vtkTexture.

### Signature
`pyvista.Texture(*args, **kwargs)`
```

--------------------------------

### PointSet Class

Source: https://docs.pyvista.org/api/core/pointsets

A concrete class for storing a set of points with no cell connectivity. It extends the vtkPointSet class.

```APIDOC
## PointSet

### Description
Concrete class for storing a set of points.

### Class Signature
`PointSet(*args, **kwargs)`
```

--------------------------------

### Generating and Plotting a Spline with Tubes

Source: https://docs.pyvista.org/index.html

Generates a 3D spline from an array of NumPy points and then creates a tube around it. Useful for visualizing paths or curves in 3D space. The scalar bar is hidden.

```python
import numpy as np
import pyvista as pv

# Make the xyz points
theta = np.linspace(-10 * np.pi, 10 * np.pi, 100)
z = np.linspace(-2, 2, 100)
r = z**2 + 1
x = r * np.sin(theta)
y = r * np.cos(theta)
points = np.column_stack((x, y, z))

spline = pv.Spline(points, 500).tube(radius=0.1)
spline.plot(scalars='arc_length', show_scalar_bar=False)
```

--------------------------------

### Generate Cell Blocks with Reversed Grid Dimensions

Source: https://docs.pyvista.org/api/examples/_autosummary/pyvista.examples.cells.generate_cell_blocks

Generates cell blocks on a grid with reversed dimensions (4x3x1). This demonstrates how to control the layout by altering the `block_dimensions` parameter.

```python
>>> cell_blocks = generate_cell_blocks(cell_types, block_dimensions=(4, 3, 1))
>>> plot_cell(cell_blocks, cpos='xy', **size_kwargs)
```

--------------------------------

### Add Data to PartitionedDataSet

Source: https://docs.pyvista.org/api/core/partitioned

Append individual PyVista dataset objects (like Sphere or Cube) to the PartitionedDataSet.

```python
partitions.append(pv.Sphere())
partitions.append(pv.Cube(center=(0, 0, -1)))
```

--------------------------------

### Generate TRIANGLE Cell with 'source' Generator

Source: https://docs.pyvista.org/api/examples/_autosummary/pyvista.examples.cells.generate_cell_blocks

Generates a MultiBlock dataset containing a single TRIANGLE cell using the 'source' generator. This method uses vtkCellTypeSource and may generate multiple cells to fill a block.

```python
>>> triangle = generate_cell_blocks(pv.CellType.TRIANGLE, 'source')
>>> plot_cell(triangle, cpos='xy')
```

--------------------------------

### Generate Cell Blocks on a Dimensioned Grid

Source: https://docs.pyvista.org/api/examples/_autosummary/pyvista.examples.cells.generate_cell_blocks

Generates cell blocks arranged on a specified grid dimension (3x4x1). This allows for structured placement of different cell types.

```python
>>> lines = [pv.CellType.LINE] * 3
>>> polygons = [pv.CellType.POLYGON] * 3
>>> wedges = [pv.CellType.WEDGE] * 3
>>> pyramids = [pv.CellType.PYRAMID] * 3
>>> cell_types = [*lines, *polygons, *wedges, *pyramids]
>>> cell_blocks = generate_cell_blocks(cell_types, block_dimensions=(3, 4, 1))
>>> size_kwargs = dict(point_size=40, font_size=20)
>>> plot_cell(cell_blocks, cpos='xy', **size_kwargs)
```

--------------------------------

### Plotting Finite Element Analysis Stress Data

Source: https://docs.pyvista.org/index.html

Plots the 'X' component of elastic stress from a 3D notch specimen. Requires the 'Nodal Stress' scalar data and uses a 'turbo' colormap.

```python
from pyvista import examples
mesh = examples.download_notch_stress()
mesh.plot(scalars='Nodal Stress', component=0, cmap='turbo', cpos='xy')
```

--------------------------------

### Mesh Operations Helpers

Source: https://docs.pyvista.org/api/core/helpers

Functions for manipulating existing mesh objects.

```APIDOC
## merge

### Description
Merge several datasets.

### Method
`merge(datasets[, merge_points, ...])`
```

```APIDOC
## translate

### Description
Translate and orient a mesh to a new center and direction.

### Method
`translate(surf[, center, direction])`
```

```APIDOC
## generate_plane

### Description
Return a vtkPlane.

### Method
`generate_plane(normal, origin)`
```

```APIDOC
## fit_plane_to_points

### Description
Fit a plane to points using its `principal_axes()`.

### Method
`fit_plane_to_points(points[, return_meta, ...])`
```

```APIDOC
## fit_line_to_points

### Description
Fit a line to points using its `principal_axes()`.

### Method
`fit_line_to_points(points, *[, resolution, ...])`
```
Tokens:
Raw