Skip to content

Python Controllers

Viewer interaction is organized around focused controller objects returned from the session facade.

Camera

_camera

CameraController(session: 'ViewerSessionFacade')

Control the viewer camera in structure-space coordinates.

The viewer renders chemistry-style structure coordinates with z as the semantic up axis. Internally the Bevy camera still uses its own world convention, so focus points and pan vectors are rotated before being sent to the low-level backend.

frame_all() -> None

Reset the camera to frame the whole current structure.

look_at(focus, radius: float | None = None, yaw: float | None = None, pitch: float | None = None) -> None

Set the camera focus and optionally update view parameters.

Parameters:

  • focus –

    Structure-space (x, y, z) focus point.

  • radius (float or None, default: None ) –

    Camera distance from the focus point.

  • yaw (float or None, default: None ) –

    Orbit angle around the structure z axis, in radians.

  • pitch (float or None, default: None ) –

    Tilt away from the structure xy plane, in radians.

orbit(yaw_delta: float = 0.0, pitch_delta: float = 0.0) -> None

Apply an immediate orbit step.

Parameters:

  • yaw_delta (float, default: 0.0 ) –

    Increment around the structure z axis, in radians.

  • pitch_delta (float, default: 0.0 ) –

    Increment away from the structure xy plane, in radians.

pan(delta) -> None

Translate the camera focus by a structure-space delta.

Parameters:

  • delta –

    Structure-space (x, y, z) translation applied to the focus point.

set_focus(focus) -> None

Move the camera focus to a new structure-space point.

Parameters:

  • focus –

    Structure-space (x, y, z) focus point.

set_radius(radius: float) -> None

Set the camera distance from the current focus point.

Parameters:

  • radius (float) –

    Camera distance from the current focus point.

set_rotation(yaw: float | None = None, pitch: float | None = None) -> None

Set the camera yaw and pitch in structure-space terms.

Parameters:

  • yaw (float or None, default: None ) –

    Orbit angle around the structure z axis, in radians.

  • pitch (float or None, default: None ) –

    Tilt away from the structure xy plane around structure x, in radians.

start_orbit(yaw_rate: float = 0.5, pitch_rate: float = 0.0) -> None

Start continuous orbit motion.

Parameters:

  • yaw_rate (float, default: 0.5 ) –

    Continuous rotation rate around the structure z axis, in radians per second.

  • pitch_rate (float, default: 0.0 ) –

    Continuous tilt rate, in radians per second.

stop() -> None

Stop any active camera motion started by start_orbit.

zoom(factor: float | None = None, delta: float | None = None) -> None

Zoom by a multiplicative factor or additive radius delta.

Parameters:

  • factor (float or None, default: None ) –

    Multiplicative zoom factor.

  • delta (float or None, default: None ) –

    Additive change in camera radius.

Colors and Selection

_color

ScalarRangeTracker()

Track a scalar range across multiple arrays or frames.

limits: tuple[float, float] property

Return the current (min, max) limits.

update(values) -> tuple[float, float]

Expand the tracked range with finite values from an array.

Parameters:

  • values –

    Array-like scalar values.

Returns:

ColorController(session: 'ViewerSessionFacade')

Manage scalar fields and color mappings for the current viewer session.

by_scalar(name: str, palette: str = 'viridis', colors=None, min: float | None = None, max: float | None = None, append: bool = False) -> None

Color atoms by a named scalar field.

Parameters:

  • name (str) –

    Scalar field name to visualize.

  • palette (str, default: "viridis" ) –

    Built-in colormap name.

  • colors (sequence, default: None ) –

    Explicit sampled colors used instead of a built-in palette.

  • min (float or None, default: None ) –

    Lower bound for scalar normalization.

  • max (float or None, default: None ) –

    Upper bound for scalar normalization.

  • append (bool, default: False ) –

    If True, append the rule instead of replacing existing color rules.

range_tracker() -> ScalarRangeTracker

Create a helper for keeping a fixed scalar range across frames.

Returns:

reset() -> None

Restore default element-based coloring.

set_atom_scalars(name: str, values, frame_index: int | None = None) -> None

Store a per-atom scalar field.

Parameters:

  • name (str) –

    Scalar field name.

  • values –

    Per-atom scalar values for the target frame.

  • frame_index (int or None, default: None ) –

    Frame index to update. None uses the current frame.

ViewerSelection(session: 'ViewerSessionFacade', selection, frame_index: int | None = None)

Apply scalar and color operations to a subset of atoms.

ball_and_stick(atom_scale: float = 0.45, bond_radius: float = 0.08, bond_color=(0.7, 0.7, 0.7), bond_scope: str = 'both_selected', frame_index: int | None = None) -> 'ViewerSessionFacade'

Apply ball-and-stick rendering to the selection.

Parameters:

  • atom_scale (float, default: 0.45 ) –

    Relative atom radius for selected atoms.

  • bond_radius (float, default: 0.08 ) –

    Radius of rendered bonds.

  • bond_color (tuple, default: (0.7, 0.7, 0.7) ) –

    Bond color as RGB values.

  • bond_scope (str, default: "both_selected" ) –

    Bond-selection rule passed to the render backend.

  • frame_index (int or None, default: None ) –

    Frame index to update. None uses the selection's default frame.

Returns:

