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

Distribution How Install
Jupyter widget anywidget inline viewer pip install megane
JupyterLab extension 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
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 .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 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 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              `megane serve` backend (FastAPI + WebSocket)
  widget.py              anywidget Jupyter widget
tests/                   Tests (Python, TypeScript, E2E)

License

MIT

Project links

Data verified by PyPI on Jul 12, 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 Jul 12, 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.10.0.tar.gz (3.3 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.10.0-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.10.0-cp314-cp314-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (3.6 MB view details)

Uploaded CPython 3.14manylinux: glibc 2.17+ ARM64

megane-0.10.0-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.10.0-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (3.6 MB view details)

Uploaded CPython 3.13manylinux: glibc 2.17+ ARM64

megane-0.10.0-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.10.0-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (3.6 MB view details)

Uploaded CPython 3.12manylinux: glibc 2.17+ ARM64

megane-0.10.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (3.7 MB view details)

Uploaded CPython 3.11manylinux: glibc 2.17+ x86-64

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

Uploaded CPython 3.11manylinux: glibc 2.17+ ARM64

megane-0.10.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (3.7 MB view details)

Uploaded CPython 3.10manylinux: glibc 2.17+ x86-64

megane-0.10.0-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.10.0.tar.gz.

File metadata

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

File hashes

Hashes for megane-0.10.0.tar.gz
Algorithm Hash digest
SHA256 d71179f59afb9f186dbc2894b3dee99875974e66cf2d54f44115f6627543d8ce
MD5 ec5ff240f25cdaa0e92aa9a35d2e1785
BLAKE2b-256 b6d316e8a5a452cd39260e9d82ea913d203b64224be34338885a8ed0be2e9224

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for megane-0.10.0-cp314-cp314-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 a4d47dc55fe5c17b44abdbcbb0c53646c185cf7ada4ba721dfb95a83a9485780
MD5 aa625b01be1d2d5fb5e9114a09ac5598
BLAKE2b-256 eaca7682bb55f279ad21e436d049e0905cf3c2701ff7c011aba84e2eef6df49d

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for megane-0.10.0-cp314-cp314-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 0ae8c587298d0c589c546e5ae372e31a6234c0b25d3b94d63c2c2adb2650bf9d
MD5 2c0e07fe434c109b42a4b90fabdb5821
BLAKE2b-256 6061362f835bbd001feb5b0fb23c854686b3bc06360a33277e749c8f1bc64def

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for megane-0.10.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 fb2ee1f4b42edaf75087e5ffe059e5b00fc747220c7b502fdba12f6e5e5670c0
MD5 788d83798fe0187babddad9f457bd4fb
BLAKE2b-256 71744d5df49f2fe6fd81f36561dcf88b04ce27609e318f9d383f0ee97079a05e

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for megane-0.10.0-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 34777184a361f9acde26073f8380f7a075dacfb66ab1518bfecce810b00c42c8
MD5 406b6564399606ec949ed5ca28f61a15
BLAKE2b-256 c4549de07009e80450e39c8a4ef2a45f61b7baa99656eaf3ef9ed0b08f4425cb

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for megane-0.10.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 9b4c3fd36ca5d18ebb07f01aa1724b02094de1e53968ecc05bb16b5e11b5d9e4
MD5 4da08806e9ed3e07c2f89467116b90ce
BLAKE2b-256 39969f0b17221c6b1eeaa36fd249c68c144ccfdc4a890ddd2806f6478042ea36

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for megane-0.10.0-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 9a3a6a0ffbe41e19c9d4f35c0c38816d54fb22e58f1310b6b8c1679421a3a27e
MD5 200981abe0a38938ad36e65af3c85fb3
BLAKE2b-256 98ea119de78d7903cfd8c116d7f922961ab8df9e222ee330be7b1bf4e2bbbf50

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for megane-0.10.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 281cc2863d153de5fe4497b57a487d99a7d0c9bce6657f07a35c5647c4b9c2bb
MD5 7460bc87810e5a2c021fda290fec3987
BLAKE2b-256 47621be4ee37eb2685f917f1cec7a58d3a02df5ea082cc203f2f44c6cda82fe3

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for megane-0.10.0-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 6c2ec07632b85da8be76b5d74f99c0689f43dfbef255dfbc51765ac26e690ada
MD5 b287a29043ca287845f6b15d53d82b65
BLAKE2b-256 547cb1acec68b7eeb5a77394f9081c522b16537354bc60b6dc5667db3ec9feea

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for megane-0.10.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 55869cd66d39568e40b82818ce8d26e688a0d7e87b5fc085317e75946cfd6f92
MD5 d91dd9fe55ff53a7818ce8b97f95b77f
BLAKE2b-256 3d946e2e9d50aca31bd482ad8bb9dbd5d4952a9a6542962bd8d3384847dfb508

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for megane-0.10.0-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 b1a9c776983c377c5cc5782fe35235977e3769972d68dc8ee5915e5474569c90
MD5 49b4c70d5083b811a3a6f478e9e44381
BLAKE2b-256 b85cd4f3accc9608422c1e413ef174e7cdc97eecd9717019b6a04b6e352501be

See more details on using hashes here.

Provenance

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

0.11.0

11 files

This release

0.10.0 This release

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