diff --git a/README.md b/README.md index ab8a5e6..31dd6e1 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ A modern Python reimagining of Methfessel's [XBS](https://www.ccl.net/cca/software/X-WINDOW/xbs/) ball-and-stick viewer (1995), named after [August Wilhelm von Hofmann](https://en.wikipedia.org/wiki/August_Wilhelm_von_Hofmann) who built the first ball-and-stick molecular models in 1865. -hofmann renders crystal and molecular structures as depth-sorted ball-and-stick images with static, publication-quality vector output (SVG, PDF) via matplotlib. +hofmann renders crystal and molecular structures as depth-sorted ball-and-stick images, producing publication-quality static output (SVG, PDF, PNG) and trajectory animations (GIF, MP4) via matplotlib.

LLZO garnet with ZrO6 polyhedra rendered with hofmann @@ -15,6 +15,7 @@ hofmann renders crystal and molecular structures as depth-sorted ball-and-stick ## Features - Static publication-quality output (SVG, PDF, PNG) via matplotlib +- Trajectory animations (GIF, MP4) with per-frame colouring - XBS `.bs` and `.mv` (trajectory) file formats - Optional ASE `Atoms` and pymatgen `Structure` interoperability - Periodic boundary conditions with automatic image expansion @@ -41,6 +42,12 @@ For pymatgen interoperability: pip install "hofmann[pymatgen]" ``` +For animation export (GIF/MP4): + +```bash +pip install "hofmann[animation]" +``` + ### Requirements - Python 3.11+ @@ -49,6 +56,8 @@ pip install "hofmann[pymatgen]" - scipy >= 1.10 - ase >= 3.22 (optional) - pymatgen >= 2024.1.1 (optional) +- imageio >= 2.30 (optional, for GIF animation export) +- imageio-ffmpeg >= 0.5 (optional, for MP4 animation export) ## Quick start @@ -120,6 +129,7 @@ Full documentation is available at [hofmann.readthedocs.io](https://hofmann.read - [Scenes and structures](https://hofmann.readthedocs.io/en/latest/scenes.html) -- scenes, frames, bonds, polyhedra - [Rendering](https://hofmann.readthedocs.io/en/latest/rendering.html) -- views, render styles, unit cells, axes - [Colouring](https://hofmann.readthedocs.io/en/latest/colouring.html) -- per-atom data colouring, custom functions, multiple layers +- [Animations](https://hofmann.readthedocs.io/en/latest/animations.html) -- trajectory animations, per-frame colouring - [Interactive viewer](https://hofmann.readthedocs.io/en/latest/interactive.html) -- mouse and keyboard controls - [XBS file format](https://hofmann.readthedocs.io/en/latest/xbs-format.html) -- `.bs` and `.mv` format reference - [API reference](https://hofmann.readthedocs.io/en/latest/api.html) -- full autodoc API diff --git a/docs/getting-started.rst b/docs/getting-started.rst index 6d51b53..bcb1b08 100644 --- a/docs/getting-started.rst +++ b/docs/getting-started.rst @@ -22,6 +22,12 @@ For pymatgen interoperability (optional): pip install "hofmann[pymatgen]" +For animation export (optional): + +.. code-block:: bash + + pip install "hofmann[animation]" + For development (tests + docs): .. code-block:: bash @@ -37,6 +43,8 @@ Requirements - scipy >= 1.10 - ase >= 3.22 (optional, for :func:`~hofmann.from_ase`) - pymatgen >= 2024.1.1 (optional, for :func:`~hofmann.from_pymatgen`) +- imageio >= 2.30 (optional, for :meth:`~hofmann.StructureScene.render_animation`) +- imageio-ffmpeg >= 0.5 (optional, for MP4 output via :meth:`~hofmann.StructureScene.render_animation`) Rendering from an XBS file diff --git a/docs/index.rst b/docs/index.rst index da4748d..8ca27d6 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,8 +6,8 @@ viewer (1995), named after `August Wilhelm von Hofmann`_ who built the first ball-and-stick molecular models in 1865. hofmann renders crystal and molecular structures as depth-sorted -ball-and-stick images with static, publication-quality output via -matplotlib (vector SVG/PDF). +ball-and-stick images, producing publication-quality static output +(SVG, PDF, PNG) and trajectory animations (GIF, MP4) via matplotlib. .. image:: _static/llzo.svg :width: 480px