Pymol scenesmith

pymol-scenesmith

When to use / what it does

Use this skill for one-off DIY structural views when a human is at the screen: label domains, show before/after a sequence truncation, highlight a subsequence, show an interface, draw honest contact dashes, or make a PyMOL session that can be inspected and adjusted. It also supports reproducible headless bakes when the user asks for unattended artifacts.

The general assembly method

This is the skill's spine. A novel scene shape is assembled the same way as the worked examples in references/recipes.md.

1. Resolve the structure: load a local CIF/PDB path, or fetch <pdbid> into a stable object name.
2. Establish a visible neutral base: hide everything, show cartoon, and color br_gray.
3. Map spans defined in sequence or annotation space to true CIF author resi with scripts/scene_helpers.py::map_span_to_resi, then build selections with selection_for_span.
4. Color and represent by role with the palette.
5. Optionally add side-by-side copies, closest-heavy-atom contact dashes, bands, or labels.
6. Save the .pse, bake headless if an artifact is needed, then launch PyMOL for eyeballing.

The rules that still bind

1. Map sequence/annotation spans to CIF author resi via scripts/scene_helpers.py::map_span_to_resi; never hardcode resi N-M from a sequence range; never use +1. A span over a trimmed CIF may map to fewer or zero residues, and the scene should say so.
2. Contact and measurement dashes use closest_heavy_atom_pair, not CA-CA.
3. Keep the base structure visible so highlights have structural context.
4. A user-supplied palette overrides scripts/presets.pml verbatim.

Run it: launch, then optionally bake

The default path is interactive: build the scene and open it with the Windows PyMOL launcher:

subprocess.Popen([r"D:\PyMOL2\PyMOLWinWithConsole.bat", pse_path])

When producing unattended artifacts, bake headlessly with:

subprocess.run([r"D:\PyMOL2\Scripts\pymol.exe", "-cq", pml_path], check=True)

Use Windows absolute paths written with forward slashes inside .pml files, for example Path(path).resolve().as_posix(). Diagnostics manifests are optional; use them for unattended runs, batches, or when mapping reports skips. See references/inputs.md.

Minimum working example

This .pml maps a sequence-space span through the shipped helper instead of hardcoding resi.

reinitialize
@D:/OUROBOROS-AI4S/pymol-scenesmith/scripts/presets.pml
load D:/data/example.cif, m
hide everything, m
show cartoon, m
color br_gray, m

python
import sys
sys.path.insert(0, r"D:/OUROBOROS-AI4S/pymol-scenesmith/scripts")
from scene_helpers import Residue, map_span_to_resi, selection_for_span

# Fill residues from a CIF parser that preserves chain file order and author resi.
residues = [Residue("100", "A"), Residue("101", "C"), Residue("102A", "D")]
sequence = "XXACDYY"
resis, skipped = map_span_to_resi(residues, sequence, start=2, end=4)
print(f"highlight: resolved={len(resis)} skipped_unmapped={skipped}")
cmd.select("highlight", selection_for_span("m", "H", resis))
cmd.show("sticks", "highlight")
cmd.color("br_orange", "highlight")
python end

orient m
save D:/data/example_out.pse

Open the saved session with D:\PyMOL2\PyMOLWinWithConsole.bat. Bake with D:\PyMOL2\Scripts\pymol.exe -cq <script.pml> when you need a reproducible artifact.

Palette

The fallback palette names are br_orange, br_amber, br_cyan, br_teal, br_gray, and br_ink. The five pastel slots are fills from the user's Unicorn Dream palette. br_ink is a true near-black for labels, outlines, and measurement dashes. If the user supplies a palette, it overrides the fallback verbatim.

Live preview

For a running PyMOL instance, a socket bridge can make live preview the primary editing loop:

import json, socket

def send_pymol(code: str, host="127.0.0.1", port=9123):
    payload = (json.dumps({"code": code}) + "\n").encode()
    with socket.create_connection((host, port), timeout=3) as sock:
        sock.sendall(payload)

Use live preview for interactive shaping, then save or bake the session once the human-visible scene is right.

Pointers

references/recipes.md contains the assembly method plus four worked recipes. references/inputs.md covers inputs, mapping, Windows paths, contact dashes, and optional diagnostics. references/example-antibody.md contains the antibody/antigen color grammar used by interface scenes.