Plotter

Plotter is a small wrapper around PyVista that supports two visualization modes:

• Desktop (Qt): an interactive Qt window powered by pyvistaqt.QtInteractor (requires PySide6 + pyvistaqt)
• Notebook (Jupyter): PyVista’s notebook backends (set notebook=True)

It is designed for quick inspection of VTK datasets produced by pyemsi (especially *.pvd time series and *.vtm multiblock outputs), while still allowing you to access the underlying PyVista objects directly.

Installation notes

• Desktop/Qt mode requires PySide6 and pyvistaqt in addition to pyvista.
• Notebook mode requires a supported PyVista notebook backend. The default in pyemsi is backend="html".

If Qt dependencies are missing and you instantiate Plotter(notebook=False), it raises an ImportError with the suggested packages to install.

Initialization

from pyemsi import Plotter

# Load a dataset (VTU/VTM/PVD/...)
p = Plotter("path/to/output.pvd")

# Notebook mode (Jupyter)
p_nb = Plotter("path/to/output.pvd", notebook=True, backend="html")

Parameters

• filepath (str | Path | None, optional) — Mesh file to load immediately (calls set_file()).
• title (str, default: "pyemsi Plotter") — Qt window title (desktop mode only).
• window_size (tuple[int, int], default: (1024, 768)) — Qt window size (desktop mode only).
• position (tuple[int, int] | None, default: None) — Qt window position (desktop mode only).
• notebook (bool, default: False) — Use PyVista notebook plotting instead of Qt.
• backend (str | None, default: "html") — PyVista notebook backend passed to pyvista.set_jupyter_backend().
• **kwargs — Passed to the underlying plotter (QtInteractor in desktop mode, pyvista.Plotter in notebook mode).

Working with time series (*.pvd)

When the input file is a *.pvd, Plotter.reader is a PVDReader. You can select a time step before plotting:

Plotter also exposes convenience proxies to PyVista’s TimeReader API:

• active_time_value
• number_time_points
• time_values
• set_active_time_point(time_point)
• set_active_time_value(time_value)
• time_point_value(time_point)

If the underlying reader is not a TimeReader, the getter-style attributes return None, and the setter methods are silent no-ops that return None.

from pyemsi import Plotter

p = Plotter("path/to/output.pvd")
p.set_active_time_point(-1)          # last time step (silent no-op if not time-aware)
p.plotter.view_xy()                  # any PyVista camera helper
p.set_scalar("B-Mag (T)", mode="element", cell2point=True)
p.set_vector("B-Vec (T)", scale="B-Mag (T)", factor=5e-3, opacity=0.5)
p.show()

Visualization pipeline

If a file was loaded (via filepath or set_file()), show() and export() will (re)build the visualization in this order:

1. Scalar field (set_scalar())
2. Contours (set_contour())
3. Vector glyphs (set_vector())
4. Feature edges (set_feature_edges(), enabled by default)
5. Camera reset

If no file was loaded, you can still use the underlying plotter directly and add any PyVista meshes/actors.

Methods

	Description
set_file(filepath)	Set reader from a mesh file.
set_active_time_point(time_point)	Select active time step (no-op if not time-aware).
set_active_time_value(time_value)	Select active time by value (no-op if not time-aware).
time_point_value(time_point)	Get time value for a time step (or None).
set_feature_edges(...)	Configure feature-edge overlay.
set_scalar(...)	Configure scalar coloring.
set_contour(...)	Configure contours.
set_vector(...)	Configure vector glyphs.
get_block_names()	Get list of block names from multi-block mesh.
get_block_visibility(block_name)	Check visibility state of a block.
set_block_visibility(block_name, visible)	Set visibility for a single block.
set_blocks_visibility(visibility)	Set visibility for multiple blocks in batch.
query_point(...)	Query point data for a single point.
query_points(...)	Query point data for multiple points.
query_cell(...)	Query cell data for a single cell.
query_cells(...)	Query cell data for multiple cells.
show()	Render (Qt window or notebook output).
export(...)	Save a screenshot to an image file.

Attributes

	Description
plotter	Underlying plotter (QtInteractor desktop / pv.Plotter notebook).
reader	PyVista reader created by set_file() (e.g. for *.pvd).
mesh	Lazily reads/caches the current mesh from reader.
active_time_value	Current time value if reader is time-aware, else None.
number_time_points	Number of time steps if time-aware, else None.
time_values	Available time values if time-aware, else None.