PyVista3DViewer

Aliases:

  • petres.viewers.Viewer3D

class petres.viewers.PyVista3DViewer[source]

Bases: Base3DViewer

Render and manage 3D geoscience scenes using PyVista.

This viewer configures a PyVista plotter with a scene theme and camera, and provides helpers to add domain objects such as corner-point grids, zones, and horizons.

Parameters:

  • plotter (pyvista.Plotter or None, default=None) – Existing PyVista plotter to use. If None, a new plotter is created.

  • theme (PyVista3DViewerTheme or None, default=None) – Visual scene configuration. If None, a default theme is used.

  • camera (Camera3D or None, default=None) – Camera configuration. If None, an isometric default camera setup is used.

  • z_scale (float, default=1.0) – Scale factor for the z-axis to enhance vertical exaggeration.

Initialize viewer state with plotter, theme, and camera defaults.

Raises:

AssertionError – If resolved plotter, theme, or camera has an invalid type.

theme: PyVista3DViewerTheme
camera: Camera3D
plotter: Plotter
__init__(plotter=None, theme=None, camera=None, z_scale=None)[source]

Initialize viewer state with plotter, theme, and camera defaults.

Raises:

AssertionError – If resolved plotter, theme, or camera has an invalid type.

set_z_scale(z_scale)[source]

Set the z-axis scale factor for vertical exaggeration.

Parameters:

z_scale (float) – Positive finite value used to scale the z-axis in the rendered scene.

Raises:

ValueError – If z_scale is not a positive finite float.

set_plotter(plotter=None, record=True)[source]

Assign the underlying PyVista plotter.

Parameters:

  • plotter (pyvista.Plotter) – Plotter instance used for all rendering operations.

  • record (bool, default=True) –

    Whether to record mesh additions for later replay.

    When enabled, all calls to plotter.add_mesh are recorded and can be replayed on a new plotter instance. This is useful when switching plotters or when the plotter needs to be reinitialized.

Raises:

AssertionError – If plotter is not a pyvista.Plotter instance.

set_theme(theme)[source]

Assign the active scene theme.

Parameters:

theme (PyVista3DViewerTheme) – Theme containing background, axes, and title display settings.

Raises:

AssertionError – If theme is not a PyVista3DViewerTheme instance.

set_camera(camera)[source]

Assign the active camera configuration.

Parameters:

camera (Camera3D) – Camera preset and relative view adjustments used for rendering.

Raises:

AssertionError – If camera is not a Camera3D instance.

show(*, title=None)[source]

Render the current scene and open the interactive viewer window.

Parameters:

title (str or None, default=None) – Optional scene title text displayed at the configured theme position.

screenshot(path, *, transparent=False, width=None, height=None)[source]

Save a screenshot of the current plotter window to an image file.

Parameters:

  • path (str) – File path where the screenshot image will be saved.

  • transparent (bool, default=False) – Whether the background should be transparent. If True, the background color is ignored and the output image will have an alpha channel with transparency.

  • width (int) – Desired output image width in pixels.

  • height (int) – Desired output image height in pixels.

Returns:

This method saves the screenshot to disk and does not return anything.

Return type:

None

Notes

This method can be called directly after show(). In that case it reuses the cached scene camera and window size captured when the viewer was closed. If width and height are not provided, the last known window size is used. The viewer is rendered off-screen and the result is saved directly to path using the requested pixel dimensions.

add_grid(grid, *, show_inactive=False, color=None, scalars=None, cmap=None, colorbar_title=None, **kwargs)[source]

Add a supported grid to the current 3D scene.

Parameters:

  • grid (CornerPointGrid) – Grid object to visualize.

  • show_inactive (bool, default=False) – If True, include inactive cells in the rendered geometry.

  • color (Any, default=None) – Optional fixed color override for the grid mesh.

  • scalars (str or None, optional) – Property name to color by; if None uses solid color.

  • cmap (str or None, default=None) – Matplotlib-compatible colormap name used when scalars is provided.

  • colorbar_title (str or None, default=None) – Optional title for the scalar bar when scalars are provided.

  • **kwargs (Any) – Additional keyword arguments forwarded to the grid layer renderer.

Returns:

The current viewer instance for fluent chaining.

Return type:

PyVista3DViewer

Raises:

TypeError – If grid is not a supported grid type.

add_pillars(pillars, *, color='black', line_width=2.5, **kwargs)[source]

Add a pillar grid to the current 3D scene.

Parameters:

  • pillars (PillarGrid) – Pillar grid model to render.

  • color (Any, default="black") – Color used for the pillar lines and direction arrows.

  • line_width (float, default=2.5) – Width used when rendering the pillar line.

  • **kwargs (Any) – Additional keyword arguments forwarded to the pillar layer renderer.

Returns:

The current viewer instance for fluent chaining.

Return type:

PyVista3DViewer

add_wells(wells, *, label_font_size=15, label_color='red', line_color='red', line_width=2.0, **kwargs)[source]
add_zones(zones, *, x=None, y=None, xlim=None, ylim=None, ni=None, nj=None, dx=None, dy=None, show_layers=True, cmap='petres', **kwargs)[source]

Add multiple zones to the scene using a discrete colormap.

