xyzrender 0.3.1

Publication-quality molecular graphics.

xyzrender: Publication-quality molecular graphics.

Render molecular structures as publication-quality SVG, PNG, PDF, and animated GIF from XYZ, mol/SDF, MOL2, PDB, SMILES, CIF, cube files, quantum chemistry input or output — from the command line or from Python/Jupyter.

xyzrender turns molecular structures into clean vector SVG graphics — plus PNG, PDF, and animated GIF — ready for papers, presentations, and supporting information. It reads XYZ, mol/SDF, MOL2, PDB, SMILES, CIF, cube files, and QM input/output files from Gaussian, ORCA, NWChem, Q-Chem, Psi4, MOPAC, GAMESS, Turbomole, and periodic codes (VASP, Quantum ESPRESSO, SIESTA, ABINIT, CP2K). The SVG rendering approach is built on and inspired by xyz2svg by Ksenia Briling @briling.

Most molecular visualisation tools require manual setup: loading files into a GUI, tweaking camera angles, exporting at the right resolution and adding specific TS or NCI bonds. xyzrender skips this. One command gives you a (mostly) oriented, depth-cued structure with correct bond orders, aromatic ring rendering, automatic bond connectivity, with automatic TS / NCI bond detection. Orientation control is available through an interface to v by Ksenia Briling @briling.

What it handles out of the box:

• Bond orders and aromaticity — double bonds, triple bonds, and aromatic ring notation detected automatically from geometry via xyzgraph
• Transition state bonds — forming/breaking bonds rendered as dashed lines, detected automatically from imaginary frequency vibrations via graphRC
• Stereochemistry labels — R/S, E/Z, axial, planar (metallocene and CIP), and helical chirality labels detected and annotated automatically via xyzgraph
• Non-covalent interactions — hydrogen bonds and other weak interactions shown as dotted lines, detected automatically via xyzgraph
• Bond display rules — selectively hide or add bonds using element categories (M, sbm, L, het), element pairs (M-L, Fe-het), pi-coordination (M-pi), or atom indices; haptic mode replaces pi-coordination fans with single centroid bonds
• Surfaces — molecular orbitals, electron density, ESP colormapping, NCI surfaces, and vdW spheres; solid, mesh, contour, and dot styles; lobe outlines for opaque MOs; interlocked-silhouette vdW spheres based on CineMol-style
• Styling — highlight & molecule color, radius scaling (by element, category, or index), per-atom fill opacity (bond-agnostic), style regions, atom property colormaps with colorbar, and depth-of-field / depth-fog effects
• Annotations — distances, angles, dihedrals, custom labels, atom indices, and 3D vector arrows (dipoles, forces, fields)
• Structural overlay — overlay two structures in contrasting colours; auto-aligned by best-fit (centres on the metals when present, falls back to fuzzy substructure matching that tolerates atom substitutions, then geometric best-fit). Override with --align-atoms. Per-overlay style knobs; --no-align keeps raw coords
• Conformer ensemble — overlay all frames from a multi-frame XYZ trajectory, with palette colouring and opacity control
• Convex hull, hull faces & pores — semi-transparent facets over selected atoms or rings, exposed faces of molecular cages, and pore rendering
• GIF animations — rotation, TS vibration, trajectory, diffuse/assembly, and depth-of-field animations
• Input formats — XYZ, mol/SDF, MOL2, PDB, SMILES, CIF, cube files, and QM input/output from Gaussian, ORCA, NWChem, Q-Chem, Psi4, MOPAC, GAMESS, Turbomole, CP2K, VASP, Quantum ESPRESSO, SIESTA, and ABINIT
• Crystal / periodic structures — unit cell box, ghost atoms, supercells, and crystallographic axis arrows; auto-detected from VASP POSCAR, QE pw.in, SIESTA FDF, ABINIT, CP2K, and extXYZ Lattice= headers
• Multiple output formats — vector SVG (default), PNG, PDF, and GIF — all from the same command

Preconfigured but extensible. Built-in presets (default, flat, paton, pmol, skeletal, bubble, vdw, tube, mtube, btube, wire, graph) cover common use cases. Every setting — colors, radii, bond widths, gradients, fog — can be overridden via CLI flags or a custom JSON config file.

