molsysviewer package#

Subpackages#

Submodules#

molsysviewer.demo module#

molsysviewer.layers module#

class molsysviewer.layers.Layer(view, tag, *, kind=None, meta=None)[source]#

Bases: object

Wrapper for a non-structural visual layer (shapes, overlays) addressed by tag.

Parameters:

  • view (Any)

  • tag (str)

  • kind (str | None)

  • meta (Optional[Dict[str, Any]])

delete()[source]#

Remove this layer and its visuals.

Return type:

None

hide()[source]#

Hide this layer (all contained visuals).

Return type:

None

set_tag(new_tag)[source]#

Change this layer’s tag (and update the registry).

Parameters:

new_tag (str)

Return type:

None

show()[source]#

Show this layer (all contained visuals).

Return type:

None

molsysviewer.new_view module#

molsysviewer.new_view.new_view(molecular_system, selection='all', structure_indices='all', *, debug_js=None, view=None)[source]#

Create and return a MolSysView, optionally loading a molecular system.

This is a convenience factory. It instantiates a MolSysView (unless one is provided via view), calls view.load(...) with the given inputs, and returns the view.

Parameters:

  • molecular_system (Any)

  • selection (str | Sequence[int])

  • structure_indices (str | Sequence[int])

  • debug_js (bool | None)

  • view (MolSysView | None)

Return type:

MolSysView

molsysviewer.regions module#

class molsysviewer.regions.Region(view, tag, selection, *, atom_indices=None, representation=None, repr_params=None)[source]#

Bases: object

Wrapper for a molecular region (Mol* component) addressed by tag.

Parameters:

  • view (Any)

  • tag (str)

  • selection (str | Any)

  • atom_indices (Optional[list[int]])

  • representation (str | None)

  • repr_params (Optional[Dict[str, Any]])

delete()[source]#

Remove this region and its representations.

Return type:

None

hide()[source]#

Hide this region (all attached representations).

Return type:

None

new_complementary_region(tag=None, **kwargs)[source]#

Create a new region with the complement of this region’s atoms.

The resulting tag defaults to f"Global-{self.tag}" if not provided.

Parameters:

  • tag (str | None)

  • kwargs (Any)

Return type:

Region

set_representation(representation=None, *, preset=None, **params)[source]#

Apply or update a representation for this region.

Allowed Mol* types (normalized, case-insensitive): cartoon, backbone, ball-and-stick (aliases: sticks, ballstick), carbohydrate, ellipsoid, gaussian-surface, gaussian-volume, label, line (aliases: licorice, wire), molecular-surface (alias: surface), orientation, plane, point, putty, spacefill (alias: vdw).

If preset is provided, it supersedes representation and applies a Mol* preset (auto, atomic-detail, polymer-and-ligand, polymer-cartoon, coarse-surface, empty).

Parameters:

  • representation (str | None)

  • preset (str | None)

  • params (Any)

Return type:

None

show()[source]#

Show this region (all attached representations).

Return type:

None

molsysviewer.viewer module#

class molsysviewer.viewer.MolSysView(*, debug_js=None)[source]#

Bases: object

Mol* viewer widget with a Python-facing API.

Provides structure loading, visibility control, shape management, and utilities to export static HTML views for documentation or sharing.

Parameters:

debug_js (bool | None)

clear_decorations(*, shapes=True, styles=True, labels=True)[source]#

Clear decorative elements (shapes/styles/labels) without touching the loaded structure or camera.

Parameters:

  • shapes (bool)

  • styles (bool)

  • labels (bool)

Return type:

None

get_camera_snapshot(*, pretty=False)[source]#

Return the last camera snapshot received from the frontend.

Parameters:

pretty (bool) – If True, return a formatted JSON string instead of a dict.

Return type:

dict | str | None

hide(selection='all', structure_indices='all', syntax='MolSysMT')[source]#

Hide atoms matching the given selection (MolSysMT syntax by default).

Parameters:

  • selection (str | Any)

  • structure_indices (str | Any)

  • syntax (str)

info(element='system', selection='all', syntax='MolSysMT', skip_digestion=False)[source]#
isolate(selection='all', structure_indices='all', syntax='MolSysMT')[source]#

Show only the atoms in selection; hide everything else (reset if selection == ‘all’).

Parameters:

  • selection (str | Any)

  • structure_indices (str | Any)

  • syntax (str)

property js_logs: list[dict[str, str]]#

