Skip to main content

megane

Spectacles for atomistic data.

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

CI PyPI npm License Python Docs codecov

Docs · Getting Started · PyPI · npm

megane demo


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.
  • 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.

Distribution How Install
Jupyter widget anywidget inline viewer pip install megane
JupyterLab extension Open any supported structure, trajectory, volumetric, or spectrum file — plus .megane.json pipelines — straight from the file browser pip install megane
Standalone web app megane serve in the browser pip install megane
React component (npm) <MeganeViewer /> component npm install megane-viewer
VS Code extension Custom editor for the same file types, registered by extension and by VASP basename (POSCAR/CONTCAR/XDATCAR) Extension

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-agnosticMoleculeRenderer 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.

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)

Format Extension Description
PDB .pdb Protein Data Bank
GRO .gro GROMACS structure file
XYZ .xyz, .jxyz Cartesian coordinate format, incl. multi-frame and Lattice= extended XYZ. .jxyz is Jmol's second extension for the same format
MOL/SDF .mol, .sdf MDL Molfile (V2000)
MOL2 .mol2 Tripos MOL2 (multi-molecule, aromatic bonds)
LAMMPS data .data, .lammps LAMMPS data file
CIF .cif Crystallographic Information File
mmCIF .mmcif Macromolecular CIF (PDBx/mmCIF)
AMBER topology .prmtop AMBER parameter/topology file (atom names, elements, bonds)
ASE .traj .traj ASE trajectory (ULM binary format) — self-contained with elements, bonds, and frames
XCrySDen .xsf, .axsf XCrySDen structure; .axsf is a multi-frame animation with optional per-frame cell and per-atom forces
CML .cml Chemical Markup Language (Open Babel / Avogadro / ChemDraw), with explicit bonds and optional crystal cell
VASP POSCAR, CONTCAR, XDATCAR, .vasp VASP crystal structure; XDATCAR is multi-frame. Matched by filename as well as extension, since the standard names carry no extension
Molden .molden Molden quantum-chemistry output — [Atoms] geometry (AU or Angstrom) and [GEOMETRIES] XYZ optimisation frames
Chem3D XML .c3xml PerkinElmer Chem3D / ChemDraw XML (CDXML family) — nodes with explicit bonds and orders
Odyssey .xodydata, .odydata Wavefunction Odyssey — the XML layout and the older Spartan-style text layout, told apart by content rather than extension
CASTEP magres .magres CASTEP / Quantum ESPRESSO NMR output — the [atoms] block (lattice + labelled atoms) with per-block units
GAMESS output .gamess GAMESS (US / Firefly) log output — every COORDINATES OF ALL ATOMS ARE block becomes a frame
CASTEP phonon .phonon CASTEP lattice-dynamics output — the header (cell + fractional coordinates + species) renders as a periodic structure

Volumetric formats (LoadVolumetric node)

Format Extension Description
Gaussian CUBE .cube, .cub Gaussian cube grid (Bohr, converted to Angstrom on read)
OpenDX .dx OpenDX scalar field — the APBS electrostatics output, also read by VMD and PyMOL

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.

Format Extension Description
JCAMP-DX .jdx, .jcamp, .dx IR / NMR / MS / UV-Vis spectra; AFFN plus the compressed ASDF forms (SQZ, DIF, DUP). .dx is shared with OpenDX volumetric grids and resolved by sniffing the file head

Trajectory formats (LoadTrajectory node)

Format Extension Description
XTC .xtc GROMACS compressed trajectory
DCD .dcd CHARMM/NAMD binary trajectory
AMBER NetCDF .nc AMBER NetCDF trajectory
LAMMPS dump .lammpstrj, .dump LAMMPS dump trajectory

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 (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 14 of the 16 supported formats (mmCIF and AMBER prmtop are accessible via the raw megane_parser PyO3 extension)
  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)

License

MIT

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

