Skip to content

Utilities and Errors

This page covers the small public helpers exported from aseview.__all__. For viewer-specific constructor settings, use the dedicated API pages: MolecularViewer, SurfaceViewer, OverlayViewer, NormalViewer, FragSelector, and LiteViewer.

Public import surface

from aseview import (
    MolecularData,
    MolecularViewer,
    SurfaceViewer,
    OverlayViewer,
    NormalViewer,
    FragSelector,
    LiteViewer,
    view,
    set_theme,
    get_theme,
    list_themes,
    ImageExportError,
)

These names are the supported top-level import surface. Lower-level modules under aseview.surface_*, parser helpers, and template internals are implementation details unless they are promoted here.

MolecularData

MolecularData converts ASE Atoms objects into the JSON-compatible frame contract consumed by the browser viewers.

from ase.build import molecule
from aseview import MolecularData

atoms = molecule("H2O")
frame = MolecularData.from_atoms(atoms)

assert frame["symbols"] == ["O", "H", "H"]
assert len(frame["positions"]) == 3

The serialized frame includes only values that are present and JSON-safe. Cell, PBC, forces, charges, magnetic moments, arrays, energy, and name metadata are preserved when they are unambiguous. aseview does not infer energy or forces provenance: if a value is present it is passed through for display/export; if it is absent or non-finite it is omitted rather than fabricated.

Fixed atoms and move masks

fixed is an index list in the displayed atom order:

{"fixed": [0, 3, 4]}

It is not a boolean mask. Boolean fixed masks and three-axis selective-dynamics masks live under arrays.fixed and arrays.move_mask when those arrays are available. When a viewer is created from a filtered or duplicated index list, the Python serializer remaps fixed indices to the displayed output atoms.

Theme helpers

import aseview

aseview.list_themes()   # ['dark', 'darkgreen', 'glass', 'simple', 'spring']
aseview.get_theme()     # current global default
aseview.set_theme("spring")

The global theme affects new MolecularViewer, SurfaceViewer, OverlayViewer, NormalViewer, and FragSelector instances when their constructor theme= is None. LiteViewer uses its fixed lightweight template and does not accept a per-instance theme.

Every full theme directory contains five runtime templates: molecular_viewer.html, normal_viewer.html, overlay_viewer.html, frag_selector.html, and surface_viewer.html.

view()

view() is a notebook-friendly shorthand for creating a LiteViewer, showing it immediately, and returning it:

from ase.build import molecule
from aseview import view

atoms = molecule("H2O")
viewer = view(atoms, styles="cinematic", hide_hs=True, center=True)

Use MolecularViewer directly when you need the full settings panel, themed templates, trajectory plots, or the complete molecular viewer API.

ImageExportError

ImageExportError is raised by Python PNG/GIF export helpers when browser export fails or returns invalid image data.

from aseview import ImageExportError, MolecularViewer

try:
    MolecularViewer(atoms).save_png("molecule.png")
except ImageExportError as exc:
    print(f"image export failed: {exc}")

The error means no valid image was confirmed. The export path validates browser data before writing the destination file, so corrupt or non-image payloads fail before replacing output.