pyvista_js.Plotter

pyvista_js.Plotter#

class pyvista_js.Plotter(lighting: str | None = 'default')#

Bases: object

Main plotting interface for pyvista-js.

This class provides a PyVista-like API for creating 3D visualizations in the browser using vtk.js as the rendering backend.

Parameters:

lighting (str or None, optional) – Lighting mode for the plotter. Options are: - "default" (default): Creates a default directional light - None: No default lights are created, giving full control over lighting

Examples

>>> import pyvista_js as pv
>>> plotter = pv.Plotter()
>>> mesh = pv.Sphere()
>>> _ = plotter.add_mesh(mesh, color='red')
>>> plotter.show()

Create a plotter with no default lights:

>>> plotter = pv.Plotter(lighting=None)
>>> light = pv.Light(position=(1, 1, 1), intensity=2.0)
>>> plotter.add_light(light)
>>> mesh = pv.Sphere()
>>> _ = plotter.add_mesh(mesh, color='white')
>>> plotter.show()
__init__(lighting: str | None = 'default') → None#

Initialize a new Plotter instance.

Parameters:

lighting (str or None, optional) – Lighting mode. "default" creates a default directional light, None creates no default lights. Default is "default".

Methods

__init__([lighting])

Initialize a new Plotter instance.

add_axes(**kwargs)

Add an orientation marker (axes indicator) to the viewport.

add_light(light)

Add a light source to the scene.

add_mesh(mesh[, color, opacity, pbr, ...])

Add a mesh to the plotter.

add_points(points[, color, opacity, ...])

Add a point cloud to the plotter.

add_scalar_bar([title, vertical, n_labels])

Add a scalar bar to display the color legend.

add_text(text)

Add a text annotation to the scene.

clear()

Clear all actors from the plotter.

disable_parallel_projection()

Disable parallel projection (use perspective projection).

enable_parallel_projection()

Enable parallel (orthographic) projection.

generate_standalone_html()

Generate a complete standalone HTML page with the current scene.

screenshot([filename, ...])

Take a screenshot of the current scene.

set_environment_texture(texture)

Set the environment texture for image-based lighting (IBL).

show([container_id, cpos])

Display the visualization.

view_isometric()

View the scene from an isometric angle.

view_vector(vector[, viewup])

Point the camera in the direction of the given vector.

view_xy([negative])

View the XY plane.

view_xz([negative])

View the XZ plane.

view_yx([negative])

View the YX plane (inverse of XY).

view_yz([negative])

View the YZ plane.

view_zx([negative])

View the ZX plane (inverse of XZ).

view_zy([negative])

View the ZY plane (inverse of YZ).

Attributes

actors

Return the list of actors in the plotter.

background_color

Get or set the background color.

camera

Get or set the camera for the plotter.

camera_position

Get the camera position.
property actors: list[dict[str, Any]]#

Return the list of actors in the plotter.

add_axes(**kwargs: object) → None#

Add an orientation marker (axes indicator) to the viewport.

Displays XYZ axes in the corner of the viewport to help orient the viewer. Backed by vtk.js vtkOrientationMarkerWidget.

Parameters:

**kwargs – Reserved for future implementation. Currently accepts no parameters.

Examples

Basic usage:

>>> import pyvista_js as pv
>>> plotter = pv.Plotter()
>>> _ = plotter.add_mesh(pv.Sphere())
>>> plotter.add_axes()
>>> plotter.show()

With multiple meshes:

>>> import pyvista_js as pv
>>> plotter = pv.Plotter()
>>> _ = plotter.add_mesh(pv.Sphere(), color='red')
>>> _ = plotter.add_mesh(pv.Cube(center=(2, 0, 0)), color='blue')
>>> plotter.add_axes()
>>> plotter.show()
add_light(light: Light) → None#

Add a light source to the scene.

Parameters:

light (Light) – The Light to add.

Examples

