xyzrender

xyzrender is a tool for generating publication-quality molecular graphics in SVG, PNG, PDF, and animated GIF formats. It supports a wide range of input formats including XYZ, mol/SDF, MOL2, PDB, SMILES, CIF, SHELXL, cube files, and various quantum chemistry input/output files (Gaussian, ORCA, NWChem, etc.).

Key features include:

• Automatic Detection: Bond orders, aromaticity, transition state (TS) bonds, stereochemistry labels, and non-covalent interactions (e.g., hydrogen bonds).
• Advanced Rendering: Molecular orbitals, electron density, vdW spheres, convex hulls, and pore detection.
• Animations: Rotation, TS vibration, trajectory, and depth-of-field animations.
• Structural Overlays: Overlaying two structures with automatic alignment or manual atom alignment.
• Presets: Built-in styles like default, flat, paton, pmol, skeletal, bubble, vdw, tube, mtube, btube, wire, and graph.

xyzrender supports a wide range of publication-quality molecular graphics, including:

• Presets: Various rendering styles like Default, Flat, Paton (PyMOL-like), Pmol, Skeletal, Bubble, Tube, BTube, Wire, Graph, MTube, vdW, and haptic.
• Style Regions: Defining specific regions (e.g., Tube + ball-stick) and combining them with NCI or vdW.
• Display Options: Controlling hydrogen visibility (All H, Some H, No H), aromaticity, and Kekule structures.
• vdW Spheres: Rendering Van der Waals spheres in All atoms, Partial, or Paton-style.
• Convex Hull: Generating hulls for rings (Benzene, Anthracene) or automatic ring detection.
• Hull Faces & Pore Detection: Visualizing faces and pores for structures like Buckyballs or MOFs.
• Highlight & Color: Custom molecule coloring, multi-group highlighting, and per-atom scaling (radius/opacity).
• Depth of Field & Glow: Adding cinematic effects like DoF and atom-specific glows.
• Structural Overlays & Ensembles: Overlaying molecules with custom colors or rendering ensembles using spectral, CPK, or viridis color maps.
• Transition States (TS) & NCI: Automatic or manual TS detection, Non-Covalent Interaction (NCI) surfaces, and QM output integration.
• Annotations: Distances, angles, dihedrals, and custom labels.
• Stereochemistry: Labels for R/S, E/Z, and planar configurations.
• Atom Property Colormaps: Mapping properties like Mulliken charges to colors.
• Surfaces: Rendering Molecular Orbitals (HOMO, LUMO), Electron Density, ESP (Electrostatic Potential), and NCI surfaces from cube files.
• Crystal/Periodic Structures: Unit cells, unwrapped structures, and VASP support.
• Animations: Generating GIFs for rotation, bouncing, trajectories, and transitions.

For specific commands and Python snippets for any of these features, refer to the official examples documentation. For a full list of CLI flags, see the CLI reference.

In the Python API, options are strictly categorized based on when they are applied. Mixing them up will result in errors or ignored parameters.

Load-time options (load())

These options control how the input file is parsed and interpreted. They must be passed to the load() function. Examples include:

• smiles, charge, multiplicity, kekule, rebuild
• mol_frame, bohr, quick
• ts_detect (--ts), ts_frame
• nci_detect (--nci-detect)
• cell (--cell)
• All ensemble* options (e.g., --ensemble, --ensemble-color, --align-atoms, --max-frames)

Render-time options (render() / render_gif())

These options control the visual appearance of the molecule. They must be passed to the render() or render_gif() functions. Examples include:

• Styling (colors, backgrounds)
• Bond display rules
• Surfaces and overlays
• Hulls and annotations
• Output format/path

Note: If you use the shorthand render("path.xyz", ...) you are implicitly calling load() with default settings. If you need custom parsing (like charge=1), you must call load() explicitly first.

# Correct way to use both types of options:
# Use load() for parsing logic
mol = load("ts.out", charge=1, ts_detect=True) 

# Use render() for visual logic
render(mol, mo=True, background="black")

To ensure consistent orientation across a batch of different molecules (e.g., different orbitals or states), use the ref= parameter in render(). This uses Kabsch-alignment to align the current molecule to a saved reference.

1. Save a reference: Call render() with ref="path/to/ref.xyz". This saves the current orientation to that file.
2. Apply reference: Subsequent calls to render() using the same ref path will automatically align the molecule to that orientation.

Note: When a reference file is provided via ref=, the orient=True parameter is ignored.

from xyzrender import load, render

# First call: saves the orientation to 'reference.xyz'
mol1 = load("homo.cube")
render(mol1, mo=True, ref="reference.xyz")

# Subsequent calls: aligns mol2 to the orientation in 'reference.xyz'
mol2 = load("lumo.cube")
render(mol2, mo=True, ref="reference.xyz")

In molecular crystals, molecules are often split across the unit cell boundaries. The unwrap feature reassembles these fragments into single, contiguous molecules by shifting atoms by integer lattice translations.

• Behavior: It anchors every molecule at the image where most of its atoms reside.
• Side effects: Ghost atoms are automatically disabled when unwrapping because the molecules are now contiguous. Fully-connected frameworks (ionic or covalent networks) are left unchanged.

Python Usage: You can use the unwrap keyword in render() or apply the unwrap_molecules() transform directly to the molecule's graph.

from xyzrender import load, render
from xyzrender.crystal import unwrap_molecules

mol = load("caffeine_cell.xyz", cell=True)

# Option 1: Unwrap during rendering
render(mol, unwrap=True, output="caffeine_cell_unwrap.svg")

# Option 2: Apply transform directly to the graph
unwrap_molecules(mol.graph, mol.cell_data)