Commands, undo, and sessions

A Session owns named selections, layer names, color rules, and history for one live scene. A text program is validated as one atomic edit: if a statement fails, the scene does not change.

import molframe
import molgfx

structure = molframe.read("4hhb.cif").infer_bonds()

session = molgfx.Session(structure)
session.execute("""
select heme, resname HEM
select pocket, byres (within 5 of $heme) and protein
show cartoon, protein
show ball_and_stick radius=0.25 as pocket, $pocket
color orange, $pocket
""")

• Named selections use $name.
• Layers use @name.
• show is idempotent for the same form and target unless duplicate is requested.
• Redefining a named selection retargets dependent layers and rules.
• auto adds the size- and chemistry-appropriate default layers for the scene's structure, named after their forms, and nothing else changes: hide, recolour, or remove them like any other layer.
• volume declares a density grid; the grid values themselves arrive through a runtime binding, and the portable scene document keeps only the descriptor.
• See Query-driven visualization for named selections, visual layers, and the canonical pocket workflow.
• selection QUERY replaces active selection as one atomic, undoable Session edit; selection clears it. The browser viewer.select(query) and Python adapter delegate to this same command rather than creating a private named selection.

History, errors, and completionCopy Anchor Link

session.execute("color red, protein")  # An edit to undo and redo.
session.undo()
session.redo()
items = session.completions("show cartoon, $po")
saved = session.to_json()
restored = molgfx.Session.from_json(session.scene, saved)

CommandError.errors gives located diagnostics, including a source span and a spelling suggestion where available.

Typed commandsCopy Anchor Link

Use typed values when a text command is not the right UI contract:

from molgfx import Command

session.execute([
    Command.show("licorice", "resname HEM", layer="heme_sticks", bond_radius=0.15),
    Command.color("#ff3366", "@heme_sticks"),
    Command.opacity(0.6, "cartoon"),
])