moleculekit.viewer.molstar.mvs module#

Pure MolViewSpec scene builder shared by the Sphinx docs theme and the inline notebook viewer. Builds the same protein/nucleic + hetero scene moleculekit’s viewer shows. The structure data URL is supplied by the caller (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)#

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.

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.