Skip to main content
Ctrl+K
PyVista 0.45.0 documentation - Home
  • GitHub
  • Slack Community
  • Support
  • Contributing
  • The Paper
  • Getting Started
    • Why PyVista?
    • Authors & Citation
    • Installation
    • Connections
    • External Examples
  • User Guide
    • What is a Mesh?
    • Basic API Usage
    • PyVista Data Model
    • Transitioning from VTK to PyVista
    • Plotting Themes
    • Jupyter Notebook Plotting
      • Trame Jupyter Backend for PyVista
    • Optional Features
  • Tags
    • filter (45)
      • Boolean Operations
      • Extract Cell Centers
      • Clipping with Planes & Boxes
      • Clipping with a Surface
      • Collision
      • Computing Surface Normals
      • Volumetric Analysis
      • Connectivity
      • Contouring
      • Decimation
      • Distance Between Two Surfaces
      • Extract Cells Inside Surface
      • Extract Edges
      • Extract Surface
      • Extrude Rotation
      • Extrude Trim
      • Marching Cubes
      • Gaussian Smoothing
      • Geodesic Paths
      • Plotting Glyphs (Vectors or PolyData)
      • Table of Glyphs
      • Compute Gradients of a Field
      • Fast Fourier Transform
      • Fast Fourier Transform with Perlin Noise
      • Image Data Representations
      • Integrate Data
      • Detailed Interpolating Points
      • Compare interpolation/sampling methods
      • Computing Mesh Quality
      • Ray Tracing
      • Project to a Plane
      • Reflect Meshes
      • Detailed Resampling
      • Rotations
      • Sample Function: Perlin Noise in 2D
      • Sample Function: Perlin Noise in 3D
      • Slicing
      • Streamlines
      • 2D Streamlines
      • Subdivide Cells
      • Surface Reconstruction
      • Surface Smoothing
      • Using Common Filters
      • Voxelize a Surface Mesh
      • Warping by Vectors
    • lights (7)
      • Light Actors
      • Attenuation
      • Beam Shape
      • Light Types
      • Disabling Mesh Lighting
      • Plotter Lighting Systems
      • Shadows
    • load (29)
      • Creating an Explicit Structured Grid
      • Geometric Objects
      • Create a Kochanek Spline
      • Parametric Geometric Objects
      • Pixel Art of ALIEN MONSTERS
      • Platonic Solids
      • Create Point Cloud
      • Create a PointSet
      • Create PolyData
      • Triangle Strips
      • Unstructured Grid with Polyhedra
      • Create Sphere Mesh Multiple Ways
      • Creating a Spline
      • Creating a Structured Surface
      • Drape 2D Surface From Line
      • Create Triangulated Surface
      • Plot Truss-like FEA Solution with Cylinders
      • Creating a Uniform Grid
      • Creating an Unstructured Grid
      • Linear Cells
      • Working with glTF Files
      • Working with VRML Files
      • Read FEniCS/Dolfin Meshes
      • Load and Plot from a File
      • Read Image Files
      • Parallel Files
      • Load data using a Reader
      • Terrain Following Mesh
      • Wrapping Other Objects
    • medical (2)
      • Volume Rendering
      • Visualize Anatomical Groups
    • plot (57)
      • Anti-Aliasing
      • Setting Backface Properties
      • Background Image
      • Blurring
      • Plotting Bounds
      • Chart Basics
      • Chart Overlays
      • Clearing a Mesh or the Entire Plot
      • Colormap Choices
      • Color Cycling
      • Composite Picking
      • Depth of Field Plotting
      • Depth Peeling
      • Label based on Distance on Line
      • Measuring distance
      • Show Edges
      • Eye Dome Lighting
      • Picking elements of a mesh
      • Plot with Floors
      • Hide Cells with Ghosting
      • Create a GIF Movie
      • Render a depth image
      • Interpolate Before Mapping
      • Moving Isovalue
      • Label Points
      • Legends and glyphs
      • Lighting Properties
      • Linked Views in Subplots
      • Lookup Tables
      • Picking Meshes
      • Create a MP4 Movie
      • Save a Movie Using Glyphs
      • Create a GIF Movie of a Static Object with a Moving Colormap
      • Multi-Window Plot
      • Plot with Opacity
      • Orbiting
      • Orthogonal Slices
      • Physically Based Rendering
      • Plot Scalars Over a Circular Arc
      • Plot Over Line
      • Point Cell Scalars
      • Plotting Point Clouds
      • Picking points on a mesh
      • Scaled Gaussian Points
      • Customize Scalar Bars
      • Saving Screenshots
      • Types of Shading
      • Silhouette Highlight
      • Plot data in spherical coordinates
      • Surface Space Ambient Occlusion
      • Picking a Point on the Surface of a Mesh
      • Applying Textures
      • Control Global and Local Plotting Themes
      • Topographic Map
      • Plot Vector Component
      • Visible Vertices
      • Volume Rendering
    • widgets (10)
      • Animation
      • Box Widget
      • Checkbox Widget
      • Clip Volume Widget
      • Line Widget
      • Multiple Slider Widgets
      • Plane Widget
      • Slider Bar Widget
      • Sphere Widget
      • Spline Widget
  • Examples
    • Mesh Creation
      • Creating an Explicit Structured Grid
      • Geometric Objects
      • Create a Kochanek Spline
      • Parametric Geometric Objects
      • Pixel Art of ALIEN MONSTERS
      • Platonic Solids
      • Create Point Cloud
      • Create a PointSet
      • Create PolyData
      • Triangle Strips
      • Unstructured Grid with Polyhedra
      • Create Sphere Mesh Multiple Ways
      • Creating a Spline
      • Creating a Structured Surface
      • Drape 2D Surface From Line
      • Create Triangulated Surface
      • Plot Truss-like FEA Solution with Cylinders
      • Creating a Uniform Grid
      • Creating an Unstructured Grid
      • Linear Cells
      • Working with glTF Files
      • Working with VRML Files
      • Read FEniCS/Dolfin Meshes
      • Load and Plot from a File
      • Read Image Files
      • Parallel Files
      • Load data using a Reader
      • Terrain Following Mesh
      • Wrapping Other Objects
    • Filtering
      • Boolean Operations
      • Extract Cell Centers
      • Clipping with Planes & Boxes
      • Clipping with a Surface
      • Collision
      • Computing Surface Normals
      • Volumetric Analysis
      • Connectivity
      • Contouring
      • Decimation
      • Distance Between Two Surfaces
      • Extract Cells Inside Surface
      • Extract Edges
      • Extract Surface
      • Extrude Rotation
      • Extrude Trim
      • Marching Cubes
      • Gaussian Smoothing
      • Geodesic Paths
      • Plotting Glyphs (Vectors or PolyData)
      • Table of Glyphs
      • Compute Gradients of a Field
      • Fast Fourier Transform
      • Fast Fourier Transform with Perlin Noise
      • Image Data Representations
      • Integrate Data
      • Detailed Interpolating Points
      • Compare interpolation/sampling methods
      • Computing Mesh Quality
      • Ray Tracing
      • Project to a Plane
      • Reflect Meshes
      • Detailed Resampling
      • Rotations
      • Sample Function: Perlin Noise in 2D
      • Sample Function: Perlin Noise in 3D
      • Slicing
      • Streamlines
      • 2D Streamlines
      • Subdivide Cells
      • Surface Reconstruction
      • Surface Smoothing
      • Using Common Filters
      • Voxelize a Surface Mesh
      • Warping by Vectors
    • Plotting
      • Anti-Aliasing
      • Setting Backface Properties
      • Background Image
      • Blurring
      • Plotting Bounds
      • Chart Basics
      • Chart Overlays
      • Clearing a Mesh or the Entire Plot
      • Colormap Choices
      • Color Cycling
      • Composite Picking
      • Depth of Field Plotting
      • Depth Peeling
      • Label based on Distance on Line
      • Measuring distance
      • Show Edges
      • Eye Dome Lighting
      • Picking elements of a mesh
      • Plot with Floors
      • Hide Cells with Ghosting
      • Create a GIF Movie
      • Render a depth image
      • Interpolate Before Mapping
      • Moving Isovalue
      • Label Points
      • Legends and glyphs
      • Lighting Properties
      • Linked Views in Subplots
      • Lookup Tables
      • Picking Meshes
      • Create a MP4 Movie
      • Save a Movie Using Glyphs
      • Create a GIF Movie of a Static Object with a Moving Colormap
      • Multi-Window Plot
      • Plot with Opacity
      • Orbiting
      • Orthogonal Slices
      • Physically Based Rendering
      • Plot Scalars Over a Circular Arc
      • Plot Over Line
      • Point Cell Scalars
      • Plotting Point Clouds
      • Picking points on a mesh
      • Scaled Gaussian Points
      • Customize Scalar Bars
      • Saving Screenshots
      • Types of Shading
      • Silhouette Highlight
      • Plot data in spherical coordinates
      • Surface Space Ambient Occlusion
      • Picking a Point on the Surface of a Mesh
      • Applying Textures
      • Control Global and Local Plotting Themes
      • Topographic Map
      • Plot Vector Component
      • Visible Vertices
      • Volume Rendering
    • Widgets
      • Animation
      • Box Widget
      • Checkbox Widget
      • Clip Volume Widget
      • Line Widget
      • Multiple Slider Widgets
      • Plane Widget
      • Slider Bar Widget
      • Sphere Widget
      • Spline Widget
    • Lighting
      • Light Actors
      • Attenuation
      • Beam Shape
      • Light Types
      • Disabling Mesh Lighting
      • Plotter Lighting Systems
      • Shadows
    • Common
      • Project points to a plane and Tessellate
    • Advanced
      • Adding a New Gallery Example
      • Visualize Anatomical Groups
      • Compare Field Across Mesh Regions
      • Plot Atomic Orbitals
      • Customize Trame toolbar
      • Extending PyVista
      • Visualize Hertzian Contact Stress
      • Plot a Magnetic Field
      • Electronics Cooling CFD
      • Plot OpenFOAM data
      • Plot CFD Data
      • 3D Earth and Celestial Bodies
      • Plotting with VTK Algorithms
      • Visualize Modal Analysis of a Pump Bracket
      • Visualize the Moeller-Trumbore Algorithm
      • Turning the sphere inside out
      • Display Eigenmodes of Vibration
  • API Reference
    • Core API
      • DataObject
      • Data Sets
      • Point Sets
      • Gridded Data
      • Composite Datasets
      • Filters
      • Cameras
      • Lights
      • Cells
      • Helpers
      • Miscellaneous
      • Typing
      • Partitioned Datasets
      • Validation
    • Plotting
      • Plotting
      • PyVista and PyQt
      • Themes
      • Trame
      • pyvista.Actor
      • pyvista.Axes
      • pyvista.AxesActor
      • pyvista.AxesAssembly
      • pyvista.AxesAssemblySymmetric
      • pyvista.CameraPosition
      • pyvista.CornerAnnotation
      • pyvista.CubeAxesActor
      • pyvista.DataSetMapper
      • pyvista.Label
      • pyvista.LookupTable
      • pyvista.PlanesAssembly
      • pyvista.Plotter
      • pyvista.Prop3D
      • pyvista.Property
      • pyvista.Renderer
      • pyvista.RenderWindowInteractor
      • pyvista.Text
      • pyvista.TextProperty
      • pyvista.Timer
      • pyvista.plotting.mapper._BaseMapper
      • pyvista.plotting.opts.InterpolationType
      • pyvista.plotting.opts.RepresentationType
      • pyvista.plotting.opts.ElementType
      • pyvista.plotting.volume.Volume
      • pyvista.plotting.volume_property.VolumeProperty
      • pyvista.CompositePolyDataMapper
      • pyvista.CompositeAttributes
      • pyvista.BlockAttributes
      • Charts
      • pyvista.plotting.widgets.WidgetHelper
      • pyvista.plotting.widgets.AffineWidget3D
      • pyvista.plotting.picking.PickingHelper
      • Convenience Functions
    • Utilities
      • Geometry
      • Image
      • Parametric Objects
      • General Utilities
    • Readers
      • pyvista.get_reader
      • pyvista.AVSucdReader
      • pyvista.BMPReader
      • pyvista.BYUReader
      • pyvista.BinaryMarchingCubesReader
      • pyvista.CGNSReader
      • pyvista.DEMReader
      • pyvista.DICOMReader
      • pyvista.EnSightReader
      • pyvista.ExodusIIBlockSet
      • pyvista.ExodusIIReader
      • pyvista.FacetReader
      • pyvista.FLUENTCFFReader
      • pyvista.FluentReader
      • pyvista.GambitReader
      • pyvista.GaussianCubeReader
      • pyvista.GESignaReader
      • pyvista.GIFReader
      • pyvista.GLTFReader
      • pyvista.HDFReader
      • pyvista.HDRReader
      • pyvista.JPEGReader
      • pyvista.MFIXReader
      • pyvista.MetaImageReader
      • pyvista.MINCImageReader
      • pyvista.MultiBlockPlot3DReader
      • pyvista.Nek5000Reader
      • pyvista.NIFTIReader
      • pyvista.NRRDReader
      • pyvista.OBJReader
      • pyvista.OpenFOAMReader
      • pyvista.ParticleReader
      • pyvista.PDBReader
      • pyvista.PLYReader
      • pyvista.PNGReader
      • pyvista.PNMReader
      • pyvista.POpenFOAMReader
      • pyvista.PTSReader
      • pyvista.PVDReader
      • pyvista.Plot3DMetaReader
      • pyvista.ProStarReader
      • pyvista.SLCReader
      • pyvista.STLReader
      • pyvista.SegYReader
      • pyvista.TIFFReader
      • pyvista.TecplotReader
      • pyvista.VTKDataSetReader
      • pyvista.VTKPDataSetReader
      • pyvista.XMLImageDataReader
      • pyvista.XMLMultiBlockDataReader
      • pyvista.XMLPImageDataReader
      • pyvista.XMLPRectilinearGridReader
      • pyvista.XMLPUnstructuredGridReader
      • pyvista.XMLPartitionedDataSetReader
      • pyvista.XMLPolyDataReader
      • pyvista.XMLRectilinearGridReader
      • pyvista.XMLStructuredGridReader
      • pyvista.XMLUnstructuredGridReader
      • pyvista.XdmfReader
      • pyvista.BaseReader
      • pyvista.PointCellDataSelection
      • pyvista.TimeReader
      • Reader Enumerations
    • Examples
      • pyvista.examples.examples
      • pyvista.examples.downloads
      • pyvista.demos.demos
      • pyvista.examples.planets
      • pyvista.examples.vrml
      • pyvista.examples.download_3ds
      • pyvista.examples.gltf
      • pyvista.examples.cells
      • Dataset Gallery
  • Extras
    • Building VTK
    • PyVista within a Docker Container
    • Freezing PyVista with PyInstaller
    • Contributing
    • Sphinx PyVista Plot Directive
    • PyVista pytest Plugin
    • Using Local VTK-Data
    • Extending PyVista
  • .rst

