xyzrender

https://xyzrender.readthedocs.io/en/latest/
Admin
xyzrender is a command-line tool for creating publication-quality molecular graphics from XYZ, cube,...
Tokens:28,353
Snippets:226
Trust Score:9.6
Update:6 months ago
Show doc for...
Tokens:
Raw
### Load Built-in Styling Presets

Source: https://xyzrender.readthedocs.io/en/latest/configuration.html

Use the `--config` flag with a built-in preset name to apply a predefined style. Examples include 'default', 'flat', 'paton', and 'tube'.

```bash
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 tube
xyzrender caffeine.xyz --config mtube
xyzrender caffeine.xyz --config btube
xyzrender caffeine.xyz --config wire
xyzrender caffeine.xyz --config graph
```

--------------------------------

### GET /config/load

Source: https://xyzrender.readthedocs.io/en/latest/api/config.html

Loads a configuration from a built-in preset name or a JSON file path, merging it with default settings.

```APIDOC
## GET /config/load

### Description
Loads a configuration from a built-in preset name (e.g., 'flat', 'paton') or a path to a JSON file. The loaded configuration is merged on top of 'default.json' to ensure all keys are populated.

### Method
GET

### Endpoint
xyzrender.config.load_config(name_or_path)

### Parameters
#### Path Parameters
- **name_or_path** (string) - Required - The name of a built-in preset or a file system path to a JSON configuration file.

### Response
#### Success Response (200)
- **config** (dict) - The merged configuration dictionary.
```

--------------------------------

### Atom Colormap CLI Usage

Source: https://xyzrender.readthedocs.io/en/latest/examples/cmap.html

Examples of how to apply colormaps to molecular structures using the xyzrender command line interface.

```APIDOC
## CLI Usage: Atom Colormap

### Description
Apply a colormap to atoms based on a per-atom scalar value file. Atoms are colored according to a palette, with support for custom ranges and colorbars.

### Parameters
- **--cmap FILE** (string) - Required - Path to colormap data file (two-column: 1-indexed atom number, value).
- **--cmap-range VMIN VMAX** (float) - Optional - Override colormap range.
- **--cmap-symm** (flag) - Optional - Symmetric range about zero.
- **--cmap-palette NAME** (string) - Optional - Colormap palette name (default: viridis).
- **--cbar** (flag) - Optional - Add a vertical colorbar on the right.
- **--label-size PT** (integer) - Optional - Font size for colorbar tick labels.

### Request Example
```bash
xyzrender caffeine.xyz --hy --cmap caffeine_charges.txt --gif-rot -go caffeine_cmap.gif
xyzrender caffeine.xyz --hy --cmap caffeine_charges.txt --cmap-range -0.5 0.5
xyzrender caffeine.xyz --hy --cmap caffeine_charges.txt --cbar
```
```

--------------------------------

### Preset highlight colors

Source: https://xyzrender.readthedocs.io/en/latest/examples/highlight.html

Example of how highlight colors are defined in a JSON preset file. Colors are assigned sequentially to highlighted groups, cycling if necessary.

```json
"highlight_colors": ["orchid", "mediumseagreen", "goldenrod", "coral", "mediumpurple", "hotpink"]

```

--------------------------------

### Regenerate xyzrender outputs

Source: https://xyzrender.readthedocs.io/en/latest/examples.html

Executes the generation script to recreate all example outputs from the provided structures.

```bash
uv run bash examples/generate.sh
```

--------------------------------

### Bulk Label File Configuration

Source: https://xyzrender.readthedocs.io/en/latest/examples/annotations.html

Define multiple labels in a text file for use with the --label flag. Lines starting with non-integers or # are ignored.

```text
# sn2_label.txt
2 1 d
1 22 d
2 1 22 a
```

```bash
xyzrender sn2.out --ts --label sn2_label.txt --label-size 40
```

--------------------------------

### Bond Measurement Output Format

Source: https://xyzrender.readthedocs.io/en/latest/examples/annotations.html

Example of the text output generated by the --measure flag.

```text
Bond Distances:
     C1 - C2     1.498Å
     C1 - H4     1.104Å
Bond Angles:
     C2 - C1 - H5     109.62°
Dihedral Angles:
     H5 - C1 - C2 - O3      -55.99°
```

--------------------------------

### GET xyzrender.api.measure

Source: https://xyzrender.readthedocs.io/en/latest/api/core.html

Returns geometry measurements for a given molecule.

```APIDOC
## GET xyzrender.api.measure

### Description
Returns geometry measurements as a dictionary for a specified molecule.

### Parameters
#### Request Body
- **molecule** (str | PathLike | Molecule) - Required - A Molecule object or a file path.
- **modes** (list[str] | None) - Optional - Subset of ["d", "a", "t"] for distances, angles, dihedrals. Defaults to all three.

### Response
#### Success Response (200)
- **dict** (dict) - Geometry measurements.
```

--------------------------------

### Build and Apply Render Configuration

Source: https://xyzrender.readthedocs.io/en/latest/api/config.html

Create a RenderConfig object using a preset and style overrides, then apply it to multiple render calls.

```python
cfg = build_config("flat", atom_scale=1.5, gradient=False)
render(mol1, config=cfg)
render(mol2, config=cfg)
```

--------------------------------

### Load Custom Styling from JSON File

Source: https://xyzrender.readthedocs.io/en/latest/configuration.html

