Configuration

Built-in presets

Use --config to load a styling preset. Built-in options: default, flat, paton, pmol, skeletal, bubble, vdw, tube, mtube, btube, wire, graph.

Preset	Description
default	Radial gradients, depth fog, CPK colors
flat	No gradients, no fog — clean flat look
paton	Based on the graphic style by Rob Paton (see gist)
pmol	Ball-and-stick with element-coloured split bonds and tube shading (PyMOL-inspired)
skeletal	Skeletal formula diagram — thin bonds, minimal atoms
bubble	Space-filling (CPK) — large atoms, no bonds
vdw	True space-filling — atoms at vdW radii, interlocked silhouettes (no gaps at contacts)
tube	Tube/stick model — no atoms, thick element-coloured bonds with cylinder shading
mtube	Metal tube — tube bonds with black edge stroke; metals auto-highlighted via preset region
btube	Ball-and-tube — ball-and-stick atoms with element-coloured tube bonds and outline stroke
wire	Wireframe — no atoms, thin element-coloured bonds with cylinder shading
graph	Minimal graph look — teal bonds, bold outlined nodes with light tinted centers

xyzrender caffeine.xyz --config flat
xyzrender caffeine.xyz --config paton
xyzrender caffeine.xyz --config pmol
xyzrender caffeine.xyz --config skeletal
xyzrender caffeine.xyz --config bubble --hy
xyzrender caffeine.xyz --config vdw
xyzrender caffeine.xyz --config tube
xyzrender caffeine.xyz --config mtube
xyzrender caffeine.xyz --config btube
xyzrender caffeine.xyz --config wire
xyzrender caffeine.xyz --config graph

CLI flags override preset values:

xyzrender caffeine.xyz --config paton --bo   # paton preset but with bond orders on
xyzrender caffeine.xyz --config default --no-fog

Custom presets (JSON)

Create a JSON file with any keys you want to override. Everything else falls back to the default. Load it with --config:

xyzrender caffeine.xyz --config my_style.json

The most commonly overridden keys are below. The full set of fields lives on RenderConfig in src/xyzrender/types.py (also rendered in the Types reference) — anything documented there is a valid preset key, including radius_scale, atom_opacity, vdw_interlocking, atom_interlocking, vdw_outline_width, vdw_h_scale, h_scale, mo_outline_width, mo_outline_color, surface_style, skeletal_style, skeletal_label_color, cell_color, cell_line_width, axis_colors, axis_width_scale, highlight_colors, hull_colors, hull_edge_width_ratio, vector_scale, vector_color, dof_strength, glow_strength, …

{
  "canvas_size": 800,
  "atom_scale": 2.5,
  "bond_width": 20,
  "bond_color": "#000000",
  "ts_color": "#1E90FF",
  "ts_dash": [1.2, 2.2],
  "ts_width": 1.2,
  "nci_color": "#228B22",
  "nci_element": true,
  "nci_dash": [0.08, 2.0],
  "nci_width": 1.0,
  "atom_stroke_width": 3,
  "gradient": true,
  "atom_gradient_strength": 1.0,
  "fog": true,
  "fog_strength": 1.2,
  "bond_orders": true,
  "background": "#ffffff",
  "vdw_opacity": 0.25,
  "vdw_scale": 1.0,
  "vdw_gradient_strength": 1.6,
  "vdw_interlocking": true,
  "vdw_outline_width": 0,
  "h_scale": 0.6,
  "vdw_h_scale": 0.7,
  "surface_opacity": 1.0,
  "surface_style": "solid",
  "mo_pos_color": "steelblue",
  "mo_neg_color": "maroon",
  "mo_outline_width": 0,
  "mo_outline_color": "#000000",
  "nci_mode": "avg",
  "dens_iso": 0.001,
  "dens_color": "steelblue",
  "label_font_size": 30,
  "label_color": "#222222",
  "label_offset": 1.5,
  "cmap_unlabeled": "#ffffff",
  "bond_color_by_element": false,
  "bond_gradient": false,
  "bond_gradient_strength": 0.3,
  "bond_outline_color": "#000000",
  "bond_outline_width": 0,
  "atom_wash": 0.0,
  "atoms_above_bonds": false,
  "colors": {
    "C": "silver",
    "H": "whitesmoke",
    "N": "slateblue",
    "O": "red"
  },
  "regions": {
    "M": "flat"
  },
  "overlay": {
    "color": "mediumorchid",
    "opacity": 0.6,
    "atom_scale": 1.5,
    "bond_width": 15
  }
}