>>> import pyvista_js as pv
>>> plotter = pv.Plotter()
>>> _ = plotter.add_mesh(pv.Sphere(), color='white')
>>> light = pv.Light(position=(5, 5, 5), color='white', intensity=2.0)
>>> plotter.add_light(light)
>>> plotter.show()
add_mesh(mesh: PolyData | UnstructuredGrid, color: str | tuple[float, float, float] | None = None, opacity: float = 1.0, pbr: bool = False, metallic: float = 0.0, roughness: float = 0.5, smooth_shading: bool = True, texture: Texture | None = None, show_edges: bool = False, edge_color: str | tuple[float, float, float] | None = None, style: str = 'surface', scalars: str | None = None, cmap: str = 'viridis', **kwargs: object) → dict[str, object]#

Add a mesh to the plotter.

Parameters:

  • mesh (Mesh) – The mesh object to add to the scene.

  • color (str or tuple, optional) – Color of the mesh. Can be a color name or RGB tuple.

  • opacity (float, optional) – Opacity of the mesh, between 0 (transparent) and 1 (opaque).

  • pbr (bool, optional) – Enable physically based rendering (PBR). Default is False.

  • metallic (float, optional) – Metallic factor for PBR, between 0 (non-metallic) and 1 (fully metallic). Only used when pbr=True. Default is 0.0.

  • roughness (float, optional) – Roughness factor for PBR, between 0 (mirror-like) and 1 (fully rough). Only used when pbr=True. Default is 0.5.

  • smooth_shading (bool, optional) – Enable smooth shading (Gouraud interpolation). When True, the mesh surface appears smooth by interpolating normals across polygons. When False, flat shading is used where each polygon face has a uniform color. Default is True.

  • texture (Texture, optional) – Surface texture to apply to the mesh. Create one with Texture. The mesh should have texture coordinates set (e.g., via texture_map_to_plane()) or use a primitive (Sphere, Cube, Cylinder) that generates them automatically.

  • show_edges (bool, optional) – Show the edges of the mesh. Default is False.

  • edge_color (str or tuple, optional) – Color of the edges when show_edges=True. Can be a color name or RGB tuple. If not specified, defaults to black.

  • style (str, optional) – Visualization style of the mesh. One of 'surface' (default), 'wireframe', or 'points'.

  • scalars (str, optional) – Name of the scalar array to use for coloring. The array must exist in mesh.point_data.

  • cmap (str, optional) – Name of the colormap to use when rendering scalars. Default is ‘viridis’. Supported colormaps: ‘viridis’, ‘plasma’, ‘inferno’, ‘magma’, ‘jet’, ‘rainbow’, ‘turbo’, ‘coolwarm’.

  • **kwargs – Additional rendering options.

Returns:

The vtk.js actor representing the mesh.

Return type:

actor

Examples

>>> import pyvista_js as pv
>>> plotter = pv.Plotter()
>>> mesh = pv.Sphere()
>>> _ = plotter.add_mesh(mesh, color='red', opacity=0.8)

PBR example:

>>> import pyvista_js as pv
>>> plotter = pv.Plotter()
>>> mesh = pv.Sphere()
>>> _ = plotter.add_mesh(mesh, color='white', pbr=True, metallic=0.8, roughness=0.1)

Texture example:

>>> import pyvista_js as pv
>>> from pyvista_js import examples
>>> plotter = pv.Plotter()
>>> sphere = pv.Sphere()
>>> texture = examples.download_masonry_texture()
>>> _ = plotter.add_mesh(sphere, texture=texture)
>>> plotter.show()

Show edges:

>>> import pyvista_js as pv
>>> plotter = pv.Plotter()
>>> mesh = pv.Sphere()
>>> _ = plotter.add_mesh(mesh, show_edges=True, edge_color='black')
>>> plotter.show()

Wireframe rendering:

>>> import pyvista_js as pv
>>> plotter = pv.Plotter()
>>> mesh = pv.Cube()
>>> _ = plotter.add_mesh(mesh, style='wireframe')
>>> plotter.show()

Surface with edges:

>>> import pyvista_js as pv
>>> plotter = pv.Plotter()
>>> mesh = pv.Cube()
>>> _ = plotter.add_mesh(mesh, style='surface', show_edges=True)
>>> plotter.show()

Scalar coloring:

>>> import pyvista_js as pv
>>> mesh = pv.Sphere()
>>> mesh['elevation'] = mesh.points[:, 2]
>>> plotter = pv.Plotter()
>>> _ = plotter.add_mesh(mesh, scalars='elevation', cmap='viridis')
>>> plotter.show()