Create a JSON file to define custom styling options and load it using the `--config` flag. This allows for fine-grained control over appearance.

```bash
xyzrender caffeine.xyz --config my_style.json
```

--------------------------------

### Apply Rendering Presets

Source: https://xyzrender.readthedocs.io/en/latest/examples/basics.html

Use command-line arguments to apply different rendering presets to a molecule file. Each preset offers a distinct visual style.

```bash
xyzrender caffeine.xyz                        # default
xyzrender caffeine.xyz --config flat          # flat: no gradient
xyzrender caffeine.xyz --config paton         # paton: PyMOL-style
xyzrender caffeine.xyz --config pmol          # pmol: ball-and-stick + element-coloured bonds (PyMOL-inspired)
xyzrender caffeine.xyz --config bubble --hy   # space-filling-like
xyzrender caffeine.xyz --config tube          # tube: cylinder-shaded sticks
xyzrender caffeine.xyz --config mtube         # mtube: metal tube with edge stroke
xyzrender caffeine.xyz --config btube         # btube: ball-and-tube with element-coloured bonds
xyzrender caffeine.xyz --config wire          # wire: thin element-coloured lines
```

--------------------------------

### Build and Reuse Configuration

Source: https://xyzrender.readthedocs.io/en/latest/api/core.html

Build a configuration object once and reuse it for multiple rendering calls to improve efficiency.

```python
cfg = build_config("flat", atom_scale=1.5)
render(mol1, config=cfg)
render(mol2, config=cfg)
```

--------------------------------

### Render Periodic Structures

Source: https://xyzrender.readthedocs.io/en/latest/examples/crystal.html

Render periodic structures from VASP, Quantum ESPRESSO, SIESTA, ABINIT, and CP2K input files. File format is auto-detected by extension. Use `--gif-rot` for animated rotations.

```bash
xyzrender NV63.vasp -o NV63_vasp.svg
```

```bash
xyzrender NV63.vasp --gif-rot -go NV63_vasp.gif
```

```bash
xyzrender NV63.in --no-axes -o NV63_qe.svg
```

--------------------------------

### Render conformer ensembles via CLI

Source: https://xyzrender.readthedocs.io/en/latest/examples/ensemble.html

Generate ensemble visualisations from XYZ files using command-line flags for alignment and styling.

```bash
xyzrender triphenylbenzol.xyz --ensemble -o triphenylbenzol_ensemble.svg
xyzrender triphenylbenzol.xyz --ensemble --align-atoms 21,22,23 --ensemble-color spectral --opacity 0.4 -o triphenylbenzol_ensemble_custom.svg
```

--------------------------------

### Rendering and Configuration

Source: https://xyzrender.readthedocs.io/en/latest/api/core.html

APIs for configuring rendering and generating visualizations like GIFs.

```APIDOC
## Style Configuration and Rendering

### Description
Allows reuse of style configurations for rendering molecules and generating GIFs.

### Functions
#### `build_config(style, **kwargs)`
Builds a rendering configuration object. Example: `cfg = build_config("flat", atom_scale=1.5)`.

#### `render(mol, config=None)`
Renders a molecule. Accepts a `Molecule` object and an optional configuration.

#### `render_gif(filename, gif_rot=None, gif_trj=False, gif_ts=False)`
Generates a GIF animation. 

Parameters:
  - **filename** (str) - Path to the input file (e.g., `.xyz`, `.pdb`).
  - **gif_rot** (str) - Axis for GIF rotation (e.g., 'y').
  - **gif_trj** (bool) - Whether to render a trajectory.
  - **gif_ts** (bool) - Whether to render a transition state.

### Example Usage
```python
# Reuse a style config:
cfg = build_config("flat", atom_scale=1.5)
render(mol1, config=cfg)
render(mol2, config=cfg)

# For GIFs use render_gif():
render_gif("mol.xyz", gif_rot="y")
render_gif("trajectory.xyz", gif_trj=True)
render_gif("ts.xyz", gif_ts=True)
```
```

--------------------------------

### Override Preset Values with CLI Flags

Source: https://xyzrender.readthedocs.io/en/latest/configuration.html

CLI flags can override specific settings within a chosen preset. For example, `--bo` enables bond orders for the 'paton' preset, and `--no-fog` disables fog for the 'default' preset.

```bash
xyzrender caffeine.xyz --config paton --bo
xyzrender caffeine.xyz --config default --no-fog
```

--------------------------------

### Render Electron Density Surfaces

Source: https://xyzrender.readthedocs.io/en/latest/examples/dens_esp.html

Commands to generate electron density isosurfaces with various configurations including custom thresholds, colors, opacity, and GIF rotation.

```bash
xyzrender caffeine_dens.cube --dens -o caffeine_dens.svg
xyzrender caffeine_dens.cube --dens --iso 0.01 -o caffeine_dens_iso.svg
xyzrender caffeine_dens.cube --dens --dens-color teal --opacity 0.75 -o caffeine_dens_custom.svg
xyzrender caffeine_dens.cube --dens --gif-rot -go caffeine_dens.gif
```

--------------------------------

### Full Configuration Options JSON

Source: https://xyzrender.readthedocs.io/en/latest/configuration.html

This JSON object lists all available configuration keys for styling xyzrender outputs. It covers canvas size, atom and bond properties, gradients, fog, and color definitions.