Logs received from the frontend when debug_js is enabled.

property layers: Mapping[str, Layer]#

Public registry of layers (non-structural visuals).

load(molecular_system, selection='all', structure_indices='all', syntax='MolSysMT', label=None)[source]#

Load a molecular system (MolSysMT-compatible) into the viewer.

Parameters:

  • molecular_system (Any)

  • selection (str | Any)

  • structure_indices (str | Any)

  • syntax (str)

  • label (str | None)

Return type:

None

new_layer(*, tag=None, kind=None, **meta)[source]#

Create a new layer (non-structural visual group).

Parameters:

  • tag (str | None)

  • kind (str | None)

  • meta (Any)

Return type:

Layer

new_region(selection='all', *, atom_indices=None, tag=None, representation=None, complement_of_regions=None, **repr_params)[source]#

Create a new region (structural subset) with an optional representation.

Parameters:

  • selection (str | Any) – MolSysMT selection string/expression. Ignored if atom_indices is provided.

  • atom_indices (list[int] | None) – Explicit atom indices for the region (bypasses selection). If not provided, they are computed from selection when possible.

  • tag (str | None) – Optional tag for the region. Auto-generated if omitted.

  • representation (str | None) – Optional representation type (normalized and validated).

  • complement_of_regions (str | list[str] | None) – Tags of regions to exclude. If “all”/”All”/”ALL”, the region covers the complement of all existing regions. Ignored if atom_indices is set.

  • repr_params (Any)

Return type:

Region

Notes

Requires a loaded molecular system. Call load(...) before creating regions. When using complement_of_regions, the union of those regions’ atom indices is removed from the full system to build the new region. Region indices are taken from their stored atom_indices (acks) when available.

property regions: Mapping[str, Region]#

Public registry of regions (structural selections).

reset_camera()[source]#

Reset the camera / view in the frontend.

Return type:

None

reset_viewer()[source]#

Fully clear the viewer and reset internal state (requires a new load(…)).

Return type:

None

set_camera_snapshot(snapshot, *, duration_ms=0)[source]#

Apply a previously saved camera snapshot.

Parameters:

  • snapshot (dict) – Camera snapshot dict (Mol* format).

  • duration_ms (int) – Transition duration in milliseconds.

Return type:

None

set_controls_visible(visible, *, autohide=None, position=None, position_fullscreen=None)[source]#

Show or hide the on-canvas controls (reset/full/bg/spin/swing + trajectory bar). Optionally toggle autohide and positions.

Parameters:

  • visible (bool)

  • autohide (bool | None)

  • position (list[str] | tuple[str, str] | None)

  • position_fullscreen (list[str] | tuple[str, str] | None)

Return type:

None

show(selection='all', structure_indices='all', syntax='MolSysMT', *, force=False)[source]#

Show the widget (first call or if force=True) and optionally adjust visibility.

Parameters:

  • selection (str | Any)

  • structure_indices (str | Any)

  • syntax (str)

  • force (bool)

property visible_atom_indices#

Return the indices of currently visible atoms.

property visible_structure_indices#

Return the indices of currently visible structures.

write_html(output_filename, *, title='MolSysViewer', include_controls=True, include_popout=True, mode='standalone', inline_messages=True)[source]#

Export this viewer widget to an HTML file.

Parameters:

  • output_filename (str) – Path to the HTML file to create.

  • title (str) – Optional title for the exported HTML page.

  • include_controls (bool) – If True (default), include the on-canvas control buttons (Reset, Fullscreen, background toggle, Spin, Swing) in the exported view. Set this to False if you prefer a minimal viewer without these controls, for example when embedding inside another application that already provides its own UI.

  • include_popout (bool) – If True (default), include the popout button and allow opening a popout window.

  • mode (str) –

    • "standalone" (default): produce a self-contained HTML using the widget embed machinery.

    • "lite": produce a lightweight HTML that loads the runtime from the CDN and replays messages (suitable for embedded docs-light views).

  • inline_messages (bool) – Only used when mode="lite". If True (default), embed the replay messages inline in the HTML.

Return type:

None

zoom(selection='all', structure_indices='all', syntax='MolSysMT', *, duration_ms='250 ms', extra_radius='4.0 angstroms', min_radius='1.0 angstroms')[source]#

Focus the camera on the geometric center of a selection of atoms.

