[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 currently limited to 1GB to prevent memory issues. Larger files are streamed in chunks which is only supported locally, not via remote SSH.

⚙️ 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

Category	Description	Example Settings
General	Global appearance and behavior	color_scheme, background_color
Structure	3D structure visualization	atom_radius, bond_thickness, show_cell, lighting, show_image_atoms
Trajectory	Animation and playback controls	fps, auto_play, display_mode, show_controls
Plots	Scatter plots and histograms	scatter_point_size, plot_grid_lines, auto_fit_range
Performance	Memory and processing options	chunk_size, use_indexing, sphere_segments

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"