```json
{
  "canvas_size": 800,
  "atom_scale": 2.5,
  "bond_width": 20,
  "bond_color": "#000000",
  "ts_color": "#1E90FF",
  "nci_color": "#228B22",
  "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": 0.845,
  "surface_opacity": 1.0,
  "mo_pos_color": "steelblue",
  "mo_neg_color": "maroon",
  "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"
  }
}
```

--------------------------------

### Animated Rotation with Faces and Pore (CLI)

Source: https://xyzrender.readthedocs.io/en/latest/examples/hull.html

Generate an animated GIF with rotation for a MOF-5 structure, including faces and pore sphere, using the command line.

```bash
xyzrender MOF-5.xyz --hull faces --pore --no-cell --gif-rot
```

--------------------------------

### Render MOF-5 with Faces and Pore Sphere (CLI)

Source: https://xyzrender.readthedocs.io/en/latest/examples/hull.html

Use the command-line interface to render a MOF-5 structure including faces and a pore sphere. The `--no-cell` flag removes the unit cell.

```bash
xyzrender MOF-5.xyz --hull faces --pore --no-cell -o mof5_faces_pore.svg
```

--------------------------------

### Metal Tube Preset with Unbond Pi

Source: https://xyzrender.readthedocs.io/en/latest/examples/basics.html

Apply the 'mtube' preset for metal complexes and optionally use '--unbond pi' to clean up the visualization by removing pi-coordination clutter.

```bash
xyzrender caffeine.xyz --config mtube
xyzrender mnh.xyz --config mtube --unbond pi --hy
```

--------------------------------

### Render Electrostatic Potential (ESP) Surfaces

Source: https://xyzrender.readthedocs.io/en/latest/examples/dens_esp.html

Commands to map electrostatic potential onto a density isosurface using both density and ESP cube files.

```bash
xyzrender caffeine_dens.cube --esp caffeine_esp.cube -o caffeine_esp.svg
xyzrender caffeine_dens.cube --esp caffeine_esp.cube --iso 0.005 --opacity 0.75 -o caffeine_esp_custom.svg
```

--------------------------------

### build_render_config

Source: https://xyzrender.readthedocs.io/en/latest/api/config.html

Merges a base configuration dictionary with CLI overrides to create a final RenderConfig.

```APIDOC
## xyzrender.config.build_render_config

### Description
Merge config dict with CLI overrides into a RenderConfig.

### Parameters
* **_config_data_** - The base configuration data, typically from a JSON file.
* **_cli_overrides_** - A dictionary containing only explicitly set CLI values (non-`None`).

### Notes
CLI values take precedence over config file values.

### Return type
`RenderConfig`
```

--------------------------------

### Configuration Parameters

Source: https://xyzrender.readthedocs.io/en/latest/api/config.html

Details regarding specific configuration parameters and overrides.

```APIDOC
## Configuration Parameters

### Description
Details on specific rendering parameters used within the configuration.

### Parameters
- **nci_mode** (string) - Optional - Accepts 'avg', 'pixel', 'uniform', or a color name/hex code.
- **flat_mo** (boolean) - Optional - Overrides the configuration default when set to True.
```

--------------------------------

### Render Faces and Pore Sphere with Python

Source: https://xyzrender.readthedocs.io/en/latest/examples/hull.html

Render a molecular structure with both faces and a pore sphere using the Python API. Specify `hull="faces"` for face rendering.

```python
# Faces + pore:
render(mol, hull="faces", pore=True, no_cell=True, output="mof5_faces_pore.svg")
```

--------------------------------

### Measure Bond Geometries via CLI

Source: https://xyzrender.readthedocs.io/en/latest/examples/annotations.html

Commands to output bond distances, angles, and dihedrals to stdout.

```bash
xyzrender ethanol.xyz --measure          # all: distances, angles, dihedrals
xyzrender ethanol.xyz --measure d        # distances only
xyzrender ethanol.xyz --measure d a      # distances and angles
```

--------------------------------

### Apply Atom Colormaps via CLI

Source: https://xyzrender.readthedocs.io/en/latest/examples/cmap.html

Commands to generate rotated GIFs, set explicit ranges, or add colorbars to atom visualizations.

```bash
xyzrender caffeine.xyz --hy --cmap caffeine_charges.txt --gif-rot -go caffeine_cmap.gif
xyzrender caffeine.xyz --hy --cmap caffeine_charges.txt --cmap-range -0.5 0.5
xyzrender caffeine.xyz --hy --cmap caffeine_charges.txt --cbar
```

--------------------------------

### Customize Pore Sphere Rendering (CLI)

Source: https://xyzrender.readthedocs.io/en/latest/examples/hull.html

Customize the appearance of the pore sphere by specifying color and opacity via the command line.

```bash
xyzrender MOF-5.xyz --pore --pore-color coral --pore-opacity 0.3 -o mof5_pore_custom.svg
```

--------------------------------

### Render Pore Sphere with Python

Source: https://xyzrender.readthedocs.io/en/latest/examples/hull.html

Use the Python API to load a molecule and render it with a pore sphere. Ensure `no_cell=True` to exclude the unit cell.

```python
from xyzrender import load, render, render_gif

mol = load("MOF-5.xyz")

# Pore sphere:
render(mol, pore=True, no_cell=True, output="mof5_pore.svg")
```

--------------------------------

### RenderConfig Options

Source: https://xyzrender.readthedocs.io/en/latest/api/types.html

This section lists the available configuration options for rendering within XYZrender. These options control various visual aspects of the rendered output.