Adding a New Gallery Example

Contents

  • Section Title
  • Plots and images
  • Caveat - Plotter must be within One Cell
  • This Cell Cannot Run the Plotter
  • Animations
  • Adding Example Files
  • Adding a Wrapped Example

Note

Go to the end to download the full example code.

Adding a New Gallery Example#

This example demonstrates how to add a new PyVista Sphinx Gallery example as well as being a template that can be used in their creation.

Each example should have a reference tag/key in the form:

.. _<example_name>_example:

The .. _ is necessary. Everything that follows is your reference tag, which can potentially be used within a docstring. As convention, we keep all references all in snake_case.

This section should give a brief overview of what the example is about and/or demonstrates. The title should be changed to reflect the topic your example covers.

New examples should be added as python scripts to:

examples/<index>-<directory-name>/<some_example>.py

Note

Avoid creating new directories unless absolutely necessary.If you must create a new folder, make sure to add a README.txt containing a reference, a title and a single sentence description of the folder. Otherwise the new folder will be ignored by Sphinx.

Example file names should be underscore-separated snake case:

some_example.py

After this preamble is complete, the first code block begins. This is where you typically set up your imports.

Note

By default, the documentation scrapper will generate both a static image and an interactive widget for each plot. If you want to turn this feature off define at the top of your file:

