MatterVis: Crystal Structure Visualization Toolkit

Overview

MatterVis is a Python toolkit for deterministic, publication-quality material visualization. Its lightweight core renders PNG/PDF/SVG on the CPU; Plotly, Dash/Web APIs, Textual, Cube isosurfaces, and animation encoders are optional frontends.

Key Features

• ASCII-first chemistry TUI — A non-visual model can rotate the projected structure, select stable atom IDs, traverse bonds, and read MolCrysKit names, line notation, CIP descriptors, crystal enantiomer composition, warnings, and evidence without treating JSON as the primary observation
• Stateful agent sessions — Python and JSONL callers can choose each next semantic camera or selection action from the latest deterministic Unicode or ASCII-7 observation without driving a browser or PTY
• Agent-ready CLI — Five explicit subcommands (inspect, capabilities, render, serve, tui) separate bounded diagnosis, dependency preflight, browser-free static output, Web service, and terminal interaction
• Browser Viewer — Drag-and-drop CIF upload and interactive 3D display with Mesh3d atoms and bonds. Scatter3d fast rendering is used only when explicitly selected; atom count never changes the representation
• Coordination Topology — Automatic coordination-number detection via the nearest-neighbour gap, continuous shape measure (CShM) classification against 12 ideal polyhedra (CN 4–12), planarity RMS, and prism/antiprism twist analysis
• Publication Export — The base CPU backend renders PNG with per-pixel depth handling and emits true-vector PDF/SVG from the same backend-neutral geometry
• Multi-Panel Figures — uniform_viewport(scenes) stamps a shared world-cube on any list of scenes so every build_figure call emits at the same physical length per pixel
• Composable 3-D geometry: validated Cartesian meshes, lattice/HKL-aligned through-cylinders, and bounded implicit surfaces use the depth-tested Mesh3d path.
• Automation API — REST + WebSocket endpoints on the same Flask server; drive the viewer from notebooks, agents, or subprocesses
• Zero Catalog Required — Ships with a bundled DAP-4.cif so mat-vis serve works out of the box

Unit Cell — DAP-4 unit cell (flat ORTEP with element colours)

Coordination Shell — A-site coordination with convex hull overlay (CN=9, tricapped trigonal prism)

Three Display Modes — Formula unit, unit cell, and coordination shell side by side

Publication-Quality Export — Colour ORTEP-style Matplotlib renderer with labels

Asymmetric Unit — Diagnostic crystallographic view with atom labels and unit-cell context

Installation

From PyPI (recommended)

pip install matter-vis

From source (development)

git clone https://github.com/SchrodingersCattt/MatterVis.git
cd MatterVis
python -m pip install "molcrys-kit>=0.7.0"
pip install -e .

All dependencies are declared in pyproject.toml; requires-python = ">=3.10". Install only the frontend the requested output needs:

Extra	Adds
base	CPU 3D and Matplotlib 2D PNG/PDF/SVG, inspection, ORTEP, rings, and polyhedra
[plotly]	Interactive Plotly/WebGL HTML
[plotly-export]	Plotly + Kaleido static export
[web]	Dash, REST, WebSocket, compression, and Plotly
[tui]	Textual terminal UI
[cube]	Cube input inspection and isosurfaces
[animation]	GIF/MP4 encoders
[all]	Every optional frontend
[test]	Test tools

Browser screenshots and the Web UI's default static export combine [web] with [plotly-export]. Ask the resolver for the exact combined command:

mat-vis capabilities --require web-screenshot --json
mat-vis capabilities --require static-web-export --json

MolCrysKit is required and is the only chemistry structure source. MatterVis does not fall back to private MolCrysKit fields or local chemistry heuristics.

Quick Start

CLI — one-liner from CIF to figure

Install MatterVis, then render a crystal structure with a single command:

# Primary terminal observation and chemistry inspection
mat-vis tui structure.cif

# Stateful online agent session (one JSON action per stdin line)
printf '%s\n' '{"action":"observe"}' '{"action":"close"}' | \
  mat-vis tui structure.cif --session-format jsonl --charset ascii7

# PNG with default ball-and-stick style
mat-vis inspect structure.cif --json
mat-vis render structure.cif -o figure.png --backend cpu --check --json
mat-vis render structure.cif -o figure.png --backend cpu --json

# True projected 2D ball-and-stick (Matplotlib; no 3D lighting)
mat-vis render structure.cif -o figure-2d.png --backend matplotlib --json \
  --view unit_cell --style ball_stick --camera-axis c --orthogonal

# PDF, full unit cell, ORTEP hatch marks over flat-shaded ellipsoids
mat-vis render structure.cif -o figure.pdf \
  --backend cpu --view unit_cell --style ortep --shading flat \
  --ortep-mode ortep_hatch --missing-adp-policy error

# Interactive HTML for supplementary information
mat-vis render structure.cif -o si_figure.html --backend plotly \
  --show-hydrogen --show-labels

# Launch the interactive browser viewer
python -m pip install "matter-vis[web]"
mat-vis serve --cif structure.cif

See docs/cli.md for the full flag reference and common recipes.

Python API — programmatic control

from mat_viewer.agent import load_structure, prepare_render, render
from mat_viewer.render.contracts import RenderSpec, ViewSpec

structure = load_structure("scripts/data/DAP-4.cif")
plan = prepare_render(
    structure,
    view=ViewSpec(display="unit_cell"),
    render_spec=RenderSpec(backend="cpu", width=900, height=720),
)
result = render(plan, output="dap4.svg", backend="cpu")

Command Line Interface

Installing MatterVis also installs the mat-vis command. The CLI is self-documenting; use --help at any level to see the exact arguments:

mat-vis --help
mat-vis inspect --help
mat-vis capabilities --help
mat-vis render --help
mat-vis serve --help
mat-vis tui --help

The main subcommands cover:

• mat-vis tui ... — ASCII structure observation, deterministic atom selection, and chemistry inspector for non-visual agents
• mat-vis inspect ... --json — optional bounded structure/source metadata for programmatic callers
• mat-vis capabilities ... --json — availability and exact install commands
• mat-vis render ... — render atomistic structures and trajectories from CIF, Cube, VASP, XYZ, ASE, and LAMMPS inputs to PNG/PDF/SVG/HTML/GIF/MP4
• mat-vis serve ... — launch the interactive Dash browser viewer with drag-and-drop CIF upload, topology analysis, and REST + WebSocket API

Documentation

You are…	Start here
Understanding the design	Architecture
Using the library	API Reference · CLI Reference
AI agent (calling MatterVis)	Caller API Contracts
AI agent (modifying code)	AGENTS.md · Developer Notes
Topology scores	Scores Reference

mat_viewer/ — source code · scripts/ — runnable demo scripts · docs/ — full documentation

License

This project is licensed under the MIT License — see the LICENSE file for details.