```APIDOC
## RenderConfig Options

### Description
Configuration options for controlling the visual appearance of rendered molecular structures.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
This section details individual configuration parameters available under `RenderConfig`:

- `RenderConfig.atom_gradient_strength` (float) - Controls the strength of the gradient applied to atoms.
- `RenderConfig.atom_scale` (float) - Scales the size of atoms.
- `RenderConfig.atom_stroke_color` (color) - Sets the stroke color for atoms.
- `RenderConfig.atom_stroke_width` (float) - Sets the stroke width for atoms.
- `RenderConfig.atom_wash` (bool) - Applies a wash effect to atoms.
- `RenderConfig.atoms_above_bonds` (bool) - Renders atoms above bonds.
- `RenderConfig.auto_orient` (bool) - Automatically orients the view.
- `RenderConfig.axis_colors` (list of colors) - Sets the colors for the axes.
- `RenderConfig.axis_width_scale` (float) - Scales the width of the axes.
- `RenderConfig.background` (color) - Sets the background color.
- `RenderConfig.bond` (bool) - Toggles the display of bonds.
- `RenderConfig.bond_color` (color) - Sets the default bond color.
- `RenderConfig.bond_color_by_element` (bool) - Colors bonds based on the elements they connect.
- `RenderConfig.bond_gap` (float) - Sets the gap between bonds.
- `RenderConfig.bond_gradient` (bool) - Applies a gradient to bonds.
- `RenderConfig.bond_gradient_strength` (float) - Controls the strength of the bond gradient.
- `RenderConfig.bond_orders` (bool) - Displays bond orders.
- `RenderConfig.bond_outline_color` (color) - Sets the outline color for bonds.
- `RenderConfig.bond_outline_width` (float) - Sets the outline width for bonds.
- `RenderConfig.bond_width` (float) - Sets the width of bonds.
- `RenderConfig.canvas_size` (tuple of int) - Sets the canvas size (width, height).
- `RenderConfig.cbar` (bool) - Toggles the color bar.
- `RenderConfig.cell_color` (color) - Sets the color for the unit cell.
- `RenderConfig.cell_data` (bool) - Displays unit cell data.
- `RenderConfig.cell_line_width` (float) - Sets the line width for the unit cell.
- `RenderConfig.cmap_palette` (string) - Specifies the colormap palette.
- `RenderConfig.cmap_range` (tuple of floats) - Sets the range for the colormap.
- `RenderConfig.cmap_symm` (bool) - Applies symmetry to the colormap.
- `RenderConfig.cmap_unlabeled` (bool) - Applies colormap to unlabeled atoms.
- `RenderConfig.color_overrides` (dict) - Overrides colors for specific atoms or elements.
- `RenderConfig.dens_color` (color) - Sets the color for density surfaces.
- `RenderConfig.dens_contours` (bool) - Toggles density contours.
- `RenderConfig.dens_isovalue` (float) - Sets the isovalue for density surfaces.
- `RenderConfig.dof` (bool) - Enables depth of field effect.
- `RenderConfig.dof_strength` (float) - Controls the strength of the depth of field effect.
- `RenderConfig.dpi` (int) - Sets the dots per inch for output.
- `RenderConfig.ensemble_colors` (list of colors) - Sets colors for ensemble members.
- `RenderConfig.esp_surface` (bool) - Toggles the display of ESP surfaces.
- `RenderConfig.fixed_center` (tuple of floats) - Sets a fixed center for the view.
- `RenderConfig.fixed_span` (float) - Sets a fixed span for the view.
- `RenderConfig.flat_mo` (bool) - Renders molecular orbitals flat.
- `RenderConfig.fog` (bool) - Enables fog effect.
- `RenderConfig.fog_strength` (float) - Controls the strength of the fog effect.
- `RenderConfig.gradient` (bool) - Applies a gradient to the background.
- `RenderConfig.haptic` (bool) - Enables haptic feedback.
- `RenderConfig.hide_bonds` (bool) - Hides all bonds.
- `RenderConfig.hide_h` (bool) - Hides hydrogen atoms.
- `RenderConfig.highlight_colors` (dict) - Defines highlight colors for specific groups or atoms.
- `RenderConfig.highlight_groups` (list of lists) - Specifies groups of atoms to highlight.
- `RenderConfig.hue_shift_factor` (float) - Adjusts the hue shift factor.
- `RenderConfig.hull_atom_indices` (list of int) - Indices of atoms to include in the convex hull.
- `RenderConfig.hull_colors` (list of colors) - Colors for the convex hull.
- `RenderConfig.hull_edge_width_ratio` (float) - Ratio for the width of convex hull edges.
- `RenderConfig.hull_opacity` (float) - Opacity of the convex hull.
- `RenderConfig.hull_ordered` (bool) - Orders the convex hull.
- `RenderConfig.idx_format` (string) - Format string for atom indices.
- `RenderConfig.label_color` (color) - Sets the color for labels.
- `RenderConfig.label_font_size` (float) - Sets the font size for labels.
- `RenderConfig.label_offset` (tuple of floats) - Offsets labels from their atoms.
- `RenderConfig.light_shift_factor` (float) - Adjusts the light shift factor.
- `RenderConfig.mo_blur_sigma` (float) - Sigma value for blurring molecular orbitals.
- `RenderConfig.mo_contours` (bool) - Toggles contours for molecular orbitals.
- `RenderConfig.mo_isovalue` (float) - Isovalue for molecular orbitals.
- `RenderConfig.mo_neg_color` (color) - Color for negative molecular orbitals.
- `RenderConfig.mo_pos_color` (color) - Color for positive molecular orbitals.
- `RenderConfig.mo_upsample_factor` (int) - Upsampling factor for molecular orbitals.
- `RenderConfig.mol_color` (color) - Sets the default molecule color.
- `RenderConfig.nci_bonds` (bool) - Toggles NCI bonds.
- `RenderConfig.nci_color` (color) - Sets the color for NCI surfaces.
- `RenderConfig.nci_contours` (bool) - Toggles NCI contours.
- `RenderConfig.nci_isovalue` (float) - Isovalue for NCI surfaces.
- `RenderConfig.nci_mode` (string) - Mode for NCI surface generation.
- `RenderConfig.overlay_color` (color) - Sets the color for overlays.
- `RenderConfig.padding` (float) - Adds padding around the molecule.
- `RenderConfig.periodic_image_opacity` (float) - Opacity for periodic images.
- `RenderConfig.pore_centroids` (bool) - Toggles display of pore centroids.
- `RenderConfig.pore_node_ids` (list of int) - IDs of nodes for pore visualization.
- `RenderConfig.pore_radii` (list of float) - Radii of pores.
- `RenderConfig.pore_sphere_color` (color) - Color for pore spheres.
- `RenderConfig.pore_sphere_opacity` (float) - Opacity for pore spheres.
- `RenderConfig.pore_spheres` (bool) - Toggles display of pore spheres.
- `RenderConfig.radius_scale` (float) - Scales the radii of atoms and bonds.
- `RenderConfig.region_specs` (list of StyleRegion) - Specifies regions for custom styling.
- `RenderConfig.saturation_shift_factor` (float) - Adjusts the saturation shift factor.
- `RenderConfig.show_cell` (bool) - Toggles the display of the unit cell.
- `RenderConfig.show_convex_hull` (bool) - Toggles the display of the convex hull.
- `RenderConfig.show_h_indices` (bool) - Shows indices for hydrogen atoms.
- `RenderConfig.show_hull_edges` (bool) - Shows edges of the convex hull.
- `RenderConfig.show_indices` (bool) - Shows atom indices.
- `RenderConfig.skeletal_label_color` (color) - Color for skeletal labels.
- `RenderConfig.skeletal_style` (string) - Style for skeletal representations.
- `RenderConfig.style_regions` (list of StyleRegion) - Defines styling for specific regions.
- `RenderConfig.surface_opacity` (float) - Opacity for molecular surfaces.
- `RenderConfig.surface_style` (string) - Style for molecular surfaces.
- `RenderConfig.transparent` (bool) - Enables transparency.
- `RenderConfig.ts_bonds` (bool) - Toggles TS bonds.
- `RenderConfig.ts_color` (color) - Sets the color for TS bonds.
- `RenderConfig.unbond` (bool) - Toggles unbonds.
- `RenderConfig.vdw_gradient_strength` (float) - Controls the strength of the VDW gradient.
- `RenderConfig.vdw_indices` (list of int) - Indices of atoms for VDW representation.
- `RenderConfig.vdw_opacity` (float) - Opacity for VDW representation.
- `RenderConfig.vdw_scale` (float) - Scales the VDW radii.
- `RenderConfig.vector_color` (color) - Sets the color for vectors.
- `RenderConfig.vector_scale` (float) - Scales the vectors.
- `RenderConfig.vectors` (bool) - Toggles the display of vectors.

### Request Example
```json
{
  "atom_scale": 1.5,
  "bond_width": 0.5,
  "background": "#FFFFFF"
}
```

### Response
#### Success Response (200)
- `RenderConfig` (object) - The updated rendering configuration.

#### Response Example
```json
{
  "atom_scale": 1.5,
  "bond_width": 0.5,
  "background": "#FFFFFF"
}
```
```