# sphinx_gallery_start_ignore

PYVISTA_GALLERY_FORCE_STATIC_IN_DOCUMENT = True

# sphinx_gallery_end_ignore

If you want to use static images only for some of your plots. Define PYVISTA_GALLERY_FORCE_STATIC before the plot/show command that produces the image you want to turn into static.

...
pl.show()  # this will be interactive plot

...
pl.show()  # this will be static plot
from __future__ import annotations

import pyvista as pv
from pyvista import examples

Section Title#

Code blocks can be broken up with text “sections” which are interpreted as restructured text.

This will also be translated into a markdown cell in the generated jupyter notebook or the HTML page.

Sections can contain any information you may have regarding the example such as step-by-step comments or notes regarding motivations etc.

As in Jupyter notebooks, if a statement is unassigned at the end of a code block, output will be generated and printed to the screen according to its __repr__ method. Otherwise, you can use print() to output text.

# Create a dataset and exercise it's repr method
dataset = pv.Sphere()
dataset
HeaderData Arrays
PolyDataInformation
N Cells1680
N Points842
N Strips0
X Bounds-4.993e-01, 4.993e-01
Y Bounds-4.965e-01, 4.965e-01
Z Bounds-5.000e-01, 5.000e-01
N Arrays1
NameFieldTypeN CompMinMax
NormalsPointsfloat323-1.000e+001.000e+00


