Viewer UI#

This page introduces the on-canvas UI you see inside the viewer.

When you are working in a notebook, it is easy to focus on code and forget that the viewer also provides a small, practical UI for everyday actions.

Here we will walk through what appears on the canvas (buttons, the structures bar, and the popout). If what you need is camera navigation (zoom, snapshots, and interaction), see Camera and controls.

The canvas#

A good way to understand the UI is to start from a concrete view.

Below, the demo system is rendered on the canvas (the 3D viewport). The small UI elements you see on top of the canvas are the on-canvas controls.

import molsysviewer as viewer

view = viewer.demo["pentalanine"]
view.show()

A few practical notes:

  • The canvas is rendered on the browser side by Mol* (MolStar).

  • You drive it from the Python side by calling methods on a MolSysView object (view).

  • When a molecular system has multiple structures, the viewer shows a small structures bar so you can move between them.

Take a moment to click the buttons on the canvas above (Reset, Fullscreen, Background, Spin/Swing), and try moving the structures slider to see how the view changes.

UI controls#

MolSysViewer provides a compact set of on-canvas controls so you can perform common actions without writing code for every interaction.

Buttons#

The on-canvas buttons are:

  • Reset: reset the camera view.

  • Full: toggle fullscreen.

  • Bg: toggle light/dark background.

  • Spin: toggle continuous spin animation.

  • Swing: toggle rocking animation.

  • Pop: open a synced popout window (only when enabled).

The Pop button deserves a bit more context; see Popout.

Tip

  • These buttons are meant to be used interactively while you work. You can always reproduce the same actions from Python later (for example, reset the camera with view.reset_camera()).

Structures bar#

If your molecular system has multiple structures, the viewer exposes a small structures bar. It only appears when there is more than one structure.

You can:

  • Step backward/forward by step using the − and + buttons.

  • Play/pause using the play button (▶ / ⏸).

  • Scrub to a structure index using the slider.

  • Read the current position as current / total (1-based).

  • Set the step size and playback FPS with the numeric fields.

Controls customization#

You can hide the on-canvas UI entirely from your notebook:

view.set_controls_visible(False)

You can also enable autohide and configure placement:

view.set_controls_visible(
    True,
    autohide=True,
    position=["top", "right"],
    position_fullscreen=["bottom", "right"],
)

Defaults come from molsysviewer.config:

  • molsysviewer.config.show_controls

  • molsysviewer.config.autohide_controls

  • molsysviewer.config.controls_position

  • molsysviewer.config.controls_position_fullscreen

Popout#

The popout is a second viewer window that acts like a synced “twin” of your main canvas.

It is useful when you want to keep a large, clean viewer window (for example, on a second monitor or during a presentation), while still driving the scene from your notebook.

If popout is enabled, try clicking the Pop button on the canvas above. Then interact with the popout: rotate the scene, zoom, and move between structures. You should see that it stays synced with the host view:

  • camera changes,

  • spin/swing toggles,

  • and scene operations (load, shapes, regions, layers).

Notes

  • Your browser may block popouts by default. If the popout does not open, check the popup-blocker settings.

  • In docs-light exports (write_html(..., mode="lite")), the popout button is controlled by include_popout.