Compare smooth shading (left) and flat shading (right) side by side:

>>> import pyvista_js as pv
>>> plotter = pv.Plotter()
>>> color = (0.8, 0.6, 0.2)
>>> smooth = pv.Sphere(center=(-1.5, 0, 0), theta_resolution=8, phi_resolution=8)
>>> _ = plotter.add_mesh(smooth, color=color, smooth_shading=True)
>>> flat = pv.Sphere(center=(1.5, 0, 0), theta_resolution=8, phi_resolution=8)
>>> _ = plotter.add_mesh(flat, color=color, smooth_shading=False)
>>> plotter.show()
add_points(points: object, color: str | tuple[float, float, float] | None = None, opacity: float = 1.0, point_size: float = 5.0, render_points_as_spheres: bool = False, **kwargs: object) → dict[str, object]#

Add a point cloud to the plotter.

Parameters:

  • points (array-like or PolyData) – Point coordinates as an (n, 3) numpy array or PolyData object.

  • color (str or tuple, optional) – Color of the points. Can be a color name or RGB tuple.

  • opacity (float, optional) – Opacity of the points, between 0 (transparent) and 1 (opaque).

  • point_size (float, optional) – Size of the points in pixels. Default is 5.0.

  • render_points_as_spheres (bool, optional) – Render points as spheres instead of screen-space squares. Default is False.

  • **kwargs – Additional rendering options.

Returns:

The vtk.js actor representing the point cloud.

Return type:

actor

Examples

>>> import pyvista_js as pv
>>> import numpy as np
>>> points = np.random.rand(100, 3)
>>> plotter = pv.Plotter()
>>> _ = plotter.add_points(points, color='red', point_size=10)
>>> plotter.show()

With spheres:

>>> plotter = pv.Plotter()
>>> points = np.random.rand(50, 3)
>>> _ = plotter.add_points(
...     points, color='blue', point_size=8, render_points_as_spheres=True
... )
>>> plotter.show()
add_scalar_bar(title: str = '', vertical: bool = True, n_labels: int = 5) → None#

Add a scalar bar to display the color legend.

This method adds a scalar bar (color legend) that shows the mapping between scalar values and colors. The scalar bar is linked to the active scalar colormap from the most recently added mesh.

Parameters:

  • title (str, optional) – Title text to display on the scalar bar. Default is an empty string.

  • vertical (bool, optional) – Whether to orient the scalar bar vertically (True) or horizontally (False). Default is True.

  • n_labels (int, optional) – Number of labels to display on the scalar bar. Default is 5.

Examples

>>> import pyvista_js as pv
>>> import numpy as np
>>> mesh = pv.Sphere()
>>> mesh['height'] = mesh.points[:, 2]
>>> plotter = pv.Plotter()
>>> plotter.add_mesh(mesh, scalars='height', cmap='viridis')
>>> plotter.add_scalar_bar(title='Height', vertical=True)
>>> plotter.show()

Horizontal scalar bar:

>>> plotter = pv.Plotter()
>>> plotter.add_mesh(mesh, scalars='height', cmap='viridis')
>>> plotter.add_scalar_bar(title='Height', vertical=False, n_labels=7)
>>> plotter.show()
add_text(text: Text) → None#

Add a text annotation to the scene.

Parameters:

text (Text) – The Text to add.

Examples

>>> import pyvista_js as pv
>>> plotter = pv.Plotter()
>>> _ = plotter.add_mesh(pv.Sphere(), color='white')
>>> text = pv.Text("Hello World", position=(0.5, 0.9))
>>> plotter.add_text(text)
>>> plotter.show()
property background_color: tuple[float, float, float]#

Get or set the background color.

Parameters:

color (str or tuple) – Color name (e.g., ‘white’, ‘black’, ‘red’) or RGB tuple with values between 0 and 1 (e.g., (1.0, 1.0, 1.0) for white).

Returns:

RGB color tuple with values between 0 and 1.

Return type:

tuple

Examples

>>> import pyvista_js as pv
>>> plotter = pv.Plotter()
>>> plotter.background_color = 'white'
>>> plotter.background_color
(1.0, 1.0, 1.0)
>>> plotter.background_color = (0.5, 0.5, 0.5)
property camera: Camera | None#

