Skip to main content

Getting Started

Prerequisites​

  • Python 3.10 or later
  • Node.js 22+ (for web development)

Installation​

Python (PyPI)​

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:

import megane

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 Python Pipeline API.

Standalone web app (megane serve)​

The easiest way to run megane serve locally is with 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

For running from source, see the Standalone web app guide.

React component (npm)​

The MeganeViewer React component is pipeline-store-driven — it manages its own snapshot, bonds, trajectory, etc. internally. Host apps just supply the file-ingestion callback that pushes the chosen file into the global pipeline store:

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"
    />
  );
}

For multiple independent viewers per page (e.g. embedding in MDX docs), use PipelineViewer instead — see the React component (npm) guide.

Supported File Formats​

FormatExtensionDescription
PDB.pdbProtein Data Bank — most common molecular structure format
GRO.groGROMACS structure file
XYZ.xyz, .jxyzSimple cartesian coordinate format (single- or multi-frame); .jxyz is Jmol's second name for it
MOL.molMDL Molfile (V2000) — small molecules with bond information
SDF.sdfMDL SDfile — uses the MOL V2000 parser
MOL2.mol2Tripos MOL2
CIF.cifCrystallographic Information File — the asymmetric unit is expanded to the full cell on load
mmCIF.mmcifMacromolecular CIF (PDBx/mmCIF) — large structure databases
LAMMPS data.data, .lammpsLAMMPS data file
AMBER topology.prmtopAMBER parameter/topology file (no coordinates)
VASPPOSCAR, CONTCAR, XDATCAR, .vaspVASP crystal structure; XDATCAR is multi-frame. Matched by filename as well as extension
Molden.moldenMolden output — [Atoms] geometry and [GEOMETRIES] XYZ optimisation frames
XCrySDen.xsf, .axsfXCrySDen structure; .axsf is a multi-frame animation with optional per-atom forces
CML.cmlChemical Markup Language (Open Babel / Avogadro / ChemDraw)
Chem3D XML.c3xmlPerkinElmer Chem3D / ChemDraw XML
Odyssey.xodydata, .odydataWavefunction Odyssey — XML and older Spartan-style text layouts
CASTEP magres.magresCASTEP / Quantum ESPRESSO NMR output — the [atoms] block
GAMESS output.gamessGAMESS (US / Firefly) log — each coordinate block becomes a frame
CASTEP phonon.phononCASTEP lattice-dynamics output (structure half)
XTC.xtcGROMACS compressed trajectory
DCD.dcdCHARMM/NAMD binary trajectory
ASE .traj.trajASE trajectory (ULM binary format)
LAMMPS dump.lammpstrj, .dump, .trjLAMMPS dump — opens standalone as a multi-frame structure, or attaches to a topology
AMBER NetCDF.ncAMBER compressed trajectory (NetCDF format)
Gaussian CUBE.cube, .cubVolumetric grid, rendered as an isosurface over a loaded structure
OpenDX.dxVolumetric scalar field (APBS electrostatics)
JCAMP-DX.jdx, .jcamp, .dxIR / NMR / MS / UV-Vis spectra, drawn by the SpectrumPlot node
GROMACS topology.topBond connectivity for the Add Bond node
CHARMM/NAMD PSF.psfBond connectivity for the Add Bond node

Not every host opens every extension from its native file picker — see Platform Support for the per-host matrix.

Next Steps​