Config Reference

Configuration loading for xyzrender.

class xyzrender.config.SurfaceOverrides(iso=None, mo_pos_color=None, mo_neg_color=None, mo_blur=None, mo_upsample=None, flat_mo=False, dens_color=None, nci_mode=None, nci_cutoff=None)

Bases: object

Per-render surface override values from render()/render_gif() kwargs.

Constructed once at the public-API boundary and passed through internal surface-pipeline calls as a single object — replaces a kwargs-dict hop. Non-None fields supersede preset defaults on cfg inside build_surface_params().

nci_mode accepts 'avg', 'pixel', 'uniform', or a colour name/hex (implying uniform mode). flat_mo=True overrides cfg.flat_mo; False defers to it.

dens_color: str | None = None

flat_mo: bool = False

iso: float | None = None

mo_blur: float | None = None

mo_neg_color: str | None = None

mo_pos_color: str | None = None

mo_upsample: int | None = None

nci_cutoff: float | None = None

nci_mode: str | None = None

xyzrender.config.apply_hydrogen_flags(cfg, *, hy, no_hy=False)

Single source of truth for –hy / –no-hy logic. Called by CLI and Python API.

hy=None → hide C-H (default), hy=True → show all, hy=[1,3] → show specific (1-indexed).

Return type:

None

xyzrender.config.build_config(config_name='default', *, canvas_size=None, atom_scale=None, bond_width=None, atom_stroke_width=None, bond_color=None, bond_outline_color=None, bond_outline_width=None, mo_outline_color=None, mo_outline_width=None, ts_color=None, ts_element=None, ts_dash=None, ts_width=None, nci_color=None, nci_element=None, nci_dash=None, nci_width=None, background=None, transparent=False, gradient=None, hue_shift_factor=None, light_shift_factor=None, saturation_shift_factor=None, fog=None, fog_strength=None, bo=None, label_font_size=None, vdw_opacity=None, vdw_scale=None, atom_gradient_strength=None, bond_gradient_strength=None, vdw_gradient_strength=None, hide_bonds=False, unbond=None, bond=None, hy=None, no_hy=False, orient=None, opacity=None, ts_bonds=None, nci_bonds=None, vdw_indices=None, show_indices=False, idx_format='sn', atom_cmap=None, cmap_range=None, cmap_palette=None, cbar=False, cmap_symm=False)

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.

• 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.

• … – 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.

• 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.

• atom_cmap (dict[int, float] | None) – Atom property colour map (0-indexed keys).

Returns:

Ready to pass to render() as config=.

Return type:

RenderConfig

Example

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

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.

xyzrender.config.build_region_config(config_name='default', **overrides)

Build a RenderConfig for use as a StyleRegion config.

Only per-atom/bond fields are meaningful; global fields (canvas, fog, surfaces) are ignored by the renderer for region configs.

Return type:

RenderConfig

xyzrender.config.build_render_config(config_data, cli_overrides)

Merge config dict with CLI overrides into a RenderConfig.

config_data is the base layer (from JSON). cli_overrides contains only explicitly-set CLI values (non-None). CLI values win over config file values.

Return type:

RenderConfig

xyzrender.config.build_surface_params(cfg, overrides, *, has_mo=False, has_dens=False, has_esp=False, has_nci=False)

Merge cfg defaults with per-render overrides into typed *Params.

Returns None for any surface that is not active (has_* flag is False), so callers can use simple if params: checks.

Return type:

tuple[MOParams | None, DensParams | None, ESPParams | None, NCIParams | None]

xyzrender.config.load_config(name_or_path)

Load config from a built-in preset name or a JSON file path.

All presets (including named built-ins like "flat" or "paton") are merged on top of default.json so unspecified keys always inherit the standard defaults. The "default" preset itself is returned as-is.

Return type:

dict