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

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 { 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.11.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.11.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.11.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.11.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.11.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.11.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.11.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.11.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.11.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.11.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.11.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.11.0.tar.gz.

File metadata

  • Download URL: megane-0.11.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.11.0.tar.gz
Algorithm Hash digest
SHA256 209cc0961a5482fee324b9d1d90fe1e02bdbbb52e12d71671660c2383c60db35
MD5 4a6bfab6b88d0e65422bb0b33dc37b44
BLAKE2b-256 b18b990a3f47febd5d09a72ed4be0a93f7c8fd361d54ae190eba49210fb3f617

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for megane-0.11.0-cp314-cp314-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 328e15919d9ef5bc46274cd6be55c2854f90a269c3a13ea016214dff64a345a7
MD5 5b03bd7e451e2033b3c1eb0f3e51c277
BLAKE2b-256 16167d6630630a31aadc0666dddd2bdf74d6b517201059cc028b33b221879543

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for megane-0.11.0-cp314-cp314-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 04275e212e547fa14ccfba0ce955fba8ff8af53dd2ac0f10eaed6c3a6ee112df
MD5 2d3c1eee0c03c4ed699bce93111af211
BLAKE2b-256 e73ae833859a91e8aef6745458ae7d3af9f309caf17c732e92a60bee56da4af4

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for megane-0.11.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 4899142beaeb45c84da905426060af2f446834fc27d3b01932e9d960a3d68a4f
MD5 4d37e5259ffa9f552fe3bb4e9b857a5a
BLAKE2b-256 db8dc182f43489fd5a4da661e066d4bfb61fb3061eee45f46ff6dafc00fb47c5

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for megane-0.11.0-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 697f7a5549e6c5f3a3aabf7d6cc0dfb121654ad409642a3536962cabe786a448
MD5 b26cc323178438fad684448ac5d1c9e1
BLAKE2b-256 8739664ac9872ba13c93cc0a0144eff8640a7809b854613195fab25b76cae384

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for megane-0.11.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 c6f34965a6bf84a8c01bb79da5f9147309f553b5c944f4611ca3bd23cd12bdea
MD5 16d0da52d2a386a304198b4b45f2a7ac
BLAKE2b-256 de61abcbb60036c225c544fa959b3da8bd5089cd6ba3474112998d1a79e66b7f

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for megane-0.11.0-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 ad1c74a8315c7f6741d7400818d7413259362b5a7d02447e638405e189acac6c
MD5 024e86e49c15f372c3833f6dd9d335b4
BLAKE2b-256 fb5d29af1abe5ddb07544db4810cab6bea8370252c4a774535430ba00c5a7384

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for megane-0.11.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 4cb52a3af895449c2d7a8f95e129a3cd17c1f216e26808fd4a2e8cdedee9b218
MD5 278a14d06ce144918573d2e331eb60c1
BLAKE2b-256 6966fc77816c1d8424566066c47fdc9b977b29d5d92549d4c9a5f483bd95df63

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for megane-0.11.0-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 bf33f427748857d256a82ecc4b252ef5992169feb9d970bc6b2ae83971c8c1d4
MD5 5c70c9a73b296921ee7347b8b7e49429
BLAKE2b-256 e8737cc31704d3998771b69e761a876d1a7ff7d7b957f97212f9246cf72b3456

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for megane-0.11.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 81278d3440cde323da5bfcd0f17394a480ad583c06dd8d2f9a61cbf8bcee683a
MD5 2205114499d5628c80c560fbd570ebd3
BLAKE2b-256 82e38dcaa3073e96f8470875bd80c2a38b46edec4cf660947a891058ccb02d7d

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for megane-0.11.0-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 05dacae3b8789decb8c8f589a85d7c17a9cda356ed528d66aa50317a51ce35dc
MD5 52a7fa1630332588718a1e775c139eaf
BLAKE2b-256 d3b74b17529329966a7c6541fb00db63ff269b4e670b1db45b2d2bf08df813c3

See more details on using hashes here.

Provenance

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

0.13.0

11 files

0.12.0

11 files

This release

0.11.0 This release

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