megane

Spectacles for atomistic data.

1M+ atoms at 60fps. Visual pipelines. Jupyter widget, standalone web app, React component, VS Code extension.

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, standalone web app (megane serve), React component (npm), and VS Code extension. Rust-based parsers for 26 formats (PDB, GRO, XYZ, MOL/SDF, MOL2, CIF, mmCIF, CML, LAMMPS data, AMBER topology, GROMACS topology, CHARMM/NAMD PSF, XTC, DCD, ASE .traj, LAMMPS dump, AMBER NetCDF, VASP, Molden, XCrySDen XSF, JCAMP-DX, Chem3D XML, Odyssey, CASTEP magres, GAMESS output, CASTEP phonon) 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. 19 node types with 9 typed data channels flowing through color-coded edges. Load multiple structures with layer-based rendering to compare systems side by side.
• megane Builder — A structure editor next to the viewer (/builder.html in megane serve): add, delete, move and re-element atoms, draw bonds, sketch molecules in Ketcher (embedded in 3D by RDKit), and build bulk crystals, supercells and slabs. Save as XYZ / PDB / MOL — also available from Python as megane.save_structure().
• 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: parsers for 26 formats (PDB, GRO, XYZ, MOL/SDF, MOL2, CIF, mmCIF, CML, LAMMPS data, AMBER topology, GROMACS topology, CHARMM/NAMD PSF, XTC, DCD, ASE .traj, LAMMPS dump, AMBER NetCDF, VASP, Molden, XCrySDen XSF, JCAMP-DX, Chem3D XML, Odyssey, CASTEP magres, GAMESS output, CASTEP phonon) are written in Rust and compiled to both PyO3 (Python) and WASM (browser). Parse once, run anywhere. The volumetric readers (Gaussian CUBE, OpenDX) are TypeScript-side.

Visual Pipelines

Wire nodes to build visualization workflows — no code required.

19 node types across 5 categories: load data (structure, trajectory, streaming, vector, volumetric, spectrum), bonds, process (filter, modify, color, representation, replicate), overlay (labels, polyhedra, surface meshes, isosurfaces, vectors), and display in a 3D viewport or a 2D spectrum plot.

9 typed data channels — particle, bond, cell, label, mesh, trajectory, vector, volumetric, spectrum — 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

Works with React 18 and React 19 (peer dependency: react@^18.2.0 || ^19.0.0).

Quick Start

Jupyter widget

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.

Standalone web app (megane serve)

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

Open http://localhost:8080 in your browser. megane Builder, the structure editor, is at http://localhost:8080/builder.html.

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 component (npm)

import { useCallback } from "react";
import "megane-viewer/styles.css";
import { MeganeViewer, usePipelineStore } from "megane-viewer/lib";

function App() {
  const handleUpload = useCallback((file: File) => {
    usePipelineStore.getState().openFile(file);
  }, []);

  return (
    <MeganeViewer
      onUploadStructure={handleUpload}
      width="100%"
      height="600px"
    />
  );
}

Supported File Formats

Structure formats (LoadStructure node)

Volumetric formats (LoadVolumetric node)

A grid has no atoms of its own, so it is rendered as an isosurface over a separately-loaded structure. .dx is shared with JCAMP-DX spectra, so the loader sniffs the content and says so if the file is really a spectrum.

Spectrum formats (LoadSpectrum node)

A spectrum is a 2D (x, y) trace with no atoms or coordinates, so it is drawn by the terminal SpectrumPlot node instead of reaching the 3D renderer.

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/megane-labs/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 (26 formats: PDB, GRO, XYZ, MOL/SDF, MOL2, CIF, mmCIF, CML, LAMMPS data/dump, AMBER topology/NetCDF, GROMACS topology, CHARMM/NAMD PSF, XTC, DCD, ASE .traj, VASP, Molden, XCrySDen XSF, JCAMP-DX, Chem3D XML, Odyssey, CASTEP magres, GAMESS output, CASTEP phonon)
  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/               Python wrappers for 22 of the 26 supported formats, plus the PSF / GROMACS .top topology sidecars (mmCIF and AMBER prmtop are accessible via the raw megane_parser PyO3 extension; Gaussian CUBE and OpenDX are browser-side only)
  pipeline.py            Pipeline builder (NetworkX-style DAG)
  protocol.py            Binary protocol encoder
  server.py              `megane serve` backend (FastAPI + WebSocket)
  widget.py              anywidget Jupyter widget
tests/                   Tests (Python, TypeScript, E2E)

Contributing

Contributions are welcome! See CONTRIBUTING.md for the development setup, test commands, and project design rules. Fork PRs run the full CI and E2E pixel checks automatically — no tokens or setup needed on your side. This project follows the Contributor Covenant Code of Conduct; security issues should be reported privately per SECURITY.md.

License

MIT