megane

Spectacles for atomistic data.

1M+ atoms at 60fps. Visual pipelines. Jupyter, browser, React, VSCode.

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, CLI server, React component, and VSCode extension. Rust-based parsers for 15 formats (PDB, GRO, XYZ, MOL/SDF, MOL2, CIF, mmCIF, LAMMPS data, AMBER topology, XTC, DCD, ASE .traj, LAMMPS dump, AMBER NetCDF) 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. 16 node types with 7 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.

Environment How Install
Jupyter anywidget inline viewer pip install megane
JupyterLab Open .pdb, .gro, .xyz, .mol, .sdf, .mol2, .cif, .mmcif, .data/.lammps, .prmtop, .traj, .xtc, .dcd, .nc, .lammpstrj/.dump, .megane.json from the file browser pip install megane
Browser megane serve local server pip install megane
React <MeganeViewer /> component npm install megane-viewer
VSCode Custom editor for .pdb, .gro, .xyz, .mol, .sdf, .mol2, .cif, .mmcif, .data/.lammps, .prmtop, .traj, .xtc, .lammpstrj, .dump, .dcd, .nc, .megane.json Extension

For a per-platform breakdown of supported formats and UI features (including known gaps), see Platform Support.

The secret: parsers for 15 formats (PDB, GRO, XYZ, MOL/SDF, MOL2, CIF, mmCIF, LAMMPS data, AMBER topology, XTC, DCD, ASE .traj, LAMMPS dump, AMBER NetCDF) are written in Rust and compiled to both PyO3 (Python) and WASM (browser). Parse once, run anywhere.

Visual Pipelines

Wire nodes to build visualization workflows — no code required.

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

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

Quick Start

Jupyter Notebook

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.

CLI (Docker)

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

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 Cartesian coordinate 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

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 (15 formats: PDB, GRO, XYZ, MOL/SDF, MOL2, CIF, mmCIF, LAMMPS data/dump, AMBER topology/NetCDF, XTC, DCD, ASE .traj)
  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 13 of the 15 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              FastAPI WebSocket server
  widget.py              anywidget Jupyter widget
tests/                   Tests (Python, TypeScript, E2E)

License

MIT

Project links

Data verified by PyPI on Jun 27, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.15.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for hodakamori from gravatar.com hodakamori

Credits

Author: hodakamori

GitHub Statistics

Data verified by PyPI on Jun 27, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.10

Provides Extra

dev traj

Tags

molecular viewer pdb jupyter widget anywidget

Classifiers

