moleculekit.viewer.backends module#

Registry of viewer backends.

A backend is anything that can show a Molecule: an application embedding moleculekit, a notebook widget, a browser viewer driven from Pyodide. Registering one makes its name usable as mol.view(viewer=...), and lets a viewer that is already on screen follow the changes made to mol.reps afterwards, rather than having to rebuild its scene or replace moleculekit’s own methods to notice them.

A backend is duck-typed. Only view is required:

  • view(mol, name=None): show the molecule. Called by moleculekit.molecule.Molecule.view().

  • representation_added(mol, index, params): a representation was appended.

  • representation_updated(mol, index, params): one was changed in place.

  • representation_removed(mol, index): one was removed, or all of them when index is None.

  • volume_representation_added/updated/removed(vol, index, params): the same three for the isosurfaces of a moleculekit.volume.Volume.

params is the same translated description the Mol* scene is built from (for a molecule type, color, opacity, size_factor, label_fields, sel and the rest; for a volume isovalue, color, opacity, wireframe and visibility), or None when a molecule’s selection matched no atoms. A backend that leaves a method out simply does not hear about that kind of change.

Examples

>>> from moleculekit.viewer.backends import register_viewer
>>> class Printer:
...     def view(self, mol, name=None):
...         print(f"showing {mol.numAtoms} atoms")
...     def representation_added(self, mol, index, params):
...         print(f"rep {index} is a {params['type']}")
>>> register_viewer("printer", Printer())
>>> mol.reps.add("protein", "NewCartoon")
rep 0 is a cartoon
>>> mol.view(viewer="printer")
showing 1701 atoms
moleculekit.viewer.backends.default_viewer()#

The registered backend to use when nothing else chose one.

A live viewer being registered is a strong signal that it is where a molecule should go, so a single registered backend becomes the default. Several are ambiguous, and then the usual resolution order applies.

Returns:

name – The name of the only registered backend, or None.

Return type:

str or None

moleculekit.viewer.backends.get_viewer(name)#

Look a backend up by name.

Parameters:

name (str) – The name it was registered under. Case insensitive.

Returns:

backend – The backend, or None if nothing is registered under that name.

Return type:

object or None

moleculekit.viewer.backends.notify(event, obj, index, params, kind='representation')#

Tell every backend that cares about a change to an object’s reps.

Parameters:

  • event (str) – added, updated or removed.

  • obj (moleculekit.molecule.Molecule or Volume) – The object whose representations changed. A backend showing several objects uses this to tell which one it was, and ignores those it is not showing.

  • index (int or None) – Which representation, or None when all of them were removed.

  • params (callable) – Returns the translated representation, called only if a backend is listening, since translating a molecule’s resolves the selection against it and a scene being built has no need of it.

  • kind (str) – representation for a molecule’s, volume_representation for a volume’s. It names the methods a backend implements to hear about them, so that a backend showing both can tell them apart.

moleculekit.viewer.backends.register_viewer(name, backend)#

Register a viewer backend under a name.

Parameters:

  • name (str) – The name to pass as mol.view(viewer=name). Case insensitive.

  • backend (object) – An object with a view method, and optionally the representation callbacks described in this module’s docstring.

Raises:

ValueError – If the backend has no view method, or the name is one of the built-in viewers, which are not replaceable this way.

moleculekit.viewer.backends.unregister_viewer(name)#

Forget a registered backend.

Parameters:

name (str) – The name it was registered under.