--------------------------------

### Render molecular animation via CLI

Source: https://xyzrender.readthedocs.io/en/latest/_sources/index.md.txt

Generates an animated GIF of a transition state with NCI surfaces and vdW spheres using a single command.

```bash
xyzrender bimp.out --gif-ts --gif-rot --nci --vdw 84-169
```

--------------------------------

### build_config

Source: https://xyzrender.readthedocs.io/en/latest/api/config.html

Constructs a RenderConfig object from a preset configuration and optional style overrides.

```APIDOC
## xyzrender.config.build_config

### Description
Build a `RenderConfig` from a preset and style kwargs.

### Parameters
* **_config_name_** (`str`) - Preset name (`"default"`, `"flat"`, `"paton"`, …) or path to a custom JSON config file.
* **_itrión_** - Style overrides; any `None` value falls back to the preset default.
* **canvas_size** – Style overrides; any `None` value falls back to the preset default.
* **atom_scale** – Style overrides; any `None` value falls back to the preset default.
* **bond_width** – Style overrides; any `None` value falls back to the preset default.
* **atom_stroke_width** – Style overrides; any `None` value falls back to the preset default.
* **bond_color** – Style overrides; any `None` value falls back to the preset default.
* **bond_outline_color** – Style overrides; any `None` value falls back to the preset default.
* **bond_outline_width** – Style overrides; any `None` value falls back to the preset default.
* **ts_color** – Style overrides; any `None` value falls back to the preset default.
* **nci_color** – Style overrides; any `None` value falls back to the preset default.
* **background** – Style overrides; any `None` value falls back to the preset default.
* **transparent** (`bool`) – Style overrides; any `None` value falls back to the preset default.
* **gradient** (`bool` | `None`) – Style overrides; any `None` value falls back to the preset default.
* **hue_shift_factor** (`float` | `None`) – Style overrides; any `None` value falls back to the preset default.
* **light_shift_factor** (`float` | `None`) – Style overrides; any `None` value falls back to the preset default.
* **saturation_shift_factor** (`float` | `None`) – Style overrides; any `None` value falls back to the preset default.
* **fog** (`bool` | `None`) – Style overrides; any `None` value falls back to the preset default.
* **fog_strength** (`float` | `None`) – Style overrides; any `None` value falls back to the preset default.
* **bo** (`bool` | `None`) – Style overrides; any `None` value falls back to the preset default.
* **label_font_size** (`int` | `None`) – Style overrides; any `None` value falls back to the preset default.
* **vdw_opacity** (`float` | `None`) – Style overrides; any `None` value falls back to the preset default.
* **vdw_scale** (`float` | `None`) – Style overrides; any `None` value falls back to the preset default.
* **atom_gradient_strength** (`float` | `None`) – Style overrides; any `None` value falls back to the preset default.
* **bond_gradient_strength** (`float` | `None`) – Style overrides; any `None` value falls back to the preset default.
* **vdw_gradient_strength** (`float` | `None`) – Style overrides; any `None` value falls back to the preset default.
* **hide_bonds** (`bool`) – Style overrides; any `None` value falls back to the preset default.
* **unbond** (`list`[`tuple`[`int`, `int`]] | `None`) – Style overrides; any `None` value falls back to the preset default.
* **bond** (`list`[`tuple`[`int`, `int`]] | `None`) – Style overrides; any `None` value falls back to the preset default.
* **hy** (`bool` | `list`[`int`] | `None`) – Style overrides; any `None` value falls back to the preset default.
* **no_hy** (`bool`) – Style overrides; any `None` value falls back to the preset default.
* **orient** (`bool` | `None`) – `True` / `False` to force / suppress PCA auto-orientation. `None` (default) enables auto-orientation.
* **opacity** (`float` | `None`) – Style overrides; any `None` value falls back to the preset default.
* **ts_bonds** (`list`[`tuple`[`int`, `int`]] | `None`) – Manual TS / NCI bond overlays as 0-indexed atom pairs.
* **nci_bonds** (`list`[`tuple`[`int`, `int`]] | `None`) – Manual TS / NCI bond overlays as 0-indexed atom pairs.
* **vdw_indices** (`list`[`int`] | `None`) – VdW sphere atom list (0-indexed). `[]` = all atoms, `None` = off.
* **show_indices** (`bool`) – Enable atom index labels.
* **idx_format** (`str`) – Style overrides; any `None` value falls back to the preset default.
* **atom_cmap** (`dict`[`int`, `float`] | `None`) – Atom property colour map (0-indexed keys).
* **cmap_range** (`tuple`[`float`, `float`] | `None`) – Style overrides; any `None` value falls back to the preset default.
* **cmap_palette** (`str`) – Style overrides; any `None` value falls back to the preset default.
* **cbar** (`bool`) – Style overrides; any `None` value falls back to the preset default.
* **cmap_symm** (`bool`) – Style overrides; any `None` value falls back to the preset default.

### Returns
Ready to pass to `render()` as `config=`.

### Return type
`RenderConfig`

### Example
```python
cfg = build_config("flat", atom_scale=1.5, gradient=False)
render(mol1, config=cfg)
render(mol2, config=cfg)
```

### Notes
Bond/index/cmap params use **0-indexed** atom numbering (the internal convention). The Python API converts from user-facing 1-indexed values before calling this function; the CLI passes _parse_pairs() output directly.
```

