One-line summary: Create publication-quality 3D scientific visualizations — vector fields, isosurfaces, streamlines, and volume rendering — using Mayavi and VTK.
When to Use This Skill
When visualizing 3D scalar fields (temperature, pressure, density)
When plotting vector fields (electromagnetic, fluid velocity, magnetic)
When rendering isosurfaces from volumetric data
When creating streamlines and stream tubes for flow visualization
When animating 3D physics simulations
When exporting high-resolution 3D renders for publications
Trigger keywords: Mayavi, VTK, 3D visualization, isosurface, vector field, streamlines, volume rendering, mlab, 3D plot, scientific visualization, scalar field
Background & Key Concepts
Mayavi Architecture
Mayavi is built on VTK (Visualization Toolkit) and provides a Python API (mlab) for rapid 3D visualization:
mlab: High-level API similar to matplotlib for 3D plots
Off-screen rendering: Useful for batch/server rendering
Key Visualization Types
Data Type
Mayavi Module
Scalar field (volume)
mlab.contour3d, mlab.volume_slice
Vector field
mlab.quiver3d, mlab.flow
Isosurface
mlab.contour3d
Streamlines
mlab.flow
Point cloud
mlab.points3d
Off-screen Rendering
For server/CI environments without a display:
from mayavi import mlab
mlab.options.offscreen = True
Environment Setup
Install Dependencies
# Install via conda (recommended — VTK binary wheels)
conda install -c conda-forge mayavi
# Or via pip (requires VTK)
pip install mayavi>=4.8 numpy>=1.24 scipy>=1.11 matplotlib>=3.7
# On headless servers, also install:
pip install pyopengl
export DISPLAY=:0 # or use xvfb-run on Linux
Verify Installation
import numpy as np
from mayavi import mlab
# Test off-screen rendering
mlab.options.offscreen = True
fig = mlab.figure(bgcolor=(1, 1, 1), size=(400, 400))
x, y, z = np.mgrid[-2:2:20j, -2:2:20j, -2:2:20j]
s = np.exp(-(x**2 + y**2 + z**2))
mlab.contour3d(s, contours=5, opacity=0.5)
mlab.savefig("test_mayavi.png")
mlab.close()
print("Mayavi off-screen rendering: OK")
Core Workflow
Step 1: Scalar Field Visualization
import numpy as np
from mayavi import mlab
mlab.options.offscreen = True# Remove for interactive mode# ------------------------------------------------------------------ ## Visualize a 3D Gaussian scalar field with isosurfaces# ------------------------------------------------------------------ #
N = 60
x, y, z = np.mgrid[-3:3:N*1j, -3:3:N*1j, -3:3:N*1j]
# Anisotropic Gaussian
sigma_x, sigma_y, sigma_z = 1.0, 1.5, 0.8
field = np.exp(-(x**2/(2*sigma_x**2) + y**2/(2*sigma_y**2) + z**2/(2*sigma_z**2)))
# ----- Figure 1: Isosurfaces ------------------------------------ #
fig1 = mlab.figure(bgcolor=(0.1, 0.1, 0.1), size=(800, 600))
# Multiple isosurfaces at different levelsfor level, color, opacity in [
(0.8, (1.0, 0.2, 0.2), 0.9), # Inner (red)
(0.5, (0.2, 0.8, 0.2), 0.5), # Middle (green)
(0.2, (0.2, 0.2, 1.0), 0.2), # Outer (blue)
]:
mlab.contour3d(x, y, z, field, contours=[level],
color=color, opacity=opacity)
mlab.colorbar(title="Field value", orientation='vertical')
mlab.axes(xlabel='X', ylabel='Y', zlabel='Z')
mlab.title("3D Gaussian — Isosurfaces", size=0.3)
mlab.view(azimuth=45, elevation=60, distance=12)
mlab.savefig("scalar_field_isosurfaces.png", magnification=2)
print("Saved: scalar_field_isosurfaces.png")
# ----- Figure 2: Volume slices ---------------------------------- #
fig2 = mlab.figure(bgcolor=(0.95, 0.95, 0.95), size=(800, 600))
mlab.pipeline.volume(mlab.pipeline.scalar_field(x, y, z, field))
mlab.axes(xlabel='X', ylabel='Y', zlabel='Z')
mlab.view(azimuth=30, elevation=70, distance=14)
mlab.savefig("scalar_field_volume.png", magnification=2)
mlab.close(all=True)
print("Saved: scalar_field_volume.png")
Step 2: Vector Field Visualization
import numpy as np
from mayavi import mlab
mlab.options.offscreen = True# ------------------------------------------------------------------ ## Visualize magnetic dipole field: B = (3(m·r̂)r̂ - m) / r³# ------------------------------------------------------------------ #
N = 15
x, y, z = np.mgrid[-3:3:N*1j, -3:3:N*1j, -3:3:N*1j]
# Magnetic moment along z-axis
m = np.array([0, 0, 1])
eps = 0.3# Avoid singularity at origin
r = np.sqrt(x**2 + y**2 + z**2) + eps
r_hat_x = x / r
r_hat_y = y / r
r_hat_z = z / r
# m · r̂
m_dot_r = m[2] * r_hat_z # Only z-component of m is non-zero# B = (3(m·r̂)r̂ - m) / r³
Bx = (3 * m_dot_r * r_hat_x - m[0]) / r**3
By = (3 * m_dot_r * r_hat_y - m[1]) / r**3
Bz = (3 * m_dot_r * r_hat_z - m[2]) / r**3
B_mag = np.sqrt(Bx**2 + By**2 + Bz**2)
fig = mlab.figure(bgcolor=(0.05, 0.05, 0.15), size=(900, 700))
# Quiver plot (arrows) — subsample to avoid clutter
step = 2
mlab.quiver3d(
x[::step, ::step, ::step],
y[::step, ::step, ::step],
z[::step, ::step, ::step],
Bx[::step, ::step, ::step],
By[::step, ::step, ::step],
Bz[::step, ::step, ::step],
scalars=B_mag[::step, ::step, ::step],
mode='arrow',
scale_factor=0.3,
colormap='jet',
)
# Add magnetic moment marker (dipole location)
mlab.points3d(0, 0, 0, scale_factor=0.3, color=(1, 1, 0)) # Yellow dot# Field lines (streamlines seeded on circle in xy-plane)
seed_x = np.cos(np.linspace(0, 2*np.pi, 12)) * 1.0
seed_y = np.sin(np.linspace(0, 2*np.pi, 12)) * 1.0
seed_z = np.zeros(12)
field_src = mlab.pipeline.vector_field(x, y, z, Bx, By, Bz, scalars=B_mag)
streamlines = mlab.pipeline.streamline(
field_src,
seedtype='point',
seed_resolution=0,
integration_direction='both',
linetype='tube',
tube_radius=0.05,
)
mlab.colorbar(title="|B| (a.u.)", orientation='vertical')
mlab.axes(xlabel='X', ylabel='Y', zlabel='Z')
mlab.title("Magnetic Dipole Field", size=0.3)
mlab.view(azimuth=45, elevation=55, distance=14)
mlab.savefig("vector_field_dipole.png", magnification=2)
mlab.close(all=True)
print("Saved: vector_field_dipole.png")
Step 3: 3D Streamlines for Fluid Flow
import numpy as np
from mayavi import mlab
mlab.options.offscreen = True# ------------------------------------------------------------------ ## Potential flow: flow past a sphere using superposition# Uniform flow U₀ + doublet (Stokes stream function)# ------------------------------------------------------------------ #
N = 25
x, y, z = np.mgrid[-3:3:N*1j, -3:3:N*1j, -3:3:N*1j]
U0 = 1.0# Free stream velocity
R = 0.8# Sphere radius
r = np.sqrt(x**2 + y**2 + z**2) + 1e-6# Potential flow velocity components# u = U0(1 - R³/r³ * (1 - 3x²/r²) * ...)# Simplified for irrotational sphere flow:
factor = R**3 / r**5
u = U0 * (1 - factor * (r**2 - 3*x**2))
v = U0 * (3 * factor * x * y)
w = U0 * (3 * factor * x * z)
# Mask inside sphere
inside = r < R
u[inside] = 0; v[inside] = 0; w[inside] = 0
velocity_mag = np.sqrt(u**2 + v**2 + w**2)
fig = mlab.figure(bgcolor=(0.1, 0.15, 0.2), size=(1000, 700))
# Sphere surface
sphere_phi, sphere_theta = np.mgrid[0:np.pi:50j, 0:2*np.pi:50j]
sx = R * np.sin(sphere_phi) * np.cos(sphere_theta)
sy = R * np.sin(sphere_phi) * np.sin(sphere_theta)
sz = R * np.cos(sphere_phi)
mlab.mesh(sx, sy, sz, color=(0.7, 0.7, 0.9), opacity=0.8)
# Streamlines seeded on yz-plane upstream
src_y = np.linspace(-2, 2, 8)
src_z = np.linspace(-2, 2, 8)
SY, SZ = np.meshgrid(src_y, src_z)
SX = -2.5 * np.ones_like(SY)
field = mlab.pipeline.vector_field(x, y, z, u, v, w, scalars=velocity_mag)
stream = mlab.pipeline.streamline(
field,
seedtype='plane',
integration_direction='forward',
linetype='tube',
tube_radius=0.03,
colormap='cool',
)
stream.seed.widget.origin = np.array([-2.5, -2.0, -2.0])
stream.seed.widget.point1 = np.array([-2.5, 2.0, -2.0])
stream.seed.widget.point2 = np.array([-2.5, -2.0, 2.0])
stream.seed.widget.resolution = 7
mlab.colorbar(title="|u| (m/s)", orientation='vertical')
mlab.axes(xlabel='X', ylabel='Y', zlabel='Z')
mlab.title("Potential Flow Past a Sphere", size=0.25)
mlab.view(azimuth=20, elevation=70, distance=14)
mlab.savefig("streamlines_sphere.png", magnification=2)
mlab.close(all=True)
print("Saved: streamlines_sphere.png")
Advanced Usage
Animation — Rotating Scalar Field
import numpy as np
from mayavi import mlab
import os
mlab.options.offscreen = True# Create animated PNG sequence for a time-evolving field
N = 40
x, y, z = np.mgrid[-3:3:N*1j, -3:3:N*1j, -3:3:N*1j]
os.makedirs("frames", exist_ok=True)
for frame, t inenumerate(np.linspace(0, 2*np.pi, 36)):
field = np.sin(x + t) * np.cos(y - t/2) * np.exp(-z**2/4)
fig = mlab.figure(bgcolor=(0.0, 0.0, 0.0), size=(600, 600))
mlab.contour3d(x, y, z, field, contours=4, colormap='RdBu',
opacity=0.6, vmin=-1, vmax=1)
mlab.axes()
mlab.view(azimuth=frame * 10, elevation=60, distance=15)
mlab.savefig(f"frames/frame_{frame:03d}.png")
mlab.close()
print("Frames saved. Combine with: ffmpeg -r 12 -i frames/frame_%03d.png animation.mp4")
Troubleshooting
Error: No display name and no $DISPLAY environment variable
Cause: Headless server, no X11 display.
Fix:
# Linux: use xvfb virtual display
pip install pyopengl
Xvfb :1 -screen 0 1024x768x24 &
export DISPLAY=:1
# OR use EGL offscreen (no Xvfb needed)export ETS_TOOLKIT=null
from mayavi import mlab
mlab.options.offscreen = True# Must set BEFORE any mlab calls
