megane

Spectacles for atomistic data.

1M+ atoms at 60fps. Visual pipelines. Jupyter, browser, React, VSCode.

Docs · Getting Started · PyPI · npm

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, 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

megane renders over 1 million atoms at 60fps in the browser. Small systems get high-quality InstancedMesh spheres and cylinders; large systems automatically switch to GPU-accelerated billboard impostors. No desktop app, no plugin — just a browser tab.

Trajectory streaming works over WebSocket via a binary protocol. Load an XTC file and scrub through thousands of frames in real time, without reading everything into memory.

Anywhere

One codebase, every environment.

For a per-platform breakdown of supported formats and UI features (including known gaps), see Platform Support.

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.

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.

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.

Integrate

megane is not a walled garden. It fits into your existing workflow.

Plotly — Click a point on a Plotly FigureWidget to jump to a trajectory frame. Use megane's on_event("frame_change") callback to update Plotly markers in sync.

MDX / Next.js — Drop <MeganeViewer /> or <Viewport /> into your .mdx documentation. WASM parsing works out of the box with a one-line webpack config.

ipywidgets — React to frame_change, selection_change, and measurement events. Compose megane with any widget in the Jupyter ecosystem.

Framework-agnostic — MoleculeRenderer is a plain Three.js class. Mount it in Vue, Svelte, or a vanilla <div>.

Installation

Python

pip install megane

npm (for React embedding)

npm install megane-viewer

Quick Start

Jupyter Notebook

import megane

viewer = megane.view("protein.pdb")
viewer  # displays in notebook

With a trajectory:

viewer = megane.view_traj("protein.pdb", xtc="trajectory.xtc")
viewer.frame_index = 50  # jump to frame 50

For advanced usage (filtering, multi-layer rendering, custom pipelines), see the Pipeline API.

CLI (Docker)

docker build -t megane .
docker run --rm -p 8080:8080 megane

Open http://localhost:8080 in your browser.

To view your own files, mount them into the container:

docker run --rm -p 8080:8080 -v ./mydata:/data megane \
  megane serve /data/protein.pdb --port 8080 --no-browser

React

import { MeganeViewer, parseStructureFile } from "megane-viewer/lib";

function App() {
  const [snapshot, setSnapshot] = useState(null);

  const handleUpload = async (file: File) => {
    const result = await parseStructureFile(file);
    setSnapshot(result.snapshot);
  };

  return <MeganeViewer snapshot={snapshot} mode="local" /* ... */ />;
}

Supported File Formats

Structure formats (LoadStructure node)

Trajectory formats (LoadTrajectory node)

Development

Prerequisites

• Python 3.10+
• Node.js 22+
• Rust (for building the parser)
• wasm-pack (for building WASM bindings)
• uv

Setup

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

# Node.js
npm install
npm run build

Running megane serve

After setup, build and install the package, then start the server:

maturin develop --release
megane serve protein.pdb

Development Mode

# Terminal 1: Vite dev server
npm run dev

# Terminal 2: Python backend
uv run megane serve protein.pdb --dev --no-browser

Tests

uv run pytest              # Python tests
npm test                   # TypeScript unit tests
cargo test -p megane-core  # Rust tests
make test-all              # All tests

Project Structure

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, CIF, XTC, LAMMPS, .traj)
  logic/                 Bond / label / vector source logic
  components/            React UI components
  hooks/                 Custom React hooks
  stream/                WebSocket client
crates/                  Rust workspace
  megane-core/           Core parsers and bond inference
  megane-python/         PyO3 Python extension
  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
tests/                   Tests (Python, TypeScript, E2E)

License

MIT