megane-0.13.1.tar.gz (3.6 MB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

megane-0.13.1-cp314-cp314-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (3.9 MB view details)

Uploaded CPython 3.14manylinux: glibc 2.17+ x86-64

megane-0.13.1-cp314-cp314-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (3.9 MB view details)

Uploaded CPython 3.14manylinux: glibc 2.17+ ARM64

megane-0.13.1-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (3.9 MB view details)

Uploaded CPython 3.13manylinux: glibc 2.17+ x86-64

megane-0.13.1-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (3.9 MB view details)

Uploaded CPython 3.13manylinux: glibc 2.17+ ARM64

megane-0.13.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (3.9 MB view details)

Uploaded CPython 3.12manylinux: glibc 2.17+ x86-64

megane-0.13.1-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (3.9 MB view details)

Uploaded CPython 3.12manylinux: glibc 2.17+ ARM64

megane-0.13.1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (4.0 MB view details)

Uploaded CPython 3.11manylinux: glibc 2.17+ x86-64

megane-0.13.1-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (3.9 MB view details)

Uploaded CPython 3.11manylinux: glibc 2.17+ ARM64

megane-0.13.1-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (4.0 MB view details)

Uploaded CPython 3.10manylinux: glibc 2.17+ x86-64

megane-0.13.1-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (3.9 MB view details)

Uploaded CPython 3.10manylinux: glibc 2.17+ ARM64

File details

Details for the file megane-0.13.1.tar.gz.

File metadata

  • Download URL: megane-0.13.1.tar.gz
  • Upload date:
  • Size: 3.6 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for megane-0.13.1.tar.gz
Algorithm Hash digest
SHA256 9713ad736d12a51955b3879793712390da92c7e13f7cb6ddc280de3442b79ba1
MD5 5ed54022268e06f763c27e726e0961c1
BLAKE2b-256 0e56a3507c643c8eea20dbd36dc1471f62bbd245f08d8ed6a1df2b6204b28c71

See more details on using hashes here.

Provenance

The following attestation bundles were made for megane-0.13.1.tar.gz:

Publisher: publish-pypi.yml on hodakamori/megane

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file megane-0.13.1-cp314-cp314-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for megane-0.13.1-cp314-cp314-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 7ed03c9e0df0271f417c4c4d88fb412a20fbf17700c2b4e77ea60556be150189
MD5 0aa5e059fca54f2e7a0339fffea6612d
BLAKE2b-256 4da924463d074ed1b5446c0911821ef68617958b29e1a431fc47175589fe65aa

See more details on using hashes here.

Provenance

The following attestation bundles were made for megane-0.13.1-cp314-cp314-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: publish-pypi.yml on hodakamori/megane

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file megane-0.13.1-cp314-cp314-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for megane-0.13.1-cp314-cp314-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 bc3f83d9eab21d964676ce99e198cf889cdc6d72903373a7b7840c84484dc1a4
MD5 ed65d2c3dfb1345c6556fe4fee761de4
BLAKE2b-256 802d7ff015c32846c969898ab287746321a4759ad8c16bbb61e5deff1d0bb278

See more details on using hashes here.

Provenance

The following attestation bundles were made for megane-0.13.1-cp314-cp314-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: publish-pypi.yml on hodakamori/megane

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file megane-0.13.1-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for megane-0.13.1-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 cef5270d5aba3ea3cd38d1c2980946d7cece63eec9b51b73979434d28755f027
MD5 23a44c7e652b342489049388901cc327
BLAKE2b-256 ec92d7a0310959a757902975eefca95fff65ae349ec4d2fe685b730f3555dd1a

See more details on using hashes here.

Provenance

The following attestation bundles were made for megane-0.13.1-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: publish-pypi.yml on hodakamori/megane

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file megane-0.13.1-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for megane-0.13.1-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 bda05f66cfd3a74ae255d8b6975c8fa9bdec775b62a67c4a9192f6f788dcd0d6
MD5 8453e4160e1bab81efcd74bec4fe51e2
BLAKE2b-256 653620ab3ffc3989627437e8548841ede3b3762d031abee5a7afa98bbcbb8770

See more details on using hashes here.

Provenance

The following attestation bundles were made for megane-0.13.1-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: publish-pypi.yml on hodakamori/megane

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file megane-0.13.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for megane-0.13.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 33a6e570619bd6bb562974c0e6d2fc86630d08e5b8732e01f754798e93f0c893
MD5 1b86a3dbbbea2586199663f5078d6551
BLAKE2b-256 ac08da788564ff5e9b490125b0c1553100b20202f8934abd40dd0a4103ed1665

See more details on using hashes here.

Provenance

The following attestation bundles were made for megane-0.13.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: publish-pypi.yml on hodakamori/megane

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file megane-0.13.1-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for megane-0.13.1-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 a52ee11635a5d711df68ef5216b06fe5951761da87e88d83f76094026ef6cccc
MD5 4f26aa17dc402a269ebb9fbe698c81c0
BLAKE2b-256 a34eb1f131caef7d40a6156d2bda8b02bf854fe8261ae9c411d5fc6f64b8bcec

See more details on using hashes here.

Provenance

The following attestation bundles were made for megane-0.13.1-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: publish-pypi.yml on hodakamori/megane

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file megane-0.13.1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for megane-0.13.1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 e8b675b6b788406a3ae287f01dd75eb753390c92fb4e3885cb75e3b034077cc7
MD5 7bf3b84676fba110c9d1ea312560d258
BLAKE2b-256 4ab91762b5e3ac093f56dbdf180eef84e56b06dfd67722a5c20de47d00c8c6d5

See more details on using hashes here.

Provenance

The following attestation bundles were made for megane-0.13.1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: publish-pypi.yml on hodakamori/megane

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file megane-0.13.1-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for megane-0.13.1-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 5117518cfd4e6b11742ff026addf649b2be007f371b9513dce2f4797a5ddad93
MD5 f3880669508bd89414c30e38fbb0bb09
BLAKE2b-256 0fc6b1219a52b41f33714700010446a6604a383f8f536ef254c89f93b7357f1f

See more details on using hashes here.

Provenance

The following attestation bundles were made for megane-0.13.1-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: publish-pypi.yml on hodakamori/megane

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file megane-0.13.1-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for megane-0.13.1-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 4ee76017304b81ac9eee1fadfa95827fec65564f75fea993607facc442b8b6de
MD5 ff1d4c7f54036db7ff9b8377fdb2f7b9
BLAKE2b-256 d8a75e8bd703a79680b69c3446ed4fe06a0bda97ea96a48c93ecd9ca384877eb

See more details on using hashes here.

Provenance

The following attestation bundles were made for megane-0.13.1-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: publish-pypi.yml on hodakamori/megane

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file megane-0.13.1-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for megane-0.13.1-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 5f13acefec510f03b2b8d18920f0a8451c8495d90277155294ea45a0241770de
MD5 9670aade05a9a07fd62e6a821b2015ec
BLAKE2b-256 c185fab167132d33e2ca7fa0e54fcea7aad4e1ee0a0f4cc53d09354b4adb97de

See more details on using hashes here.

Provenance

The following attestation bundles were made for megane-0.13.1-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: publish-pypi.yml on hodakamori/megane

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.15.0

11 files

0.14.0

11 files

This release

0.13.1 This release

11 files

0.13.0

11 files

0.12.0

11 files

0.11.0

11 files

0.10.0

11 files

0.9.1

11 files

0.9.0

11 files

0.8.0

11 files

0.7.0

9 files

0.6.2

9 files

0.6.1

9 files

0.6.0

9 files

0.5.0

9 files

0.4.0

9 files

0.3.2

9 files

0.3.0

9 files

0.2.0

9 files

0.1.1

9 files

0.1.0

8 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page