--------------------------------

### Control Bond Order Notation

Source: https://xyzrender.readthedocs.io/en/latest/examples/basics.html

Choose between default aromatic notation or Kekulé bond orders using the '--bo -k' flag.

```bash
xyzrender benzene.xyz --hy              # aromatic notation (default)
xyzrender caffeine.xyz --bo -k          # Kekulé bond orders
```

--------------------------------

### Render conformer ensembles via Python

Source: https://xyzrender.readthedocs.io/en/latest/examples/ensemble.html

Use the render function to create ensemble visualisations with various palette, opacity, and alignment configurations.

```python
from xyzrender import render

render("triphenylbenzol.xyz", ensemble=True)                                          # CPK colours
render("triphenylbenzol.xyz", ensemble=True, ensemble_palette="spectral")             # spectral palette
render("triphenylbenzol.xyz", ensemble=True, ensemble_color="#FF0000")                # single colour
render("triphenylbenzol.xyz", ensemble=True, ensemble_palette="viridis", opacity=0.4) # faded
render("triphenylbenzol.xyz", ensemble=True, align_atoms=[21, 22, 23])               # align on subset
render("triphenylbenzol.xyz", ensemble=True, max_frames=10)                          # limit frames
```

--------------------------------

### Auto-Detect Aromatic Rings for Convex Hulls (CLI)

Source: https://xyzrender.readthedocs.io/en/latest/examples/hull.html

Use `--hull rings` to automatically detect aromatic rings and draw a convex hull around each. A specified color is applied, and the output is saved.

