Metadata-Version: 2.5
Name: proteinmotion
Version: 0.14.0
Summary: Animate proteins, DNA, and RNA with a Manim-inspired Python API and native GPU or Blender EEVEE rendering
Project-URL: Homepage, https://pdpppd.github.io/proteinmotion/
Project-URL: Documentation, https://pdpppd.github.io/proteinmotion/docs/getting-started/
Project-URL: Repository, https://github.com/pdpppd/proteinmotion
Project-URL: Issues, https://github.com/pdpppd/proteinmotion/issues
Project-URL: Changelog, https://github.com/pdpppd/proteinmotion/releases
Author: Pranav Punuru
License-Expression: MIT
License-File: LICENSE
License-File: THIRD_PARTY.md
License-File: src/proteinmotion/fonts/OFL.txt
License-File: src/proteinmotion/licenses/Manim-LICENSE.txt
Keywords: animation,dna,gpu,manim,molecular-visualization,protein,rna
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.11
Requires-Dist: av<19,>=18
Requires-Dist: fonttools<5,>=4.55
Requires-Dist: gemmi<0.8,>=0.7
Requires-Dist: mapbox-earcut<3,>=1.0
Requires-Dist: numpy>=1.26
Requires-Dist: pillow>=10
Requires-Dist: scikit-image<0.27,>=0.24
Requires-Dist: scipy>=1.12
Requires-Dist: uharfbuzz<1,>=0.45
Requires-Dist: wgpu<0.33,>=0.31
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.9; extra == 'dev'
Requires-Dist: twine>=6.1; extra == 'dev'
Provides-Extra: md
Requires-Dist: mdanalysis<3,>=2.9; extra == 'md'
Provides-Extra: plots
Requires-Dist: matplotlib>=3.8; extra == 'plots'
Provides-Extra: preview
Requires-Dist: glfw>=2.7; extra == 'preview'
Requires-Dist: rendercanvas<3,>=2.4; extra == 'preview'
Description-Content-Type: text/markdown

# 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.

