viznoir

VTK is all you need. Cinema-quality science visualization for AI agents.

Science Storytelling

One prompt → physics analysis → cinematic renders → LaTeX equations → publication-ready story.

What it does

An MCP server that gives AI agents full access to VTK's rendering pipeline — no ParaView GUI, no Jupyter notebooks, no display server. Your agent reads simulation data, applies filters, renders cinema-quality images, and exports animations, all headless.

Works with: Claude Code · Cursor · Windsurf · Gemini CLI · any MCP client

Quick Start

1. Install

Terminal

pip install viznoir

# With optional extras
pip install "viznoir[mesh]"       # meshio + trimesh (50+ formats)
pip install "viznoir[composite]"  # Pillow + matplotlib (split_animate)
pip install "viznoir[all]"        # everything

Requires Python ≥3.10. VTK wheel auto-installed (EGL headless rendering supported).

2. Verify

server.ts

mcp-server-viznoir --help    # server entry point
python -c "import viznoir; print(viznoir.__version__)"

3. Use with an MCP client

Add to your MCP client config (claude_desktop_config.json, ~/.cursor/mcp.json, etc.):

config.json

{
  "mcpServers": {
    "viznoir": {
      "command": "mcp-server-viznoir",
      "env": {
        "VIZNOIR_DATA_DIR": "/path/to/your/simulation/data",
        "VIZNOIR_OUTPUT_DIR": "/path/to/output"
      }
    }
  }
}

Then ask your AI agent:

"Open cavity.foam, render the pressure field with cinematic lighting, then create a physics decomposition story."

4. Or use as a Python library (advanced)

All tool implementations are importable as async functions. You provide a VTKRunner and await the result:

server.ts

import asyncio
from viznoir.core.runner import VTKRunner
from viznoir.tools.inspect import inspect_data_impl
from viznoir.tools.render import render_impl

async def main():
    runner = VTKRunner()

    meta = await inspect_data_impl(file_path="cavity.foam", runner=runner)
    print(meta["fields"], meta["timesteps"])

    result = await render_impl(
        file_path="cavity.foam",
        field_name="p",
        runner=runner,
        colormap="Cool to Warm",
        camera="isometric",
        width=1920, height=1080,
        output_filename="pressure.png",
    )
    print(result.file_path)

asyncio.run(main())

See docs for the full tool reference.

Capabilities

Category	Tools
Rendering	`render` · `cinematic_render` · `batch_render` · `volume_render`
Filters	`slice` · `contour` · `clip` · `streamlines` · `pv_isosurface`
Analysis	`inspect_data` · `inspect_physics` · `extract_stats` · `analyze_data`
Probing	`plot_over_line` · `integrate_surface` · `probe_timeseries`
Animation	`animate` · `split_animate`
Comparison	`compare` · `compose_assets`
Export	`preview_3d` · `execute_pipeline`

22 tools · 12 resources · 4 prompts · 50+ file formats (OpenFOAM, VTK, CGNS, Exodus, STL, glTF, …)

Showcase — 10 Domains, One Pipeline

Every frame below is a single MCP tool call. No GUI, no post-processing, no ParaView. Annotations are rendered inside the 3D scene via VTK-native text actors and leader lines — no Photoshop, no matplotlib overlay.



Medical CT skull volume	CFD Combustion streamlines	Thermal Heatsink gradient	Geoscience Seismic wavefield	Automotive DrivAerML · 8.8M cells

Molecular H₂O electron density	Vascular Cerebral aneurysm MRA	Planetary Bennu · 196K triangles	Structural Cantilever FEA stress	Volume Thermal threshold

Physics-Aware Animations

Seven presets convert raw simulation data into publication-ready motion — each binds a rendering primitive to a physical phenomenon.

Preset	Physics	Rendering
`streamline_growth`	Lagrangian advection	Particle path-line extension over time
`clip_sweep`	Pressure gradient cross-section	Moving clip plane
`layer_reveal`	CT density classification	Progressive isosurface stacking
`iso_sweep`	Orbital topology	Isovalue sweep with camera orbit
`warp_oscillation`	Structural mode shape	Warp-by-vector harmonic displacement
`light_orbit`	Oblique illumination	Rotating key light for material reveal
`threshold_reveal`	Feature hierarchy	Threshold peeling from outside → in

Story Composition (`compose_assets`)

Cavity Story

Inspect → render → annotate → compose → narrate. One prompt produces a 4-panel physics decomposition with LaTeX-rendered governing equations.

Layouts: story (vertical narrative) · grid (N×M comparison) · slides (16:9 keynote) · video (MP4 with transitions)

Full interactive gallery: https://kimimgo.github.io/viznoir/#showcase

Architecture

Code

  prompt                    "Render pressure from cavity.foam"
    │
  MCP Server                22 tools · 12 resources · 4 prompts
    │
  VTK Engine                readers → filters → renderer → camera
    │                       EGL/OSMesa headless · cinematic lighting
  Physics Layer             topology analysis · context parsing
    │                       vortex detection · stagnation points
  Animation                 7 physics presets · easing · timeline
    │                       transitions · compositor · video export
  Output                    PNG · WebP · MP4 · GLTF · LaTeX

Numbers


22 MCP tools	24 VTK filters
10 domains	19 native file formats
6/6 VTK data types	50+ formats via meshio

Documentation

Homepage: kimimgo.github.io/viznoir

Developer docs: kimimgo.github.io/viznoir/docs — full tool reference, domain gallery, architecture guide

License

MIT