Parameters:

  • selection (str | Any) – MolSysMT selection string/expression or a list of atom indices. If a list is provided, it is passed through MolSysMT and used directly.

  • structure_indices (str | Any) – Structure indices to apply when resolving the selection.

  • syntax (str) – Selection syntax understood by MolSysMT.

  • duration_ms (Any) – Transition duration in milliseconds for the camera move.

  • extra_radius (Any) – Extra padding (Å) added to the selection’s bounding sphere.

  • min_radius (Any) – Minimum radius (Å) to enforce for the camera focus.

Return type:

None

molsysviewer.whole module#

class molsysviewer.whole.Whole(view)[source]#

Bases: object

Wrapper for operations on the whole structure (non-deletable, non-retaggable).

Parameters:

view (Any)

hide()[source]#

Hide the global representation(s).

Return type:

None

set_representation(representation=None, *, preset=None, **params)[source]#

Set or update the global representation for the whole structure.

If the global representation was hidden, this call will show it again.

Parameters:

  • representation (str | None) – Simple representation type (e.g., cartoon, ball-and-stick, line). Ignored if preset is provided.

  • preset (str | None) – Optional Mol* preset (auto, atomic-detail, polymer-and-ligand, polymer-cartoon, coarse-surface, empty). When provided, supersedes representation and applies the preconfigured style bundle.

  • params (Any)

Return type:

None

show()[source]#

Show the global representation(s).

Return type:

None

molsysviewer.widget module#

class molsysviewer.widget.MolSysViewerWidget(**kwargs)[source]#

Bases: AnyWidget

Parameters:

  • args (object)

  • kwargs (object)

autohide_controls#

A boolean (True, False) trait.

controls_position#

An instance of a Python list.

controls_position_fullscreen#

An instance of a Python list.

debug_js#

A boolean (True, False) trait.

enable_popout#

A boolean (True, False) trait.

initial_messages#

An instance of a Python list.

popup_js_source#

A trait for unicode strings.

show_controls#

A boolean (True, False) trait.

Module contents#

class molsysviewer.MolSysView(*, debug_js=None)[source]#

Bases: object

Mol* viewer widget with a Python-facing API.

Provides structure loading, visibility control, shape management, and utilities to export static HTML views for documentation or sharing.

Parameters:

debug_js (bool | None)

clear_decorations(*, shapes=True, styles=True, labels=True)[source]#

Clear decorative elements (shapes/styles/labels) without touching the loaded structure or camera.

Parameters:

  • shapes (bool)

  • styles (bool)

  • labels (bool)

Return type:

None

get_camera_snapshot(*, pretty=False)[source]#

Return the last camera snapshot received from the frontend.

Parameters:

pretty (bool) – If True, return a formatted JSON string instead of a dict.

Return type:

dict | str | None

hide(selection='all', structure_indices='all', syntax='MolSysMT')[source]#

Hide atoms matching the given selection (MolSysMT syntax by default).

Parameters:

  • selection (str | Any)

  • structure_indices (str | Any)

  • syntax (str)

info(element='system', selection='all', syntax='MolSysMT', skip_digestion=False)[source]#
isolate(selection='all', structure_indices='all', syntax='MolSysMT')[source]#

Show only the atoms in selection; hide everything else (reset if selection == ‘all’).

Parameters:

  • selection (str | Any)

  • structure_indices (str | Any)

  • syntax (str)

property js_logs: list[dict[str, str]]#

Logs received from the frontend when debug_js is enabled.

property layers: Mapping[str, Layer]#

Public registry of layers (non-structural visuals).

load(molecular_system, selection='all', structure_indices='all', syntax='MolSysMT', label=None)[source]#

Load a molecular system (MolSysMT-compatible) into the viewer.

Parameters:

  • molecular_system (Any)

  • selection (str | Any)

  • structure_indices (str | Any)

  • syntax (str)

  • label (str | None)

Return type:

None

new_layer(*, tag=None, kind=None, **meta)[source]#

Create a new layer (non-structural visual group).

Parameters:

  • tag (str | None)

  • kind (str | None)

  • meta (Any)

Return type:

Layer

new_region(selection='all', *, atom_indices=None, tag=None, representation=None, complement_of_regions=None, **repr_params)[source]#

Create a new region (structural subset) with an optional representation.

