pymol-fundamentals

name	pymol-fundamentals
description	Use when working with PyMOL for molecular visualization tasks including loading structures, creating representations, coloring, selections, and basic analysis.
version	0.1.0

PyMOL Fundamentals

Core operations for molecular visualization through PyMOL.

Sending Commands

All commands go through the CLI wrapper. Never use raw sockets.

# Single command
~/.pymol-agent-bridge/bin/pymol-agent-bridge exec "cmd.fetch('1ubq')"

# Multiple commands via heredoc
~/.pymol-agent-bridge/bin/pymol-agent-bridge exec "$(cat <<'PYMOL'
cmd.hide('everything')
cmd.show('cartoon')
cmd.color('spectrum')
PYMOL
)"

# Get values back via print()
~/.pymol-agent-bridge/bin/pymol-agent-bridge exec "print(cmd.get_names())"

All cmd.* examples below should be sent this way.

Loading Structures

Fetch from PDB

cmd.fetch("1ubq")  # Downloads and loads structure
cmd.fetch("1ubq", name="my_protein")  # Custom object name

Load Local File

cmd.load("/path/to/file.pdb")
cmd.load("/path/to/file.pdb", "object_name")

Check Loaded Objects

cmd.get_names()  # Returns list of all objects
cmd.get_names("objects")  # Only objects
cmd.get_names("selections")  # Only selections

Representations

Show/Hide Representations

Available representations: cartoon, sticks, spheres, surface, mesh, lines, ribbon, dots

cmd.show("cartoon", "all")
cmd.hide("lines", "all")
cmd.show("sticks", "resi 1-10")

Representation as Exclusive

cmd.as_("cartoon", "all")  # Shows cartoon, hides all others

Cartoon Styles

cmd.set("cartoon_fancy_helices", 1)
cmd.set("cartoon_smooth_loops", 1)
cmd.cartoon("oval", "ss h")  # Oval helices
cmd.cartoon("tube", "ss l+")  # Tube loops

Selection Syntax

Basic Selections

Selection	Meaning
all	Everything
1ubq	Object named 1ubq
chain A	Chain A
resi 1-50	Residues 1-50
resn ALA	All alanines
name CA	Alpha carbons
elem C	Carbon atoms

Property-Based Selections

Selection	Meaning
ss h	Alpha helices
ss s	Beta sheets
ss l+	Loops
organic	Ligands/small molecules
polymer.protein	Protein chains
solvent	Water molecules

Proximity Selections

# Atoms within 5 Angstroms
cmd.select("nearby", "all within 5 of ligand")

# Expand to complete residues
cmd.select("binding_site", "byres (protein within 5 of ligand)")

Boolean Operations

cmd.select("pocket", "resi 45-48 and chain A")
cmd.select("not_water", "all and not solvent")
cmd.select("interface", "chain A within 4 of chain B")

Coloring

Named Colors

cmd.color("red", "ss h")
cmd.color("yellow", "ss s")
cmd.color("green", "ss l+")
cmd.color("cyan", "chain A")

Utility Coloring

cmd.util.cbc()  # Color by chain
cmd.util.cbag("ligand")  # By atom, green carbons
cmd.util.rainbow("all")  # N-to-C rainbow

Spectrum Coloring

cmd.spectrum("count", "rainbow", "all")  # Rainbow by residue
cmd.spectrum("b", "blue_white_red", "all")  # By B-factor
cmd.spectrum("pc", "rainbow", "all")  # By partial charge

Secondary Structure Coloring

cmd.dss()  # Assign secondary structure (replaces deprecated util.ss)
cmd.color("red", "ss h")
cmd.color("yellow", "ss s")
cmd.color("green", "ss l+")

Camera Control

View Manipulation

cmd.center("selection")  # Center on selection
cmd.zoom("selection")  # Zoom to fit selection
cmd.zoom("selection", 5)  # Zoom with 5 Angstrom buffer
cmd.orient("selection")  # Align to principal axes
cmd.reset()  # Reset view

Rotation and Movement

cmd.turn("y", 90)  # Rotate 90 degrees around Y
cmd.move("z", 10)  # Move camera along Z
cmd.rock()  # Toggle rocking animation

Measurements

Distance