Get or set the camera for the plotter.

Parameters:

cam (Camera) – The camera object to use for rendering.

Returns:

The current camera, or None if not set.

Return type:

Camera or None

Examples

>>> import pyvista_js as pv
>>> plotter = pv.Plotter()
>>> _ = plotter.add_mesh(pv.Sphere())
>>> camera = pv.Camera()
>>> camera.position = (5, 5, 5)
>>> camera.focal_point = (0, 0, 0)
>>> plotter.camera = camera
>>> plotter.show()
property camera_position: tuple[float, float, float] | tuple[tuple[float, float, float], tuple[float, float, float], tuple[float, float, float]] | None#

Get the camera position.

Returns:

If a camera is set, returns a 3-tuple of 3-tuples: (position, focal_point, view_up). Otherwise returns None.

Return type:

tuple or None

Examples

>>> import pyvista_js as pv
>>> plotter = pv.Plotter()
>>> plotter.camera_position = [(2.0, 5.0, 13.0), (0.0, 0.0, 0.0), (0.0, 1.0, 0.0)]
>>> plotter.camera_position
((2.0, 5.0, 13.0), (0.0, 0.0, 0.0), (0.0, 1.0, 0.0))
clear() → None#

Clear all actors from the plotter.

Examples

>>> import pyvista_js as pv
>>> plotter = pv.Plotter()
>>> _ = plotter.add_mesh(pv.Sphere())
>>> plotter.clear()
disable_parallel_projection() → None#

Disable parallel projection (use perspective projection).

Switches the camera from parallel projection to perspective projection.

If no camera is set, creates a default camera with perspective projection.

Examples

>>> import pyvista_js as pv
>>> plotter = pv.Plotter()
>>> _ = plotter.add_mesh(pv.Sphere())
>>> plotter.enable_parallel_projection()
>>> plotter.disable_parallel_projection()
>>> plotter.show()
enable_parallel_projection() → None#

Enable parallel (orthographic) projection.

Switches the camera from perspective projection to parallel projection. This is useful for viewing 2D datasets, CAD-like orthographic views, and scientific visualization where perspective distortion is undesirable.

If no camera is set, creates a default camera with parallel projection enabled.

Examples

>>> import pyvista_js as pv
>>> plotter = pv.Plotter()
>>> _ = plotter.add_mesh(pv.Cube())
>>> plotter.enable_parallel_projection()
>>> plotter.view_isometric()
>>> plotter.show()
generate_standalone_html() → str#

Generate a complete standalone HTML page with the current scene.

Returns:

A full HTML document string containing the visualization.

Return type:

str

Examples

>>> import pyvista_js as pv
>>> plotter = pv.Plotter()
>>> _ = plotter.add_mesh(pv.Sphere())
>>> html = plotter.generate_standalone_html()
>>> '<!DOCTYPE html>' in html
True
screenshot(filename: str | Path | None = None, transparent_background: bool | None = None, return_img: bool = True, window_size: tuple[int, int] | list[int] | None = None, scale: int | None = None) → np.ndarray | None#

Take a screenshot of the current scene.

Parameters:

  • filename (str, Path, or None, optional) – File path to save the image. If None, no file is written. Supported formats: PNG, JPEG. Default is None.

  • transparent_background (bool or None, optional) – Whether to make the background transparent. If None, uses the current background setting. Default is None.

  • return_img (bool, optional) – If True, return a numpy array of the image. Default is True.

  • window_size (tuple or list of int, optional) – Temporarily resize the window to (width, height) before capturing. If None, uses the current window size. Default is None.

  • scale (int or None, optional) – Scale factor for the window size to produce a higher-resolution image. For example, scale=2 will double the resolution. Default is None.

Returns:

If return_img is True, returns a numpy array with shape (height, width, 3) for RGB or (height, width, 4) for RGBA (when transparent_background=True). Otherwise returns None.

Return type:

numpy.ndarray or None

Examples

Save a screenshot to a file:

>>> import pyvista_js as pv
>>> sphere = pv.Sphere()
>>> pl = pv.Plotter()
>>> _ = pl.add_mesh(sphere)
>>> pl.screenshot("screenshot.png")

