Types Reference

Core types for xyzrender.

class xyzrender.types.BondStyle(*values)

Bases: Enum

Visual bond style.

DASHED = 'dashed'

DOTTED = 'dot'

SOLID = 'solid'

class xyzrender.types.CellData(lattice, cell_origin=<factory>)

Bases: object

Periodic lattice data for crystal structure rendering.

Parameters:

• lattice (ndarray) – 3x3 array where each row is a lattice vector (a, b, c) in Ångströms.

• cell_origin (ndarray) – 3-vector (Å) of the (0,0,0) cell corner in the current coordinate frame. Defaults to the origin; updated during GIF rotation so the box keeps pace with the atoms.

cell_origin: ndarray

lattice: ndarray

class xyzrender.types.DensParams(isovalue=0.001, color='steelblue')

Bases: object

Parameters for electron density surface rendering.

Parameters:

• isovalue (float) – Isovalue at which to extract the density isosurface.

• color (str) – Fill color for the density contour (hex or CSS4 name).

color: str = 'steelblue'

isovalue: float = 0.001

class xyzrender.types.ESPParams(isovalue=0.001)

Bases: object

Parameters for electrostatic potential (ESP) surface rendering.

Parameters:

isovalue (float) – Isovalue of the density isosurface onto which ESP is mapped.

isovalue: float = 0.001

class xyzrender.types.GIFResult(path)

Bases: object

Wraps a rendered GIF path with Jupyter inline display support.

property path: Path

Path to the GIF file on disk.

save(path)

Write the GIF to path.

Return type:

None

class xyzrender.types.HighlightGroup(indices, color)

Bases: object

A group of atoms to highlight with a specific color.

color: str

indices: list[int]

class xyzrender.types.MOParams(isovalue=0.05, pos_color='steelblue', neg_color='maroon', blur_sigma=0.8, upsample_factor=3, flat=False)

Bases: object

Parameters for MO (molecular orbital) surface rendering.

Parameters:

• isovalue (float) – Isovalue at which to extract the MO surface.

• pos_color (str) – Color for the positive-phase lobe (hex or CSS4 name).

• neg_color (str) – Color for the negative-phase lobe (hex or CSS4 name).

• blur_sigma (float) – Gaussian blur sigma in 2D grid-cell units applied before upsampling.

• upsample_factor (int) – Integer upsampling multiplier applied to the 2D projection grid.

• flat (bool) – Render lobes as flat-filled shapes (no depth shading).

blur_sigma: float = 0.8

flat: bool = False

isovalue: float = 0.05

neg_color: str = 'maroon'

pos_color: str = 'steelblue'

upsample_factor: int = 3

class xyzrender.types.NCIParams(isovalue=0.3, color='forestgreen', color_mode='avg', dens_cutoff=None)

Bases: object

Parameters for NCI (non-covalent interaction) surface rendering.

Parameters:

• isovalue (float) – Reduced density gradient isovalue for the NCI flood-fill.

• color (str) – Fallback fill color when color_mode is 'uniform' (hex or CSS4 name).

• color_mode (str) – How to assign colors to each NCI lobe: 'avg' uses the average sign(lambda2)*rho value per lobe, 'pixel' maps per-pixel values (raster PNG), 'uniform' uses color for every lobe.

• dens_cutoff (float | None) – Optional density magnitude cutoff; voxels with density magnitude (abs(rho)) above this are excluded (useful for non-NCIPLOT cubes where nuclear contributions are not pre-removed).

color: str = 'forestgreen'

color_mode: str = 'avg'

dens_cutoff: float | None = None

isovalue: float = 0.3

class xyzrender.types.OverlayConfig(color='mediumorchid', opacity=None, atom_scale=None, atom_stroke_width=None, atom_stroke_color=None, bond_width=None, bond_color=None, bond_outline_width=None, bond_outline_color=None, unbond=<factory>, bond=<factory>, show=<factory>, ts_bonds=<factory>, config=None)

Bases: object

Per-overlay style overrides.

Scalar fields (color, atom_scale, bond_width, stroke / outline variants) are the CLI- and preset-friendly shortcuts. All are absolute — same semantics as RenderConfig — and None/empty means inherit the primary. For fields without a dedicated shortcut (bond_gap, fog, gradient strengths, skeletal_style, …), set config to a full RenderConfig; it’s attached as a StyleRegion over the overlay’s node IDs at merge time. Scalar shortcuts still win over values inside config because the renderer applies per-node / per-edge override attributes on top of the style-region config.

atom_scale: float | None = None

atom_stroke_color: str | None = None

atom_stroke_width: float | None = None

bond: list[str]

bond_color: str | None = None

bond_outline_color: str | None = None

bond_outline_width: float | None = None

bond_width: float | None = None

color: str = 'mediumorchid'

config: RenderConfig | None = None

opacity: float | None = None

show: list[str]

ts_bonds: list[tuple[int, int]]

unbond: list[str]

