matterviz 0.3.4 → 0.3.6

package/readme.md

@@ -1,146 +1,219 @@
-<h1 align="center">
-  <sub><img src="static/favicon.svg" alt="Logo" width="40px"></sub> MatterViz
-</h1>
+# [MatterViz VSCode Extension]
 
-<h4 align="center">
+[matterviz vscode extension]: https://marketplace.visualstudio.com/items?itemName=janosh.matterviz
 
-[![Tests](https://github.com/janosh/matterviz/actions/workflows/test.yml/badge.svg)](https://github.com/janosh/matterviz/actions/workflows/test.yml)
-[![GH Pages](https://github.com/janosh/matterviz/actions/workflows/gh-pages.yml/badge.svg)](https://github.com/janosh/matterviz/actions/workflows/gh-pages.yml)
-[![VSCode Extension](https://img.shields.io/badge/Install%20VSCode-Extension-blue?logo=typescript&logoColor=white)](https://marketplace.visualstudio.com/items?itemName=janosh.matterviz)
-[![Docs](https://img.shields.io/badge/Read-the%20docs-blue?logo=googledocs&logoColor=white)](https://matterviz.janosh.dev)
-[![Open in StackBlitz](https://img.shields.io/badge/Open%20in-StackBlitz-darkblue?logo=stackblitz&logoColor=white)](https://stackblitz.com/github/janosh/matterviz)
-[![Zenodo DOI](https://zenodo.org/badge/498793280.svg)](https://doi.org/10.5281/zenodo.17094509)
+**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.
 
-</h4>
+## ✨ Features
 
-`matterviz` is a toolkit for building interactive web UIs for materials science: 3D crystal structures, molecules, MD/relaxation trajectories, periodic tables, phase diagrams, convex hulls, spectral data (bands, DOS, XRD), heatmaps, and scatter plots.
+### 🔬 **Structure Visualization**
 
-## 🔌 &thinsp; [MatterViz VSCode Extension]
+- **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
 
-Visualize crystal structures, molecules, and molecular dynamics trajectories [directly in VSCode][MatterViz VSCode Extension]. Features include:
+### 🎬 **Trajectory Analysis**
 
-- Native support for common file formats (CIF, POSCAR, XYZ, TRAJ, HDF5, etc.)
-- Context menu (right click > "Render with MatterViz") and keyboard shortcuts (<kbd>ctrl</kbd>+<kbd>shift</kbd>+<kbd>v</kbd> on Windows, <kbd>cmd</kbd>+<kbd>shift</kbd>+<kbd>v</kbd> on Mac) for quick access
-- Custom viewer for MD trajectories/geometry optimizations
-- **Extensive customization options** via VSCode settings - see [Configuration Guide](extensions/vscode/readme.md#️-configuration--customization) for examples
+- **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
 
-[matterviz vscode extension]: https://marketplace.visualstudio.com/items?itemName=janosh.matterviz
+### 🎨 **Customization**
 
-## 🗺️ &thinsp; Roadmap
+- **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
 
-- **✅ MatterViz Web**: [matterviz.janosh.dev](https://matterviz.janosh.dev)
-- **✅ MatterViz VSCode/Cursor**: [marketplace.visualstudio.com/items?itemName=janosh.matterviz](https://marketplace.visualstudio.com/items?itemName=janosh.matterviz)
-- **✅ pymatviz**: [Jupyter](https://jupyter.org)/[Marimo](https://marimo.io) widgets for Python notebooks. See [`pymatviz` readme](https://github.com/janosh/pymatviz/blob/main/readme.md#interactive-widgets).
+## 🚀 Installation
 
-![Landing page showing 3D structure viewers](https://github.com/janosh/matterviz/releases/download/v0.2.2/2026-01-23-landing-page.webp)
+Search for "MatterViz" in the VS Code Extensions marketplace.
 
-## ⚛️ &thinsp; 3D Structure Viewer
+## 📋 Usage
 
-Interactively visualize crystal structures and molecules. Supports drag-and-drop file loading for CIF, POSCAR, XYZ/EXTXYZ, pymatgen JSON, OPTIMADE JSON, and compressed formats.
+### Quick Start
 
-![3D Structure Viewer](https://github.com/janosh/matterviz/releases/download/v0.2.2/2026-01-23-structure-viewer.webp)
+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)
 
-## 📊 &thinsp; Periodic Table Heatmap
+### Supported File Formats
 
-Visualize elemental properties across the periodic table. The inset scatter plot shows how properties vary with atomic number - here demonstrating the periodicity of first ionization energy.
+#### Structure Files
 
-![Periodic table heatmap](https://github.com/janosh/matterviz/releases/download/v0.2.2/2026-01-23-heatmap.webp)
+- **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
 
-## 🔬 &thinsp; Element Details Pages
+#### Trajectory Files
 
-Rich element pages with physical properties, electron configurations, Bohr atom visualizations, and element photos.
+- **TRAJ** - ASE trajectory files
+- **ExtXYZ** - Extended XYZ trajectories
+- **HDF5/H5** - `flame` HDF5 trajectory formats
+- **JSON** - `pymatgen` JSON trajectory formats
 
-![Element details page for gold](https://github.com/janosh/matterviz/releases/download/v0.2.2/2026-01-23-details-page.webp)
+#### Fermi Surface Files
 
-## 🔨 &thinsp; Installation
+- **BXSF** - XCrySDen band structure format
+- **FRMSF** - FermiSurfer format
 
-```sh
-npm add -D matterviz
-```
+#### Volumetric Data Files
 
-## 📙 &thinsp; Usage
+- **CUBE** - Gaussian cube files
+- **CHGCAR/ELFCAR/LOCPOT/AECCAR/PARCHG** - VASP volumetric output
 
-### Periodic Table
+#### Compressed Files
 
-```svelte
-<script>
-  import { PeriodicTable } from 'matterviz'
+All formats above are also supported with `.gz` compression.
 
-  const heatmap_values = { H: 10, He: 4, Li: 8, Fe: 3, O: 24 }
-</script>
+#### JSON Files with Multiple Data Types
 
-<PeriodicTable {heatmap_values} />
-```
+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.
 
-### Structure
+### Custom Editor Integration
 
-```svelte
-<script>
-  import { Structure } from 'matterviz'
-  const data_url = '/structures/TiO2.cif'
-  // supports .cif, .poscar, .xyz/.extxyz, pymatgen JSON, OPTIMADE JSON, .gz
-</script>
+MatterViz automatically registers as a custom editor for trajectory files such as `.traj`, `.h5`, `.hdf5`, `.xyz.gz`, etc.
 
-<Structure {data_url} style="width: 500px; aspect-ratio: 1" />
-```
+### Remote SSH Support
+
+MatterViz supports [VSCode](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh)/[Cursor](https://open-vsx.org/extension/jajera/vsx-remote-ssh) 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
 
-### Composition
+MatterViz provides extensive customization options through VSCode settings. Access these via:
 
-```svelte
-<script>
-  import { Composition } from 'matterviz'
-  // modes can be 'pie' (default) | 'bubble' | 'bar'
-</script>
+- **Settings UI**: `File → Preferences → Settings` → Search for "MatterViz"
+- **JSON Settings**: `Ctrl+Shift+P` → "Preferences: Open Settings (JSON)"
 
-<Composition composition="LiFePO4" mode="pie" />
+### Common Configuration Scenarios
+
+#### 🎨 **Visual Appearance**
+
+```json
+{
+  "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
+#### 🎬 **Trajectory Playback**
+
+```json
+{
+  "matterviz.trajectory.auto_play": true,
+  "matterviz.trajectory.fps": 10,
+  "matterviz.trajectory.display_mode": "structure+scatter",
+  "matterviz.trajectory.show_controls": true
+}
+```
+
+#### 📊 **Plot Customization**
+
+```json
+{
+  "matterviz.scatter.point_size": 5,
+  "matterviz.scatter.line_width": 3,
+  "matterviz.plot.grid_lines": true,
+  "matterviz.scatter.show_legend": true
+}
+```
 
-```svelte
-<script>
-  import { Trajectory } from 'matterviz'
-  // supports .xyz/.extxyz, .traj, .hdf5, .npz, .pkl, .dat, .gz, .zip, .bz2, .xz
-</script>
+#### 🔧 **Performance Optimization**
 
-<Trajectory data_url="/traj/ase-md.xyz" auto_play fps={10} style="max-height: 700px" />
+```json
+{
+  "matterviz.trajectory.chunk_size": 500,
+  "matterviz.trajectory.bin_file_threshold": 10485760,
+  "matterviz.structure.sphere_segments": 16
+}
 ```
 
-## 🧪 &thinsp; Coverage
+### Setting Categories
 
-| Statements                                                                                 | Branches                                                                          | Lines                                                                            |
-| ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
-| ![Statements](https://img.shields.io/badge/statements-99.84%25-brightgreen.svg?style=flat) | ![Branches](https://img.shields.io/badge/branches-82.92%25-yellow.svg?style=flat) | ![Lines](https://img.shields.io/badge/lines-99.84%25-brightgreen.svg?style=flat) |
+| 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`                              |
 
-## 🙏 &thinsp; Acknowledgements
+### Pro Tips
 
-- Element properties in `src/lib/element/data.ts` were combined from [`Bowserinator/Periodic-Table-JSON`](https://github.com/Bowserinator/Periodic-Table-JSON/blob/master/PeriodicTableJSON.json) under Creative Commons license and [`robertwb/Periodic Table of Elements.csv`](https://gist.github.com/robertwb/22aa4dbfb6bcecd94f2176caa912b952) (unlicensed).
-- Thanks to [Images of Elements](https://images-of-elements.com) for providing photos of elemental crystals and glowing excited gases.
-- Thanks to [@kadinzhang](https://github.com/kadinzhang) and their [Periodicity project](https://ptable.netlify.app) [[code](https://github.com/kadinzhang/Periodicity)] for the idea to display animated Bohr model atoms and inset a scatter plot into the periodic table to visualize the periodic nature of elemental properties.
-- Big thanks to all sources of element images. See [`fetch-elem-images.ts`](https://github.com/janosh/matterviz/blob/-/src/scripts/fetch-elem-images.ts) and [`static/elements`](https://github.com/janosh/matterviz/tree/main/static/elements).
-- Thanks to [@ixxie](https://github.com/ixxie) ([shenhav.fyi](https://shenhav.fyi)) for great suggestions.
+- **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
 
-This project would not have been possible as a one-person side project without many fine open-source projects. 🙏 To name just a few:
+## ⌨️ Keyboard Shortcuts
 
-|           3D graphics           |               2D graphics                |                     Docs                     |               Bundler               |               Testing                |
-| :-----------------------------: | :--------------------------------------: | :------------------------------------------: | :---------------------------------: | :----------------------------------: |
-| [three.js](https://threejs.org) |          [d3](https://d3js.org)          |         [mdsvex](https://mdsvex.com)         |     [vite](https://vitejs.dev)      | [playwright](https://playwright.dev) |
-| [threlte](https://threlte.xyz)  | [sharp](https://sharp.pixelplumbing.com) | [rehype](https://github.com/rehypejs/rehype) | [sveltekit](https://kit.svelte.dev) |     [vitest](https://vitest.dev)     |
+- `Ctrl+Shift+V` / `Cmd+Shift+V` → Render structure/trajectory with MatterViz
 
-## How to cite `matterviz`
+## 🐛 Bug Reporting
 
-Use [`citation.cff`](citation.cff) or cite the [Zenodo record](https://zenodo.org/badge/latestdoi/498793280) using the following BibTeX entry:
+If you encounter any issues with MatterViz, you can use the built-in bug reporting command to collect debug information:
 
-```bib
-@software{riebesell_matterviz_2022,
-  title = {matterviz: visualization toolkit for materials informatics},
-  author = {Riebesell, Janosh and Evans, Matthew},
-  date = {2026-01-23},
-  year = {2026},
-  doi = {10.5281/zenodo.17094509},
-  url = {https://github.com/janosh/matterviz},
-  note = {10.5281/zenodo.17094509 - https://github.com/janosh/matterviz},
-  urldate = {2026-01-23}, % optional, replace with your date of access
-  version = {0.3.1}, % replace with the version you use
-}
+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](https://github.com/janosh/matterviz/issues/new)
+
+## 📄 License
+
+This extension is [MIT-Licensed](./license).
+
+## 🔗 Related Projects
+
+- **✅ MatterViz Web**: [matterviz.janosh.dev](https://matterviz.janosh.dev)
+- **✅ pymatviz**: [Jupyter](https://jupyter.org)/[Marimo](https://marimo.io) extension for Python notebooks. Read about widgets in [`pymatviz` readme](https://github.com/janosh/pymatviz/blob/main/readme.md#interactive-widgets) for details.
+
+## 🤝 Contributing
+
+We welcome contributions! Please see our [Contributing Guide](../../contributing.md) for details.
+
+## 🛠️ Development
+
+```bash
+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](https://open-vsx.org/extension/janosh/matterviz) and [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=janosh.matterviz):
+
+```bash
+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"
 ```

package/scripts/sync-config.ts

@@ -0,0 +1,101 @@
+import { readFileSync, writeFileSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { SETTINGS_CONFIG, type SettingType } from '$lib/settings'
+
+// VSCode configuration generator that derives from your central settings schema
+function sync_package_config() {
+  const script_dir = dirname(fileURLToPath(import.meta.url))
+  const package_path = resolve(script_dir, `..`, `package.json`)
+  const package_content = JSON.parse(readFileSync(package_path, `utf-8`))
+
+  // Auto-generate VSCode settings from SETTINGS_CONFIG
+  const vscode_config: Record<string, unknown> = {}
+
+  // Helper to process settings schema
+  function process_setting_schema(schema: SettingType, key_path: string) {
+    if (schema && typeof schema === `object` && `value` in schema) {
+      // Skip settings that don't apply to editor context
+      if (schema.context && ![`editor`, `all`].includes(schema.context)) return
+
+      // This is a SettingSchema - cast to any to access dynamic properties
+      const config: Record<string, unknown> = {
+        type:
+          typeof schema.value === `boolean`
+            ? `boolean`
+            : typeof schema.value === `number`
+              ? `number`
+              : Array.isArray(schema.value)
+                ? `array`
+                : `string`,
+        default: schema.value,
+        description: schema.description,
+      }
+
+      // Add constraints from schema
+      if (schema.minimum !== undefined) config.minimum = schema.minimum
+      if (schema.maximum !== undefined) config.maximum = schema.maximum
+      if (schema.minItems !== undefined) config.minItems = schema.minItems
+      if (schema.maxItems !== undefined) config.maxItems = schema.maxItems
+      if (schema.enum) config.enum = Object.keys(schema.enum)
+
+      // Add array item type for arrays
+      if (Array.isArray(schema.value)) {
+        const first_item = schema.value[0]
+        config.items = {
+          type:
+            typeof first_item === `boolean`
+              ? `boolean`
+              : typeof first_item === `string`
+                ? `string`
+                : `number`,
+        }
+      }
+
+      vscode_config[key_path] = config
+    } else if (schema && typeof schema === `object`) {
+      // This is a nested object, recurse
+      Object.entries(schema).forEach(([key, value]) => {
+        const nested_key = key_path ? `${key_path}.${key}` : key
+        process_setting_schema(value as SettingType, nested_key)
+      })
+    }
+  }
+
+  // Process all settings from SETTINGS_CONFIG
+  Object.entries(SETTINGS_CONFIG).forEach(([key, value]) => {
+    const base_key = `matterviz.${key}`
+    process_setting_schema(value, base_key)
+  })
+
+  // Preserve existing non-schema settings (like auto_render, theme, etc.)
+  const existing_props = package_content.contributes?.configuration?.properties || {}
+  const preserved_props: Record<string, unknown> = {}
+
+  for (const [key, value] of Object.entries(existing_props)) {
+    // Preserve settings that aren't auto-generated from SETTINGS_CONFIG
+    // Exclude both old .defaults.* settings and new schema-generated settings
+    const is_schema_setting = Object.keys(SETTINGS_CONFIG).some(
+      (config_key) =>
+        key.startsWith(`matterviz.${config_key}`) ||
+        key.startsWith(`matterviz.defaults.${config_key}`),
+    )
+    if (!is_schema_setting) preserved_props[key] = value
+  }
+
+  // Update package.json with generated + preserved settings
+  package_content.contributes ??= {}
+  package_content.contributes.configuration ??= { title: `MatterViz`, properties: {} }
+  package_content.contributes.configuration.properties = {
+    ...preserved_props,
+    ...vscode_config,
+  }
+
+  writeFileSync(package_path, JSON.stringify(package_content, null, 2) + `\n`, `utf-8`)
+  console.info(
+    `✅ Synced ${Object.keys(vscode_config).length} settings from SETTINGS_CONFIG to package.json`,
+  )
+}
+
+// Run the sync
+sync_package_config()

package/src/declarations.d.ts

@@ -0,0 +1,2 @@
+declare module '$lib/app.css' {}
+declare module '$lib/theme/themes.mjs' {}