Skip to content

Commit 5e6b874

Browse files
janoshjanosh
committed
VSCode extension for rendering structures and trajectories with MatterViz directly in editor tabs (#82)
* VSCode extension for rendering structures and trajectories with MatterViz directly in editor tabs * add extension icon.png and readme.md outlining features, installation, usage - Replace logo.svg with favicon.svg in the main readme - Add .vscodeignore file to exclude unnecessary files from the VS Code extension - add MIT license for extension - extension package.json include repository, bugs, license, keywords, and categories for better discoverability * StructureControls.svelte add clipboard copy feedback - address coderabbit comments - remove matterviz-0.1.0-beta.1.vsix accidentally committed and gitignore * fix npx playwright test tests/playwright/structure.test.ts * mention the VSCode extension in the main README, lower min supported vscode version from 1.101 to 1.96 - unit tests for VSCode extension functionalities covering file handling and message processing
1 parent e6b5b8b commit 5e6b874

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

49 files changed

+2579
-820
lines changed

‎.gitignore

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,5 +19,5 @@ src/types
1919
# coverage
2020
test-results
2121

22-
# TODO remove once fully implemented
23-
extensions/vscode/
22+
# vscode extension
23+
*.vsix

‎.pre-commit-config.yaml

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -24,13 +24,15 @@ repos:
2424
- id: deno-fmt
2525
name: Deno format
2626
entry: deno fmt
27-
files: \.(ts|js|svelte)$
27+
types_or: [file]
2828
language: system
29+
args: [--config, deno.jsonc]
2930
- id: deno-lint
3031
name: Deno lint
3132
entry: deno lint
32-
files: \.(ts|js|svelte)$
33+
types_or: [file]
3334
language: system
35+
args: [--config, deno.jsonc, --permit-no-files, --fix]
3436

3537
- repo: https://github.com/codespell-project/codespell
3638
rev: v2.4.1

‎changelog.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Changelog
22

3-
#### [v0.1.0](https://github.com/janosh/matterviz/compare/v0.1.0...v0.1.0)
3+
## [v0.1.0](https://github.com/janosh/matterviz/compare/v0.1.0...v0.1.0)
44

55
> 19 June 2025
66

‎deno.jsonc

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -8,8 +8,6 @@
88
"vitest": "deno run -A --node-modules-dir npm:vitest run tests/vitest/**/*.ts",
99
"e2e": "npx playwright test",
1010
"test:install": "npx playwright install chromium",
11-
"lint": "deno lint",
12-
"fmt": "deno fmt",
1311
"package": "svelte-package",
1412
"changelog": "deno run -A https://github.com/janosh/workflows/raw/refs/heads/main/scripts/make-release-notes.ts"
1513
},
@@ -54,9 +52,9 @@
5452
},
5553
"fmt": {
5654
"exclude": [
57-
"src/site/structures/*",
58-
"src/site/molecules/*",
59-
"src/site/trajectories/*"
55+
"src/site/structures/*.json",
56+
"src/site/molecules/*.json",
57+
"src/site/trajectories/*.json"
6058
],
6159
"indentWidth": 2,
6260
"lineWidth": 90,

‎extensions/vscode/.vscodeignore

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# Source files
2+
src/**
3+
webview/**
4+
*.ts
5+
6+
# Build files
7+
tsconfig.json
8+
.vscode/**

‎extensions/vscode/icon.png

45 KB
Loading

‎extensions/vscode/license

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2025 Janosh Riebesell
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
The software is provided "as is", without warranty of any kind, express or
16+
implied, including but not limited to the warranties of merchantability,
17+
fitness for a particular purpose and noninfringement. In no event shall the
18+
authors or copyright holders be liable for any claim, damages or other
19+
liability, whether in an action of contract, tort or otherwise, arising from,
20+
out of or in connection with the software or the use or other dealings in the
21+
software.

‎extensions/vscode/package.json

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
{
2+
"name": "matterviz",
3+
"displayName": "MatterViz",
4+
"description": "Visualize crystal structures and MD trajectories in VSCode",
5+
"version": "0.1.0",
6+
"publisher": "janosh",
7+
"type": "module",
8+
"icon": "icon.png",
9+
"repository": "https://github.com/janosh/matterviz",
10+
"bugs": "https://github.com/janosh/matterviz/issues",
11+
"license": "MIT",
12+
"keywords": [
13+
"chemistry",
14+
"materials",
15+
"visualization",
16+
"structure",
17+
"trajectory",
18+
"3d",
19+
"molecular dynamics",
20+
"crystallography"
21+
],
22+
"categories": [
23+
"Data Science",
24+
"Machine Learning",
25+
"Visualization",
26+
"Notebooks",
27+
"Education"
28+
],
29+
"engines": { "vscode": "^1.96.0" },
30+
"main": "./dist/extension.cjs",
31+
"contributes": {
32+
"commands": [{
33+
"command": "matterviz.renderStructure",
34+
"title": "Render with MatterViz"
35+
}],
36+
"keybindings": [{
37+
"command": "matterviz.renderStructure",
38+
"key": "ctrl+shift+v",
39+
"mac": "cmd+shift+v",
40+
"when": "resourceExtname =~ /\\.(cif|poscar|vasp|xyz|extxyz|json|yaml|yml|traj|gz|h5|hdf5)$/"
41+
}],
42+
"menus": {
43+
"explorer/context": [{
44+
"command": "matterviz.renderStructure",
45+
"when": "resourceExtname =~ /\\.(cif|poscar|vasp|xyz|extxyz|json|yaml|yml|traj|gz|h5|hdf5)$/"
46+
}]
47+
},
48+
"customEditors": [{
49+
"viewType": "matterviz.viewer",
50+
"displayName": "MatterViz Viewer",
51+
"selector": [{ "filenamePattern": "*.{traj,gz,h5,hdf5}" }],
52+
"priority": "option"
53+
}]
54+
},
55+
"scripts": {
56+
"build": "rm -rf dist && tsc && mv dist/extension.{,c}js && vite build",
57+
"dev": "tsc --watch & vite build --watch & mv dist/extension.{,c}js",
58+
"vitest": "vitest"
59+
},
60+
"devDependencies": {
61+
"@sveltejs/vite-plugin-svelte": "^5.1.0",
62+
"@types/vscode": "^1.96.0",
63+
"svelte": "^5.34.8",
64+
"typescript": "^5.8.3",
65+
"vite": "^7.0.0",
66+
"vitest": "^3.2.4"
67+
}
68+
}

‎extensions/vscode/readme.md

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
# MatterViz VS Code Extension
2+
3+
**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.
4+
5+
## ✨ Features
6+
7+
### 🔬 **Structure Visualization**
8+
9+
- **Crystal Structures**: Visualize CIF, POSCAR, VASP, and other crystallographic formats
10+
- **Molecular Systems**: Display XYZ, JSON, and YAML molecular structures
11+
- **Interactive 3D Viewer**: Rotate, zoom, and explore structures with intuitive controls
12+
- **Atomic Properties**: View element information, bonding, and structural details
13+
14+
### 🎬 **Trajectory Analysis**
15+
16+
- **MD Trajectories**: Animate and analyze molecular dynamics simulations
17+
- **Multi-format Support**: Handle TRAJ, ExtXYZ, HDF5, and compressed formats
18+
- **Playback Controls**: Navigate through trajectory frames with timeline controls
19+
- **Frame Analysis**: Extract and analyze individual frames from trajectories
20+
21+
### 🎨 **Customization**
22+
23+
- **Color Schemes**: Multiple built-in color schemes (Jmol, VESTA, Alloy, Pastel, etc.)
24+
- **Visualization Modes**: Ball-and-stick, space-filling, wireframe representations
25+
- **Export Options**: Save visualizations to PNG or export structure data to ASE XYZ and pymatgen JSON
26+
27+
## 🚀 Installation
28+
29+
Search for "MatterViz" in the VS Code Extensions marketplace.
30+
31+
## 📋 Usage
32+
33+
### Quick Start
34+
35+
1. **Open a structure file** in VS Code (`.cif`, `.poscar`, `.xyz`, `.json`, etc.)
36+
2. **Right-click** in the explorer or editor
37+
3. **Select "Render with MatterViz"** from the context menu
38+
4. **Or use the keyboard shortcut**: `Ctrl+Shift+V` (Windows/Linux) / `Cmd+Shift+V` (Mac)
39+
40+
### Supported File Formats
41+
42+
#### Structure Files
43+
44+
- **CIF** - Crystallographic Information Files
45+
- **POSCAR/CONTCAR** - VASP structure files
46+
- **XYZ/ExtXYZ** - Standard molecular coordinate formats
47+
- **JSON** - JSON-formatted structure data
48+
- **YAML/YML** - YAML structure definitions
49+
50+
#### Trajectory Files
51+
52+
- **TRAJ** - ASE trajectory files
53+
- **ExtXYZ** - Extended XYZ trajectories
54+
- **HDF5/H5** - `torch-sim` HDF5 trajectory formats
55+
- **JSON** - `pymatgen` JSON trajectory formats
56+
- **Compressed files** - `.gz` compressed versions of above
57+
58+
### Custom Editor Integration
59+
60+
MatterViz automatically registers as a custom editor for trajectory files (`.traj`, `.h5`, `.hdf5`, `.gz`), providing seamless integration with VS Code's editor system.
61+
62+
## ⌨️ Keyboard Shortcuts
63+
64+
| Shortcut | Action |
65+
| ------------------------------ | ------------------------------- |
66+
| `Ctrl+Shift+V` / `Cmd+Shift+V` | Render structure with MatterViz |
67+
68+
## 🛠️ Development
69+
70+
This extension is built with:
71+
72+
- **TypeScript** - Main extension logic
73+
- **Svelte 5** - Modern reactive webview components
74+
- **Vite** - Fast build tooling
75+
- **Three.js** - 3D visualization engine
76+
77+
### Building from Source
78+
79+
```bash
80+
cd extensions/vscode
81+
pnpm install
82+
pnpm build
83+
vsce package
84+
```
85+
86+
## 🤝 Contributing
87+
88+
We welcome contributions! Please see our [Contributing Guide](../../contributing.md) for details.
89+
90+
## 📄 License
91+
92+
This extension is [MIT-Licensed](./license).
93+
94+
## 🐛 Issues & Support
95+
96+
- **Bug Reports**: [GitHub Issues](https://github.com/janosh/matterviz/issues)
97+
- **Feature Requests**: [GitHub Discussions](https://github.com/janosh/matterviz/discussions)
98+
- **Documentation**: [MatterViz Docs](https://matterviz.janosh.dev)
99+
100+
## 🔗 Related Projects
101+
102+
- **MatterViz Web**: Full-featured web application at [matterviz.janosh.dev](https://matterviz.janosh.dev)
103+
- (TODO) **MatterViz CLI**: Command-line interface for batch processing
104+
- (TODO) **MatterViz iPython**: [Jupyter](https://jupyter.org)/[Marimo](https://marimo.io) extension for interactive Python-based visualization

0 commit comments

Comments
 (0)