ProteinMotion

ProteinMotion is a Python package for animating proteins, DNA, and RNA. Load a structure or trajectory, choose a molecular representation, add animations and labels, and export a video. The scene API follows Manim's add, play, and wait syntax.

Documentation · Video examples · Reference manual · PyPI · Releases

Calmodulin in focus is a 68-second EEVEE film at 1080p/60 fps. It shows helix close-ups, focus pulls, transparent surroundings, backbone atoms, and a surface colored by B factor. Full script and output · Python source

The calmodulin and troponin C demo also covers NMR conformations, backbone morphing, distance measurements, and interaction highlights.

Install

Use Python 3.11 or later and a GPU. Windows NVIDIA systems use Vulkan for rendering and NVENC for video encoding. macOS uses Metal and VideoToolbox; on Apple silicon, use an arm64 Python installation.

Install from PyPI into your Python environment:

python -m pip install proteinmotion
proteinmotion doctor --check-encoders

To make the proteinmotion command available from any directory, install it with pipx:

pipx install proteinmotion
pipx ensurepath

Open a new terminal after ensurepath. The pipx installation has its own Python environment. For scripts that import proteinmotion directly, use the pip command in the environment where you run those scripts.

To update an existing installation, run python -m pip install --upgrade proteinmotion or pipx upgrade proteinmotion, depending on how you installed it.

Install optional trajectory readers and the interactive preview with python -m pip install "proteinmotion[md,preview]", or pipx install "proteinmotion[md,preview]" for the global command.

On Windows, use 64-bit Python and a current NVIDIA driver. doctor --check-encoders checks the GPU and tests available video encoders. See Windows setup and GPU selection.

The package includes fonts, shaders, a sample structure, and a starter script. PyAV supplies the FFmpeg libraries used for video export. See the installation guide for virtual environments and platform setup.

Render a video

proteinmotion init my-movie
proteinmotion render my-movie/film.py ProteinMovie --fps 60 -o my-movie/film.mp4

init creates film.py and a ubiquitin structure in my-movie/. Edit the script to change the structure, selected residues, or animations.

A scene looks like this:

from proteinmotion import Protein, ProteinScene, Rotate, Colorize, Write


class MyMovie(ProteinScene):
    def construct(self):
        protein = Protein.from_file("protein.cif").cartoon()
        self.add(protein)
        self.camera.frame(protein)

        helix = protein.select(chain="A", residues=(23, 34))
        self.play(Rotate(protein, angle=1.2), run_time=3)
        self.play(Colorize(helix, "#50e0d0"), run_time=1.5)
        self.play(Write(helix.callout("α helix")), run_time=2)
        self.focus(helix, run_time=1.5)
        self.wait(2)

Use a structure file and residue selection that match your protein. Residue ranges use inclusive PDB author numbers. Coordinates are in ångströms; angles are in radians. Animations in one play() call run together. Successive calls run in sequence.

Render with Studio

Studio is included in version 0.13.0 and later. It adds classic cartoons, molecular surfaces, four lighting presets, three materials, ambient occlusion, and film effects.

proteinmotion render my-movie/film.py ProteinMovie --renderer studio \
  --lighting soft --material medium --effects film --fps 60 -o studio.mp4

Store settings on a scene with renderer = "studio" and look = StudioLook(lighting="soft", material="medium", effects="clean") to share them across interactive preview, stills, and video. The native renderer remains the default. See the Studio guide and rendered examples.

New in 0.15

• Cα-only morphs: StructureMorph animates coarse models and predicted folding pathways that contain only Cα atoms. Each residue turns with its neighbours, consecutive Cα atoms keep their 3.8 Å spacing, and secondary structure comes from Cα geometry. align=False keeps structures that are already superposed in place. See morphs.
• Two traces on one plot: TimeSeriesPlot(show_value=False) hides the cursor value of a second trace drawn on the same axes.
• Fixes: camera chains follow moving regions in any argument order, cryo-EM maps no longer wrap at their box edges, distance heatmaps leave out ligands, libx265 movies play in Apple players, and the command line applies EEVEE options when the scene itself chooses EEVEE.
• Readable source: the package code is commented throughout, and CONTRIBUTING.md describes how a frame goes from the timeline to pixels.

New in 0.14