cmd.distance("dist1", "resi 10 and name CA", "resi 20 and name CA")

Polar Contacts (Hydrogen Bonds)

cmd.distance("hbonds", "ligand", "protein", mode=2)
cmd.distance("polar", "selection1", "selection2", mode=2)

Angles and Dihedrals

cmd.angle("ang1", "atom1", "atom2", "atom3")
cmd.dihedral("dih1", "atom1", "atom2", "atom3", "atom4")

Object Management

Create and Extract

cmd.create("new_obj", "selection")  # Copy selection to new object
cmd.extract("extracted", "selection")  # Move selection to new object

Delete and Remove

cmd.delete("object_name")  # Delete entire object
cmd.remove("selection")  # Remove atoms from object
cmd.delete("all")  # Clear everything

Common Workflows

Basic Protein Visualization

cmd.fetch("1ubq")
cmd.show("cartoon", "1ubq")
cmd.hide("lines", "1ubq")
cmd.dss()
cmd.color("green", "ss h")
cmd.color("yellow", "ss s")
cmd.color("cyan", "ss l+")
cmd.center("1ubq")

Ligand-Binding Site View

cmd.fetch("1hsg")
cmd.select("lig", "organic")
cmd.select("prot", "polymer.protein")
cmd.select("site", "byres (prot within 5 of lig)")
cmd.show("cartoon", "prot")
cmd.hide("lines")
cmd.show("sticks", "lig")
cmd.show("sticks", "site")
cmd.util.cbag("lig")
cmd.color("yellow", "site and elem C")
cmd.distance("contacts", "lig", "site", mode=2)
cmd.zoom("lig", 8)

Multi-Structure Comparison

cmd.fetch("1ubq")
cmd.fetch("1ubi")
result = cmd.align("1ubi", "1ubq")
print(f"RMSD: {result[0]:.2f} A over {result[1]} atoms")
cmd.color("green", "1ubq")
cmd.color("cyan", "1ubi")
cmd.show("cartoon", "all")
cmd.hide("lines")

Image Capture

The Correct Pattern

Always render with cmd.ray() first, then save with cmd.png() — never pass width/height to cmd.png().

# CORRECT: ray first, then png without dimensions
cmd.ray(1200, 900)
cmd.png("/path/to/image.png")

# WRONG — causes view corruption:
# cmd.png("/path/to/image.png", 1200, 900)

Why this matters: Passing dimensions to cmd.png() corrupts PyMOL's internal view matrix. The Z-distance grows exponentially (from ~120 to ~50000+) after just 3-4 cycles of reinitialize + fetch + png, causing the view to zoom out into invisibility. cmd.ray() renders to an offscreen buffer without touching the viewport.

Quick Snapshot (Preview)

# Fast OpenGL render (no ray tracing) — good for checking your work
cmd.draw(1200, 900)
cmd.png("/path/to/preview.png")

Saving to a Scratch Directory

When the user hasn't specified where to save, use a scratch directory:

import os
scratch = os.path.expanduser("~/.pymol-agent-bridge/scratch")
os.makedirs(scratch, exist_ok=True)
cmd.ray(1200, 900)
cmd.png(scratch + "/snapshot.png")

Then read the image file to show the user what PyMOL is displaying.

Common Sizes

Use Case	Ray Size	Notes
Quick check	800x600	cmd.draw() is fine
Presentation	1200x900	Ray trace recommended
Publication	2400x1800	Always ray trace

For full rendering settings (lighting, shadows, antialiasing, DPI), see the publication-figures skill.

Tips

• Use cmd.get_names() to verify objects loaded correctly
• Use cmd.count_atoms("selection") to verify selection syntax
• organic selects ligands; polymer.protein selects protein
• byres expands atom selections to complete residues
• mode=2 in distance shows polar contacts (H-bonds)
• cmd.dss() assigns secondary structure (newer than util.ss)
• Use cmd.remove("solvent") after loading to remove water molecules (cleaner visualizations)
• Use cmd.util.cnc() after showing sticks to color by element (N blue, O red, S yellow)
• Use cmd.rebuild() after cmd.show("surface") to ensure surface is generated before saving images
• For charge-colored surfaces: color atoms by residue type first, then show surface (surface inherits atom colors)