megane-viewer 0.3.2 → 0.4.0

package/README.md

@@ -11,6 +11,9 @@
   <a href="https://pypi.org/project/megane/"><img src="https://img.shields.io/pypi/v/megane" alt="PyPI" /></a>
   <a href="https://www.npmjs.com/package/megane-viewer"><img src="https://img.shields.io/npm/v/megane-viewer" alt="npm" /></a>
   <a href="https://github.com/hodakamori/megane/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License" /></a>
+  <a href="https://pypi.org/project/megane/"><img src="https://img.shields.io/pypi/pyversions/megane" alt="Python" /></a>
+  <a href="https://hodakamori.github.io/megane/"><img src="https://img.shields.io/badge/docs-online-blue" alt="Docs" /></a>
+  <a href="https://codecov.io/gh/hodakamori/megane"><img src="https://codecov.io/gh/hodakamori/megane/graph/badge.svg" alt="codecov" /></a>
 </p>
 
 <p align="center">
@@ -29,8 +32,8 @@
 ## Features
 
 - **1M+ Atoms at 60fps** — Billboard impostor rendering scales from small molecules to massive complexes in real time. InstancedMesh for small systems auto-switches to GPU-accelerated billboard impostors for large systems. Stream XTC trajectories over WebSocket.
-- **Runs Everywhere** — Jupyter widget, CLI server, React component, and VSCode extension. Rust-based PDB, GRO, XYZ, MOL, and XTC parsers shared between Python (PyO3) and browser (WASM) — parse once, run anywhere.
-- **Visual Pipeline Editor** — Build visualization workflows by wiring nodes. 8 node types (load, bond, filter, modify, labels, polyhedra, viewport) with 6 typed data channels (particle, bond, cell, label, mesh, trajectory) flowing through color-coded edges.
+- **Runs Everywhere** — Jupyter widget, CLI server, React component, and VSCode extension. Rust-based PDB, GRO, XYZ, MOL, CIF, XTC, LAMMPS, and ASE .traj parsers shared between Python (PyO3) and browser (WASM) — parse once, run anywhere.
+- **Visual Pipeline Editor** — Build visualization workflows by wiring nodes or let the AI generator build them from natural language. 11 node types with 7 typed data channels flowing through color-coded edges. Load multiple structures with layer-based rendering to compare systems side by side.
 - **Embed & Integrate** — Control the viewer from Plotly via ipywidgets events. Embed in MDX / Next.js docs. React to `frame_change`, `selection_change`, and `measurement` events. Use the framework-agnostic renderer from Vue, Svelte, or vanilla JS.
 
 ### Scale
@@ -48,17 +51,17 @@ One codebase, every environment.
 | **Jupyter** | anywidget inline viewer | `pip install megane` |
 | **Browser** | `megane serve` local server | `pip install megane` |
 | **React** | `<MeganeViewer />` component | `npm install megane-viewer` |
-| **VSCode** | Custom editor for .pdb, .gro, .xyz | Extension |
+| **VSCode** | Custom editor for .pdb, .gro, .xyz, .mol, .sdf, .cif | Extension |
 
-The secret: PDB, GRO, XYZ, MOL, and XTC parsers are written in **Rust** and compiled to both **PyO3** (Python) and **WASM** (browser). Parse once, run anywhere.
+The secret: PDB, GRO, XYZ, MOL, CIF, XTC, LAMMPS, and ASE .traj parsers are written in **Rust** and compiled to both **PyO3** (Python) and **WASM** (browser). Parse once, run anywhere.
 
 ### Visual Pipelines
 
 Wire nodes to build visualization workflows — no code required.
 
-**8 node types** across 5 categories: load data, add bonds, filter atoms by query, modify scale and opacity per-group, generate labels, render coordination polyhedra, and display in a 3D viewport.
+**11 node types** across 5 categories: load data (structure, trajectory, streaming, vector), process (filter, modify), overlay (bonds, labels, polyhedra, vectors), and display in a 3D viewport.
 
-**6 typed data channels** — particle, bond, cell, label, mesh, trajectory — flow through color-coded edges. Only matching types can connect.
+**7 typed data channels** — particle, bond, cell, label, mesh, trajectory, vector — flow through color-coded edges. Only matching types can connect.
 
 Pipelines serialize to JSON, so you can save, share, and version-control your visualization recipes.
 
