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.0.tar.gz (3.5 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.0-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.0-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.0-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.0-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.0-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.0-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.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (3.9 MB view details)

Uploaded CPython 3.11manylinux: glibc 2.17+ x86-64

megane-0.13.0-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.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (3.9 MB view details)

Uploaded CPython 3.10manylinux: glibc 2.17+ x86-64

megane-0.13.0-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.0.tar.gz.

File metadata

  • Download URL: megane-0.13.0.tar.gz
  • Upload date:
  • Size: 3.5 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.0.tar.gz
Algorithm Hash digest
SHA256 f6298a160127888f4f836b4b14cadd1eeafe32f8065c094c8e308a74905c6d45
MD5 821f5d8eca64188bba30d43fcfd0d77e
BLAKE2b-256 cfae8c81df157f9d2c6fabd003213d0264e1dfc8d46c1930b7626836285d82d1

See more details on using hashes here.

Provenance

The following attestation bundles were made for megane-0.13.0.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.0-cp314-cp314-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for megane-0.13.0-cp314-cp314-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 52327aa6cf5a2bce528da95ecacd842cbcff8b02f200399a8014ef2a5eb97193
MD5 514fdb7347e52a733aab852a647c7ec9
BLAKE2b-256 c2e037185943b15610bab3d144636a56b9429d7a3ca25db460d90ce33655cf59

See more details on using hashes here.

Provenance

The following attestation bundles were made for megane-0.13.0-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.0-cp314-cp314-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for megane-0.13.0-cp314-cp314-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 ed857a79deb2e3fa3bb2b0d5a89f7153589471bdb74b01eed723269289ca11c1
MD5 ab8bb869ce3977cfea426a7b6045b6d4
BLAKE2b-256 a3b030829b46ac7fb54ac40ecd6681dfdce782fe13a9bf044e97e40e7db893d3

See more details on using hashes here.

Provenance

The following attestation bundles were made for megane-0.13.0-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.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for megane-0.13.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 a06d8b3c153d8e7b0c7c3031a998fe50746cf34880ff22b301453b769b8f3d19
MD5 1ba3fb33cd1bb1c1cb57f4828588f213
BLAKE2b-256 1e528a2d8ccbf7aca7fd56ad76f7a76d760f4d2d9165da42578333651df33a40

See more details on using hashes here.

Provenance

The following attestation bundles were made for megane-0.13.0-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.0-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for megane-0.13.0-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 62a5cab0439a1716cfd0ab459e877fe26e306495749f51f27ca231a67482e6a4
MD5 7b797c4372c88b382cc9ca420a98b20d
BLAKE2b-256 6756d04a4da34fa09c21a5026a819e1c924d3f59971626055a5cb30ec5915958

See more details on using hashes here.

Provenance

The following attestation bundles were made for megane-0.13.0-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.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for megane-0.13.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 69d03e11e6f7888f3a682a9f30b251bdb16665f2606c02101feeaf78d5798aa8
MD5 0b10e0ec079c50f2152e545609a32456
BLAKE2b-256 998c069e29f023647f43549ba07001a0f3977ea42d17cff8cc75a507e3fb57d4

See more details on using hashes here.

Provenance

The following attestation bundles were made for megane-0.13.0-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.0-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for megane-0.13.0-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 611c67e14cd41647f507aa687bb219b3f9e09b9d8a20c39e5519a6c1e487963c
MD5 cf002fb2a89ff5f199690bf2f34bccf1
BLAKE2b-256 cd1cf4142fddc0e15e81903e538b0774badb449fe4cde7ae7869aba2f7e4f053

See more details on using hashes here.

Provenance

The following attestation bundles were made for megane-0.13.0-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.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for megane-0.13.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 0d59e5a04bd5bf9f3d10b226dbad8c79a791d12a4dda78d8edc42906779a4a3b
MD5 4436b23989ade9e65cf359e17856ddf3
BLAKE2b-256 cda4fb2195b95914ef8a6c6ec084d6130c5a8d7d56b7ace3c241dd5a22942449

See more details on using hashes here.

Provenance

The following attestation bundles were made for megane-0.13.0-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.0-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for megane-0.13.0-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 0e4ea2dadd557996c6957090d7eb3c8ffab5fe47d607e1e3203e02d696d4a06d
MD5 0d3e137601eb54d9e0a918f9639d87bf
BLAKE2b-256 ad2db883f8e87a45bc2801f104cd7aa716c6042d2eb681224507fa0e1d774336

See more details on using hashes here.

Provenance

The following attestation bundles were made for megane-0.13.0-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.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for megane-0.13.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 979c78c9916ab3ef65756d54126b0e0b40d6cf2a1b48ee9aa64618fff3e731ab
MD5 848565a2149a878d276f0d5eaae764b6
BLAKE2b-256 99561dc4022050119c6d3d4bf6c0c101955f01140d33d3dff246bc71aeda603a

See more details on using hashes here.

Provenance

The following attestation bundles were made for megane-0.13.0-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.0-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for megane-0.13.0-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 7537a61f487031feae97e90fefdd82b9151af5380c6affd1bf2a97c3bf8cd57f
MD5 6e9a61785356471929f58017c111d75c
BLAKE2b-256 17d5ebac42f538551da6b6fb48a60cbe70a31f4c924c961289e90957a6c45e74

See more details on using hashes here.

Provenance

The following attestation bundles were made for megane-0.13.0-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

0.13.1

11 files

This release

0.13.0 This release

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