Plots and images#

If you use anything that outputs an image (for example, pyvista.Plotter.show()) the resulting image will be rendered within the output HTML.

Note

Unless sphinx_gallery_thumbnail_number = <int> is included at the top of the example script, first figure (this one) will be used for the gallery thumbnail image.

Also note that this image number uses one based indexing.

dataset.plot(text='Example Figure')
add example

Caveat - Plotter must be within One Cell#

It’s not possible for a single pyvista.Plotter object across multiple cells because these are closed out automatically at the end of a cell.

Here we just exercise the pyvista.Actor repr for demonstrating why you might want to instantiate a plotter without showing it in the same cell.

pl = pv.Plotter()
actor = pl.add_mesh(dataset)
actor
add example
Actor (0x7f18555b1840)
  Center:                     (0.0, 0.0, 0.0)
  Pickable:                   True
  Position:                   (0.0, 0.0, 0.0)
  Scale:                      (1.0, 1.0, 1.0)
  Visible:                    True
  X Bounds                    -4.993E-01, 4.993E-01
  Y Bounds                    -4.965E-01, 4.965E-01
  Z Bounds                    -5.000E-01, 5.000E-01
  User matrix:                Identity
  Has mapper:                 True

Property (0x7f18555b1660)
  Ambient:                     0.0
  Ambient color:               Color(name='lightblue', hex='#add8e6ff', opacity=255)
  Anisotropy:                  0.0
  Color:                       Color(name='lightblue', hex='#add8e6ff', opacity=255)
  Culling:                     "none"
  Diffuse:                     1.0
  Diffuse color:               Color(name='lightblue', hex='#add8e6ff', opacity=255)
  Edge color:                  Color(name='black', hex='#000000ff', opacity=255)
  Edge opacity:                1.0
  Interpolation:               InterpolationType.FLAT
  Lighting:                    True
  Line width:                  1.0
  Metallic:                    0.0
  Opacity:                     1.0
  Point size:                  5.0
  Render lines as tubes:       False
  Render points as spheres:    False
  Roughness:                   0.5
  Show edges:                  False
  Specular:                    0.0
  Specular color:              Color(name='lightblue', hex='#add8e6ff', opacity=255)
  Specular power:              100.0
  Style:                       "Surface"

