Molstar (Mol*)#

Molstar is the molecular visualizer bundled with Horus. Mol* is an open source molecular visualizer written in TypeScript and WebGL. You can find tutorials, documentation and the source code of Mol* at https://molstar.org.

Molstar implementation in Horus

In order to control Mol* from Horus, we use the MolstarAPI, a bridge built for communicating Blocks with the molecular visualizer.

MolstarAPI#

MolstarAPI is a library for creating and manipulating molecular structures in the embedded Mol* visualizer inside Horus. It is designed to be used within Blocks in order to add, visualize or edit molecular structures.

In order to control the molecular visualizer within a Block action, you need to import the MolstarAPI class and use the desired methods.

from HorusAPI import MolstarAPI

my_pdb_file = "/path/to/1crn.pdb"
molecule_name = "1crn crystal structure"

with open(my_pdb_file, "r") as f:
    pdb_file_contents = f.read()

# Create the structure calling directly the Mol* API
MolstarAPI().addPDB(pdb_file_contents, molecule_name)

The Mol* actions will be stored in the flow and will be applied to the canvas after it finishes. The actions will be applied in the order they were called. If a flow is not opened, the actions will be applied when the flow is first opened. After apllying the actions, the flow will be saved again with the updated Mol* state.

MolViewSpec#

The MolstarAPI in Horus is compatible with MolViewSpec. For more information about this library, please visit the MolViewSpec documentation.

Horus comes with mvs embedded inside the MolstarAPI, you can access the library by calling the mvs attribute of the MolstarAPI class.

from HorusAPI import MolstarAPI

mol = MolstarAPI()

# MolviewSpec
mvs = mol.mvs
builder = mvs.create_builder()
(
    builder.download(url="https://www.ebi.ac.uk/pdbe/entry-files/download/1cbs_updated.cif")
    .parse(format="mmcif")
    .assembly_structure(assembly_id="1")
    .component()
    .representation()
)

# We can load the scene in Mol* using the loadMVJS method
mol.loadMVJS(builder.get_state())

MolstarAPI methods#

The MolstarAPI module

class MolstarAPI(*args, **kwargs)#

API for interacting with Mol* visualizer inside Horus

addBox(center: list[float], sides: list[float] | None = None, lineSize: float = 1, color: str | None = None, opacity: float = 1) → None#

Adds a box to the scene.

Parameters:

  • center – The x, y and z coordinates of the center of the box as a list of [x, y ,z]

  • sides – The a, b and c lengths of the box as a list of [a, b ,c].

Defaults to [1, 1, 1] :param lineSize: The width of the lines. Defaults to 1. :param color: The color of the box as an RGB hex string (i.e. #0000FF) Defaults to random color. :param opacity: The opacity of the box (0.0 - 1.0). Defaults to 1.

addMolecule(filePath: str, label: str | None = None) → None#

Adds the given Molecule file to Mol*

Parameters:

  • filePath – The path to the molecule file

  • label – The label for the molecule. Optional. Defaults to the filename

addSphere(x: float, y: float, z: float, radius: float, color: str | None = None, opacity: float = 1) → None#

Adds a sphere to the scene.

Parameters:

  • x – The x coordinate of the sphere in Angstroms

  • y – The y coordinate of the sphere in Angstroms

  • z – The z coordinate of the sphere in Angstroms

  • radius – The radius of the sphere in Angstroms

  • color – The color of the sphere as an RGB hex string (i.e. #0000FF)

  • opacity – The opacity of the sphere (0.0 - 1.0)

focusResidue(residue: int, structureLabel: str | None = None, chain: str | None = None, nearRadius: int = 5) → None#

Focuses on the given residue

Parameters:

  • residue – The sequence number of the residue to focus

  • structureLabel – The label of the structure to focus

  • chain – The chain ID of the residue to focus

  • nearRadius – The radius around the residue to display nearby residues

loadMVJS(mvjs: Dict[str, Any], replaceExisting: bool = False) → None#

Loads a molviewspec session into Mol*

Parameters:

mvjs – The molviewspec session to load as a dictionary

(returned by the .get_state() method of molviewspec builder) :param replaceExisting: Whether to replace the existing session or not

loadTrajectory(topology: str, trajectory: str, label: str | None = None) → None#

Adds the given trajectory file to Mol*

Parameters:

  • topology – The path to the topology file

  • trajectory – The path to the trajectory file

  • label – The label for the trajectory. Optional. Defaults to the filename

property mvs#

The molviewspec library. Use it to build complex scenes

reset() → None#

Resets the visualizer

setBackgroundColor(color: str) → None#

Sets the background color of the scene

Parameters:

color – The color to set the background to as an RGB hex string (i.e. #0000FF)

setSpin(speed: float = 1) → None#

Sets the spin of the molecule.

Parameters:

speed – The rotation speed. Defaults to 1. To stop it, set the speed to 0