Get image data as numpy array:

>>> import pyvista_js as pv
>>> sphere = pv.Sphere()
>>> pl = pv.Plotter()
>>> _ = pl.add_mesh(sphere)
>>> img = pl.screenshot(return_img=True)
>>> img.shape
(400, 600, 3)

High-resolution screenshot with scaling:

>>> import pyvista_js as pv
>>> sphere = pv.Sphere()
>>> pl = pv.Plotter()
>>> _ = pl.add_mesh(sphere)
>>> pl.screenshot("high_res.png", scale=2)

Screenshot with transparent background:

>>> import pyvista_js as pv
>>> sphere = pv.Sphere()
>>> pl = pv.Plotter()
>>> _ = pl.add_mesh(sphere)
>>> pl.screenshot("transparent.png", transparent_background=True)
set_environment_texture(texture: str | CubeMap) → None#

Set the environment texture for image-based lighting (IBL).

Used with PBR materials to provide realistic reflections and lighting.

Parameters:

texture (str or CubeMap) – Either a URL string pointing to an equirectangular image, or a CubeMap returned by download_sky_box_cube_map().

Examples

URL string:

>>> import pyvista_js as pv
>>> plotter = pv.Plotter()
>>> _ = plotter.add_mesh(pv.Sphere(), color='white', pbr=True, metallic=1.0, roughness=0.1)
>>> plotter.set_environment_texture('https://example.com/env.jpg')
>>> plotter.show()

CubeMap:

>>> import pyvista_js as pv
>>> from pyvista_js import examples
>>> cubemap = examples.download_sky_box_cube_map()
>>> plotter = pv.Plotter()
>>> _ = plotter.add_mesh(
...     pv.Sphere(), color='white', pbr=True, metallic=1.0, roughness=0.1)
>>> plotter.set_environment_texture(cubemap)
>>> plotter.show()
show(container_id: str | None = None, cpos: str | tuple[float, float, float] | tuple[tuple[float, float, float], tuple[float, float, float], tuple[float, float, float]] | list[float] | list[tuple[float, float, float]] | list[list[float]] | None = None) → None#

Display the visualization.

In browser environments, this will render the scene using vtk.js.

Parameters:

  • container_id (str, optional) – HTML element ID for the visualization container. Defaults to a unique ID generated per Plotter instance to avoid conflicts when calling show() multiple times in the same session.

  • cpos (str, tuple, or list, optional) –

    Camera position specification. Can be:

    • String shortcut: ‘xy’, ‘xz’, ‘yz’, ‘yx’, ‘zx’, ‘zy’, or ‘iso’

    • Direction vector: 3-element tuple/list (x, y, z)

    • Full camera spec: 3-tuple/list of 3-tuples/lists: [(position), (focal_point), (view_up)]

Examples

Basic usage:

>>> import pyvista_js as pv
>>> plotter = pv.Plotter()
>>> _ = plotter.add_mesh(pv.Sphere())
>>> plotter.show()

With camera position string shortcut:

>>> plotter = pv.Plotter()
>>> _ = plotter.add_mesh(pv.Sphere())
>>> plotter.show(cpos='xy')

With direction vector:

>>> plotter = pv.Plotter()
>>> _ = plotter.add_mesh(pv.Sphere())
>>> plotter.show(cpos=(1, 0, 0))

With full camera specification:

>>> plotter = pv.Plotter()
>>> _ = plotter.add_mesh(pv.Sphere())
>>> plotter.show(cpos=[(2.0, 5.0, 13.0), (0.0, 0.0, 0.0), (0.0, 1.0, 0.0)])
view_isometric() → None#

View the scene from an isometric angle.

The isometric view shows all three axes equally, looking from the (1, 1, 1) direction.

Examples

>>> import pyvista_js as pv
>>> plotter = pv.Plotter()
>>> _ = plotter.add_mesh(pv.Cube())
>>> plotter.view_isometric()
>>> plotter.show()
view_vector(vector: tuple[float, float, float], viewup: tuple[float, float, float] | None = None) → None#

Point the camera in the direction of the given vector.