```bash
xyzrender mn-h2.log --ts --hull rings --hull-color teal -o mnh_hull_rings.svg
```

--------------------------------

### XYZRender CLI - Input / Output Flags

Source: https://xyzrender.readthedocs.io/en/latest/cli_reference.html

Flags related to specifying input files, output paths, and handling molecular data.

```APIDOC
## XYZRender CLI - Input / Output Flags

### Description
Flags for controlling input and output operations, including file paths, molecular data handling, and debugging.

### Flags
- `-o`, `--output` (string): Specifies the static output path for the rendered image. Supported formats include `.svg`, `.png`, `.pdf`.
- `--smi SMILES` (string): Embeds a SMILES string into the 3D representation. Requires RDKit to be installed.
- `--mol-frame N` (integer): Selects the record index from a multi-molecule SDF file. Defaults to 0.
- `--rebuild` (boolean): Ignores existing file connectivity and re-detects bonds using `xyzgraph`.
- `-c`, `--charge` (integer): Sets the molecular charge.
- `-m`, `--multiplicity` (integer): Sets the spin multiplicity.
- `--config` (string): Specifies a configuration preset (`default`, `flat`, `paton`, `pmol`, `skeletal`, `tube`, `mtube`, `wire`, `graph`) or provides a path to a JSON configuration file.
- `-d`, `--debug` (boolean): Enables debug logging.
```

--------------------------------

### Rendering Configuration Parameters

Source: https://xyzrender.readthedocs.io/en/latest/api/core.html

Parameters used to configure the rendering of molecular structures, including geometry, labels, and surface overlays.

```APIDOC
## Rendering Configuration Parameters

### Description
Configuration options for the xyzrender rendering engine, controlling molecule orientation, bond visibility, atom labeling, and surface overlays.

### Parameters
- **config** (str | RenderConfig) - Optional - Config preset name, path to JSON config, or RenderConfig object.
- **orient** (bool | None) - Optional - Force/suppress PCA auto-orientation.
- **ref** (str | PathLike | None) - Optional - Path to orientation reference XYZ file.
- **unbond** (list[str] | None) - Optional - Bond display rules to hide specific bonds.
- **bond** (list[str] | None) - Optional - Force-show or add bonds.
- **ts_bonds** (list[tuple[int, int]] | None) - Optional - Manual TS/NCI bond overlays.
- **nci_bonds** (list[tuple[int, int]] | None) - Optional - Manual TS/NCI bond overlays.
- **vdw** (bool | list[int] | None) - Optional - VdW sphere display settings.
- **idx** (bool | str) - Optional - Atom index label settings.
- **cmap** (str | PathLike | dict[int, float] | None) - Optional - Atom property colour map.
- **labels** (list[str] | None) - Optional - Inline annotation spec strings.
- **label_file** (str | None) - Optional - Path to an annotation file.
- **stereo** (bool | list[str]) - Optional - Stereochemistry label settings.
- **stereo_style** (str) - Optional - Placement for R/S labels.
- **vectors** (Any) - Optional - Vector arrows to overlay.
- **mo** (bool) - Optional - Render MO lobes.
- **dens** (bool) - Optional - Render density isosurface.
- **esp** (str | PathLike | None) - Optional - Path to ESP .cube file.
- **nci** (str | PathLike | None) - Optional - Path to NCI .cube file.
- **hull** (bool | str | list[int] | list[list[int]] | None) - Optional - Hull display settings.
- **hull_color** (str | list[str] | None) - Optional - Hull color settings.
- **hull_opacity** (float | None) - Optional - Fill opacity for hull surfaces.
- **hull_edge** (bool | None) - Optional - Draw hull edges.
- **hull_edge_width_ratio** (float | None) - Optional - Width ratio for hull edges.

### Response
- **SVGResult** (object) - Wrapper around the SVG string, displays inline in Jupyter.
```

--------------------------------

### Draw Multiple Convex Hulls with Per-Hull Colors (CLI)

Source: https://xyzrender.readthedocs.io/en/latest/examples/hull.html

Define multiple atom subsets using space-separated ranges with `--hull` to create separate convex hulls. Assign specific colors to each hull using `--hull-color` and save the output.

```bash
xyzrender anthracene.xyz --hull 1-6 4,6-10 8,10-14 -o anthracene_hull.svg
```

--------------------------------

### Render Animated GIF with Convex Hull for a Subset (Python)

Source: https://xyzrender.readthedocs.io/en/latest/examples/hull.html

Create an animated GIF by rotating the molecule and rendering a convex hull for a specified atom subset. Includes options for rotation, hull color, opacity, and output file name.

```python
render_gif(benzene, gif_rot="y", hull=[1, 2, 3, 4, 5, 6],
           hull_color="steelblue", hull_opacity=0.35, output="images/benzene_ring_hull.gif")
```

--------------------------------

### Render Structural Faces of a MOF, Hiding the Cell (CLI)

Source: https://xyzrender.readthedocs.io/en/latest/examples/hull.html

Detect structural faces in a periodic structure like a MOF and render them, while hiding the periodic cell visualization using `--no-cell`. Output is saved to an SVG file.

```bash
xyzrender MOF-5.xyz --hull faces --no-cell -o mof5_faces.svg
```

--------------------------------

### Skip bond-order optimization

Source: https://xyzrender.readthedocs.io/en/latest/api/core.html

