{
"markdown": "# viznoir\n\n> VTK is all you need. Cinema-quality science visualization for AI agents.\n\n\n\n[](https://github.com/kimimgo/viznoir/actions/workflows/ci.yml)\n[](https://pypi.org/project/viznoir/)\n[](https://pypi.org/project/viznoir/)\n[](https://github.com/kimimgo/viznoir/blob/main/LICENSE)\n[](https://github.com/tkoyama010/awesome-vtk)\n\n
\n\n\n\n\n\n*One prompt → physics analysis → cinematic renders → LaTeX equations → publication-ready story.*\n\n
\n\n
\n\n## What it does\n\nAn 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.\n\n**Works with:** Claude Code · Cursor · Windsurf · Gemini CLI · any MCP client\n\n## Quick Start\n\n### 1. Install\n\n```bash\npip install viznoir\n\n# With optional extras\npip install \"viznoir[mesh]\" # meshio + trimesh (50+ formats)\npip install \"viznoir[composite]\" # Pillow + matplotlib (split_animate)\npip install \"viznoir[all]\" # everything\n```\n\nRequires Python ≥3.10. VTK wheel auto-installed (EGL headless rendering supported).\n\n### 2. Verify\n\n```bash\nmcp-server-viznoir --help # server entry point\npython -c \"import viznoir; print(viznoir.__version__)\"\n```\n\n### 3. Use with an MCP client\n\nAdd to your MCP client config (`claude_desktop_config.json`, `~/.cursor/mcp.json`, etc.):\n\n```json\n{\n \"mcpServers\": {\n \"viznoir\": {\n \"command\": \"mcp-server-viznoir\",\n \"env\": {\n \"VIZNOIR_DATA_DIR\": \"/path/to/your/simulation/data\",\n \"VIZNOIR_OUTPUT_DIR\": \"/path/to/output\"\n }\n }\n }\n}\n```\n\nThen ask your AI agent:\n\n> *\"Open cavity.foam, render the pressure field with cinematic lighting, then create a physics decomposition story.\"*\n\n### 4. Or use as a Python library (advanced)\n\nAll tool implementations are importable as `async` functions. You provide a `VTKRunner` and `await` the result:\n\n```python\nimport asyncio\nfrom viznoir.core.runner import VTKRunner\nfrom viznoir.tools.inspect import inspect_data_impl\nfrom viznoir.tools.render import render_impl\n\nasync def main():\n runner = VTKRunner()\n\n meta = await inspect_data_impl(file_path=\"cavity.foam\", runner=runner)\n print(meta[\"fields\"], meta[\"timesteps\"])\n\n result = await render_impl(\n file_path=\"cavity.foam\",\n field_name=\"p\",\n runner=runner,\n colormap=\"Cool to Warm\",\n camera=\"isometric\",\n width=1920, height=1080,\n output_filename=\"pressure.png\",\n )\n print(result.file_path)\n\nasyncio.run(main())\n```\n\nSee [docs](https://kimimgo.github.io/viznoir/docs) for the full tool reference.\n\n## Capabilities\n\n| Category | Tools |\n|----------|-------|\n| **Rendering** | `render` · `cinematic_render` · `batch_render` · `volume_render` |\n| **Filters** | `slice` · `contour` · `clip` · `streamlines` · `pv_isosurface` |\n| **Analysis** | `inspect_data` · `inspect_physics` · `extract_stats` · `analyze_data` |\n| **Probing** | `plot_over_line` · `integrate_surface` · `probe_timeseries` |\n| **Animation** | `animate` · `split_animate` |\n| **Comparison** | `compare` · `compose_assets` |\n| **Export** | `preview_3d` · `execute_pipeline` |\n\n**22 tools** · **12 resources** · **4 prompts** · **50+ file formats** (OpenFOAM, VTK, CGNS, Exodus, STL, glTF, …)\n\n## Showcase — 10 Domains, One Pipeline\n\nEvery frame below is a single MCP tool call. No GUI, no post-processing, no ParaView.\nAnnotations are rendered **inside the 3D scene** via VTK-native text actors and leader lines — no Photoshop, no matplotlib overlay.\n\n\n\n| | | | | |\n|:-:|:-:|:-:|:-:|:-:|\n|  |  |  |  |  |\n| **Medical**
CT skull volume | **CFD**
Combustion streamlines | **Thermal**
Heatsink gradient | **Geoscience**
Seismic wavefield | **Automotive**
DrivAerML · 8.8M cells |\n|  |  |  |  |  |\n| **Molecular**
H₂O electron density | **Vascular**
Cerebral aneurysm MRA | **Planetary**
Bennu · 196K triangles | **Structural**
Cantilever FEA stress | **Volume**
Thermal threshold |\n\n
\n\n### Physics-Aware Animations\n\nSeven presets convert raw simulation data into publication-ready motion — each binds a rendering primitive to a physical phenomenon.\n\n| Preset | Physics | Rendering |\n|--------|---------|-----------|\n| `streamline_growth` | Lagrangian advection | Particle path-line extension over time |\n| `clip_sweep` | Pressure gradient cross-section | Moving clip plane |\n| `layer_reveal` | CT density classification | Progressive isosurface stacking |\n| `iso_sweep` | Orbital topology | Isovalue sweep with camera orbit |\n| `warp_oscillation` | Structural mode shape | Warp-by-vector harmonic displacement |\n| `light_orbit` | Oblique illumination | Rotating key light for material reveal |\n| `threshold_reveal` | Feature hierarchy | Threshold peeling from outside → in |\n\n### Story Composition (`compose_assets`)\n\n\n\n\n\n*Inspect → render → annotate → compose → narrate. One prompt produces a 4-panel physics decomposition with LaTeX-rendered governing equations.*\n\n
\n\nLayouts: `story` (vertical narrative) · `grid` (N×M comparison) · `slides` (16:9 keynote) · `video` (MP4 with transitions)\n\n**Full interactive gallery:** https://kimimgo.github.io/viznoir/#showcase\n\n## Architecture\n\n```\n prompt \"Render pressure from cavity.foam\"\n │\n MCP Server 22 tools · 12 resources · 4 prompts\n │\n VTK Engine readers → filters → renderer → camera\n │ EGL/OSMesa headless · cinematic lighting\n Physics Layer topology analysis · context parsing\n │ vortex detection · stagnation points\n Animation 7 physics presets · easing · timeline\n │ transitions · compositor · video export\n Output PNG · WebP · MP4 · GLTF · LaTeX\n```\n\n## Numbers\n\n| | |\n|---|---|\n| **22** MCP tools | **24** VTK filters |\n| **10** domains | **19** native file formats |\n| **6/6** VTK data types | **50+** formats via meshio |\n\n## Documentation\n\n**Homepage:** [kimimgo.github.io/viznoir](https://kimimgo.github.io/viznoir/)\n\n**Developer docs:** [kimimgo.github.io/viznoir/docs](https://kimimgo.github.io/viznoir/docs) — full tool reference, domain gallery, architecture guide\n\n## License\n\nMIT\n",
"bytes": 8115,
"sha": "04b75f8eafa2abf952034d91791d11d304a4731640b45e8bc09a9196002974ec",
"repo_slug": "kimimgo/viznoir",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_kimimgo_viznoir_432e5987/readme"
}