DataSetMapper (0x7f18555b1660)
  Scalar visibility:           False
  Scalar range:                (0.0, 1.0)
  Interpolate before mapping:  True
  Scalar map mode:             default
  Color mode:                  direct

Attached dataset:
PolyData (0x7f183fa7fd60)
  N Cells:    1680
  N Points:   842
  N Strips:   0
  X Bounds:   -4.993e-01, 4.993e-01
  Y Bounds:   -4.965e-01, 4.965e-01
  Z Bounds:   -5.000e-01, 5.000e-01
  N Arrays:   1

This Cell Cannot Run the Plotter#

The plotter will already be closed by sphinx_gallery.

# This cannot be run here because the plotter is already closed and would raise
# an error:
# >>> pl.show()

# You can, however, close out the plotter or access other attributes.
pl.close()

Animations#

You can even create animations, and while there is a full example in Create a MP4 Movie, this cell explains how you can create an animation within a single cell.

Here, we explode a simple sphere.

pl = pv.Plotter(off_screen=True)

# optimize for size
pl.open_gif('example_movie.gif', palettesize=16)

sphere = pv.Sphere(theta_resolution=10, phi_resolution=10)

# Add initial mesh to setup the camera
actor = pl.add_mesh(sphere)
pl.background_color = 'w'