• Torsions and secondary structure: build peptides from a sequence with Protein.build, measure and animate φ, ψ, ω, and χ angles with SetTorsions, and plot residues on Ramachandran plots drawn from high-resolution structures. Cartoons follow DSSP as secondary structure forms and blend between coil, helix, and strand. See torsions.
• Two states of one protein: StructureMorph animates between two experimental structures, even when their chains, missing residues, ligands, or atoms differ. Domains swing along arcs about the part that stays put. domain_motion measures the hinge, Protein.from_file(path, assembly="1") builds biological assemblies, and Protein.fetch("1ANF") downloads PDB and AlphaFold DB entries. See morphs.
• Data on structures: heatmaps for AlphaFold PAE and distance matrices, and pLDDT, hydropathy, and conservation color presets. See heatmaps, confidence, and conservation.
• Smoother rendering: cartoons keep their orientation through morphs and trajectories, Studio fades end without a jump, and stills and movies up to 1920 × 1080 are supersampled for clean edges.

Upgrading to 0.15

• Camera animations in one play() call now run after molecular motion whatever the argument order, and play(rate_func=...) eases chained animations once. A scene that listed a camera.animate focus before a moving molecule, or chained a Focus under a clip-wide rate_func, renders differently.
• DensityMap.from_file reads a space group 1 map with 90° cell angles, as MRC2014 writes cryo-EM volumes, as non-periodic: sampling outside the box returns NaN and crops stop at the box edge.
• Heatmap.distances(region=...) leaves out the region's ligands, ions, and water, so its rows and columns are polymer residues.
• Camera.clearest_view picks the nearest of several equally clear views, and Write on a plot staggers over the glyphs it draws.
• MD files whose frame times do not strictly increase have no timestamps (Trajectory.times is None), and read_alignment treats a one-line string as a file path.

Upgrading to 0.14

• Native and Studio stills and movies up to 1920 × 1080 now render at twice the width and height and average down. Edges are smoother at up to four times the GPU work. Pass ProteinScene(supersampling=1) or --supersampling 1 for the earlier output.
• Files without helix and sheet records, such as AlphaFold models and many NMR and MD structures, now get DSSP secondary structure instead of an all-coil cartoon. Pass secondary="file" to Protein.from_file for the earlier behavior.
• Cartoon and ribbon orientation now follows the Cα trace, so ribbons no longer flip during motion. Where the twist between two residues is ambiguous, usually at sharp kinks and in loops, the ribbon makes that turn through a short round section.

Upgrading to 0.13

• Thread and Unthread now move the actual cartoon, ribbon, or ball-and-stick geometry. Pass mode="wire" to keep the earlier glowing-wire entrance. Surface threading raises an error.
• SetOpacity(protein, value) now changes the global object opacity. Use scope="residues" to change all local opacity multipliers as in earlier versions.
• Distance plots now use backbone anchors by default, matching distance rulers. Pass anchor="centroid" for the earlier plot behavior.

The readable-authoring guide covers reusable styles, selection filters, independent timing, and migration details.

Render with Blender EEVEE

EEVEE adds depth of field with focus on a protein, residue, or selected region. Install Blender 4.5 or later separately. EEVEE is included in Blender. The default native renderer uses the Python dependencies installed above.

proteinmotion render my-movie/film.py ProteinMovie --renderer eevee --fps 60 -o film.mp4

ProteinMotion finds Blender on PATH, in standard Windows Program Files/Blender Foundation/Blender <version> folders, or at /Applications/Blender.app on macOS. For another location, pass --blender /path/to/blender or set PROTEINMOTION_BLENDER. On macOS, EEVEE uses Metal.

Set lens focus in your scene before the first animation:

self.camera.set_focus(protein, chain="A", residues=5, fstop=5.6)
self.camera.set_focus(protein, chain="A", residues=(10, 20), atoms="CA", fstop=4)

The selected atoms define the focus point and follow the protein during motion. The camera position and zoom stay fixed. Use FocusPull to animate a change of lens focus. See the EEVEE guide and rendered example for focus pulls, quality settings, and transparency behavior.

Features