class xyzrender.types.RenderConfig(canvas_size=800, padding=20.0, atom_scale=1.0, radius_scale=<factory>, atom_stroke_width=1.5, atom_stroke_color='black', atom_wash=0.0, atoms_above_bonds=False, bond_width=5.0, bond_color='#333333', ts_color=None, ts_element=False, ts_dash=(1.2, 2.2), ts_width=1.2, nci_color=None, nci_element=False, nci_dash=(0.08, 2.0), nci_width=1.0, bond_gap=0.6, bond_color_by_element=False, bond_gradient=False, bond_gradient_strength=0.3, bond_outline_color='#000000', bond_outline_width=0.0, gradient=False, atom_gradient_strength=1.0, hue_shift_factor=0.2, light_shift_factor=0.2, saturation_shift_factor=0.2, fog=False, fog_strength=0.8, hide_bonds=False, unbond=<factory>, bond=<factory>, haptic=False, hide_h=False, show_h_indices=<factory>, auto_hide_h=True, bond_orders=True, ts_bonds=<factory>, nci_bonds=<factory>, vdw_indices=None, vdw_opacity=0.5, vdw_scale=1.0, vdw_gradient_strength=1.6, vdw_interlocking=False, atom_interlocking=False, vdw_interlock_samples=64, vdw_outline_width=None, vdw_outline_color=None, vdw_h_scale=0.7, h_scale=0.6, auto_orient=False, auto_align=True, background='#ffffff', transparent=False, dpi=300, fixed_span=None, fixed_center=None, color_overrides=None, mol_color=None, mo_contours=None, dens_contours=None, esp_surface=None, nci_contours=None, surface_opacity=1.0, flat_mo=False, surface_style='solid', annotations=<factory>, show_indices=False, idx_format='sn', label_font_size=11.0, label_color='#222222', label_offset=0.5, atom_opacity=<factory>, atom_cmap=None, cmap_range=None, cmap_symm=False, cmap_unlabeled='#ffffff', cmap_palette=None, cbar=False, mo_isovalue=0.05, mo_pos_color='steelblue', mo_neg_color='maroon', mo_blur_sigma=0.8, mo_upsample_factor=3, mo_outline_width=0.0, mo_outline_color='#000000', dens_isovalue=0.001, dens_color='steelblue', nci_isovalue=0.3, nci_mode='avg', highlight_groups=<factory>, highlight_colors=<factory>, dof=False, dof_strength=3.0, glow_indices=<factory>, glow_strength=5.0, overlay=<factory>, ensemble_colors=None, skeletal_style=False, skeletal_label_color=None, cell_data=None, show_cell=True, cell_color='#333333', cell_line_width=2.0, periodic_image_opacity=0.5, axis_colors=('firebrick', 'forestgreen', 'royalblue'), axis_width_scale=3.0, vectors=<factory>, vector_scale=1.0, vector_color='firebrick', show_convex_hull=False, hull_opacity=0.2, hull_colors=<factory>, hull_atom_indices=None, hull_ordered=False, show_hull_edges=True, hull_edge_width_ratio=0.4, pore_spheres=False, pore_sphere_opacity=0.5, pore_sphere_color='#f0d060', pore_node_ids=None, pore_centroids=None, pore_radii=None, style_regions=<factory>, region_specs=None)

Bases: object

Rendering settings.

annotations: list[AtomValueLabel | BondLabel | AngleLabel | DihedralLabel | CentroidLabel]

atom_cmap: dict[int, float] | None = None

atom_gradient_strength: float = 1.0

atom_interlocking: bool = False

atom_opacity: dict[int, float]

atom_scale: float = 1.0

atom_stroke_color: str = 'black'

atom_stroke_width: float = 1.5

atom_wash: float = 0.0

atoms_above_bonds: bool = False

auto_align: bool = True

auto_hide_h: bool = True

auto_orient: bool = False

axis_colors: tuple[str, str, str] = ('firebrick', 'forestgreen', 'royalblue')

axis_width_scale: float = 3.0

background: str = '#ffffff'

bond: list[str]

bond_color: str = '#333333'

bond_color_by_element: bool = False

bond_gap: float = 0.6

bond_gradient: bool = False

bond_gradient_strength: float = 0.3

bond_orders: bool = True

bond_outline_color: str = '#000000'

bond_outline_width: float = 0.0

bond_width: float = 5.0

canvas_size: int = 800

cbar: bool = False

cell_color: str = '#333333'

cell_data: CellData | None = None

cell_line_width: float = 2.0

cmap_palette: str | None = None

cmap_range: tuple[float, float] | None = None

cmap_symm: bool = False

cmap_unlabeled: str = '#ffffff'

color_overrides: dict[str, str] | None = None

dens_color: str = 'steelblue'

dens_contours: SurfaceContours | None = None

dens_isovalue: float = 0.001

dof: bool = False

dof_strength: float = 3.0

dpi: int = 300