xyzrender caffeine.xyz                          # SVG with sensible defaults
xyzrender ts.out --ts -o figure.png             # TS with dashed bonds as PNG
xyzrender caffeine.xyz --gif-rot -go movie.gif  # rotation GIF for slides

See web app by @BNNLab xyzrender-web.streamlit.app.

Installation

pip install xyzrender                                              # stable from PyPI
uv tool install xyzrender                                          # or via uv
uvx xyzrender mol.xyz                                              # try without installing
pip install git+https://github.com/aligfellow/xyzrender.git        # from source

Optional extras ([smi], [cif], [v], [all]) and full setup in the installation docs.

Quick start

xyzrender caffeine.xyz                            # XYZ → SVG, auto-oriented
xyzrender calc.out --ts                           # QM output with TS bonds
xyzrender caffeine.xyz --config pmol --hy         # preset + hydrogens
xyzrender caffeine.xyz --gif-rot -go caffeine.gif # rotation GIF

from xyzrender import load, render, render_gif

mol = load("caffeine.xyz")
render(mol)                          # displays inline in Jupyter
render(mol, config="paton", hy=True) # any CLI flag works as a kwarg
render_gif(mol, gif_rot="y")

Full usage, the Python API guide, every flag, and runnable examples live in the documentation and the examples/examples.ipynb notebook.

Feature gallery

Presets

Default	Flat	Paton (PyMOL-like)	Pmol

Skeletal	Bubble	Tube	BTube

Wire	Graph	MTube	vdW

MTube + unbond pi	haptic

Style regions

Tube + ball-stick region	Tube + ball-stick, NCI, vdW

Display options

All H	Some H	No H	Aromatic	Kekule

vdW spheres

All atoms	Partial	Paton-style

Convex hull

Benzene ring	Anthracene rings	Auto rings	Rotation

Hull faces & pore detection

Buckyball faces	Buckyball pore	MOF-5 faces	MOF-5 pore	MOF-5 combo	Rotation

Highlight & molecule color

Default (orchid)	Custom colour	Multi-group	Mol color + highlight

Single atom scaled (Co ×2)	Multi-group (N,O ×1.4 + H ×0.8)	Per-atom opacity + radius scale

Depth of field / Glow

DoF	Rotation	Glow (N,O atoms)

Structural overlay & ensemble

Overlay	Custom colour	Cross-molecule	Per-overlay style

Ensemble (CPK)	Ensemble (viridis)

Transition states & NCI

Auto TS	Manual TS	Auto NCI	TS + NCI custom colours	QM output

Annotations & labels

Distances + angles + dihedrals	Custom labels	TS with labels

Stereochemistry labels

Isothiourea (R/S, E/Z, planar)	TS with stereo (Mn-H₂, --ts --stereo)

Atom property colormap

Mulliken charges (rotation)	Symmetric range	With colorbar

Surfaces (cube files)

MO (HOMO)	MO (LUMO)	Density

ESP	ESP + colorbar	ESP + coolwarm	ESP fixed range (±0.03)

MO mesh	MO contour	MO dot	Density contour

NCI surface (H-bond)	NCI surface (pi-stack)	NCI mesh	Vector arrows

File formats

PDB	SMILES

Crystal / periodic structures

Unit cell	Rotation	VASP	Supercell 2×2×1	Viewing direction

GIF animations

Rotation	Bounce (50deg)	Trajectory (per-frame bonds)

TS + NCI + vdW + rotation	Trajectory	TS

Overlay rotation	MO	Density

Vectors	Diffuse / assembly

Each row in the gallery has its corresponding commands and Python snippets in the docs examples; every flag is listed in the CLI reference.

License

MIT

Acknowledgements

The SVG rendering in xyzrender is built on and heavily inspired by xyz2svg. The CPK colour scheme, core SVG atom/bond rendering logic, fog, and overall approach originate from that project.

• Ksenia Briling (@briling) — xyz2svg and v
• Iñigo Iribarren Aguirre (@iribirii) — radial gradient (pseudo-3D) rendering from xyz2svg.

