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 { 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.12.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.12.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.12.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.12.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.12.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.12.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.12.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.12.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.12.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.12.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.12.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.12.0.tar.gz.

File metadata

  • Download URL: megane-0.12.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.12.0.tar.gz
Algorithm Hash digest
SHA256 6c772770deec61d4da5492e57c949d460008c0e28494e967acfc758327d1cab5
MD5 9e43361cbd18a59eac4d4507952274eb
BLAKE2b-256 fab85b31aeb7a96d0f82ada88343a8f59ea5e8b1f8858a7c0d92321f240adf52

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for megane-0.12.0-cp314-cp314-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 ccbe37e4ca1e0b8c78808461f6308e8b069c2620406bb3435ed9513db14db48b
MD5 089acbfd861f8d9cddfc158dd14e29ed
BLAKE2b-256 26448133ae2675019bfa4fd2d1680713cee24d3235a81b985af650c626f4d165

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for megane-0.12.0-cp314-cp314-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 abd87e9290f89ae2454c6f4eba948caa8b30b6c01d1a95277b71ad019fc15684
MD5 c168108bc495e9251b82518eb8664be8
BLAKE2b-256 537492ac6e04e0443445e0055989e6f477965638b1dbbff2643995dcac416ef1

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for megane-0.12.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 4ee1b590a830bfa339398a0e3dae1d1e5dba97b9d2be4cf0e28ef83d65f8c0f7
MD5 402b1a08ff1719f1f4df6d21c8fc31cf
BLAKE2b-256 ef6874608d5a76b1c1c43ddcfa57d240e5105c1744267b25f5e7b79f91a6e13e

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for megane-0.12.0-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 17cf368a171311b424b27a3dc9aa70d928062b68ccc35b3802fee6a7623c6a83
MD5 b6f49f8e9519d83fca47f381010ca439
BLAKE2b-256 72c0f5a830430a0eb7e101f6690e79987268ebbf4c3beeb633c1439e41edec05

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for megane-0.12.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 9112ae61f7ea2936b29b07f127061b1ac37d9f9d86740cb923c8673abbb3cac3
MD5 40da6a2b02497efe2d840f6c8541e8f1
BLAKE2b-256 54ffcdcfbbe391ba85547b4cd4eb25a1a1576add55fc80d1fe482b6eed05b7e5

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for megane-0.12.0-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 62e5c13373f9c18ea477c236169f0006a23af3a18fe93c3b3967aa1759c7cb14
MD5 a58995f220a8d92764a78e41e5eaafbd
BLAKE2b-256 b0e79782fc1664611bc6780a5926ffd2b500cb2ad3dc8322a29969ba3900503c

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for megane-0.12.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 8fa3924d208e93fd05c555494cf3c477467a3d2faae5fb8e507cc7b18f0b425a
MD5 949c37c041157750ef1327493c567cee
BLAKE2b-256 b5193eb5211db9ec134c9ab9dc2516821a6dc8b874238451ac0a8251314c9fe6

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for megane-0.12.0-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 317057641f7ec9b6d239059abb818d6b42e806cb4ee709c78a4478b1a4cd6702
MD5 b188c0142f2da971872a4794ac4226c8
BLAKE2b-256 7cb0cec0654efc7ac2bb82b451ee04a12d14ad988a6d50ad9692ac50dac3a878

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for megane-0.12.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 e0402f04ea004e54354bc12923a20b4a5627977a6f151c849e2b90f8772d9a99
MD5 f98fe78f44d1feb4a66c07f56af16b05
BLAKE2b-256 e72a27c27b2acb0ad59387b939190c530efdbc2c57a1112d45255e67c41c70d3

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for megane-0.12.0-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 e318b6ec67542a13ac36ee4380e58230e71c7a2e1079b8021e3c727efff4bdb2
MD5 cc01e7810a3a9c2c8f9bd7548ee37d1e
BLAKE2b-256 af46da69532fbffd14998b4b4294ef64da22a11667176b64a8b3bb4fe9a3750f

See more details on using hashes here.

Provenance

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

This release

0.12.0 This release

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