Parameters:

  • zones (Sequence[Zone]) – Zone models to render.

  • x (numpy.ndarray or None, default=None) – X-vertex coordinates. If None, computed from grid arguments.

  • y (numpy.ndarray or None, default=None) – Y-vertex coordinates. If None, computed from grid arguments.

  • xlim (tuple[float, float] or None, default=None) – X-axis bounds used when generating vertices.

  • ylim (tuple[float, float] or None, default=None) – Y-axis bounds used when generating vertices.

  • ni (int or None, default=None) – Number of cells along X used for vertex generation.

  • nj (int or None, default=None) – Number of cells along Y used for vertex generation.

  • dx (float or None, default=None) – Cell size along X used for vertex generation.

  • dy (float or None, default=None) – Cell size along Y used for vertex generation.

  • show_layers (bool, default=True) – Whether to render individual layers within each zone.

  • cmap (str, default=DEFAULT_CMAP) – Colormap name used to assign a distinct color per zone.

  • **kwargs (Any) – Additional keyword arguments forwarded to zone rendering.

Returns:

The current viewer instance for fluent chaining.

Return type:

PyVista3DViewer

add_zone(zone, *, x=None, y=None, xlim=None, ylim=None, ni=None, nj=None, dx=None, dy=None, color=None, show_layers=True, **kwargs)[source]

Add a single zone to the scene.

Parameters:

  • zone (Zone) – Zone model to render.

  • x (numpy.ndarray or None, default=None) – X-vertex coordinates. If None, computed from grid arguments.

  • y (numpy.ndarray or None, default=None) – Y-vertex coordinates. If None, computed from grid arguments.

  • xlim (tuple[float, float] or None, default=None) – X-axis bounds used when generating vertices.

  • ylim (tuple[float, float] or None, default=None) – Y-axis bounds used when generating vertices.

  • ni (int or None, default=None) – Number of cells along X used for vertex generation.

  • nj (int or None, default=None) – Number of cells along Y used for vertex generation.

  • dx (float or None, default=None) – Cell size along X used for vertex generation.

  • dy (float or None, default=None) – Cell size along Y used for vertex generation.

  • color (Any or None, default=None) – Optional color override, converted to RGB when provided.

  • show_layers (bool, default=True) – Whether to render individual zone layers.

  • **kwargs (Any) – Additional keyword arguments forwarded to zone rendering.

Returns:

The current viewer instance for fluent chaining.

Return type:

PyVista3DViewer

add_horizon(horizon, *, x=None, y=None, xlim=None, ylim=None, ni=None, nj=None, dx=None, dy=None, color=None, scalars=True, cmap=None, colorbar_title=None, **kwargs)[source]

Add a single horizon surface to the scene.

Parameters:

  • horizon (Horizon) – Horizon model used to compute a depth surface.

  • x (numpy.ndarray or None, default=None) – X-vertex coordinates. If None, computed from grid arguments.

  • y (numpy.ndarray or None, default=None) – Y-vertex coordinates. If None, computed from grid arguments.

  • xlim (tuple[float, float] or None, default=None) – X-axis bounds used when generating vertices.

  • ylim (tuple[float, float] or None, default=None) – Y-axis bounds used when generating vertices.

  • ni (int or None, default=None) – Number of cells along X used for vertex generation.

  • nj (int or None, default=None) – Number of cells along Y used for vertex generation.

  • dx (float or None, default=None) – Cell size along X used for vertex generation.

  • dy (float or None, default=None) – Cell size along Y used for vertex generation.

  • color (Any or None, default=None) – Optional fixed surface color.

  • scalars (bool, default=True) – If True, scalar-based coloring is enabled for the surface.

  • cmap (str or None, default=None) – Colormap name used when scalar coloring is enabled.

  • **kwargs (Any) – Additional keyword arguments forwarded to surface rendering.

Returns:

The current viewer instance for fluent chaining.

Return type:

PyVista3DViewer

add_horizons(horizons, *, x=None, y=None, xlim=None, ylim=None, ni=None, nj=None, dx=None, dy=None, cmap='petres', scalars=True, **kwargs)[source]

Add multiple horizons to the scene with distinct colors.

Parameters:

  • horizons (Sequence[Horizon]) – Horizon models to render.

  • x (numpy.ndarray or None, default=None) – X-vertex coordinates. If None, computed from grid arguments.

  • y (numpy.ndarray or None, default=None) – Y-vertex coordinates. If None, computed from grid arguments.

  • xlim (tuple[float, float] or None, default=None) – X-axis bounds used when generating vertices.

  • ylim (tuple[float, float] or None, default=None) – Y-axis bounds used when generating vertices.

  • ni (int or None, default=None) – Number of cells along X used for vertex generation.

  • nj (int or None, default=None) – Number of cells along Y used for vertex generation.

  • dx (float or None, default=None) – Cell size along X used for vertex generation.

  • dy (float or None, default=None) – Cell size along Y used for vertex generation.

  • cmap (str, default=DEFAULT_CMAP) – Colormap name used to assign a distinct color per horizon.

  • scalars (bool, default=True) – If True, scalar-based coloring is enabled for the surface.

  • **kwargs (Any) – Additional keyword arguments forwarded to horizon rendering.

Returns:

The current viewer instance for fluent chaining.

Return type:

PyVista3DViewer