OverlayViewer

Overlay viewer for comparing multiple molecular structures simultaneously.

See the Overlay Comparison example for a walkthrough.

Constructor

OverlayViewer(data, index_list=None, **kwargs)

Parameters

Parameter	Type	Description	Default
`data`	`Atoms`, `List[Atoms]`, `Dict`, `str`	One or more molecular structures	Required
`index_list`	`None`, `list[int]`, `list[list[int]]`	Atom selection — see table below	`None`
`theme`	`str`	Visual theme (`"dark"`, `"spring"`, `"glass"`, `"darkgreen"`, `"simple"`, …). `None` uses the global default.	`None`
`all_visible`	`bool`	Show every overlay structure initially instead of only the first three	`False`
`visible_indices`	`list[int]`, `None`	Structure indices to show initially. Cannot be combined with `all_visible=True`.	`None`

index_list Modes

The mode is inferred automatically from the type of index_list:

Value	Mode	Behaviour
`None`	all	All atoms from every structure are used (default)
`[0, 1, 2]`	same	Same atom indices applied to every structure
`[[0, 1], [2, 3], [0, 2]]`	indices	Different atom indices per structure (length must equal number of structures)

Keyword Arguments (Settings)

Geometry Settings

Parameter	Type	Description	Default
`atomSize`	`float`	Atom sphere radius scale	`0.4`
`bondThickness`	`float`	Bond cylinder radius	`0.09`
`bondThreshold`	`float`	Bond detection threshold	`1.2`

Style Settings

Parameter	Type	Description	Default
`style`	`str`	Visual style name	`"cartoon"`
`backgroundColor`	`str`	Background color (hex)	`"#1f2937"`
`hideHydrogens`	`bool`	Hide hydrogen atoms and their bonds without removing them from the data	`False`
`showBlur`	`bool`	Apply blur to the rendered molecule canvas	`False`
`blurStrength`	`float`	Blur radius in pixels when `showBlur` is enabled	`1.5`

Color Settings

Parameter	Type	Description	Default
`colorBy`	`str`	Coloring mode	`"Atom"`
`colormap`	`str`	Colormap name (when `colorBy="Colormap"`)	`"viridis"`

colorBy Options

Value	Description
`"Atom"`	Color by element (CPK)
`"Molecule"`	Each molecule has distinct color
`"Colormap"`	Gradient colormap based on molecule index

Available Colormaps

Name	Description
`"viridis"`	Perceptually uniform (blue → green → yellow)
`"plasma"`	Perceptually uniform (purple → orange → yellow)
`"coolwarm"`	Diverging (blue → white → red)
`"jet"`	Rainbow (blue → cyan → yellow → red)
`"rainbow"`	Full spectrum
`"grayscale"`	Black to white

Display Settings

Parameter	Type	Description	Default
`showCell`	`bool`	Show unit cell	`True`
`showBond`	`bool`	Show bonds	`True`
`showShadow`	`bool`	Enable shadows	`False`
`centerMolecules`	`bool`	Center each molecule at origin before overlay	`False`
`allVisible`	`bool`	JavaScript/camelCase alias for showing every overlay structure initially	`False`
`visibleIndices`	`list[int]`, `None`	JavaScript/camelCase alias for initially visible structure indices	`None`

View Settings

Parameter	Type	Description	Default
`viewMode`	`str`	`"Orthographic"` or `"Perspective"`	`"Orthographic"`
`viewPreset`	`str`, `None`	Initial named camera direction (`"top-c"`, `"side-a"`, `"front"`, etc.)	`None`
`viewDirection`	`list[float]`, `None`	Explicit target-to-camera direction vector	`None`
`viewEuler`	`list[float]`, `None`	`[rx, ry, rz]` degrees in XYZ order, applied to `[0, 0, 1]`	`None`
`viewUp`	`list[float]`, `None`	Optional camera up-vector hint	`None`
`viewFit`	`float`	Camera fit multiplier	`1.0`
`rotationMode`	`str`	`"TrackBall"` or `"Orbit"`	`"TrackBall"`

viewDirection and preset directions are target-to-camera vectors. Presets top, bottom, front, back, left, and right use Cartesian axes. Presets top-c, bottom-c, side-a, and side-b use valid unit-cell vectors. Aliases c and top prefer the cell c axis, while a and b prefer the cell a and b axes. Missing, non-periodic, zero-length, or degenerate cells fall back to Cartesian directions.

