pyvista-tui

PyVista in the terminal.

Renders meshes directly in your terminal using off-screen VTK rendering, no GUI needed. Supports any file format PyVista can read (STL, VTK, PLY, OBJ, and dozens more). Works as a standalone CLI or directly in a standard Python or IPython interpreter.

[!NOTE] FYI, there is a legitimate feature request for this in PyVista, however this project is honestly one big April Fools joke that proved to have some actual utility.

Installation

pip install pyvista-tui

Requires Python 3.10+.

Quick Start

CLI

The CLI is exposed as both pyvista-tui and the shorter alias pvtui.

# Render a mesh inline
pvtui mesh.stl

# Interactive viewer with vim-style controls
pvtui mesh.vtk -i

# Color by a scalar array with a colormap
pvtui mesh.vtk --scalars temperature --cmap coolwarm

# Gallery view (6 axis-aligned views)
pvtui part.stl --gallery

Python API

from pyvista import examples
from pyvista_tui import plot

plot(examples.download_fea_bracket(), scalars="Equivalent (von-Mises) Stress (psi)", cmap="turbo")

Any keyword argument plot() does not name itself is forwarded to pyvista.Plotter.add_mesh, so options such as rgb, ambient, and culling work too.

Installed plugins also expose a .tui namespace on PyVista datasets and plotters:

import pyvista as pv

pv.OFF_SCREEN = True

mesh = pv.Sphere()
mesh.tui.plot(theme="matrix")

plotter = pv.Plotter()
plotter.add_mesh(mesh)
plotter.tui.show(theme="braille")

For an on-screen plotter, call plotter.show(auto_close=False) before plotter.tui.show(). For scripts that only render in the terminal, set pv.OFF_SCREEN = True before constructing the plotter.

Themes

Text-based themes work in every terminal -- they use only Unicode and ANSI colors.

pyvista-tui mesh.vtk -t braille    # Unicode braille (8x density)
pyvista-tui mesh.vtk -t matrix     # Green katakana rain
pyvista-tui mesh.vtk -t blueprint  # Sobel edge detection on blue

All 9 themes are switchable at runtime with keys 1--9:

Interactive Mode

Launch with -i for full keyboard-driven 3D navigation.

Camera

Display

Gallery View

Render 6 axis-aligned views in a single image:

pyvista-tui mesh.vtk --gallery --center

Multiple Meshes

Pass multiple paths (wildcards work) to tile them into a grid at a shared camera position:

pyvista-tui *.stl
pyvista-tui a.vtk b.vtk c.vtk --cpos xz --scalars VonMises --clim 67 250

Add --no-gallery to render each mesh full-size one after another instead:

pyvista-tui a.vtk b.vtk c.vtk --no-gallery

Shell brace expansion and character classes work well for sampling a range of time steps --- e.g. every tenth file between step_0170 and step_0230:

# Character classes --- same as step_0{170,180,190,200,210,220,230}.vtu
pyvista-tui data/step_0{1[789],2[0123]}0.vtu -y

The -y flag skips the confirmation prompt that otherwise fires when six or more meshes are passed.

All CLI Options

pyvista-tui [OPTIONS] MESH
pyvista-tui report

Terminal Compatibility

[!CAUTION] I've only tested this in iTerm2 and VSCode's terminal on my Mac. Help me make it work in more terminals, contributions welcome!

pyvista-tui adapts rendering to your terminal's capabilities. For best results, use a terminal with native image protocol support.

[!TIP] Text-based themes (-t braille, -t matrix, etc.) look good in any terminal including VS Code.

The terminal background color is auto-detected via OSC 11 so rendered images blend with your color scheme. Override with --background.

[!CAUTION] VS Code's integrated terminal does not support any image protocol and falls back to low-resolution halfcell blocks.

Development

git clone https://github.com/pyvista/pyvista-tui.git
cd pyvista-tui
just sync       # Install dependencies into .venv via uv
just test       # Run tests with coverage
just lint       # Run pre-commit hooks (ruff, formatting)
just typecheck  # Run mypy