Metadata-Version: 2.4
Name: mdmovie
Version: 0.2.0
Summary: Compose multi-panel movies of molecular dynamics simulations
Author-email: dmighty007 <dibyendumaity1999@bose.res.in>
License-Expression: MIT
Project-URL: Homepage, https://github.com/dmighty007/mdmovie
Project-URL: Documentation, https://github.com/dmighty007/mdmovie/blob/main/docs/TUTORIAL.md
Project-URL: Source, https://github.com/dmighty007/mdmovie
Project-URL: Issues, https://github.com/dmighty007/mdmovie/issues
Keywords: molecular dynamics,MDAnalysis,movie,visualization,animation,free energy surface
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: X11 Applications :: Qt
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Topic :: Multimedia :: Video
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PySide6>=6.5
Requires-Dist: MDAnalysis>=2.7
Requires-Dist: matplotlib>=3.7
Requires-Dist: numpy>=1.24
Requires-Dist: pillow>=10
Requires-Dist: imageio>=2.31
Requires-Dist: imageio-ffmpeg>=0.4.9
Requires-Dist: SciencePlots>=2.1
Provides-Extra: demo
Requires-Dist: MDAnalysisTests; extra == "demo"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-qt; extra == "test"
Requires-Dist: MDAnalysisTests; extra == "test"
Provides-Extra: dev
Requires-Dist: mdmovie[test]; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# MD Movie Maker

Turn a molecular dynamics simulation into a multi-panel movie: your rendered protein next to live plots of RMSD, radius of gyration, secondary structure or any property you can compute with MDAnalysis. The panels can play in sync or each on its own clock.

![Example movie](https://raw.githubusercontent.com/dmighty007/mdmovie/main/docs/images/demo.gif)

![A trajectory on a free-energy surface](https://raw.githubusercontent.com/dmighty007/mdmovie/main/docs/images/fes_demo.gif)

**→ New here? Follow the [illustrated tutorial](https://github.com/dmighty007/mdmovie/blob/main/docs/TUTORIAL.md)**: about 15 minutes, using example data that ships with MDAnalysisTests.

![The app](https://raw.githubusercontent.com/dmighty007/mdmovie/main/docs/images/08_sync.png)

## Features

- **Any layout.** Split, resize and swap cells, or start from a template. Text labels, logos or inset plots can float on top as overlays. The layout is resolution-independent (1080p, 4K, square, portrait, …).
- **Protein frames from any viewer.** Point the app at a folder of images from VMD, PyMOL or ChimeraX. It times them by file number or by position in the folder and reports missing frames.
- **Cropping with a fixed aspect ratio.** Lock the box to 16:9, 4:3, 1:1, a custom ratio or the shape of the cell. *Auto-trim* fits the crop around the molecule across the whole trajectory.
- **Analysis presets on an MDAnalysis Universe.**
  - Built in: RMSD, Rg, RMSF, distances, dihedrals, H-bonds, native contacts, DSSP, atoms within a cutoff, and custom Python expressions.
  - Several presets and trajectories can share one plot, with twin y-axes.
  - Analyses run in the background and results are cached.
  - [Add your own presets](https://github.com/dmighty007/mdmovie/blob/main/docs/TUTORIAL.md#12-write-your-own-analysis-preset) in a few lines.
- **Synced or independent panels.** Sync groups map movie frames to simulation time. Shift, speed up, trim, hold, hide or loop each group, and drag it on the timeline.
- **Plot animations.** Four styles: the line grows, a marker moves, the axis scrolls, or the plot stays static. A live value readout is optional.
- **Publication styles.** [SciencePlots](https://github.com/garrettj403/SciencePlots) styles (science, nature, ieee, notebook) and colour palettes, optional LaTeX, and fine control over ticks, frame, grid, limits, log scale, reference lines and legends. Each series gets its own line style, markers, width, opacity and fill.
- **Trajectories on free-energy surfaces.** Draw the current CV values as a moving point with a fading trail on top of a **pre-rendered FES picture** (calibrated in one dialog), or use the **CV map** panel to compute −kT ln P from the data. PLUMED COLVAR, GROMACS .xvg and CSV files load directly, no trajectory needed.
- **Export** to MP4 (H.264), GIF or a PNG sequence from the GUI, or headless with `mdmovie render`. The preview shows exactly what gets exported.
- Undo/redo for every edit, and projects saved as small JSON files with relative paths.

## Install

```bash
pip install mdmovie            # or: pip install "mdmovie[demo]" to include the demo trajectory
mdmovie                        # GUI (try File › Open demo project)
mdmovie render my.mdmovie.json out.mp4    # render without the GUI
```

Python 3.10 or newer. Everything, including ffmpeg for MP4 export, comes from pip; nothing else to install.

## Code map

```
mdmovie/core/       sync model (timemap), layout tree, crop math, project file
mdmovie/sources/    image sequences + LRU cache, trajectory metadata
mdmovie/analysis/   preset registry, built-in presets, cached runner
mdmovie/panels/     image (+ data overlay), plot, heatmap, CV map, text
mdmovie/render/     compositor (single drawing path for preview and export), exporter
mdmovie/ui/         main window, canvas editor, inspector, timeline, dialogs
docs/               tutorial + make_tutorial_images.py (regenerates every screenshot)
```

## Development

```bash
git clone https://github.com/dmighty007/mdmovie && cd mdmovie
pip install -e ".[dev]"
python -m pytest              # headless
```

### Releasing

1. Bump `__version__` in `mdmovie/__init__.py` and commit.
2. Tag and push: `git tag v0.2.0 && git push origin v0.2.0`.

The `publish` workflow then runs the tests, builds the sdist and wheel, checks that the tag matches the version, and uploads to PyPI with [Trusted Publishing](https://docs.pypi.org/trusted-publishers/), so no API token is stored anywhere. One-time setup: on PyPI, add a *pending publisher* for project `mdmovie`, owner `dmighty007`, repository `mdmovie`, workflow `publish.yml`, environment `pypi`. In the GitHub repository settings, create an environment named `pypi`.

## License

MIT, see [LICENSE](https://github.com/dmighty007/mdmovie/blob/main/LICENSE).