Use the quick flag to bypass bond-order optimization during graph construction.

```python
build_graph(quick=True)
```

```python
render(mol, bo=False)
```

--------------------------------

### POST xyzrender.api.orient

Source: https://xyzrender.readthedocs.io/en/latest/api/core.html

Opens a molecule in a viewer for interactive orientation.

```APIDOC
## POST xyzrender.api.orient

### Description
Opens molecule in a viewer to set orientation interactively. Atom positions are updated in-place in the molecule graph.

### Parameters
#### Request Body
- **mol** (Molecule) - Required - Molecule returned by load().

### Response
#### Success Response (200)
- **None** (None)
```

--------------------------------

### Render Structural Faces with Adjusted Planarity Tolerance (CLI)

Source: https://xyzrender.readthedocs.io/en/latest/examples/hull.html

Detect structural faces with a stricter planarity tolerance by setting `--face-planarity` to a lower value. This can result in fewer detected faces. Output is saved to an SVG file.

```bash
xyzrender MOF-5.xyz --hull faces --face-planarity 0.1 -o mof5_strict.svg
```

--------------------------------

### Render Structural Faces with Adjusted Planarity and Ring Size Filters (Python)

Source: https://xyzrender.readthedocs.io/en/latest/examples/hull.html

Render structural faces with custom settings for face planarity tolerance and minimum ring size. The output is saved to an SVG file.

```python
# Adjust face planarity and ring size filtering:
render(mol, hull="faces", face_planarity=0.1, ring_min_size=5, output="mof5_strict.svg")
```

--------------------------------

### Render MO Lobes from Cube Files

Source: https://xyzrender.readthedocs.io/en/latest/examples/mo.html

Use the `--mo` flag with a .cube file to render molecular orbital lobes. Auto-orientation is enabled by default for better visualization. Use `--no-orient` for raw coordinates or `-I` for interactive orientation.

```bash
xyzrender caffeine_homo.cube --mo -o caffeine_homo.svg
```

```bash
xyzrender caffeine_lumo.cube --mo --mo-colors maroon teal -o caffeine_lumo.svg
```

```bash
xyzrender caffeine_homo.cube --mo --hy --iso 0.03 -o homo_iso_hy.svg
```

```bash
xyzrender caffeine_homo.cube --mo --gif-rot -go caffeine_homo.gif
```

--------------------------------

### Apply Surface Styles to Density

Source: https://xyzrender.readthedocs.io/en/latest/examples/dens_esp.html

Commands to change the visual style of the electron density surface to contour or dot patterns.

```bash
xyzrender caffeine_dens.cube --dens --surface-style contour -o caffeine_dens_contour.svg
xyzrender caffeine_dens.cube --dens --surface-style dot -o caffeine_dens_dot.svg
```

--------------------------------

### Render Auto-Detected Aromatic Rings as Convex Hulls (Python)

Source: https://xyzrender.readthedocs.io/en/latest/examples/hull.html

Automatically detect aromatic rings in a molecule and render each as a separate convex hull. The `hull_color` can be set to a single color, which will cycle through a default palette for multiple rings.

```python
render(mol, hull="rings", hull_color="teal")
```

--------------------------------

### Apply Surface Styles to MO Rendering

Source: https://xyzrender.readthedocs.io/en/latest/examples/mo.html

Customize the appearance of MO surfaces using the `--surface-style` option. Supported styles include 'mesh', 'contour', and 'dot'. The default 'solid' style provides filled surfaces with depth cueing.

```bash
xyzrender caffeine_homo.cube --mo --surface-style mesh
```

```bash
xyzrender caffeine_homo.cube --mo --surface-style contour
```

```bash
xyzrender caffeine_homo.cube --mo --surface-style dot
```

--------------------------------

### POST xyzrender.api.render

Source: https://xyzrender.readthedocs.io/en/latest/api/core.html

Renders a molecule to SVG format.

```APIDOC
## POST xyzrender.api.render

### Description
Render a molecule to SVG and return an SVGResult. In a Jupyter cell, the result displays inline automatically.

### Parameters
#### Request Body
- **molecule** (str | PathLike | Molecule) - Required - A Molecule from load(), or a file path.

### Response
#### Success Response (200)
- **SVGResult** (SVGResult) - The rendered SVG output.
```

--------------------------------

### Render Multiple Convex Hulls with Per-Subset Colors (Python)

Source: https://xyzrender.readthedocs.io/en/latest/examples/hull.html

Render a molecule with multiple convex hulls, each defined by a list of atom indices. Assign distinct colors to each hull using a list of color strings and specify opacity.

```python
render(mol, hull=[[1, 2, 3, 4, 5, 6], [7, 8, 9, 10, 11, 12]],
       hull_color=["steelblue", "coral"], hull_opacity=0.35,
       output="anthracene_hull.svg")
```

--------------------------------

### Detect and Label Stereochemistry

Source: https://xyzrender.readthedocs.io/en/latest/examples/annotations.html

Use --stereo to derive and display stereochemical labels from 3D geometry. Specific classes can be filtered using a comma-separated list.

```bash
xyzrender isothio_xtb.xyz -c 1 --stereo
xyzrender mn-h2.log --ts --stereo --no-orient
```

```bash
xyzrender mol.xyz --stereo point,ez      # only R/S and E/Z
xyzrender mol.xyz --stereo point          # only R/S
```
Tokens:
Raw