pymol

Name: pymol
Author: ai4protein

244stars35forks

How to install pymol?

ai4protein/venusfactory2/pymol

$npx -y skills add ai4protein/VenusFactory2 --skill pymol

Installs into the current project.

Summary

Headless PyMOL rendering of protein structures (PNG + PSE session) and structural superposition with RMSD. Use to produce static publication-style images, color a structure by pLDDT/B-factor/chain/secondary-structure, or compare two structures by cealign. Do NOT use for interacti

Files · 1

View on GitHub

SKILL.md

1	# PyMOL Headless Rendering
2
3	## Overview
4
5	Two exposed agent tools drive an OSMesa-rendered PyMOL subprocess — no GPU, no X server. Each call writes a PNG image and a `.pse` session file to disk; the agent only sees `{file_path, metadata}` in the response, never raw image bytes.
6
7	This skill complements VenusFactory's interactive `MolstarViewer` in the frontend: use Molstar when the user is exploring a structure live, use PyMOL when you need a reproducible static image for a report.
8
9	## Prerequisites
10
11	PyMOL must be on the host's PATH. Verify with `pymol -V`. If missing, install via:
12
13	- conda (preferred): `conda install -n venus -c conda-forge pymol-open-source`
14	- pip: `pip install pymol-open-source-whl` (requires Python 3.10 ≤ x < 3.13)
15
16	When PyMOL is missing, the tools return `{status: "error", error: {type: "DependencyMissing", message: "<install hint>"}}` — surface the install command to the user instead of trying anything else.
17
18	## Project Tools (VenusFactory2)
19
20	\| Tool \| Args \| Returns \| Description \|
21	\|------\|------\|---------\|--------------\|
22	\| render_protein_structure \| `pdb_path` (required), `out_dir` (required), `color_by` (default `"plddt"`; one of `plddt` \\| `bfactor` \\| `chain` \\| `ss`), `width` (default `1200`), `height` (default `900`), `dpi` (default `150`), `timeout_secs` (default `300`) \| JSON: `{status, file_info {file_path -> <stem>_<color>.png}, content_preview (pymol stdout), biological_metadata {input_structure, color_by, png_path, pse_path, image_dimensions}}` \| Cartoon-render a single structure with one of four coloring strategies. \|
23	\| superpose_two_structures \| `pdb_a` (mobile, required), `pdb_b` (reference, required), `out_dir` (required), `width`/`height`/`dpi`/`timeout_secs` (same defaults) \| JSON: `{status, file_info {file_path -> superpose_<a>_to_<b>.png}, biological_metadata {mobile, reference, rmsd_angstroms, aligned_residues, png_path, pse_path}}` \| Align `pdb_a` onto `pdb_b` via `cealign` (auto-fallback to `align`), render the superposition, report RMSD. \|
24
25	## Coloring Strategies
26
27	\| `color_by` \| Use for \|
28	\|---\|---\|
29	\| `plddt` (default) \| AlphaFold predictions — B-factor column = pLDDT, spectrum red↔blue at 50-100 \|
30	\| `bfactor` \| Experimental structures — generic B-factor coloring \|
31	\| `chain` \| Multi-chain complexes — one color per chain \|
32	\| `ss` \| Highlight helix (green) / sheet (yellow) / loop (gray) \|
33
34	## When to Use This Skill
35
36	- User asks "show me the structure", "render it", "make an image", "compare these two structures"
37	- Building a report or visualization that needs a static image
38	- After running an AlphaFold prediction or downloading a PDB, you want to visualize the result
39	- Comparing predicted vs. experimental structure → `superpose_two_structures`
40
41	## When NOT to Use
42
43	- User wants to spin / zoom / click on the structure → use the frontend MolstarViewer instead
44	- Docking / molecular dynamics → out of scope, recommend other tools
45	- Sequence-only operation → use sequence skills (uniprot, ncbi_sequence_fetch, etc.)
46	- Animated movies → not exposed; the underlying PyMOL supports it but no agent tool surfaces it
47
48	## Output Files
49
50	Each run produces two files in `out_dir`:
51
52	- *`.png`** — the static image (returned in `file_info.file_path`).
53	- *`.pse`** — a PyMOL session file. Tell the user they can open it locally in PyMOL to continue exploring.
54
55	## Rate / Cost
56
57	PyMOL runs locally; no network. Typical render is 5-30 seconds per structure. Default timeout is 5 min — increase `timeout_secs` for very large complexes or surfaces.
58
59	## Common Mistakes
60
61	- Passing a sequence instead of a structure file → `ValidationError: empty pdb_path` or `NotFound`. Download the structure first (e.g., `download_alphafold_structure_by_uniprot_id` or `download_rcsb_structure_by_pdb_id`).
62	- Invalid `color_by` → ValidationError listing the four allowed values.
63	- PyMOL not installed → `DependencyMissing` with the install command. Show the user — don't silently fall back.
64	- Trying to render very large complexes (>1 M atoms) with surface at high DPI → can time out. Drop dpi to 100 or increase `timeout_secs`.
65
66	## References
67
68	- `references/PYMOL_REFERENCE.md` — selection syntax, common commands, gotchas (copied verbatim from google-deepmind/science-skills).
69	- `references/RECIPES.md` — 15+ copy-paste PyMOL recipes for advanced visualizations beyond what the two exposed tools cover. Useful when the user wants something custom — produce

