CLI Reference
Synopsis
aseview [OPTIONS] FILES...
Arguments
| Argument |
Description |
FILES |
One or more input files in any ASE-supported format (xyz, cif, pdb, vasp, etc.) |
Options
| Option |
Short |
Description |
Default |
--index |
-i |
Index or slice for trajectory selection |
All frames |
--format |
-f |
Force file format (auto-detected if not specified) |
Auto |
Index Examples
| Value |
Description |
0 |
First frame only |
-1 |
Last frame only |
: |
All frames |
0:10 |
Frames 0-9 |
::2 |
Every 2nd frame |
10:20:2 |
Frames 10-19, step 2 |
-10: |
Last 10 frames |
Viewer Options
| Option |
Short |
Description |
Default |
--viewer |
-v |
Viewer type: molecular, overlay, normal, frag, surface, surface-sequence |
Auto-selected |
Viewer Auto-Selection
- Multiple files →
overlay
- Single file with
--hess → normal
- Otherwise →
molecular
FragSelector (-v frag)
frag is never auto-selected and must be requested explicitly.
When a multi-frame file is provided only the first frame is used.
SurfaceViewer (-v surface)
CUBE-style surface viewing is requested explicitly with -v surface.
Use -O / --on-the-fly when the browser should request new single
isovalues from a local surface server.
Surface sequence (-v surface-sequence)
surface-sequence is explicit and is used for JSONL surface manifests or
extxyz trajectories whose frame metadata points to per-frame surface files.
Style Options
| Option |
Description |
Default |
--style |
Visual style: default, 2d, cartoon, neon, glossy, metallic, cinematic, rowan, grey, bubble |
cartoon |
--theme, -t |
Visual theme |
global default (dark) |
Available Styles
| Style |
Description |
default |
Standard CPK coloring |
2d |
Flat, high-contrast 2D-style rendering |
cartoon |
Cartoon style with black bonds |
neon |
Glowing neon effect |
glossy |
Shiny reflective surface |
metallic |
Metallic appearance |
cinematic |
Cinematic glossy ball-and-stick style |
rowan |
Rowan-inspired style |
grey |
Greyscale rendering |
bubble |
Bubble-like appearance |
Available Themes
| Theme |
Description |
dark |
Default dark theme with deep grey background |
spring |
Light pastel theme with bright, airy colors |
glass |
Glassmorphism theme with frosted translucent panels |
darkgreen |
Dark GitHub-style theme with green accent |
simple |
Light macOS-style theme with colorful gradient background |
Overlay Options
| Option |
Description |
Default |
--cmap |
Colormap for gradient coloring |
None |
Available Colormaps
| Colormap |
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 |
Normal Mode Options
| Option |
Description |
Default |
--hess |
Path to Hessian file (ORCA .hess or VASP OUTCAR, auto-detected) |
None |
Fragment Selector Options
| Option |
Short |
Description |
Default |
--bond-threshold |
-bt |
Bond detection scale factor (covalent-radii sum multiplier) |
1.2 |
Surface Options
| Option |
Short |
Description |
Default |
--surface-kind |
|
Surface kind: orbital, density, or delta_density |
orbital |
--isovalue |
|
Surface level: auto, a number, comma list, start:stop:count, or linspace(start,stop,count) |
auto |
--surface-style |
|
Surface style: solid, mesh, contour, or dot |
solid |
--surface-path-key |
|
Read per-frame surface paths from this extxyz Atoms.info key for -v surface-sequence |
None |
--surface-label-key |
|
Read frame labels from this extxyz Atoms.info key |
surface_label |
--surface-kind-key |
|
Read per-frame surface kind from this extxyz Atoms.info key |
surface_kind |
--on-the-fly |
-O |
Serve a local surface server and recompute single isovalues from the browser |
False |
start:stop:count and linspace(start,stop,count) include both endpoints,
for example 0.03:0.09:4.
Output Options
| Option |
Short |
Description |
Default |
--output |
-o |
Save HTML to file instead of serving |
None |
--port |
-p |
HTTP server port |
8080 |
--no-browser |
|
Don't open browser automatically |
False |
Utility Options
| Option |
Short |
Description |
Default |
--kill |
-k |
Kill existing process on port before starting |
False |
--help |
-h |
Show help message |
|
Examples
Basic Viewing
# Single structure
aseview molecule.xyz
# Crystal structure
aseview structure.cif
# Specific style
aseview molecule.xyz --style neon
Trajectory
# All frames with animation
aseview trajectory.xyz
# Subset of frames
aseview trajectory.xyz -i 0:100:5
# Save as HTML
aseview trajectory.xyz -o trajectory.html
Overlay Comparison
# Compare two structures
aseview reactant.xyz product.xyz
# Trajectory overlay with colormap
aseview optimization.xyz -v overlay --cmap viridis
# Multiple files
aseview conf1.xyz conf2.xyz conf3.xyz --cmap plasma
Normal Modes
# ORCA Hessian
aseview molecule.xyz --hess orca.hess
# VASP OUTCAR (auto-detected)
aseview POSCAR --hess OUTCAR
# Explicit viewer type
aseview molecule.xyz --hess orca.hess -v normal
Fragment Selector
# Open interactive 2D+3D fragment selector
aseview molecule.xyz -v frag
# Adjust bond detection threshold
aseview molecule.xyz -v frag --bond-threshold 1.4
# Save as standalone HTML (open in browser later)
aseview molecule.xyz -v frag -o selector.html
Surface Viewer
# Render a contour orbital surface with multiple precomputed isovalues
aseview HOMO.cube -v surface --surface-style contour --isovalue 0.03:0.09:4
# Density surface with four levels
aseview density.cube -v surface --surface-kind density --isovalue 0.001:0.004:4
# On-the-fly single-isovalue surface server
aseview HOMO.cube -v surface -O
# Surface sequence from an explicit JSONL manifest
aseview frames.jsonl -v surface-sequence --surface-kind orbital --isovalue 0.03
# Surface sequence from extxyz frame metadata
aseview traj.extxyz -v surface-sequence --surface-path-key surface_path --surface-kind density
Server Options
# Custom port
aseview molecule.xyz -p 9000
# Kill existing server first
aseview molecule.xyz -k -p 8080
# No auto-open browser
aseview molecule.xyz --no-browser
SSH Forwarding
# Server side
aseview molecule.xyz -p 8080 --no-browser
# Client side
ssh -L 8080:localhost:8080 user@server
# Then open http://localhost:8080 in browser