@@ -93,23 +96,37 @@ npm install megane-viewer
 ### Jupyter Notebook
 
 ```python
-import megane
+from megane import Pipeline, LoadStructure, AddBonds, Viewport, MolecularViewer
+
+# Build a pipeline
+pipe = Pipeline()
+s = pipe.add_node(LoadStructure("protein.pdb"))
+bonds = pipe.add_node(AddBonds(source="distance"))
+v = pipe.add_node(Viewport())
+pipe.add_edge(s.out.particle, bonds.inp.particle)
+pipe.add_edge(s.out.particle, v.inp.particle)
+pipe.add_edge(bonds.out.bond, v.inp.bond)
+
+# Display in notebook
+viewer = MolecularViewer()
+viewer.set_pipeline(pipe)
+viewer
+```
 
-viewer = megane.MolecularViewer()
-viewer.load("protein.pdb")
-viewer  # display in cell
+### CLI (Docker)
 
-# With trajectory
-viewer.load("protein.pdb", xtc="trajectory.xtc")
-viewer.frame_index = 50
+```bash
+docker build -t megane .
+docker run --rm -p 8080:8080 megane
 ```
 
-### CLI
+Open http://localhost:8080 in your browser.
+
+To view your own files, mount them into the container:
 
 ```bash
-megane serve protein.pdb
-megane serve protein.pdb --xtc trajectory.xtc
-megane serve  # upload from browser
+docker run --rm -p 8080:8080 -v ./mydata:/data megane \
+  megane serve /data/protein.pdb --port 8080 --no-browser
 ```
 
 ### React
@@ -138,14 +155,19 @@ function App() {
 | XYZ | `.xyz` | Cartesian coordinate format |
 | MOL/SDF | `.mol`, `.sdf` | MDL Molfile (V2000) |
 | XTC | `.xtc` | GROMACS compressed trajectory |
+| CIF | `.cif` | Crystallographic Information File |
+| LAMMPS data | `.data`, `.lammps` | LAMMPS data file |
+| ASE .traj | `.traj` | ASE trajectory (ULM binary format) |
+| LAMMPS dump | `.lammpstrj` | LAMMPS dump trajectory |
 
 ## Development
 
 ### Prerequisites
 
 - Python 3.10+
-- Node.js 18+
+- Node.js 22+
 - Rust (for building the parser)
+- [wasm-pack](https://rustwasm.github.io/wasm-pack/installer/) (for building WASM bindings)
 - [uv](https://docs.astral.sh/uv/)
 
 ### Setup
@@ -154,6 +176,9 @@ function App() {
 git clone https://github.com/hodakamori/megane.git
 cd megane
 
+# Install wasm-pack (if not already installed)
+cargo install wasm-pack
+
 # Python
 uv sync --extra dev
 
@@ -162,6 +187,15 @@ npm install
 npm run build
 ```
 
+### Running `megane serve`
+
+After setup, build and install the package, then start the server:
+
+```bash
+maturin develop --release
+megane serve protein.pdb
+```
+
 ### Development Mode
 
 ```bash
@@ -187,7 +221,7 @@ make test-all              # All tests
 src/                     TypeScript frontend
   renderer/              Three.js rendering (impostor, mesh, shaders)
   protocol/              Binary protocol decoder + web workers
-  parsers/               WASM-based file parsers (PDB, GRO, XYZ, MOL, XTC)
+  parsers/               WASM-based file parsers (PDB, GRO, XYZ, MOL, CIF, XTC, LAMMPS, .traj)
   logic/                 Bond / label / vector source logic
   components/            React UI components
   hooks/                 Custom React hooks
@@ -198,6 +232,7 @@ crates/                  Rust workspace
   megane-wasm/           WASM bindings (wasm-bindgen)
 python/megane/           Python backend
   parsers/               PDB / XTC parsers
+  pipeline.py            Pipeline builder (NetworkX-style DAG)
   protocol.py            Binary protocol encoder
   server.py              FastAPI WebSocket server
   widget.py              anywidget Jupyter widget