The interlocked-spheres rendering used by --config vdw and the --vdw overlay is adapted from CineMol by David Meijer.

• D. Meijer, M.H. Medema and J.J.J. van der Hooft, J. Cheminform., 2024, 16, 58 (DOI).

Key dependencies:

• xyzgraph — bond connectivity, bond orders, aromaticity detection and non-covalent interactions from molecular geometry
• graphRC — reaction coordinate analysis and TS bond detection from imaginary frequency vibrations
• cclib — parsing quantum chemistry output files (ORCA, Gaussian, Q-Chem, etc.)
• CairoSVG — SVG to PNG/PDF conversion
• Pillow — GIF frame assembly
• resvg-py — SVG to PNG conversion preserving SVG effects

Falls back to CairoSVG automatically (filters silently ignored). SVG output always contains the filters regardless.

Optional dependencies:

• rdkit — SMILES 3D embedding (pip install 'xyzrender[smi]')
• ase — CIF parsing, and ASE viewer integration (pip install 'xyzrender[cif]')
• v — interactive molecule orientation (pip install xyzrender[v], Linux only, not included into [all])

Contributors:

• Ksenia Briling (@briling) — vmol integration and the xyz2svg foundation
• Sander Cohen-Janes (@scohenjanes5) — crystal/periodic structure support (VASP, Quantum ESPRESSO, ghost atoms, crystallographic axes), vector annotations and gif parallelisation, gaussian input parsing
• Rubén Laplaza (@rlaplaza) — convex hull facets
• Iñigo Iribarren Aguirre (@iribirii) — logo design, radial gradients respecting colour space (pseudo-3D), skeletal rendering, ensemble display, supercell projection, metal tube preset
• James O'Brien (@JamesOBrien2) — stereochemistry detection and integration, nci/ts colour control, graph styling, pmol styling, colour palette extension, ase viewer integration, igmh cubes
• Vinicius Port (@caprilesport) — v binary path discovery
• Lucas Attia (@lucasattia) — transparent background
• Jonathan Di Pietro (@jonathandip) — CVD colour palettes

Citation

xyzrender uses xyzgraph and graphRC for all molecular graph construction — bond orders, aromaticity detection, NCI interactions, and TS bond detection. If you use xyzrender in published work, please cite:

A.S. Goodfellow* and B.N. Nguyen, J. Chem. Theory Comput., 2026, DOI: 10.1021/acs.jctc.5c02073. Preprint here.

BibTeX

@article{goodfellow2026xyzgraph,
  author  = {Goodfellow, A.S. and Nguyen, B.N.},
  title   = {Graph-Based Internal Coordinate Analysis for Transition State Characterization},
  journal = {J. Chem. Theory Comput.},
  year    = {2026},
  doi     = {10.1021/acs.jctc.5c02073},
}

Development

Information on dev setup and CI

Requires uv and just.

git clone https://github.com/aligfellow/xyzrender.git
cd xyzrender
just setup   # install dev dependencies
just check   # lint + type-check + tests

Command	Description
just check	Run lint + type-check + tests
just lint	Format and lint with ruff
just type	Type-check with ty
just test	Run pytest with coverage
just fix	Auto-fix lint issues
just build	Build distribution
just setup	Install all dev dependencies

CI

GitHub Actions runs lint, type-check, and tests on every push to main and every PR targeting main. Coverage is uploaded to Codecov.

Template

Generated from aligfellow/python-template.

Updating from the template

If this project was created with copier, you can pull in upstream template improvements:

# Run from the project root
copier update --trust

This will:

1. Fetch the latest version of the template
2. Re-ask any questions whose defaults have changed
3. Re-render the templated files with your existing answers
4. Apply the changes as a diff — your project-specific edits are preserved via a three-way merge

If there are conflicts (e.g. you modified the justfile and so did the template), copier will leave standard merge conflict markers (<<<<<<< / >>>>>>>) for you to resolve manually.

The --trust flag is required because the template defines tasks (used for git init on first copy). The tasks don't run during update, but copier requires trust for any template that declares them.

Requires that the project was originally created with copier copy, not the plain GitHub "Use this template" button.