OverlayViewer
Overlay viewer for comparing multiple molecular structures simultaneously.
Constructor
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 |
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.1 |
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 |
View Settings
| Parameter | Type | Description | Default |
|---|---|---|---|
viewMode |
str |
"Perspective" or "Orthographic" |
"Perspective" |
rotationMode |
str |
"TrackBall" or "Orbit" |
"TrackBall" |
Methods
show()
Display the viewer in a Jupyter notebook.
get_html()
Get the HTML content as a string.
save_html()
Save the viewer as an HTML file.
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()
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()