ensemble_colors: list[str] | None = None

esp_surface: ESPSurface | None = None

fixed_center: tuple[float, float] | None = None

fixed_span: float | None = None

flat_mo: bool = False

fog: bool = False

fog_strength: float = 0.8

glow_indices: list[int]

glow_strength: float = 5.0

gradient: bool = False

h_scale: float = 0.6

haptic: bool = False

hide_bonds: bool = False

hide_h: bool = False

highlight_colors: list[str]

highlight_groups: list[HighlightGroup]

hue_shift_factor: float = 0.2

hull_atom_indices: list[int] | list[list[int]] | None = None

hull_colors: list[str]

hull_edge_width_ratio: float = 0.4

hull_opacity: float = 0.2

hull_ordered: bool = False

idx_format: str = 'sn'

label_color: str = '#222222'

label_font_size: float = 11.0

label_offset: float = 0.5

light_shift_factor: float = 0.2

mo_blur_sigma: float = 0.8

mo_contours: SurfaceContours | None = None

mo_isovalue: float = 0.05

mo_neg_color: str = 'maroon'

mo_outline_color: str = '#000000'

mo_outline_width: float = 0.0

mo_pos_color: str = 'steelblue'

mo_upsample_factor: int = 3

mol_color: str | None = None

nci_bonds: list[tuple[int, int]]

nci_color: str | None = None

nci_contours: NCIContours | None = None

nci_dash: tuple[float, float] = (0.08, 2.0)

nci_element: bool = False

nci_isovalue: float = 0.3

nci_mode: str = 'avg'

nci_width: float = 1.0

overlay: OverlayConfig

padding: float = 20.0

periodic_image_opacity: float = 0.5

pore_centroids: list[tuple[float, float, float]] | None = None

pore_node_ids: list[list[int]] | None = None

pore_radii: list[float] | None = None

pore_sphere_color: str = '#f0d060'

pore_sphere_opacity: float = 0.5

pore_spheres: bool = False

radius_scale: list[tuple[str | list[int], float]]

region_specs: dict[str, str | dict] | None = None

saturation_shift_factor: float = 0.2

show_cell: bool = True

show_convex_hull: bool = False

show_h_indices: list[int]

show_hull_edges: bool = True

show_indices: bool = False

skeletal_label_color: str | None = None

skeletal_style: bool = False

style_regions: list[StyleRegion]

surface_opacity: float = 1.0

surface_style: str = 'solid'

transparent: bool = False

ts_bonds: list[tuple[int, int]]

ts_color: str | None = None

ts_dash: tuple[float, float] = (1.2, 2.2)

ts_element: bool = False

ts_width: float = 1.2

unbond: list[str]

vdw_gradient_strength: float = 1.6

vdw_h_scale: float = 0.7

vdw_indices: list[int] | None = None

vdw_interlock_samples: int = 64

vdw_interlocking: bool = False

vdw_opacity: float = 0.5

vdw_outline_color: str | None = None

vdw_outline_width: float | None = None

vdw_scale: float = 1.0

vector_color: str = 'firebrick'

vector_scale: float = 1.0

vectors: list[VectorArrow]

class xyzrender.types.SVGResult(svg)

Bases: object

Wraps a rendered SVG string with Jupyter display and file-save support.

save(path)

Write the SVG to path (must end with .svg).

Return type:

None

class xyzrender.types.StyleRegion(indices, config)

Bases: object

A subset of atoms rendered with a different visual style.

Only per-atom/bond fields are used (atom_scale, gradient, bond_width, etc.); global fields (canvas_size, background, fog, surfaces) are taken from the base config.

config: RenderConfig

indices: list[int]

class xyzrender.types.VectorArrow(vector, origin, color='#444444', label='', scale=1.0, anchor='tail', host_atom=None, draw_on_top=False, is_axis=False, font_size=None, width=None)

Bases: object

A 3D vector to be drawn as an arrow in the rendered image.

Parameters:

• vector (ndarray) – 3-component array giving the direction and magnitude of the arrow (Å or any consistent unit — the length on screen scales with the molecule).

• origin (ndarray) – 3D origin point of the arrow tail in the same coordinate frame as atom positions. Set this after resolving "com" or atom-index origins.

• color (str) – CSS hex color string (default '#444444').

• label (str) – Optional text placed near the arrowhead.

• scale (float) – Additional per-arrow length scale factor applied on top of any global vector_scale setting (default 1.0).

• host_atom (int | None) – 0-based index of the atom this arrow is centred on, or None when the origin was specified as "com" or explicit coordinates. Used by the renderer to determine whether the arrowhead protrudes in front of the host atom without an expensive nearest-neighbour search.

anchor: str = 'tail'

color: str = '#444444'

draw_on_top: bool = False

font_size: float | None = None

host_atom: int | None = None

is_axis: bool = False

label: str = ''

origin: ndarray

scale: float = 1.0

vector: ndarray

width: float | None = None