moleculekit.viewer.molstar.scene module#

The rule that decides what a Mol* scene looks like, as plain data.

Both the interactive viewer and the headless renderer consume the dict this module produces, so they cannot drift: one decides, one applies. MolViewSpec is one possible encoding of the same description (see mvs.py) and is used by the notebook viewer and the docs theme, which cannot reach the shared bundle.

The vocabulary is MolViewSpec’s: selector names, representation type names and Mol* colour theme names are spelled exactly as MVS spells them, so translating in either direction is mechanical.

moleculekit.viewer.molstar.scene.LABEL_STYLE_KEYS = ('border_width', 'border_color', 'bg_color', 'bg_opacity', 'bg_margin', 'offset_x', 'offset_y', 'offset_z')#

Cosmetic keys a label_style may carry, and the label dict keys they become. Anything else is a typo, and a typo that draws a default-looking label is worse than one that says so.

moleculekit.viewer.molstar.scene.build_scene(mol, reps=None, *, ball_and_stick_sel=None, highlight_bonds=None, focus_sel=None, rotate=None, zoom=None, background_color=None, fog=None, clip=None)#

Describe the scene for mol as a plain dict.

When reps is empty a cartoon is used for the polymer if mol has at least MIN_CARTOON_RESIDUES standard polymer residues, with ligands, ions, water, branched entities and non-standard residues as ball-and-stick, and ball-and-stick throughout otherwise. When reps is non-empty those representations are the whole scene, matching how the VMD and NGL backends treat mol.reps.

Parameters:

  • mol (Molecule) – The molecule whose topology and coordinates drive the scene. The frame used for label and tube positions is mol.frame.

  • reps (list or None, optional) – Representations to render: normally the ones held in mol.reps, together with any one-off representation added by view()’s sel, style and color arguments. An empty list or None gives the automatic scene.

  • ball_and_stick_sel (str | ndarray | None) – An extra atom selection to additionally draw as ball-and-stick. Ignored when it matches no atoms.

  • highlight_bonds (list[tuple[str, str]] | None) – Pairs of atom selections, each of which must pick exactly one atom. An orange tube is drawn between the two atoms of each pair.

  • focus_sel (str | ndarray | None) – An atom selection the camera frames on. Ignored when it matches no atoms.

  • rotate (str | tuple[float, float, float] | None) – Camera orientation, as a preset name or (rx, ry, rz) in degrees.

  • zoom (float | None) – Camera tightness. Larger values move the camera closer.

  • background_color (str | None) – Canvas background as an SVG colour name or hex string.

  • fog (float | None) – Depth cueing strength, from 0 for none to 100 for the strongest. Fog fades distant geometry into the background colour. None leaves Mol*’s own strength.

  • clip (float | None) – Half-thickness in Angstrom of the slab drawn around what the camera frames. Geometry nearer to or further from the camera than this is cut away. None draws the whole structure.

Returns:

scene – The scene description, with components always present and labels, tubes, camera and canvas present when they carry anything.

Return type:

dict

Raises:

ValueError – If every representation selection matches no atoms, if a highlight_bonds selection does not pick exactly one atom, if rotate names no known orientation preset, if fog falls outside 0 to 100, or if clip is not positive.

moleculekit.viewer.molstar.scene.default_representations(mol)#

The automatic scene written as representations any viewer can draw.

The automatic scene selects with Mol*’s builtin classifiers, which VMD and NGL have no equivalent of, so the split here is made with atom selection strings instead. It is a faithful starting point rather than a mirror: a residue moleculekit calls protein but that is spelled differently from the names in STANDARD_POLYMER_RESNAMES lands in the cartoon here and in ball-and-stick there.

Parameters:

mol (moleculekit.molecule.Molecule) – The molecule the scene would be built for.

Returns:

reps – (sel, style, color) triples in drawing order.

Return type:

list[tuple]

moleculekit.viewer.molstar.scene.focus_sphere(mols, focus_sel=None)#

The sphere the camera should frame, across every object in the scene.

With one molecule the browser can work this out from the selected atoms itself, but a selection spanning several structures cannot be expressed as one set of atom indices, so it is computed here from the coordinates.

Parameters:

  • mols (list) – The molecules in the scene. The frame used is each molecule’s own mol.frame.

  • focus_sel (str or numpy.ndarray or None, optional) – Atom selection to frame. None frames everything.

Returns:

  • center (list of float) – Middle of the framed atoms.

  • radius (float) – Distance from the centre to the furthest framed atom, never zero.

moleculekit.viewer.molstar.scene.rotation_to_direction_up(rotate)#

Resolve a rotation into the MVS direction and up vectors.

Parameters:

rotate (str or tuple of float or None) – A preset name from ORIENTATION_PRESETS, a tuple of (rx, ry, rz) rotations in degrees applied about the x, y and z axes in that order, or None for the default view.

Returns:

  • direction (tuple of float) – Unit vector from the camera position toward the target.

  • up (tuple of float) – Unit vector controlling the roll about direction.

Raises:

ValueError – If rotate is a string that names no known preset.