Orientation

Auto-orientation

Auto-orientation is on by default. xyzrender aligns the molecule so the axis of largest positional variance lies along the x-axis (PCA), giving a consistent front-facing view.

xyzrender molecule.xyz            # auto-oriented (default)
xyzrender molecule.xyz --no-orient  # raw coordinates as-is

Auto-orientation is disabled automatically when reading from stdin.

If --only or --exclude is used, the atom filter is applied first and auto-orientation is computed from the atoms that remain in the render.

Interactive rotation (-I)

The -I flag opens the molecule in an interactive viewer for rotation. xyzrender captures the rotated coordinates and renders from those.

Two viewer backends are supported via --viewer:

vmol (default)

Opens the molecule in the v molecular viewer by Ksenia Briling @briling. Rotate with the mouse or arrow keys, then press z to output the orientation and q or Esc to quit.

xyzrender molecule.xyz -I               # uses vmol by default
xyzrender molecule.xyz -I --viewer vmol # explicit

Requires pip install xyzrender[v] (or pip install vmol).

ASE GUI

Opens the molecule in ASE’s built-in graphical viewer. Rotate with the mouse, then close the window to confirm the orientation.

xyzrender molecule.xyz -I --viewer ase

Requires pip install xyzrender[cif] (or pip install ase).

For periodic structures, the unit cell is shown in the viewer automatically.

Orientation reference (--ref)

The --ref flag saves or loads a reference orientation for consistent rendering across multiple files (e.g. a batch of MO cube files).

First render — file does not exist yet, PCA-oriented positions are saved:

xyzrender homo.cube --mo --ref              # saves reference.xyz
xyzrender homo.cube --mo --ref custom.xyz   # saves custom.xyz

Subsequent renders — file exists, molecule is Kabsch-aligned to it:

xyzrender lumo.cube --mo --ref              # loads reference.xyz, same orientation
xyzrender lumo.cube --mo --ref custom.xyz   # loads custom.xyz

When loading an existing reference, --orient is ignored — the reference file IS the orientation.

Combined with -I

Orient interactively once, then reuse:

xyzrender homo.cube --mo -I --ref           # orient in viewer, save
xyzrender lumo.cube --mo --ref              # load, same orientation

If the reference file already exists, -I is skipped (the viewer is not opened).

Python API

from xyzrender import render, load

mol1 = load("homo.cube")
render(mol1, mo=True, ref="reference.xyz")   # save

mol2 = load("lumo.cube")
render(mol2, mo=True, ref="reference.xyz")   # load, same orientation

Consistent orientation across a chemical series

--ref works across related compounds with different substituents, atom counts, or conformations. The shared scaffold is detected automatically — molecules are aligned on their largest common connected substructure. This gives consistent orientations across a series of derivatives, useful for comparing substituent effects or building figure panels:

# Orient the first compound interactively and save the reference
xyzrender catalyst_a.xyz -I --ref series.xyz

# All derivatives align to the same scaffold, regardless of substitution
xyzrender catalyst_b.xyz --ref series.xyz   # different R-group
xyzrender catalyst_c.xyz --ref series.xyz   # different atom count
xyzrender catalyst_d.xyz --ref series.xyz   # different heterocycle

Note

--ref is not supported for periodic structures (inputs loaded with cell=True or crystal formats). Use -I for interactive orientation of crystals.

Piping from v

We can also pipe from v (or vmol) directly when working with .xyz files:

v molecule.xyz | xyzrender

Orient the molecule, press z to output reoriented coordinates, then q or esc to close.

Viewer installation

Both viewer backends are optional dependencies:

pip install 'xyzrender[v]'    # vmol (v viewer)
pip install 'xyzrender[cif]'  # ASE GUI
pip install 'xyzrender[all]'  # both