xyzrender 0.2.6

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, wire, and dot styles
• Styling — highlight & molecule color, radius scaling (by element, category, or index), 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 — RMSD-align two structures and render in contrasting colours; works across different atom counts via automatic scaffold detection
• 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, skeletal, bubble, 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
# latest development version:
pip install --upgrade git+https://github.com/aligfellow/xyzrender.git

Or with uv:

uv tool install xyzrender
# latest development version:
uv tool install git+https://github.com/aligfellow/xyzrender.git

To test without installing, you can use uvx

uvx xyzrender 

From Source:

Using pip:

git clone https://github.com/aligfellow/xyzrender.git
cd xyzrender
pip install .
# install in editable mode
pip install -e .
# or straight from git
pip install git+https://github.com/aligfellow/xyzrender.git

For more information on installation and optional dependencies (crystal, SMILES, CIF, GIF), see the installation docs

Quick start

xyzrender caffeine.xyz                                    # render XYZ → SVG
xyzrender calc.out                                        # QM output (ORCA, Gaussian, etc.)
xyzrender caffeine.xyz -o render.png                      # explicit output path/format
xyzrender caffeine.xyz --config paton --hy -o styled.svg  # preset + show hydrogens
xyzrender caffeine.xyz --config pmol --hy -o pmol.svg     # ball-and-stick + element-coloured bonds
xyzrender caffeine.xyz --config graph -o graph.svg        # minimalist graph-style rendering
xyzrender sn2.out --ts --hy -o ts.svg                     # auto-detect TS bonds
xyzrender caffeine.xyz --gif-rot -go caffeine.gif         # rotation GIF

Python API

from xyzrender import load, render, render_gif

mol = load("caffeine.xyz")
render(mol)                          # displays inline in Jupyter
render(mol, output="caffeine.svg")   # save as SVG/PNG/PDF

render(mol, config="paton", hy=True) # all CLI flags as kwargs
render_gif(mol, gif_rot="y")         # rotation GIF

For the full Python API (render options, build_config(), measure(), load() kwargs, return types), see the Python API guide or the runnable examples/examples.ipynb notebook.

Feature gallery

Presets

Default	Flat	Paton (PyMOL-like)	Pmol

Skeletal	Bubble	Tube	BTube

Wire	Graph	MTube

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

Radius scaling

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

Depth of field

DoF	Rotation

Structural overlay & ensemble

Overlay	Custom colour	Cross-molecule

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

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	TS + NCI + vdW + rotation	Trajectory	TS

Overlay rotation	MO	Density

Vectors	Diffuse / assembly

For usage details and CLI commands, see the examples and CLI reference in the docs.

Documentation

Full documentation at xyzrender.readthedocs.io:

• Installation — PyPI, uv, source, optional dependencies
• CLI Quickstart — getting started from the command line
• Python API Guide — render options, build_config(), measure(), return types
• Examples — presets, overlays, surfaces, crystal, annotations, and more
• Configuration — presets, custom JSON, styling flags
• CLI Reference — all flags
• Input Formats — XYZ, QM output, SDF, PDB, SMILES, CIF, cube files
• API Reference — auto-generated from docstrings

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.

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 (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
• Vinicius Port (@caprilesport) — v binary path discovery
• Lucas Attia (@lucasattia) — transparent background

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.