[![Checks](https://github.com/pdpppd/proteinmotion/actions/workflows/checks.yml/badge.svg)](https://github.com/pdpppd/proteinmotion/actions/workflows/checks.yml)
[![Documentation](https://github.com/pdpppd/proteinmotion/actions/workflows/pages.yml/badge.svg)](https://pdpppd.github.io/proteinmotion/)
[![PyPI](https://img.shields.io/pypi/v/proteinmotion?color=376e59)](https://pypi.org/project/proteinmotion/)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-376e59)](https://www.python.org/)
[![MIT license](https://img.shields.io/badge/license-MIT-376e59)](https://github.com/pdpppd/proteinmotion/blob/main/LICENSE)

[Documentation](https://pdpppd.github.io/proteinmotion/) · [Video examples](https://pdpppd.github.io/proteinmotion/gallery/) · [Reference manual](https://pdpppd.github.io/proteinmotion/reference/) · [PyPI](https://pypi.org/project/proteinmotion/) · [Releases](https://github.com/pdpppd/proteinmotion/releases)

[![Calmodulin helix with depth of field](https://pdpppd.github.io/proteinmotion/media/calmodulin-in-focus.jpg)](https://pdpppd.github.io/proteinmotion/docs/calmodulin-in-focus/)

**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](https://pdpppd.github.io/proteinmotion/docs/calmodulin-in-focus/) · [Python source](https://github.com/pdpppd/proteinmotion/blob/main/examples/calmodulin_in_focus.py)

The [calmodulin and troponin C demo](https://pdpppd.github.io/proteinmotion/docs/showcase/) 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](https://pypi.org/project/proteinmotion/) into your Python environment:

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

To make the `proteinmotion` command available from any directory, install it with [pipx](https://pipx.pypa.io/stable/installation/):

```bash
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](https://pdpppd.github.io/proteinmotion/docs/getting-started/#windows-and-nvidia-gpus).

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](https://pdpppd.github.io/proteinmotion/docs/getting-started/) for virtual environments and platform setup.

## Render a video

```bash
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:

```python
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.

```bash
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](https://pdpppd.github.io/proteinmotion/docs/studio/).

### 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](https://pdpppd.github.io/proteinmotion/docs/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](https://pdpppd.github.io/proteinmotion/docs/morphing/).
- **Data on structures:** heatmaps for AlphaFold PAE and distance matrices, and pLDDT, hydropathy, and conservation color presets. See [heatmaps, confidence, and conservation](https://pdpppd.github.io/proteinmotion/docs/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.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](https://pdpppd.github.io/proteinmotion/docs/readable-authoring/)
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](https://www.blender.org/download/) separately. EEVEE is included in Blender. The default native renderer uses the Python dependencies installed above.

```bash
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:

```python
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](https://pdpppd.github.io/proteinmotion/docs/eevee/) 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.
- **Secondary structure:** DSSP assignment when a file has no helix or sheet records, and cartoons that blend between coil, helix, and strand as the structure changes.
- **Heatmaps and presets:** AlphaFold PAE and live distance matrices, and color presets for pLDDT, hydropathy, and sequence conservation from an alignment.

The [guides](https://pdpppd.github.io/proteinmotion/docs/scenes/) 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](https://github.com/pdpppd/proteinmotion/blob/main/skills/proteinmotion-movies/SKILL.md) 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:

```bash
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](https://pdpppd.github.io/proteinmotion/docs/agent-skill/) 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](https://github.com/pdpppd/proteinmotion/blob/main/examples/structure_morph.py) |
| φ and ψ, an α helix forming, a β-hairpin from crystal angles, and ubiquitin's Ramachandran plot | [torsions.py](https://github.com/pdpppd/proteinmotion/blob/main/examples/torsions.py) |
| One ψ turn, then a peptide winding into a helix | [torsion_basics.py](https://github.com/pdpppd/proteinmotion/blob/main/examples/torsion_basics.py) |
| AlphaFold pLDDT and PAE, hydropathy, and conservation | [confidence_and_conservation.py](https://github.com/pdpppd/proteinmotion/blob/main/examples/confidence_and_conservation.py) |
| Studio threading, buried-ribose depth rings, and independent animation timing | [studio_examples.py](https://github.com/pdpppd/proteinmotion/blob/main/examples/studio_examples.py) |
| DNA morphs with C1′ matching and delayed nucleotide motion | [dna_morph.py](https://github.com/pdpppd/proteinmotion/blob/main/examples/dna_morph.py) |
| DNA base styles, strand transparency, and surfaces | [dna_styles.py](https://github.com/pdpppd/proteinmotion/blob/main/examples/dna_styles.py) |
| tRNA regions, modified bases, and B-factor surfaces | [rna_styles.py](https://github.com/pdpppd/proteinmotion/blob/main/examples/rna_styles.py) |
| Depth tunnels into GroEL–GroES | [depth_tunnels.py](https://github.com/pdpppd/proteinmotion/blob/main/examples/depth_tunnels.py) |
| Hemoglobin threaded one chain at a time | [thread_hemoglobin.py](https://github.com/pdpppd/proteinmotion/blob/main/examples/thread_hemoglobin.py) |
| Ca²⁺ ions and their coordinating side chains | [ligands_and_side_chains.py](https://github.com/pdpppd/proteinmotion/blob/main/examples/ligands_and_side_chains.py) |
| Calcium sites and a nucleotide pocket: 41-second film | [binding_sites_film.py](https://github.com/pdpppd/proteinmotion/blob/main/examples/binding_sites_film.py) |
| Troponin C Cd²⁺ sites, a bound sulfate, and representation changes | [troponin_sites.py](https://github.com/pdpppd/proteinmotion/blob/main/examples/troponin_sites.py) |
| Ubiquitin side chains across NMR conformers | [side_chain_ensemble.py](https://github.com/pdpppd/proteinmotion/blob/main/examples/side_chain_ensemble.py) |
| Ions on tRNA and spermine on Z-DNA | [nucleic_ions.py](https://github.com/pdpppd/proteinmotion/blob/main/examples/nucleic_ions.py) |
| B factors, residue colors, and cartoon thickness | [numerical_properties.py](https://github.com/pdpppd/proteinmotion/blob/main/examples/numerical_properties.py) |
| NMR playback with distance, contact, and sequence plots | [synchronized_plots.py](https://github.com/pdpppd/proteinmotion/blob/main/examples/synchronized_plots.py) |
| Electron-density contours and slices | [density_maps.py](https://github.com/pdpppd/proteinmotion/blob/main/examples/density_maps.py) |
| Calmodulin in focus: 68-second EEVEE film | [calmodulin_in_focus.py](https://github.com/pdpppd/proteinmotion/blob/main/examples/calmodulin_in_focus.py) |
| EEVEE depth of field and residue focus | [eevee_focus.py](https://github.com/pdpppd/proteinmotion/blob/main/examples/eevee_focus.py) |
| Calmodulin and troponin C feature demo | [feature_showcase.py](https://github.com/pdpppd/proteinmotion/blob/main/examples/feature_showcase.py) |
| Residue colors, surfaces, distances, and interactions | [molecular_tools.py](https://github.com/pdpppd/proteinmotion/blob/main/examples/molecular_tools.py) |
| Text, residue labels, and callouts | [labels_and_callouts.py](https://github.com/pdpppd/proteinmotion/blob/main/examples/labels_and_callouts.py) |
| Camera focus, 3D highlights, and NMR states | [nmr_regions.py](https://github.com/pdpppd/proteinmotion/blob/main/examples/nmr_regions.py) |
| Contact-guided backbone and ball-and-stick morphs | [backbone_morph.py](https://github.com/pdpppd/proteinmotion/blob/main/examples/backbone_morph.py) |
| Hydrogen bonds in an idealized alpha helix | [alpha_helix_hbonds.py](https://github.com/pdpppd/proteinmotion/blob/main/examples/alpha_helix_hbonds.py) |
| GroEL/GroES assembly | [large_protein.py](https://github.com/pdpppd/proteinmotion/blob/main/examples/large_protein.py) |

```bash
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](https://github.com/pdpppd/proteinmotion/blob/main/docs/VALIDATION.md) 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](https://pdpppd.github.io/proteinmotion/docs/rendering/) and [interaction guide](https://pdpppd.github.io/proteinmotion/docs/interactions/) describe the methods and their limits.

## Development

```bash
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](https://github.com/pdpppd/proteinmotion/blob/main/CONTRIBUTING.md) for setup and checks, and the [writing guide](https://github.com/pdpppd/proteinmotion/blob/main/docs/writing-guide.md) for documentation style.

## License

The package and website use the [MIT license](https://github.com/pdpppd/proteinmotion/blob/main/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](https://github.com/pdpppd/proteinmotion/blob/main/THIRD_PARTY.md) and [structure sources](https://pdpppd.github.io/proteinmotion/docs/rendering/#structure-provenance).

For composable timing, shared renderer settings, selection algebra, reusable styles and migration notes, see [Readable authoring](docs/readable-authoring.md).
