moleculekit.viewer.molstar.mvs module#

Translate the shared scene description (see scene.py) into MolViewSpec.

mvs_from_scene encodes an already-built scene dict and is what the inline notebook viewer calls (see inline.py’s build_inline_view). build_mvs builds the automatic protein/nucleic + hetero scene from a Molecule directly (calling build_scene itself, then mvs_from_scene); it has no caller left inside this repository, but do not delete it as dead code: it is the entry point the out-of-repo Acellera Sphinx docs theme depends on to render structures with no live viewer. The structure data URL is supplied by the caller in both cases (a published .bcif URL in docs, an inlined data: URL in notebooks).

moleculekit.viewer.molstar.mvs.build_mvs(mol, *, structure_url, ball_and_stick_sel=None, representations=None, highlight_bonds=None, focus_sel=None, rotate=None, zoom=None, background_color=None)#

Build the MolViewSpec (mvsj) JSON string describing the scene for mol.

A cartoon representation is used for the polymer when mol has at least MIN_CARTOON_RESIDUES standard polymer residues; ligands, ions, water, branched entities and any non-standard residues are drawn as ball-and-stick. Otherwise the whole structure is drawn as ball-and-stick. Formal-charge labels are added for charged atoms (up to MAX_FORMAL_CHARGE_LABELS).

Parameters:

  • mol (Molecule) – The molecule whose topology/coordinates drive the scene. The structure data itself is fetched by the viewer from structure_url; mol is used here to decide components, resolve selections and place labels.

  • structure_url (str) – The href the viewer downloads and parses as BinaryCIF (a published .bcif URL in docs, or an inlined data: URL in notebooks).

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

  • representations (list[dict] | None) – Extra representations to add. Each dict may carry atom_indices or a sel atom selection (one is required to pick atoms), plus color, opacity and any representation keywords (type defaults to "ball_and_stick"). color is None (element theme), a {"theme": name} dict, or an SVG/hex color string.

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

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

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

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

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

Returns:

mvsj – The serialized MolViewSpec scene as a JSON string.

Return type:

str

Raises:

ValueError – If any highlight_bonds selection does not pick exactly one atom, or if rotate is a string that names no known orientation preset.

moleculekit.viewer.molstar.mvs.mvs_from_scene(scene, *, structure_url)#

Encode a scene description as a MolViewSpec (mvsj) JSON string.

Parameters:
Returns:

mvsj – The serialized MolViewSpec scene as a JSON string.

Return type:

str