The colors key maps element symbols to hex values (#D9D9D9) or CSS4 named colors (steelblue), overriding the default CPK palette.

bond_outline_color / bond_outline_width add a shadow edge behind bonds (visible as an outline). Set bond_outline_width > 0 to activate (color defaults to black). In styles with a visible atom disc (pmol, btube, paton, default), each bond’s outline interleaves with the atoms so a front bond keeps its halo where it crosses a back bond. In flat styles (tube, mtube, wire) the outlines all sit in a single back-layer under the bonds.

bond_gap sets the spacing between stripes in double, triple, and aromatic bonds (default 0.6, units = fraction of bond_width). Larger values widen the gap between stripes.

TS / NCI / haptic styling. ts_dash and nci_dash are [length, gap] arrays giving the dash/dot length and the empty-gap length, both as multiples of bond_width. ts_width and nci_width are the line stroke widths as multiples of bond_width. ts_element / nci_element opt in to atom-coloured split-halves on these bonds (the same gradient solid bonds use) and require bond_color_by_element=true; if ts_color / nci_color is set, that flat colour wins. Haptic dots follow the NCI controls. See Transition States and NCI for a styling walkthrough.

The regions key defines per-atom-group style overrides. Keys are atom selectors — categories (M metals, sbm s-block metals, het heteroatoms, hal halogens, pnic pnictogens, chal chalcogens, noble noble gases, triel group 13, tetrel group 14), element symbols (Pt, Fe, …), numeric indices (1-5), or comma combinations ("hal,chal"). Values are a preset name or an inline dict of overrides:

"regions": {
  "M": "flat",
  "het": { "atom_scale": 3.0, "gradient": true }
}

Surface-related keys (mo_pos_color, mo_neg_color, dens_iso, dens_color) are only used when --mo, --dens, or --esp is active.

Building a custom preset

If you find yourself repeating the same --config + flag combination across many figures, capture it as a preset. Workflow:

1. Start small. A preset only needs the keys that differ from default. Everything else inherits.

   // my_style.json
   {
     "atom_scale": 1.5,
     "bond_width": 14,
     "atom_gradient_strength": 1.4,
     "fog": false,
     "bond_color_by_element": true,
     "bond_gradient": true
   }
   

2. Use it like any built-in. Both --config on the CLI and config= in Python accept either a preset name or a path to your JSON file — there’s nothing extra to register:

   xyzrender mol.xyz --config ./my_style.json
   xyzrender mol.xyz --config ./my_style.json --hy        # CLI flags still override
   

   from xyzrender import load, render
   mol = load("mol.xyz")
   render(mol, config="./my_style.json")                  # exactly the Python equivalent
   render(mol, config="./my_style.json", hy=True)         # kwargs override preset values
   

3. Read the built-ins as starting points. All built-in preset JSON files live in src/xyzrender/presets/ — copy tube.json or paton.json and tweak from there rather than starting from scratch.

4. Layer regions. For QM/MM-style figures, define a region inside the preset itself so users don’t need to repeat --region on the CLI:

   {
     "atom_scale": 1.6,
     "regions": {
       "M": { "atom_scale": 2.0, "atom_gradient_strength": 1.5 }
     }
   }
   

5. Reuse the same style across many renders with build_config(). Pass it either a built-in name or your JSON path — the returned RenderConfig can be passed to as many render() / render_gif() calls as you want:

   from xyzrender import build_config, render, render_gif
   
   cfg = build_config("./my_style.json")                              # your file
   cfg = build_config("paton", atom_scale=1.6)                         # built-in + tweak
   cfg = build_config("./my_style.json", bond_color="steelblue")      # file + tweak
   
   render(mol1, config=cfg)
   render(mol2, config=cfg, hy=True)
   render_gif(mol1, gif_rot="y", config=cfg)
   

   build_config() is only useful when you want to reuse a styling. For a single render, render(mol, config="./my_style.json") is exactly equivalent.

   Resolution order is always:

   default.json  <  preset / your JSON  <  build_config() kwargs  <  render(...) kwargs
   

6. Tweak fields not exposed as kwargs. build_config()’s kwargs cover the common style knobs only. For everything else (e.g. vdw_interlocking, mo_outline_width, surface_style, skeletal_label_color, the overlay block) set the value in your JSON file, or mutate the RenderConfig directly:

   cfg = build_config("./my_style.json")
   cfg.surface_style = "mesh"
   cfg.mo_outline_width = 5.0
   cfg.overlay.color = "teal"
   render(mol, config=cfg)
   

The full set of valid keys is the RenderConfig dataclass in src/xyzrender/types.py — see the Types reference for the rendered version.

Output formats

The output format is determined by the file extension of -o:

xyzrender caffeine.xyz -o out.svg   # SVG (default, scalable)
xyzrender caffeine.xyz -o out.png   # PNG (rasterised)
xyzrender caffeine.xyz -o out.pdf   # PDF (vector)

If no -o is given, output defaults to {input_basename}.svg.

Styling flags

Flag	Description
-a, --atom-scale	Atom radius scale factor
-b, --bond-width	Bond line width
-s, --atom-stroke-width	Atom outline width
--bond-color	Bond color (hex or named)
--ts-color	Color for dashed TS bonds (hex or named)
--nci-color	Color for dotted NCI bonds (hex or named)
-S, --canvas-size	Canvas size in pixels (default: 800)
-B, --background	Background color (hex or named, default: #ffffff)
-t, --transparent	Transparent background
--grad / --no-grad	Toggle radial gradients
--atom-gradient-strength	Atom gradient strength (default: 1.0)
--bond-gradient-strength	Bond cylinder gradient strength (default: 0.3)
--vdw-gradient-strength	vdW sphere gradient strength (default: 1.6)
--fog / --no-fog	Toggle depth fog
-F, --fog-strength	Depth fog strength
--bo / --no-bo	Toggle bond order rendering
--vdw-opacity	vdW sphere opacity
--vdw-scale	vdW sphere radius scale
--bond-by-element / --no-bond-by-element	Color bonds by endpoint atom colors
--bond-gradient / --no-bond-gradient	Cylinder shading on bonds (3D tube look)
--radius-scale ATOMS FACTOR	Scale selected atoms (repeatable). Multiplies on top of -a. Selectors: "1-5,M"
--region ATOMS CONFIG	Render atom subset with a different preset (repeatable). Selectors: indices "1-5", elements "Pt", categories "M" / "sbm" / "het" / "hal" / "pnic" / "chal" / "noble" / "triel" / "tetrel"