Parameters:

  • vector (tuple of float) – Direction to point the camera in, given as (vx, vy, vz).

  • viewup (tuple of float, optional) – View-up vector. Defaults to (0, 1, 0).

Examples

>>> import pyvista_js as pv
>>> plotter = pv.Plotter()
>>> _ = plotter.add_mesh(pv.Sphere())
>>> plotter.view_vector((1, 0, 0))
>>> plotter.show()

View from an isometric angle:

>>> import pyvista_js as pv
>>> plotter = pv.Plotter()
>>> _ = plotter.add_mesh(pv.Cube())
>>> plotter.view_vector((1, 1, 1))
>>> plotter.show()
view_xy(negative: bool = False) → None#

View the XY plane.

Look down the Z-axis, with the positive Z-axis pointing toward the camera.

Parameters:

negative (bool, optional) – Look in the negative Z direction (down the +Z axis). Default is False (look down the -Z axis).

Examples

>>> import pyvista_js as pv
>>> plotter = pv.Plotter()
>>> _ = plotter.add_mesh(pv.Sphere())
>>> plotter.view_xy()
>>> plotter.show()

View from the negative Z direction:

>>> import pyvista_js as pv
>>> plotter = pv.Plotter()
>>> _ = plotter.add_mesh(pv.Cube())
>>> plotter.view_xy(negative=True)
>>> plotter.show()
view_xz(negative: bool = False) → None#

View the XZ plane.

Look down the Y-axis, with the positive Y-axis pointing toward the camera.

Parameters:

negative (bool, optional) – Look in the negative Y direction (down the +Y axis). Default is False (look down the -Y axis).

Examples

>>> import pyvista_js as pv
>>> plotter = pv.Plotter()
>>> _ = plotter.add_mesh(pv.Sphere())
>>> plotter.view_xz()
>>> plotter.show()

View from the negative Y direction:

>>> import pyvista_js as pv
>>> plotter = pv.Plotter()
>>> _ = plotter.add_mesh(pv.Cube())
>>> plotter.view_xz(negative=True)
>>> plotter.show()
view_yx(negative: bool = False) → None#

View the YX plane (inverse of XY).

Look down the Z-axis from below, with the negative Z-axis pointing toward the camera.

Parameters:

negative (bool, optional) – Look in the negative Z direction (down the +Z axis). Default is False (look down the -Z axis).

Examples

>>> import pyvista_js as pv
>>> plotter = pv.Plotter()
>>> _ = plotter.add_mesh(pv.Sphere())
>>> plotter.view_yx()
>>> plotter.show()
view_yz(negative: bool = False) → None#

View the YZ plane.

Look down the X-axis, with the positive X-axis pointing toward the camera.

Parameters:

negative (bool, optional) – Look in the negative X direction (down the +X axis). Default is False (look down the -X axis).

Examples

>>> import pyvista_js as pv
>>> plotter = pv.Plotter()
>>> _ = plotter.add_mesh(pv.Sphere())
>>> plotter.view_yz()
>>> plotter.show()

View from the negative X direction:

>>> import pyvista_js as pv
>>> plotter = pv.Plotter()
>>> _ = plotter.add_mesh(pv.Cube())
>>> plotter.view_yz(negative=True)
>>> plotter.show()
view_zx(negative: bool = False) → None#

View the ZX plane (inverse of XZ).

Look down the Y-axis from below, with the negative Y-axis pointing toward the camera.

Parameters:

negative (bool, optional) – Look in the negative Y direction (down the +Y axis). Default is False (look down the -Y axis).

Examples

>>> import pyvista_js as pv
>>> plotter = pv.Plotter()
>>> _ = plotter.add_mesh(pv.Sphere())
>>> plotter.view_zx()
>>> plotter.show()
view_zy(negative: bool = False) → None#

View the ZY plane (inverse of YZ).

Look down the X-axis from the left, with the negative X-axis pointing toward the camera.

Parameters:

negative (bool, optional) – Look in the negative X direction (down the +X axis). Default is False (look down the -X axis).

Examples

>>> import pyvista_js as pv
>>> plotter = pv.Plotter()
>>> _ = plotter.add_mesh(pv.Sphere())
>>> plotter.view_zy()
>>> plotter.show()
Contents