Methods

show()

Display the viewer in a Jupyter notebook.

viewer.show(width='100%', height=600)

get_html()

Get the HTML content as a string.

html = viewer.get_html()

save_html()

Save the viewer as an HTML file.

viewer.save_html(filename)

Image export

OverlayViewer can save PNG images from Python when the optional export dependency is installed:

pip install "aseview[export]"
python -m playwright install chromium

viewer.save_png(
    "overlay.png",
    scale=2,
    transparent=False,
    background_color="#ffffff",
)

The export extra pins Playwright below 1.15 for CentOS 7/glibc 2.17 compatibility; newer Playwright browser builds may require newer glibc.

OverlayViewer.save_gif() remains unsupported because overlay GIF export is not implemented in the renderer. The CLI does not provide --save-png or --save-gif.

In the browser JavaScript module, ASEView.OverlayViewer exposes setView(viewSpec), resetView(), and savePNG(options). Export options are filename, download, returnDataUrl, scale, width, height, transparent, and backgroundColor. PNG export promises resolve with { ok: true, type: "png", filename, dataUrl?, width?, height? } or reject with an Error carrying code, message, type, and when available requestId. saveGIF(options) is intentionally unsupported and rejects with code: "unsupported_export".

UI Controls (Interactive)

The overlay viewer provides interactive controls:

Molecule Panel

Visibility toggle: Show/hide individual molecules
Opacity slider: Adjust transparency (0-100%)
Color picker: Change molecule color

Animation Controls

Play/Pause: Animate through frames
Frame slider: Manual frame selection
Speed control: Adjust playback speed

Examples

Compare Two Structures

from ase.io import read
from aseview import OverlayViewer

reactant = read("reactant.xyz")
product = read("product.xyz")

viewer = OverlayViewer([reactant, product])
viewer.show()

Atom Selection with index_list

# all (default) – show every atom
viewer = OverlayViewer([mol1, mol2, mol3])

# same – show atoms 0, 1, 2 from every structure
viewer = OverlayViewer([mol1, mol2, mol3], index_list=[0, 1, 2])

# indices – different atoms per structure
viewer = OverlayViewer(
    [mol1, mol2, mol3],
    index_list=[[0, 1, 2], [0, 1, 3], [1, 2, 3]]
)
viewer.show()

Initial Structure Visibility

# Long overlays still default to the first three visible structures.
viewer = OverlayViewer(trajectory)

# Show every structure immediately.
viewer = OverlayViewer(trajectory, all_visible=True)

# Or show only selected structures initially, such as first and last frames.
viewer = OverlayViewer(
    trajectory,
    visible_indices=[0, len(trajectory) - 1],
)
viewer.show()

Trajectory with Colormap

trajectory = read("optimization.xyz", index=":")

viewer = OverlayViewer(
    trajectory,
    colorBy="Colormap",
    colormap="viridis"
)
viewer.show()

Centered Molecules

# Center each molecule at origin for better comparison
viewer = OverlayViewer(
    [mol1, mol2, mol3],
    centerMolecules=True,
    colorBy="Molecule"
)
viewer.show()

Custom Molecule Names

Set custom names for molecules using atoms.info['name']:

from ase.build import molecule
from aseview import OverlayViewer

# Create molecules and set names
reactant = molecule("C2H6")
reactant.info['name'] = "Ethane (reactant)"

ts = molecule("C2H6")
ts.info['name'] = "Transition State"

product = molecule("C2H4")
product.info['name'] = "Ethene (product)"

viewer = OverlayViewer(
    [reactant, ts, product],
    colorBy="Molecule",
    centerMolecules=True
)
viewer.show()

Naming Convention

Without atoms.info['name'], molecules are labeled as "Molecule 1", "Molecule 2", etc. Custom names appear in the molecule control panel for easier identification.

Custom Styling

viewer = OverlayViewer(
    structures,
    style="glossy",
    colorBy="Colormap",
    colormap="plasma",
    atomSize=0.5
)
viewer.show()

Save Comparison

viewer = OverlayViewer([before, after], colorBy="Molecule")
viewer.save_html("comparison.html")