Drawing Commands¶

These methods are available on every Molvis instance, regardless of host (script, notebook, or CDN-hosted page).

Scene¶

draw_frame(frame, style=None, atom_radius=None, bond_radius=None)¶

Draw a molecular frame, replacing the current scene content.

scene.draw_frame(frame)
scene.draw_frame(frame, style="spacefill")
scene.draw_frame(frame, style="ball_and_stick", atom_radius=0.3)

draw_box(box)¶

Draw a simulation box wireframe.

scene.draw_box(box)

draw_atoms(atoms, style=None)¶

Draw individual atoms (without bonds).

scene.draw_atoms(atoms_frame, style="spacefill")

clear()¶

Clear all objects from the scene.

scene.clear()

new_frame(clear=True)¶

Create an empty frame. If clear=True, clears the current scene.

scene.new_frame()

Style¶

set_style(style=None, atom_radius=None, bond_radius=None)¶

Change the visual style without reloading the frame data.

scene.set_style(style="spacefill")
scene.set_style(atom_radius=0.5, bond_radius=0.1)

set_theme(theme)¶

Switch the color theme.

scene.set_theme("modern")
scene.set_theme("classic")

set_view_mode(mode)¶

Switch the interaction mode.

scene.set_view_mode("select")

Pipeline¶

The modifier pipeline is the single source of truth for scene content: every frame — whether loaded via the sidebar's Load File button or pushed from Python with draw_frame / set_trajectory — flows through a DataSourceModifier at the head, followed by user-added modifiers (selection, hide, color, …). The GUI sidebar and these Python commands manipulate the same pipeline, so toggling a modifier from Python is indistinguishable from clicking it in the sidebar.

list_modifiers()¶

Snapshot the current pipeline, in execution order.

for m in scene.list_modifiers():
    print(m.name, m.id, "enabled" if m.enabled else "off")

available_modifiers()¶

List every modifier type registered in the frontend's ModifierRegistry. Use the name field with add_modifier.

for entry in scene.available_modifiers():
    print(entry.name, "—", entry.category)

add_modifier(name, *, parent_id=None, enabled=None)¶

Append a modifier to the pipeline.

scene.add_modifier("Hide Hydrogens")
sel = scene.add_modifier("Expression Select")
scene.add_modifier("Hide Selection", parent_id=sel.id)

Selection-sensitive modifiers must attach to a selection-producing parent (via parent_id) or to an existing SelectModifier in the pipeline.

remove_modifier(id) / clear_pipeline()¶

scene.remove_modifier(mod.id)   # cascade-removes descendants
scene.clear_pipeline()          # drop every modifier

reorder_modifier(id, new_index)¶

scene.reorder_modifier(mod.id, 0)   # move to head

set_modifier_enabled(id, enabled) / set_modifier_parent(id, parent_id)¶

scene.set_modifier_enabled(mod.id, False)
scene.set_modifier_parent(mod.id, None)          # detach
scene.set_modifier_parent(mod.id, selector.id)   # reparent

Selection¶

get_selected()¶

Return the current selection state.

selection = scene.get_selected()

select_atom_by_id(ids)¶

Select atoms by their indices.

scene.select_atom_by_id([0, 2, 5])

Export¶

snapshot()¶

Capture the current view as PNG bytes.

png_data = scene.snapshot()

with open("molecule.png", "wb") as f:
    f.write(png_data)

export_frame()¶

Read back the current frame data from the frontend.

frame_data = scene.export_frame()

Error handling¶

All commands communicate with the frontend via JSON-RPC. If the frontend rejects a command, Python raises MolvisRPCError:

try:
    scene.draw_frame(frame)
except mv.MolvisRPCError as exc:
    print(f"Error {exc.code}: {exc}")