Interactive viewer

The interactive viewer opens a matplotlib window where you can explore a structure with mouse and keyboard controls. When the window is closed the adjusted ViewState and RenderStyle are returned, ready for static rendering.

Note

The interactive viewer requires a GUI-capable matplotlib backend such as QtAgg, TkAgg, or macosx. Non-interactive backends (Agg, pdf, svg) will not display a window.

In a Jupyter notebook, use the %matplotlib qt or %matplotlib tk magic before calling the viewer. The default inline backend does not support interactive windows.

view, style = scene.render_mpl_interactive()

# Reuse the adjusted view and style for static output:
scene.view = view
scene.render_mpl("output.svg", style=style)

You can pass an initial RenderStyle or override individual fields as keyword arguments:

view, style = scene.render_mpl_interactive(show_bonds=False)

Mouse controls

Left-drag rotates the structure.
Scroll wheel zooms in and out.

Keyboard controls

Press h during the interactive session to show a help overlay listing all keybindings.

Rotation and zoom

Key	Action
Arrow keys	Rotate around horizontal / vertical axes
`,` / `.`	Roll (rotate in the screen plane)
`+` or `=`	Zoom in
`-`	Zoom out

Pan and perspective

Key	Action
Shift + Arrow keys	Pan the view
`p` / `P`	Increase / decrease perspective strength
`d` / `D`	Increase / decrease viewing distance

Display toggles

Key	Action
`b`	Toggle bonds
`o`	Toggle outlines
`e`	Toggle polyhedra
`u`	Toggle unit cell edges
`a`	Toggle axes orientation widget

Frame navigation

For scenes with multiple frames (trajectories):

Key	Action
`[` / `]`	Step to previous / next frame
`{` / `}`	Jump to first / last frame
`f`	Toggle frame indicator
`g`	Go to a specific frame (type digits, then Enter)
`s`	Set frame step size (type digits, then Enter)

Other

Key	Action
`r`	Reset view to initial state
`h`	Toggle help overlay

Return values

The interactive viewer returns a (ViewState, RenderStyle) tuple. Any changes made during the session — rotation, zoom, perspective, and display toggles — are captured in the returned objects.

view, style = scene.render_mpl_interactive()

# The view captures rotation, zoom, pan, perspective, and distance.
scene.view = view

# The style captures display toggles (bonds, outlines, polyhedra, etc.).
scene.render_mpl("output.svg", style=style)

The returned RenderStyle uses publication-quality polygon counts (circle_segments=72, arc_segments=12) even though the interactive session uses lower-fidelity settings for responsiveness.