color_by_scalar(name: str, values, palette: str = 'viridis', colors=None, min: float | None = None, max: float | None = None, frame_index: int | None = None) -> 'ViewerSessionFacade'

Color the selection by scalar values while leaving other atoms unchanged.

Parameters:

  • name (str) –

    Scalar field name.

  • values –

    Scalar value, full-length array, or selection-length array.

  • palette (str, default: "viridis" ) –

    Built-in colormap name.

  • colors (sequence, default: None ) –

    Explicit sampled colors used instead of a built-in palette.

  • min (float or None, default: None ) –

    Lower bound for scalar normalization.

  • max (float or None, default: None ) –

    Upper bound for scalar normalization.

  • frame_index (int or None, default: None ) –

    Frame index to update. None uses the selection's default frame.

Returns:

set_atom_scalars(name: str, values, frame_index: int | None = None) -> 'ViewerSessionFacade'

Store a scalar field for the selection.

Unselected atoms are masked with NaN so later scalar coloring can leave them visually unchanged.

Parameters:

  • name (str) –

    Scalar field name.

  • values –

    Scalar value, full-length array, or selection-length array.

  • frame_index (int or None, default: None ) –

    Frame index to update. None uses the selection's default frame.

Returns:

Rendering

_render

RenderController(session: 'ViewerSessionFacade')

Manage rendering styles, bonds, and polygon faces.

add_bonds(bonds, frame_index: int | None = None) -> None

Add explicit bond connectivity for one frame.

add_faces(faces, color=(0.2, 0.6, 0.9, 0.35), face_colors=None, frame_index: int | None = None) -> None

Add explicit polygon faces for one frame.

ball_and_stick(selection=None, atom_scale: float = 0.45, bond_radius: float = 0.08, bond_color=(0.7, 0.7, 0.7), bond_scope: str = 'both_selected', frame_index: int | None = None, append: bool = False) -> None

Apply ball-and-stick rendering to a whole frame or a selection.

Parameters:

  • selection –

    Selection expression restricting the style to a subset of atoms.

  • optional –

    Selection expression restricting the style to a subset of atoms.

  • atom_scale (float, default: 0.45 ) –

    Relative atom radius for styled atoms.

  • bond_radius (float, default: 0.08 ) –

    Radius of rendered bonds.

  • bond_color (tuple, default: (0.7, 0.7, 0.7) ) –

    Bond color as RGB values.

  • bond_scope (str, default: "both_selected" ) –

    Bond-selection rule passed to the render backend.

  • frame_index (int or None, default: None ) –

    Frame index to update. None uses the current frame.

  • append (bool, default: False ) –

    If True, append the style instead of replacing existing styles.

clear_bonds(frame_index: int | None = None) -> None

Clear stored bond connectivity for one frame.

clear_faces(frame_index: int | None = None) -> None

Clear stored polygon faces for one frame.

remove_bonds(bonds, frame_index: int | None = None) -> None

Remove explicit bond connectivity for one frame.

remove_faces(faces, color=(0.2, 0.6, 0.9, 0.35), face_colors=None, frame_index: int | None = None) -> None

Remove explicit polygon faces for one frame.

reset() -> None

Restore pure space-filling rendering.

set_bonds(bonds=None, frame_index: int | None = None, *, mode: str | None = None, selection=None, cutoff_multiplier: float = 1.2) -> None

Store explicit bond connectivity for one frame.

Parameters:

  • bonds –

    Iterable of atom-index pairs, a square adjacency matrix, or a neighbor-list object with i/j arrays.

  • frame_index (int or None, default: None ) –

    Frame index to update. None uses the current frame.

  • mode (str or None, default: None ) –

    "default" derives bonds from the current frame using ASE-style natural cutoffs.

  • selection –

    Selection restricting auto-generated bonds to pairs whose endpoints are both selected.

  • optional –

    Selection restricting auto-generated bonds to pairs whose endpoints are both selected.

  • cutoff_multiplier (float, default: 1.2 ) –

    Multiplier used with ASE natural cutoffs for auto-generated bonds.

set_bonds_from_adjacency(adjacency, frame_index: int | None = None) -> None

Store bonds from a square adjacency matrix.

Parameters:

  • adjacency –

    Square boolean or numeric adjacency matrix.

  • frame_index (int or None, default: None ) –

    Frame index to update. None uses the current frame.

set_faces(faces=None, color=(0.2, 0.6, 0.9, 0.35), face_colors=None, frame_index: int | None = None, *, mode: str | None = None, selection=None, cutoff_multiplier: float = 1.2) -> None

Store explicit polygon faces for one frame.

Parameters:

  • faces –

    Iterable of face definitions expressed as atom-index sequences.

  • color (tuple, default: (0.2, 0.6, 0.9, 0.35) ) –

    Default RGBA color for all faces.

  • face_colors (sequence, default: None ) –

    Per-face RGBA colors.

  • frame_index (int or None, default: None ) –

    Frame index to update. None uses the current frame.

  • mode (str or None, default: None ) –

    "default" derives best-effort ligand-shell polyhedra from the current frame using ASE-style natural cutoffs.

  • selection –

    Selection restricting auto-generated polyhedra centers.

  • optional –

    Selection restricting auto-generated polyhedra centers.

  • cutoff_multiplier (float, default: 1.2 ) –

    Multiplier used with ASE natural cutoffs for auto-generated polyhedra.