Parameters:

  • selection (str | Any) – MolSysMT selection string/expression. Ignored if atom_indices is provided.

  • atom_indices (list[int] | None) – Explicit atom indices for the region (bypasses selection). If not provided, they are computed from selection when possible.

  • tag (str | None) – Optional tag for the region. Auto-generated if omitted.

  • representation (str | None) – Optional representation type (normalized and validated).

  • complement_of_regions (str | list[str] | None) – Tags of regions to exclude. If “all”/”All”/”ALL”, the region covers the complement of all existing regions. Ignored if atom_indices is set.

  • repr_params (Any)

Return type:

Region

Notes

Requires a loaded molecular system. Call load(...) before creating regions. When using complement_of_regions, the union of those regions’ atom indices is removed from the full system to build the new region. Region indices are taken from their stored atom_indices (acks) when available.

property regions: Mapping[str, Region]#

Public registry of regions (structural selections).

reset_camera()[source]#

Reset the camera / view in the frontend.

Return type:

None

reset_viewer()[source]#

Fully clear the viewer and reset internal state (requires a new load(…)).

Return type:

None

set_camera_snapshot(snapshot, *, duration_ms=0)[source]#

Apply a previously saved camera snapshot.

Parameters:

  • snapshot (dict) – Camera snapshot dict (Mol* format).

  • duration_ms (int) – Transition duration in milliseconds.

Return type:

None

set_controls_visible(visible, *, autohide=None, position=None, position_fullscreen=None)[source]#

Show or hide the on-canvas controls (reset/full/bg/spin/swing + trajectory bar). Optionally toggle autohide and positions.

Parameters:

  • visible (bool)

  • autohide (bool | None)

  • position (list[str] | tuple[str, str] | None)

  • position_fullscreen (list[str] | tuple[str, str] | None)

Return type:

None

show(selection='all', structure_indices='all', syntax='MolSysMT', *, force=False)[source]#

Show the widget (first call or if force=True) and optionally adjust visibility.

Parameters:

  • selection (str | Any)

  • structure_indices (str | Any)

  • syntax (str)

  • force (bool)

property visible_atom_indices#

Return the indices of currently visible atoms.

property visible_structure_indices#

Return the indices of currently visible structures.

write_html(output_filename, *, title='MolSysViewer', include_controls=True, include_popout=True, mode='standalone', inline_messages=True)[source]#

Export this viewer widget to an HTML file.

Parameters:

  • output_filename (str) – Path to the HTML file to create.

  • title (str) – Optional title for the exported HTML page.

  • include_controls (bool) – If True (default), include the on-canvas control buttons (Reset, Fullscreen, background toggle, Spin, Swing) in the exported view. Set this to False if you prefer a minimal viewer without these controls, for example when embedding inside another application that already provides its own UI.

  • include_popout (bool) – If True (default), include the popout button and allow opening a popout window.

  • mode (str) –

    • "standalone" (default): produce a self-contained HTML using the widget embed machinery.

    • "lite": produce a lightweight HTML that loads the runtime from the CDN and replays messages (suitable for embedded docs-light views).

  • inline_messages (bool) – Only used when mode="lite". If True (default), embed the replay messages inline in the HTML.

Return type:

None

zoom(selection='all', structure_indices='all', syntax='MolSysMT', *, duration_ms='250 ms', extra_radius='4.0 angstroms', min_radius='1.0 angstroms')[source]#

Focus the camera on the geometric center of a selection of atoms.

Parameters:

  • selection (str | Any) – MolSysMT selection string/expression or a list of atom indices. If a list is provided, it is passed through MolSysMT and used directly.

  • structure_indices (str | Any) – Structure indices to apply when resolving the selection.

  • syntax (str) – Selection syntax understood by MolSysMT.

  • duration_ms (Any) – Transition duration in milliseconds for the camera move.

  • extra_radius (Any) – Extra padding (Å) added to the selection’s bounding sphere.

  • min_radius (Any) – Minimum radius (Å) to enforce for the camera focus.

Return type:

None

molsysviewer.new_view(molecular_system, selection='all', structure_indices='all', *, debug_js=None, view=None)[source]#

Create and return a MolSysView, optionally loading a molecular system.

This is a convenience factory. It instantiates a MolSysView (unless one is provided via view), calls view.load(...) with the given inputs, and returns the view.

Parameters:

  • molecular_system (Any)

  • selection (str | Sequence[int])

  • structure_indices (str | Sequence[int])

  • debug_js (bool | None)

  • view (MolSysView | None)

Return type:

MolSysView

On this page