aseview

Molecular structure viewer for ASE (Atomic Simulation Environment).

 ·   ·   · 

Features

• Interactive structure, trajectory, overlay, normal-mode, and fragment-selection viewers
• Optional cube-backed SurfaceViewer for orbital, density, and delta-density isosurfaces
• ASE-backed Python API and CLI, plus a browser-only JavaScript module
• Cell/PBC display, bonds, hydrogen bonds, charges, magnetic moments, forces, and fixed-atom constraint highlighting
• Energy and max-force (Fmax) trajectory plots with independent force-plot toggling
• Radius Contrast control for reducing or restoring element-radius size differences
• Visual styles including default, cartoon, glossy, metallic, cinematic, rowan, bubble, neon, grey, and 2D
• Hide hydrogens without deleting data, and apply optional render blur to saved images
• Clipboard export for current frame or full trajectory as xyz, extxyz, cif, or POSCAR
• Cell-aware camera presets and browser PNG/GIF export for rendered viewers

Installation

aseview 0.0.14 and newer require Python 3.11 or newer. If you need Python 3.10 support, install the last compatible release, 0.0.13:

pip install "aseview<0.0.14"

Recommended:

uv venv -p 3.11
uv pip install aseview
aseview -h

pip install aseview

For development:

git clone https://github.com/kangmg/aseview.git
cd aseview
python3 scripts/run_locked_verification.py python -m pytest tests/test_imports.py -q

Contributor validation uses the committed hash-locked verification runner so docs, release artifacts, and CI checks exercise the declared dependency locks instead of an editable checkout install.

See Installation for optional PNG/GIF export setup and dependency details.

For Gaussian CUBE orbital or density surfaces, install the optional surface dependencies. This uses the published cvve package for cube/CHGCAR grid parsing:

pip install "aseview[surface]"

CLI Usage

aseview molecule.xyz
aseview trajectory.xyz -i 0:10 --style neon

See the CLI Reference for the full option list — frame indexing, viewer/style/theme selection, overlay colormaps, normal-mode Hessian input, and server options. For SSH port forwarding to a remote server, see Quick Start.

Jupyter Notebook

from ase.io import read
from aseview import MolecularViewer

atoms = read('molecule.xyz')
viewer = MolecularViewer(atoms)
viewer.show()

# PyMOL-style quick render, no control panel
from aseview import view

view(atoms, styles='cinematic', hide_hs=True, center=True)

from aseview import SurfaceViewer

viewer = SurfaceViewer(
    "HOMO.cube",
    surface_kind="orbital",
    isovalue="0.03:0.09:4",
    positive_color="#ef4444",
    negative_color="#2563eb",
    opacity_ramp=[0.25, 0.45, 0.65, 0.8],
)
viewer.show()

Surface isovalues accept explicit lists, comma lists, start:stop:count, and linspace(start,stop,count) specs. Density grids accept signed nonzero levels; negative shells use negative_color. Orbital and delta-density values are nonzero magnitudes and always generate both signed phases. Contour surfaces use a denser default extraction grid for tighter line spacing.

Every viewer accepts extensive settings — styles, camera presets, energy/force plots, constraint and polyhedron highlighting, charge/magmom coloring, and more. See the Python API reference for each class:

• MolecularViewer — structures and trajectories
• SurfaceViewer — cube-backed orbital, density, and delta-density isosurfaces
• LiteViewer / view() — lightweight wrapper, no control panel
• OverlayViewer — compare multiple structures
• NormalViewer — vibrational modes from ASE, ORCA .hess, or VASP OUTCAR
• FragSelector — synchronized 2D/3D fragment picker

Viewer Types

VS Code Extension

The vscode-extension/ package provides a native VS Code custom editor for structure files. It uses ase-ts for parsing and writing, so it does not require a Python runtime inside VS Code.

Supported default file patterns include *.xyz, *.extxyz, *.cif, *.pdb, *.vasp, POSCAR, and CONTCAR. See vscode-extension/README.md for the extension's settings (default viewer/style, read format/index) and commands.

cd vscode-extension
npm install
npm run compile
npm run package

Install the generated .vsix from VS Code with Extensions -> Install from VSIX.... On tag releases, the VS Code workflow builds the same verified package and attaches aseview-vscode-<version>.vsix plus aseview-latest.vsix to the GitHub Release assets.

Themes

aseview ships with multiple visual themes. Each theme is a complete HTML template set that controls the viewer's colour scheme, background, and UI style.

aseview molecule.xyz --theme spring
aseview molecule.xyz -t glass -o out.html

See the Theming guide for the Python/JavaScript theme API and instructions on creating custom themes.

Each full theme directory contains five runtime templates: molecular_viewer.html, normal_viewer.html, overlay_viewer.html, frag_selector.html, and surface_viewer.html. LiteViewer uses its own fixed lightweight template and is not themed per instance.

JavaScript Module

Use aseview in any web page without Python:

<div id="viewer" style="width:100%; height:500px;"></div>

<script src="https://cdn.jsdelivr.net/gh/kangmg/aseview@main/aseview/static/js/aseview.js"></script>
<script>
    const viewer = new ASEView.MolecularViewer('#viewer', { viewPreset: 'top-c' });
    viewer.setData({
        symbols: ['O', 'H', 'H'],
        positions: [
            [0.0, 0.0, 0.117],
            [0.0, 0.757, -0.469],
            [0.0, -0.757, -0.469]
        ]
    });

    viewer.setView({ preset: 'front' }).then(() => {
        return viewer.savePNG({ returnDataUrl: true, download: false });
    }).then((png) => {
        console.log(png.filename, png.dataUrl.length);
    });
</script>

See the JavaScript Module documentation for the full API reference — camera control, PNG/GIF export options and promise shapes — or try the live demo and playground.

Python viewers expose the equivalent headless save_png() and save_gif() methods when installed with the export extra (see Installation).

Supported Formats

Input files are handled through ASE in Python and ase-ts in the VS Code extension. Common formats include xyz, extxyz, cif, pdb, vasp, POSCAR, and CONTCAR — see File Formats for the full list and viewer clipboard export details.

License

MIT