# clear and overwrite the mesh on each frame
n_frames = 20
for i in range(n_frames):
    exploded = sphere.explode(factor=i / (n_frames * 2)).extract_surface()
    actor.mapper.dataset.copy_from(exploded)
    pl.camera.reset_clipping_range()
    pl.write_frame()  # Write this frame

# Be sure to close the plotter when finished
pl.close()
add example

Adding Example Files#

PyVista has a variety of example files all stored at pyvista/vtk_data, and you can add the file by following the directions there.

Under the hood, PyVista uses pooch, and you can easily access any files added with pyvista.examples.downloads.download_file().

filename = examples.download_file('bunny.ply')
filename
'/home/runner/.cache/pyvista_3/bunny.ply'

Adding a Wrapped Example#

While it’s possible to simply download a file and then read it in, it’s better for you to write a wrapped download_<example_dataset>() within /pyvista/examples/downloads.py. For example download_bunny() downloads and reads with pyvista.read().

If you intend on adding an example file, you should add a new function in downloads.py to make it easy for users to add example files.

dataset = examples.download_bunny()
dataset


# Making a Pull Request
# ~~~~~~~~~~~~~~~~~~~~~
# Once your example is complete and you've verified it builds locally, you can
# make a pull request (PR).
#
# Branches containing examples should be prefixed with `docs/` as per the branch
# naming conventions found in out `Contributing Guidelines
# <https://github.com/pyvista/pyvista/blob/main/CONTRIBUTING.rst>`_.
#
# .. note::
#    You only need to create the Python source example (``*.py``).  The jupyter
#    notebook and the example HTML will be auto-generated via `sphinx-gallery
#    <https://sphinx-gallery.github.io/>`_.
PolyDataInformation
N Cells69451
N Points35947
N Strips0
X Bounds-9.469e-02, 6.101e-02
Y Bounds3.299e-02, 1.873e-01
Z Bounds-6.187e-02, 5.880e-02
N Arrays0


Total running time of the script: (0 minutes 2.364 seconds)

Download Jupyter notebook: add_example.ipynb

Download Python source code: add_example.py

Download zipped: add_example.zip

Gallery generated by Sphinx-Gallery

Contents
  • Section Title
  • Plots and images
  • Caveat - Plotter must be within One Cell
  • This Cell Cannot Run the Plotter
  • Animations
  • Adding Example Files
  • Adding a Wrapped Example

By Alex Kaszynski and Bane Sullivan

© Copyright 2017-2025, The PyVista Developers.