Report project as malware

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.9.1.tar.gz (3.2 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.9.1-cp314-cp314-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (3.6 MB view details)

Uploaded CPython 3.14manylinux: glibc 2.17+ x86-64

megane-0.9.1-cp314-cp314-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (3.6 MB view details)

Uploaded CPython 3.14manylinux: glibc 2.17+ ARM64

megane-0.9.1-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (3.6 MB view details)

Uploaded CPython 3.13manylinux: glibc 2.17+ x86-64

megane-0.9.1-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (3.6 MB view details)

Uploaded CPython 3.13manylinux: glibc 2.17+ ARM64

megane-0.9.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (3.6 MB view details)

Uploaded CPython 3.12manylinux: glibc 2.17+ x86-64

megane-0.9.1-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (3.6 MB view details)

Uploaded CPython 3.12manylinux: glibc 2.17+ ARM64

megane-0.9.1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (3.6 MB view details)

Uploaded CPython 3.11manylinux: glibc 2.17+ x86-64

megane-0.9.1-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (3.6 MB view details)

Uploaded CPython 3.11manylinux: glibc 2.17+ ARM64

megane-0.9.1-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (3.6 MB view details)

Uploaded CPython 3.10manylinux: glibc 2.17+ x86-64

megane-0.9.1-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (3.6 MB view details)

Uploaded CPython 3.10manylinux: glibc 2.17+ ARM64

File details

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

File metadata

  • Download URL: megane-0.9.1.tar.gz
  • Upload date:
  • Size: 3.2 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for megane-0.9.1.tar.gz
Algorithm Hash digest
SHA256 a0d9fdfb5372a10b83a7bbfedaa47d69c546d3457de034584c14ae40c1adc52e
MD5 9fd728fe7dc2fb104d19e4c180190d79
BLAKE2b-256 989ea0f7e09f1a11e097adbe8b7815e45ea861287981bc38fe9ba1279566735a

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for megane-0.9.1-cp314-cp314-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 550f27c4635e0563d51b3dcdc6457b9d65d7a295c057e47b2382224b2846c830
MD5 91d276acded998ec1efa80917d0fdbb2
BLAKE2b-256 87b470cf395c88c9d94b6b1089951b66660356aecb1ed7e36f0def6b7ded46f7

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for megane-0.9.1-cp314-cp314-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 89ba450e08dc1f6facc236200773fdaef117b09de1865ce77c0fa3aa9cb8770d
MD5 fea799a453d29aa11113ac28675b3f6b
BLAKE2b-256 bca9e4b2bf68ff851b713ec30f76dc5464e95bc7af32d28efa8dd3c1dac46f6a

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for megane-0.9.1-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 ea7b4f46c598ec0cdf43b1981a19fdc1429ce594814d426b4676e4dddad6bff6
MD5 0f896b80af0a53b2a8baeeb5cab0806b
BLAKE2b-256 cb10c6b805fc71df6f64090000ab29410ed135df5cb9a43fec5ce3ff70918c4a

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for megane-0.9.1-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 f50ae30f1acff12dcd8a111d30f920d6c7cc4cdc81044f61a9f4f2285db838f7
MD5 17ec6a4b1ee1b754d26f074d27e11441
BLAKE2b-256 6a2ead50fcb59ac5a7114b8488e876dad8725e7f2109662bc3ea3ea540d35108

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for megane-0.9.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 ed3ba157d67d19298cecc54cfe7350e83612b3db6477645610d19915df7367a4
MD5 7e3f8a9f24064c28d659e1183d00f843
BLAKE2b-256 1583da07e0e4ccfb19c11cf96e5b32bb02e85765efd259c010b4c2d388b31802

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for megane-0.9.1-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 10e07ec5071abbc14336cbfbd0040a4928f51f3844a8b13de64d1dcbdeaa78e7
MD5 20a282a44896e55727a542c0b6c9a969
BLAKE2b-256 2d390873ba9135ad5b7b64620a01b451f6a1b431dc96293e4f238eb4a390199a

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for megane-0.9.1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 5c921c62df61ced2961ddb2ff78987dbdd985819072d105613b76d19e3e9e05f
MD5 553bc4cfa42ae7e92cfa23d1a1c4a2e6
BLAKE2b-256 1561020050089a5bc7572a83d2c98c2601b27f293adc4053a0aa990a78d30393

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for megane-0.9.1-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 29b65dcad87ab16e5757bf4640c59fe566eee0085eb05772edb433909b884e7f
MD5 24b2ac509f891841f6b3615ce20518f2
BLAKE2b-256 a37e66b40ec628ba684c9c4efb45cf9f1d51938a44e4d0eb406ca3853a945d3a

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for megane-0.9.1-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 0e90ea49f4bb15ef991eef1f1a9a5c327d2e720921ed678391f82989d474c549
MD5 d7b72d548c9f6d7100133d67f6aa831e
BLAKE2b-256 4fd162e6fa61773f7b633a33f618e6bd8d50ab7ba101ea5de3d0fabc0aa204de

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for megane-0.9.1-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 98b92829d351b8fa5bb28f0f877b47a7d2a300c29b1ec40af911809152d32920
MD5 a519d5135b866e2b395e487de4212983
BLAKE2b-256 cef321be821f234c78e3f435101a323d56844088cbd9a7395eeb2f07f4dff058

See more details on using hashes here.

Provenance

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

0.13.1

11 files

0.13.0

11 files

0.12.0

11 files

0.11.0

11 files

0.10.0

11 files

This release

0.9.1 This release

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