proteinmotion 0.10.1__tar.gz

proteinmotion-0.10.1/.gitignore

@@ -0,0 +1,25 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/
+*.mp4
+!website/public/media/*.mp4
+!website/public/media/docs/*.mp4
+.DS_Store
+.env
+.env.*
+!.env.example
+node_modules/
+.next/
+website/out/
+website/public/downloads/
+*.tsbuildinfo
+output/playwright/
+output/windows-nvidia/
+.playwright-cli/
+.*_offsets.npz
+.*_offsets.lock

proteinmotion-0.10.1/CONTRIBUTING.md

@@ -0,0 +1,111 @@
+# Contributing
+
+Include a reproducible example with each feature or fix. Describe the behavior, the method used, and any limits that affect the result.
+
+## Package development
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install -e '.[dev,md,preview]'
+ruff format src tests examples scripts skills
+ruff check src tests examples scripts skills
+pytest
+python -m build
+```
+
+GPU and hardware-export tests are marked `gpu` and should be run on a native GPU adapter. Some optional example-rendering scripts need `ffmpeg` and `ffprobe` (`brew install ffmpeg` on macOS). CPU checks can run with `pytest -m "not gpu"`.
+
+GitHub Actions runs CPU tests and linting on Ubuntu and Windows, then builds and installs the wheel in a clean environment. For rendering or animation changes, run the local GPU suite on Apple silicon or Windows/NVIDIA and inspect the output. Video checks decode frames with PyAV and do not require an FFmpeg executable. Windows symlink tests skip when Developer Mode or administrator privileges are unavailable. Record the setup and results in the validation report.
+
+## Documentation development
+
+The website uses Next.js static export, React, and Tailwind CSS. Website development requires Node 22 or later. The Python package has its own dependencies.
+
+```bash
+cd website
+npm ci
+npm run dev
+```
+
+Open `http://localhost:3000/proteinmotion/`. Edit Markdown in `docs/` or the site components in `website/`. The complete NMR source is inserted directly from `examples/nmr_regions.py` at build time, so it stays in sync.
+
+Before submitting:
+
+```bash
+npm run build
+npm run check
+npm run verify
+```
+
+The build exports static HTML into `website/out/`. `PAGES_BASE_PATH` defaults to `/proteinmotion`; set it to a different repository path (or an empty string for root hosting) when building for another deployment. Keep site metadata in `website/lib/config.ts` consistent with the final public URL.
+
+`npm run verify` checks exported pages, internal links, fragment targets, and media references. Browser checks should cover desktop/mobile layout, search, code copying, video controls, and reduced motion.
+
+Follow the [writing guide](docs/writing-guide.md) when editing page text, headings, captions, and metadata.
+
+### Rendered documentation examples
+
+Short examples are defined in `examples/docs_examples.py`. Their marked code sections appear beside the rendered output in the guides. To update the clips and snippets, run:
+
+```bash
+python scripts/render_docs_examples.py
+```
+
+This requires a working GPU. The command renders 720p/60 fps clips, checks every encoded frame, saves posters, and updates the matching Markdown snippets. Run it before building the website. The build checks source, input, and media hashes to catch outdated previews.
+
+Use `output=<example-id>` after the language in a Markdown code fence to pair a snippet with its clip. Existing gallery videos use `output=gallery-<demo-id>` beside their render commands.
+
+## Publishing
+
+The Pages workflow builds on pull requests and pushes. Only `main` pushes or a manual workflow run from `main` deploy. GitHub Pages must use **GitHub Actions** as its source. The workflow uploads the static export and deploys it with the official Pages actions. GitHub Pages serves the exported static files.
+
+Compressed web previews are committed in `website/public/media/`. Calmodulin in focus retains 1080p/60 fps. Other previews use 720p, with the continuous feature tour at 60 fps and shorter examples at 30 fps. Their source filenames and sizes are recorded in `provenance.json`; the scientific data provenance lives in the documentation. Original rendered videos, caches, local environments, and build outputs are ignored.
+
+## Changes and issues
+
+Open an issue with a minimal scene, input format, Python version, and the output of `proteinmotion doctor`. For rendering defects, include the relevant time or frame. Use a public example structure when reporting an issue in the public repository.
+
+A pull request should explain the behavior change and relevant checks. Record the source of example data and distinguish deposited structures, simulated trajectories, and interpolated coordinates.
+
+## Package and skill releases
+
+The AI agent skill source is `skills/proteinmotion-movies`. Its resource files are mapped into the wheel by `pyproject.toml`; keep that mapping in sync when adding a skill resource. Run the skill-creator validator when changing its instructions. The starter scene is shared by the skill and `proteinmotion init`, so maintain it once.
+
+Build with `python -m build` (the wheel is built from the sdist). Install that wheel into a fresh environment, change out of the checkout, and run `python -I /path/to/repo/scripts/check_installed_package.py --render` on a native GPU. CI runs the same installed-resource check without rendering. Distribute the wheel, source archive, skill ZIP and checksums as versioned GitHub Release assets. Publish versioned release assets after the release checks pass.
+
+
+### PyPI publishing
+
+The `publish.yml` workflow builds the source archive and wheel, validates the PyPI description, and checks the installed wheel on Linux, Windows, and macOS. Linux installation checks cover Python 3.11–3.14. A manual run with `publish` left false performs these checks without uploading.
+
+Configure a pending GitHub publisher in the PyPI account that will own the project:
+
+| Field | Value |
+|---|---|
+| PyPI project | `proteinmotion` |
+| GitHub owner | `pdpppd` |
+| Repository | `proteinmotion` |
+| Workflow filename | `publish.yml` |
+| GitHub environment | `pypi` |
+
+Create the `pypi` environment in GitHub repository settings and restrict its deployments to release tags. PyPI Trusted Publishing uses GitHub's short-lived identity credentials; it needs no stored PyPI API token. PyPI creates the project on the first successful upload. See the [PyPI setup guide](https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/).
+
+For a release:
+
+1. Update `pyproject.toml`, `proteinmotion.__version__`, and the website package version, then run `python scripts/build_reference.py`.
+2. Run package checks, `python -m build`, and `python -m twine check --strict dist/*`. Verify an isolated installation and a native GPU render with `scripts/check_installed_package.py --render`.
+3. Commit the release and create its matching `v<version>` tag. Publish a GitHub Release for that tag to start the PyPI workflow. The upload job requires the tag to match the package version and waits for all installation checks.
+4. Confirm the version on PyPI, then install it with `python -m pip install --index-url https://pypi.org/simple proteinmotion==<version>` in a fresh environment.
+
+A manual publishing run must select the version tag and set `publish` to true. PyPI distribution filenames are permanent: change the version for a corrected release instead of replacing files. Keep previous release artifacts in separate directories when building a new version.
+
+### Reference manual
+
+The manual reads signatures, defaults, inheritance, and source locations from the Python files. Descriptions and example links are maintained in `docs/reference/catalog.json`. After changing either, regenerate the reference data:
+
+```bash
+python3 scripts/build_reference.py
+```
+
+The generator uses Python’s standard library. The website build checks that the generated data matches the source and that every package export has a reference entry. Describe new parameters and methods in the catalog before building.

proteinmotion-0.10.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ProteinMotion contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

proteinmotion-0.10.1/PKG-INFO

@@ -0,0 +1,229 @@
+Metadata-Version: 2.5
+Name: proteinmotion
+Version: 0.10.1
+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/)
+[![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)](LICENSE)
+
+[Documentation](https://pdpppd.github.io/proteinmotion/) · [Video examples](https://pdpppd.github.io/proteinmotion/gallery/) · [Reference manual](https://pdpppd.github.io/proteinmotion/reference/) · [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 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.
+
+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.
+- **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.
+- **Region tools:** camera focus and 3D sphere, box, or atom highlights.
+- **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) |
+| 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).

proteinmotion-0.10.1/README.md

@@ -0,0 +1,178 @@
+# 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/)
+[![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)](LICENSE)
+
+[Documentation](https://pdpppd.github.io/proteinmotion/) · [Video examples](https://pdpppd.github.io/proteinmotion/gallery/) · [Reference manual](https://pdpppd.github.io/proteinmotion/reference/) · [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 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.
+
+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.
+- **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.
+- **Region tools:** camera focus and 3D sphere, box, or atom highlights.
+- **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) |
+| 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).

proteinmotion-0.10.1/THIRD_PARTY.md

@@ -0,0 +1,33 @@
+# Third-party notices
+
+ProteinMotion's original code is MIT licensed. The following material retains its upstream notices.
+
+## Manim animation timing
+
+The lag calculation and two-stage outline/fill behavior of `Write` / `Unwrite` are adapted from Manim Community's `Write` and `DrawBorderThenFill`, with native GPU rendering written for ProteinMotion.
+
+- Source: [creation.py at commit 485c226168e9c189512b22468de89b18dbc1780e](https://github.com/ManimCommunity/manim/blob/485c226168e9c189512b22468de89b18dbc1780e/manim/animation/creation.py)
+- License: [MIT, copyright 2018 3Blue1Brown LLC](src/proteinmotion/licenses/Manim-LICENSE.txt)
+- Adapted in `src/proteinmotion/annotations.py` and `src/proteinmotion/shaders/text.wgsl`.
+
+This package does not bundle or import Manim/Pango. Text is shaped using HarfBuzz, flattened with FontTools, triangulated with mapbox-earcut and drawn through wgpu/Metal. It is not a full or pixel-identical implementation of Manim Text, MarkupText, or MathTex.
+
+## Plot appearance
+
+Plot axes follow the visual conventions of Manim Community's [Axes](https://docs.manim.community/en/stable/reference/manim.mobject.graphing.coordinate_systems.Axes.html) and [NumberLine](https://docs.manim.community/en/stable/reference/manim.mobject.graphing.number_line.NumberLine.html): independent axis strokes, ticks, labels, and optional tips on the scene background. The plotting code in `src/proteinmotion/plots.py` is implemented in ProteinMotion and uses its native vector renderer.
+
+## Bundled Source Sans 3 fonts
+
+The unmodified Regular and Semibold OpenType fonts are from [Adobe Source Sans, commit 87b37a2daaed80fcb8e8ccb0085c4d72ddade12e](https://github.com/adobe-fonts/source-sans/tree/87b37a2daaed80fcb8e8ccb0085c4d72ddade12e).
+
+Copyright 2010–2024 Adobe, with Reserved Font Name “Source”. Distributed under the [SIL Open Font License 1.1](src/proteinmotion/fonts/OFL.txt), included beside the font binaries in source distributions and wheels. The font license does not apply to documents or videos created using the fonts.
+
+Other dependencies retain their respective upstream licenses. PDB structure provenance is documented in [docs/rendering.md](docs/rendering.md).
+
+## Starter structure
+
+The installable starter movie and Codex skill include deposited ubiquitin coordinates, [PDB 1UBQ](https://www.rcsb.org/structure/1UBQ), copied unchanged from `examples/data/1ubq.cif`. The file retains its structural metadata and source citation. These scientific data are separate from the package's original MIT-licensed code.
+
+## Blender (optional external application)
+
+The EEVEE backend runs a separately installed [Blender](https://www.blender.org/) executable. Blender and EEVEE are not bundled with ProteinMotion. Blender is distributed under the [GNU GPL](https://www.blender.org/about/license/). ProteinMotion's exported meshes and frame requests cross a process boundary; the EEVEE integration code in this repository uses the repository's MIT license.