• Representations: cartoon, ribbon, ball-and-stick, and molecular surfaces.
• Ligands and side chains: ligands, ions, and waters drawn as ball-and-stick over the cartoon. Side chains or any selected atoms can be shown or hidden residue by residue.
• DNA and RNA: nucleotide backbones with base slabs, filled rings, sticks, or ladder rods. Colors, opacity, labels, surfaces, trajectories, and EEVEE focus work with nucleotide selections.
• Animation: rotation, translation, camera movement, deformation, and transitions between representations.
• Residue styling: color and opacity changes, applied together or delayed by residue.
• Numerical properties: B factors, aligned RMSF, and imported residue values mapped to color and cartoon thickness.
• Plots: distance traces, live contact maps, sequence strips, and color legends synchronized with the movie.
• Density: MRC/CCP4 maps, animated contours, and moving slices, with map coordinates preserved.
• Labels: text writing and erasing, amino acid and nucleotide names, and callout lines that connect labels to selected regions.
• Rendering: native GPU rendering, Studio lighting/materials/film effects, or Blender EEVEE with depth of field.
• Cutaways and depth tunnels: open a window onto a hidden selection that follows the camera, or drill a tunnel with a ring every 5 Å to show how deep it lies.
• Threading: eased entrances of actual cartoon, ribbon, or ball-and-stick geometry, with the earlier glowing-wire mode available explicitly.
• Region tools: camera focus, 3D sphere, box, or atom highlights, and selection by ligand, ion, residue name, or distance.
• Measurements: distance labels, hydrogen-bond detection, and screened Coulomb estimates with imported charges.
• States and trajectories: multi-model PDB/mmCIF, NumPy arrays, and MDAnalysis readers for XTC, DCD, TRR, and other formats.
• Structure morphs: morphs between two experimental structures of one protein (chains, residues, ligands, and atoms matched automatically; domains move along screw paths and side chains turn through χ angles), biological assemblies, and contact-map matching between different proteins using Cα or DNA/RNA C1′ atoms.
• Torsions: peptides built from a sequence and φ/ψ angles, animated φ, ψ, ω, and χ changes that keep bond lengths and angles fixed, live angle markers, and Ramachandran plots over favored and allowed regions from high-resolution structures.

The guides explain the options and provide code examples. ProteinMotion runs as a standalone renderer. Its exported videos can be used in Manim or a video editor.

Use with an AI agent

The ProteinMotion Movies skill gives AI agents instructions and examples for writing scenes, rendering videos, and checking the results. Use it with an agent that can read local files and run Python commands.

Copy the skill to your agent's skills directory:

proteinmotion install-skill --path /path/to/skills/proteinmotion-movies

The installed skill includes its references and example files. For agents that read instructions directly, point them to SKILL.md and keep those files beside it.

Example request:

Use the ProteinMotion Movies skill to make a 20-second video from my structure. Show a cartoon, label chain A residues 23–34, zoom into that region, then switch to ball-and-stick.

The AI agent guide covers installation and example requests. Running proteinmotion install-skill with no path uses the Codex skills directory.

Examples

These scripts and their input structures are in the repository:

Example	Source
Hemoglobin T → R and adenylate kinase closing, morphed between deposited structures	structure_morph.py
φ and ψ, an α helix forming, a β-hairpin from crystal angles, and ubiquitin's Ramachandran plot	torsions.py
One ψ turn, then a peptide winding into a helix	torsion_basics.py
AlphaFold pLDDT and PAE, hydropathy, and conservation	confidence_and_conservation.py
Studio threading, buried-ribose depth rings, and independent animation timing	studio_examples.py
DNA morphs with C1′ matching and delayed nucleotide motion	dna_morph.py
DNA base styles, strand transparency, and surfaces	dna_styles.py
tRNA regions, modified bases, and B-factor surfaces	rna_styles.py
Depth tunnels into GroEL–GroES	depth_tunnels.py
Hemoglobin threaded one chain at a time	thread_hemoglobin.py

git clone https://github.com/pdpppd/proteinmotion.git
cd proteinmotion
python -m pip install -e '.[md,preview]'
proteinmotion render examples/nmr_regions.py RegionTour --fps 60 -o regions.mp4

Rendering and scientific methods

Rendering and export are tested on Apple silicon Macs and Windows with an NVIDIA RTX 5070 Ti. On the RTX, a 600-frame 1080p/60 fps Quickstart export took a median 1.92 seconds with NVENC versus 4.07 seconds with CPU encoding across three runs. This includes rendering, GPU readback, and encoding; scene construction is excluded. See benchmarks and test results for settings, hardware, and limits.

Morphs and NMR playback interpolate coordinates for visualization. Use an MD trajectory when you need motion from a simulation. Hydrogen bonds use geometric criteria. Electrostatic estimates use a screened Coulomb model and depend on the supplied charges. The rendering guide and interaction guide describe the methods and their limits.

Development

python -m pip install -e '.[dev,md,preview]'
ruff check src tests examples scripts skills
pytest
python -m build

Documentation is in docs/; the website is in website/. See CONTRIBUTING.md for setup and checks, and the writing guide for documentation style.

License

The package and website use the MIT license. Write timing is adapted from MIT-licensed Manim. The bundled Source Sans 3 fonts use the SIL Open Font License. See third-party notices and structure sources.

For composable timing, shared renderer settings, selection algebra, reusable styles and migration notes, see Readable authoring.