Scripts are the source
Builds are idempotent and report their numerical checks: for the case study, the retinal dihedral path, the salt-bridge distance, the worst morph bond deviation, the pathway profile and the ion clearance.
Open source · Apache-2.0 · v0.1.0
Molecular Animation
Honest, beautiful molecular films from a scientific brief. An open framework for turning a scientific brief into a molecular animation with Blender. It builds scenes from PDB structures, renders labelled and clean films, and keeps a production record of what is experimental and what is illustrative.
It is designed to be driven by an AI agent, such as Claude Code working through Blender MCP, and works just as well by hand.
You hand over
A request, a paper-style brief or a reference.
You get back
- A scripted Blender 5.2 scene built from PDB structures
- Rendered takes, delivered as labelled and clean MP4 and WebM films with posters
- A production record that states, beat by beat, what is experimental and what is illustrative
Case study · Channelrhodopsin
The twist that opens a pathway.
A 21-second film made from a single brief, generated with ChatGPT, on the 2026 Nobel Prize in Physiology or Medicine. A photon twists retinal in channelrhodopsin C1C2, the protein’s interaction network rearranges, and a cation pathway opens.
A 21-second silent film of channelrhodopsin C1C2, built from PDB structures 9GO1 and 9GO2. It opens on the protein dimer in a lipid membrane as photons arrive, dives into the retinal pocket, and shows retinal twisting from all-trans to 13-cis (an illustrative morph between the two crystal states). Lys132 then swings toward Glu129 to form a salt bridge. A section through the cation pathway first shows it interrupted, as in the crystal, then open in an illustrative conducting-state model as sodium ions cross the membrane. Throughout, lipids, side chains and the protein move with illustrative thermal motion at literature rates, one second of film standing for about a nanosecond.
Evidence on screen
Every beat says what it is.
A molecular film can easily look more certain than the science behind it. Each beat is tagged on screen as a deposited structure, a prediction or an illustrative step. Each film’s table states the clock its thermal motion runs on; longer steps, such as channel opening, are compressed, and their timescales are labels.
| Screen time | What moves | Evidence | Level |
|---|---|---|---|
| Throughout | Lipids move as whole molecules, side chains turn about their bonds and the protein flexes in its slowest modes, on a clock of 1 s of film ≈ 1 ns. | Literature rates for bilayers and proteins, and an elastic-network model; not a simulation of C1C2. | Illustrative |
| 0–4 s | Wide section of the C1C2 dimer in a lipid bilayer; photons arrive from the extracellular side. | Structure: PDB 9GO1. Membrane: procedural, not simulated. Photons and light: symbolic. | ExperimentalSymbolic |
| 4–7 s | The camera dives into one protomer; a camera-aimed cutaway opens onto the retinal pocket. | PDB 9GO1 | Experimental |
| 7–10.5 s | A photon is absorbed and retinal twists from all-trans to 13-cis, with Trp262 repacking. | Illustrative morph between 9GO1 and 9GO2 coordinates | Illustrative |
| 11–14.5 s | Lys132 swings toward Glu129 (9.0 → 2.66 Å) and a salt-bridge marker appears. | Endpoint: 9GO2 alt B. Path: illustrative morph. | Illustrative |
| 15–17 s | A section through the pathway; the cavity shows as separate pockets. | 9GO2 free-radius profile | Experimental |
| 17–21 s | The pockets join and Na⁺ ions cross with stop-and-go motion. | Illustrative conducting-state model | Illustrative |
Claims the film depends on were measured in code before animation: the retinal C12–C13=C14–C15 dihedral moves from −176° to +0.6°, and the Lys132–Glu129 distance from 9.0 to 2.66 Å. Thermal motion uses literature rates for lipid bilayers and proteins, not measurements of C1C2, and there is no simulation. The ion transits through the channel are an illustrative model whose rate is not physiological.
Case study · ART
A hidden repertoire of RNA.
A 31-second film on array-associated reverse transcriptases (ART), a recently reported enzyme system, made from a brief generated with ChatGPT and our own AlphaFold Server predictions. In the genome of Staphylococcus phage SA1, a repeat array is expressed as distinct short RNAs, beside a reverse transcriptase and a partner protein whose relationship is still unknown. The repeat layout resembles a CRISPR array, but ART loci lack cas genes.
A 31-second silent film of the ART locus of Staphylococcus phage SA1. It opens close on the phage DNA, built base pair by base pair from GenBank MW218148.1, as a repeat lights up; the camera pulls back as four more copies recur between unique spacers, and a locus map places the array beside a reverse-transcriptase gene and a partner gene. Four RNAs from the array resolve beneath their units, as low-confidence AlphaFold 3 predictions. The camera travels to the reverse transcriptase, predicted with AlphaFold 3, and a cutaway opens onto its YADD motif. Finally the partner protein appears, and dashed question marks link RNA, reverse transcriptase and partner: how they work together is not known. Throughout, each molecule tumbles and flexes with illustrative thermal motion.
The RNAs, the reverse transcriptase and the partner protein are AlphaFold Server output, provided under and subject to the AlphaFold Server Output Terms of Use. Their placement, illustrative motion, view and colours are ours.
| Screen time | What moves | Evidence | Level |
|---|---|---|---|
| Throughout | Each molecule tumbles and diffuses as a whole and flexes in its slowest modes; the DNA bends and twists, on a clock of 1 s of film ≈ 5 ns. | Literature rates, crowding as measured in E. coli; positions are editorial and nothing touches. Not a simulation. | Illustrative |
| 0–7 s | Close on the phage DNA as a repeat lights up; the camera pulls back as four more copies recur between unique spacers. | Sequence: GenBank MW218148.1. Repeat positions: our comparison of the sequence. DNA shape: illustrative. | ExperimentalIllustrative |
| 7–11 s | The whole array; a locus map places it beside the reverse-transcriptase gene and a partner gene. | GenBank annotation | Experimental |
| 11–17.5 s | Four RNAs resolve beneath their units of the array. | AlphaFold 3 predictions, low confidence (mean pLDDT 40–50); RNA ends assumed. | Predicted |
| 18–24.5 s | The camera travels to the reverse transcriptase; a cutaway opens onto its YADD motif. | AlphaFold 3 prediction (pTM 0.80) | Predicted |
| 25–31 s | The partner protein resolves; dashed question marks link RNA, reverse transcriptase and partner. | Partner: low-confidence prediction (mean pLDDT 33). Links: hypotheses; no confident interface (ipTM ≤ 0.24). | PredictedSymbolic |
Measured in code before animation: a 14-nucleotide seed occurs five times in the array tract (with at most one mismatch), on one strand only. Around it lies a 49-nucleotide repeat in five copies, separated by spacers of 122–163 nucleotides; three copies are 98–100 % identical and two are degenerate. No complex of the RNA, the reverse transcriptase and the partner was predicted with confidence, so the film keeps them apart: the closest pair stays more than 100 Å apart.
Workflow
From brief to film.
An agent, or a person, follows the same seven steps. Open Blender with the MCP add-on, start Claude Code in the repository and hand it the brief with /new-film.
- 01
Understand
Write a one-page brief: the one idea, the structures and their evidence levels, the beats, the look and the deliverables.
- 02
Ground the science
Fetch the PDB entries and measure the claims the film depends on, in code, before anything is animated.
- 03
Build
Script the shot from the project template and the molanim framework. Builds are idempotent and report their numerical checks.
- 04
Inspect
Review stills, a preview contact sheet and motion statistics that flag jumps and seams.
- 05
Refine
Iterate on camera, representation and pacing until the one idea reads clearly.
- 06
Render and deliver
Render with Cycles, add the separate label pass, and encode labelled and clean films with posters.
- 07
Record
Write down what was built, the numbers, the evidence level of every beat, the checks and the known limits.
- Try it
Hand over a brief
Read the workflow/new-film path/to/brief.md
Inside the framework
Science in numpy. Pictures in Blender.
molanim separates a unit-tested science layer that runs anywhere from a Blender layer that draws it, and pipeline.py runs the whole production from one command line.
Science layer
Pure numpy, unit-tested, no Blender required.
- mmCIF reading and biological assemblies
- Atom-matched states between deposited structures
- Constrained morphs that keep bond lengths and angles
- Pathway and pore profiles
- Procedural membranes
- Illustrative ion motion with clearance checks
- Camera paths
Blender layer
Representations, materials, camera and labels for Blender 5.2.
- Sphere and ball-and-stick molecules
- Camera-aimed cutaways instead of global transparency
- Cavity tubes and interaction markers
- A studio look and depth-of-field camera rig
- A separate label pass for captions, evidence tags and pointers
Camera-aimed cutawaysA funnel opens the barrel of green fluorescent protein (PDB 1EMA) to its chromophore, without global transparency. 
Cavity tubesThe pore of the KcsA potassium channel (PDB 1K4C) as a measured free-radius profile, with the deposited K⁺ ions. 
Procedural membranesThe aquaporin-1 tetramer (PDB 1J4N) in a POPC-like bilayer, cut as a section. Context, not simulation.
$ python pipeline.py doctor # Blender, GPU, ffmpeg, packages, checksums
$ python pipeline.py new gfp --pdb 1EMA --title "Green fluorescent protein"
$ python pipeline.py build gfp # ~3 s: projects/gfp/gfp.blend
$ python pipeline.py still gfp 165 --percent 50
$ python pipeline.py render gfp --take take-01
$ python pipeline.py render gfp --overlay --take labels-01
$ python pipeline.py deliver gfpReproducibility
Built to be checked.
Requirements: Blender 5.2, a Cycles-capable GPU (NVIDIA OptiX recommended), ffmpeg with libx264 and libvpx-vp9, and Python 3.10 or later. Structures come from the RCSB Protein Data Bank.
Pinned inputs
Structures are committed with checksums. Blender 5.2 is pinned, every call uses factory startup, and the GPU is selected explicitly.
Verified output
A check command rebuilds a shot and compares a freshly rendered poster with the delivered one. After a refactor, the case study's posters matched within 1/255.
Contact
Have a structure that deserves a film?
Talk to us about molecular animation, or start from the repository and its case study.