Metadata-Version: 2.5
Name: proteinmotion
Version: 0.12.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 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 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:** wires fly in, trace each chain from C to N terminus with glowing tips, and fade into the protein.
- **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:** contact-map matching using protein Cα or DNA/RNA C1′ atoms, delayed motion along each chain, and fades for unmatched residues.

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