MatterViz VSCode Extension

MatterViz offers a VSCode extension for rendering crystal structures and molecular dynamics (MD) or geometry optimization trajectories directly in the editor to speed up typical materials science/computational chemistry workflows.

✨ Features

🔬 Structure Visualization

• Crystal Structures: Visualize CIF, POSCAR, VASP, and other crystallographic formats
• Molecular Systems: Display XYZ, JSON, and YAML molecular structures
• Interactive 3D Viewer: Rotate, zoom, and explore structures with intuitive controls
• Atomic Properties: View element information, bonding, and structural details

🎬 Trajectory Analysis

• MD Trajectories: Animate and analyze molecular dynamics simulations
• Multi-format Support: Handle TRAJ, ExtXYZ, HDF5, and compressed formats
• Playback Controls: Navigate through trajectory frames with timeline controls
• Frame Analysis: Extract and analyze individual frames from trajectories

🎨 Customization

• Color Schemes: Multiple built-in color schemes (Jmol, VESTA, Alloy, Pastel, etc.)
• Visualization Modes: Ball-and-stick, space-filling, wireframe representations
• Export Options: Save visualizations to PNG or export structure data to ASE XYZ and pymatgen JSON

🚀 Installation

Search for "MatterViz" in the VS Code Extensions marketplace.

📋 Usage

Quick Start

1. Open a structure file in VS Code (.cif, .poscar, .xyz, .json, etc.)
2. Right-click in the explorer or editor
3. Select "MatterViz: Open" from the context menu
4. Or use the keyboard shortcut: Ctrl+Shift+V (Windows/Linux) / Cmd+Shift+V (Mac)

Supported File Formats

Structure Files

• CIF - Crystallographic Information Files
• POSCAR/CONTCAR - VASP structure files
• XYZ/ExtXYZ - Standard molecular coordinate formats
• JSON - JSON-formatted structure data (pymatgen, OPTIMADE)
• YAML/YML - YAML structure definitions

Trajectory Files

• TRAJ - ASE trajectory files
• ExtXYZ - Extended XYZ trajectories
• HDF5/H5 - flame HDF5 trajectory formats
• JSON - pymatgen JSON trajectory formats

Fermi Surface Files

• BXSF - XCrySDen band structure format
• FRMSF - FermiSurfer format

Volumetric Data Files

• CUBE - Gaussian cube files
• CHGCAR/ELFCAR/LOCPOT/AECCAR/PARCHG - VASP volumetric output

Compressed Files

All formats above are also supported with .gz compression.

JSON Files with Multiple Data Types

When a .json file contains recognized data (structures, band structures, DOS, convex hulls, phase diagrams, Fermi surfaces, Brillouin zones, XRD patterns, or tabular data), MatterViz opens a JSON browser with a navigable tree sidebar and visualization canvas. Renderable nodes are marked with colored badges -- click to render, or drag to a canvas edge to create a split view with multiple visualizations side by side. When both band structure and DOS data are found together, they're rendered as a combined Bands+DOS plot.

Custom Editor Integration

MatterViz automatically registers as a custom editor for trajectory files such as .traj, .h5, .hdf5, .xyz.gz, etc.

Remote SSH Support

MatterViz supports VSCode/Cursor remote SSH connections. Connect to your server via Remote SSH extension, and MatterViz should work just like it does locally.

• ✅ Remote file access: Visualize structures and trajectories on remote servers (HPC clusters, cloud instances, etc.)
• ✅ No manual file transfer: Files are read directly from the remote filesystem
• ✅ File watching: Changes to remote files are automatically detected and reloaded
• ⚠️ File size limit: Files are read into extension memory in one operation on both local and Remote SSH workspaces. Non-text files larger than 1 GiB are rejected to prevent memory issues. XYZ/EXTXYZ text trajectories are limited by Node.js text decoding and are currently rejected above about 512 MiB. Other text formats (e.g. JSON, POSCAR, CIF) above about 400 MiB are rejected because large-file loading currently supports trajectories only.

⚙️ Configuration & Customization

MatterViz provides extensive customization options through VSCode settings. Access these via:

• Settings UI: File → Preferences → Settings → Search for "MatterViz"
• JSON Settings: Ctrl+Shift+P → "Preferences: Open Settings (JSON)"

Common Configuration Scenarios

🎨 Visual Appearance

{
  "matterviz.color_scheme": "Jmol",
  "matterviz.background_color": "#ffffff",
  "matterviz.background_opacity": 0.8,
  "matterviz.structure.show_image_atoms": true,
  "matterviz.structure.atom_radius": 1.2,
  "matterviz.structure.bond_thickness": 0.8
}

🎬 Trajectory Playback

{
  "matterviz.trajectory.auto_play": true,
  "matterviz.trajectory.fps": 10,
  "matterviz.trajectory.display_mode": "structure+scatter",
  "matterviz.trajectory.show_controls": true
}

📊 Plot Customization

{
  "matterviz.scatter.point.size": 5,
  "matterviz.scatter.line.width": 3,
  "matterviz.plot.grid_lines": true,
  "matterviz.scatter.show_legend": true
}

🔧 Performance Optimization

{
  "matterviz.trajectory.chunk_size": 500,
  "matterviz.trajectory.bin_file_threshold": 10485760,
  "matterviz.structure.sphere_segments": 16
}

Setting Categories

Pro Tips

• Reset to defaults: Remove custom settings from your JSON config
• Project-specific settings: Use workspace settings (.vscode/settings.json) for per-project customization
• Theme integration: MatterViz automatically adapts to your VSCode color theme
• Performance: Reduce sphere_segments for better performance with large structures

⌨️ Keyboard Shortcuts

• Ctrl+Shift+V / Cmd+Shift+V → Render structure/trajectory with MatterViz

🐛 Bug Reporting

If you encounter any issues with MatterViz, you can use the built-in bug reporting command to collect debug information:

1. Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
2. Run "Report MatterViz Bug"
3. The command will open a new document with detailed debug information including:
   • Your OS and version
   • VSCode/Cursor version
   • MatterViz version
   • Whether you're in a remote session
   • Files currently being rendered
   • System resources and memory usage
   • Extension configuration
4. Copy the information and include it when creating a GitHub issue

📄 License

This extension is MIT-Licensed.

🔗 Related Projects

• ✅ MatterViz Web: matterviz.janosh.dev
• ✅ pymatviz: Jupyter/Marimo extension for Python notebooks. Read about widgets in pymatviz readme for details.

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

🛠️ Development

git clone https://github.com/janosh/matterviz
cd matterviz/extensions/vscode
npm install
npm run build
vsce package  # creates .vsix for local install

Publishing

Publish to both Open VSX and VS Code Marketplace:

cd extensions/vscode
npm run package

# Open VSX (token at ~/.config/matterviz/ovsx-token)
npx ovsx publish matterviz-*.vsix -p $(cat ~/.config/matterviz/ovsx-token)

# VS Code Marketplace (requires `brew install azure-cli` for auth)
az login --allow-no-subscriptions --scope https://app.vssps.visualstudio.com/.default
TOKEN=$(python3 -c "import json,os;c=json.load(open(os.path.expanduser('~/.azure/msal_token_cache.json')));print(next(t['secret'] for t in c['AccessToken'].values() if 'vssps.visualstudio.com' in t.get('target','')))")
vsce publish --no-dependencies -p "$TOKEN"