People who liked this also viewed

6 picks

Type

pymol

244stars35forks

View on GitHub

How to install pymol?

ai4protein/venusfactory2/pymol

$npx -y skills add ai4protein/VenusFactory2 --skill pymol

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# PyMOL Headless Rendering
2
3	## Overview
4
5	Two exposed agent tools drive an OSMesa-rendered PyMOL subprocess — no GPU, no X server. Each call writes a PNG image and a `.pse` session file to disk; the agent only sees `{file_path, metadata}` in the response, never raw image bytes.
6
7	This skill complements VenusFactory's interactive `MolstarViewer` in the frontend: use Molstar when the user is exploring a structure live, use PyMOL when you need a reproducible static image for a report.
8
9	## Prerequisites
10
11	PyMOL must be on the host's PATH. Verify with `pymol -V`. If missing, install via:
12
13	- conda (preferred): `conda install -n venus -c conda-forge pymol-open-source`
14	- pip: `pip install pymol-open-source-whl` (requires Python 3.10 ≤ x < 3.13)
15
16	When PyMOL is missing, the tools return `{status: "error", error: {type: "DependencyMissing", message: "<install hint>"}}` — surface the install command to the user instead of trying anything else.
17
18	## Project Tools (VenusFactory2)
19
20	\| Tool \| Args \| Returns \| Description \|
21	\|------\|------\|---------\|--------------\|
22	\| render_protein_structure \| `pdb_path` (required), `out_dir` (required), `color_by` (default `"plddt"`; one of `plddt` \\| `bfactor` \\| `chain` \\| `ss`), `width` (default `1200`), `height` (default `900`), `dpi` (default `150`), `timeout_secs` (default `300`) \| JSON: `{status, file_info {file_path -> <stem>_<color>.png}, content_preview (pymol stdout), biological_metadata {input_structure, color_by, png_path, pse_path, image_dimensions}}` \| Cartoon-render a single structure with one of four coloring strategies. \|
23	\| superpose_two_structures \| `pdb_a` (mobile, required), `pdb_b` (reference, required), `out_dir` (required), `width`/`height`/`dpi`/`timeout_secs` (same defaults) \| JSON: `{status, file_info {file_path -> superpose_<a>_to_<b>.png}, biological_metadata {mobile, reference, rmsd_angstroms, aligned_residues, png_path, pse_path}}` \| Align `pdb_a` onto `pdb_b` via `cealign` (auto-fallback to `align`), render the superposition, report RMSD. \|
24
25	## Coloring Strategies
26
27	\| `color_by` \| Use for \|
28	\|---\|---\|
29	\| `plddt` (default) \| AlphaFold predictions — B-factor column = pLDDT, spectrum red↔blue at 50-100 \|
30	\| `bfactor` \| Experimental structures — generic B-factor coloring \|
31	\| `chain` \| Multi-chain complexes — one color per chain \|
32	\| `ss` \| Highlight helix (green) / sheet (yellow) / loop (gray) \|
33
34	## When to Use This Skill
35
36	- User asks "show me the structure", "render it", "make an image", "compare these two structures"
37	- Building a report or visualization that needs a static image
38	- After running an AlphaFold prediction or downloading a PDB, you want to visualize the result
39	- Comparing predicted vs. experimental structure → `superpose_two_structures`
40
41	## When NOT to Use
42
43	- User wants to spin / zoom / click on the structure → use the frontend MolstarViewer instead
44	- Docking / molecular dynamics → out of scope, recommend other tools
45	- Sequence-only operation → use sequence skills (uniprot, ncbi_sequence_fetch, etc.)
46	- Animated movies → not exposed; the underlying PyMOL supports it but no agent tool surfaces it
47
48	## Output Files
49
50	Each run produces two files in `out_dir`:
51
52	- *`.png`** — the static image (returned in `file_info.file_path`).
53	- *`.pse`** — a PyMOL session file. Tell the user they can open it locally in PyMOL to continue exploring.
54
55	## Rate / Cost
56
57	PyMOL runs locally; no network. Typical render is 5-30 seconds per structure. Default timeout is 5 min — increase `timeout_secs` for very large complexes or surfaces.
58
59	## Common Mistakes
60
61	- Passing a sequence instead of a structure file → `ValidationError: empty pdb_path` or `NotFound`. Download the structure first (e.g., `download_alphafold_structure_by_uniprot_id` or `download_rcsb_structure_by_pdb_id`).
62	- Invalid `color_by` → ValidationError listing the four allowed values.
63	- PyMOL not installed → `DependencyMissing` with the install command. Show the user — don't silently fall back.
64	- Trying to render very large complexes (>1 M atoms) with surface at high DPI → can time out. Drop dpi to 100 or increase `timeout_secs`.
65
66	## References
67
68	- `references/PYMOL_REFERENCE.md` — selection syntax, common commands, gotchas (copied verbatim from google-deepmind/science-skills).
69	- `references/RECIPES.md` — 15+ copy-paste PyMOL recipes for advanced visualizations beyond what the two exposed tools cover. Useful when the user wants something custom — produce

People who liked this also viewed

6 picks

Type