parallel-matplotlib-animation 0.1.1__tar.gz → 0.1.3__tar.gz

parallel_matplotlib_animation-0.1.3/.github/workflows/docs.yml

@@ -0,0 +1,40 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches: [main]
+  release:
+    types: [published]
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install FFmpeg
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y ffmpeg
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --frozen --extra dev
+
+      - name: Render example videos
+        # The gallery MP4s are git-ignored, so render them here. The
+        # embed_example_videos.py MkDocs hook copies them into the built site.
+        run: uv run bash examples/run_all_except_benchmarks.sh
+
+      - name: Deploy docs to GitHub Pages
+        run: uv run mkdocs gh-deploy --force --clean

parallel_matplotlib_animation-0.1.3/.github/workflows/publish.yml

@@ -0,0 +1,42 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Build package
+        run: uv build
+
+      - name: Upload dist artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi-nely
+    permissions:
+      id-token: write  # required for OIDC trusted publisher
+
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

parallel_matplotlib_animation-0.1.3/.github/workflows/tests.yml

@@ -0,0 +1,33 @@
+name: Tests
+
+on:
+  push:
+    branches: ["main", "dev-*"]
+  pull_request:
+    branches: ["main"]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install FFmpeg
+        run: sudo apt-get update && sudo apt-get install -y ffmpeg
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --frozen --extra dev
+
+      - name: Run tests
+        run: uv run pytest tests

parallel_matplotlib_animation-0.1.3/.gitignore

@@ -0,0 +1,308 @@
+output/
+
+######################################################################
+
+# Created by https://www.toptal.com/developers/gitignore/api/python,linux,macos,windows,git,vim,visualstudiocode
+# Edit at https://www.toptal.com/developers/gitignore?templates=python,linux,macos,windows,git,vim,visualstudiocode
+
+### Git ###
+# Created by git for backups. To disable backups in Git:
+# $ git config --global mergetool.keepBackup false
+*.orig
+
+# Created by git when using merge tools for conflicts
+*.BACKUP.*
+*.BASE.*
+*.LOCAL.*
+*.REMOTE.*
+*_BACKUP_*.txt
+*_BASE_*.txt
+*_LOCAL_*.txt
+*_REMOTE_*.txt
+
+### Linux ###
+*~
+
+# temporary files which can be created if a process still has a handle open of a deleted file
+.fuse_hidden*
+
+# KDE directory preferences
+.directory
+
+# Linux trash folder which might appear on any partition or disk
+.Trash-*
+
+# .nfs files are created when an open file is removed but is still being accessed
+.nfs*
+
+### macOS ###
+# General
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Icon must end with two \r
+Icon
+
+
+# Thumbnails
+._*
+
+# Files that might appear in the root of a volume
+.DocumentRevisions-V100
+.fseventsd
+.Spotlight-V100
+.TemporaryItems
+.Trashes
+.VolumeIcon.icns
+.com.apple.timemachine.donotpresent
+
+# Directories potentially created on remote AFP share
+.AppleDB
+.AppleDesktop
+Network Trash Folder
+Temporary Items
+.apdisk
+
+### macOS Patch ###
+# iCloud generated files
+*.icloud
+
+### Python ###
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+### Python Patch ###
+# Poetry local configuration file - https://python-poetry.org/docs/configuration/#local-configuration
+poetry.toml
+
+# ruff
+.ruff_cache/
+
+# LSP config files
+pyrightconfig.json
+
+### Vim ###
+# Swap
+[._]*.s[a-v][a-z]
+!*.svg  # comment out if you don't need vector files
+[._]*.sw[a-p]
+[._]s[a-rt-v][a-z]
+[._]ss[a-gi-z]
+[._]sw[a-p]
+
+# Session
+Session.vim
+Sessionx.vim
+
+# Temporary
+.netrwhist
+# Auto-generated tag files
+tags
+# Persistent undo
+[._]*.un~
+
+### VisualStudioCode ###
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+!.vscode/*.code-snippets
+
+# Local History for Visual Studio Code
+.history/
+
+# Built Visual Studio Code Extensions
+*.vsix
+
+### VisualStudioCode Patch ###
+# Ignore all local history of files
+.history
+.ionide
+
+### Windows ###
+# Windows thumbnail cache files
+Thumbs.db
+Thumbs.db:encryptable
+ehthumbs.db
+ehthumbs_vista.db
+
+# Dump file
+*.stackdump
+
+# Folder config file
+[Dd]esktop.ini
+
+# Recycle Bin used on file shares
+$RECYCLE.BIN/
+
+# Windows Installer files
+*.cab
+*.msi
+*.msix
+*.msm
+*.msp
+
+# Windows shortcuts
+*.lnk
+
+# End of https://www.toptal.com/developers/gitignore/api/python,linux,macos,windows,git,vim,visualstudiocode

parallel_matplotlib_animation-0.1.1/README.md → parallel_matplotlib_animation-0.1.3/PKG-INFO

@@ -1,3 +1,25 @@
+Metadata-Version: 2.4
+Name: parallel-matplotlib-animation
+Version: 0.1.3
+Summary: Animate matplotlib figures into videos, in parallel but with efficient caching
+Project-URL: Repository, https://github.com/nely-epfl/parallel-matplotlib-animation
+Author-email: Sibo Wang-Chen <sibo.wang@epfl.ch>
+License-File: LICENSE
+Requires-Python: <3.15,>=3.10
+Requires-Dist: matplotlib>=3.10.0
+Requires-Dist: numpy<3,>=2
+Requires-Dist: parallel-video-io==0.1.8
+Requires-Dist: tqdm>=4.67
+Provides-Extra: benchmark
+Requires-Dist: pandas<3.0,>=2.0; extra == 'benchmark'
+Requires-Dist: plotly<7.0,>=6.8; extra == 'benchmark'
+Provides-Extra: dev
+Requires-Dist: mkdocs-material<10.0,>=9.5; extra == 'dev'
+Requires-Dist: mkdocstrings[python]>=0.29; extra == 'dev'
+Requires-Dist: pytest<10.0,>=9.0; extra == 'dev'
+Requires-Dist: ruff>=0.15; extra == 'dev'
+Description-Content-Type: text/markdown
+
 # parallel-matplotlib-animation
 
 Create matplotlib animations rendered to video in parallel, with efficient resources reuse.
@@ -21,7 +43,7 @@ Renders matplotlib animations by:
 1. Creating a bunch of worker processes, and creating matplotlib resources (plt.Figure, plt.Axes, artists, etc.) once per worker
 2. Distributing frames across workers via a dynamic queue
 3. Rendering the assigned frames from each worker, but updating the data only (without redrawing the whole plot from scratch) 
-4. Encoding frames to video with PyAV (very efficient FFmpeg under the hood)
+4. Encoding frames to video with [parallel-video-io](https://github.com/sibocw/parallel-video-io) (FFmpeg under the hood, with automatic GPU/NVENC acceleration when available)
 
 **Key design: Figure reuse.** In each worker process, `setup()` runs once to create the figure, then `update()` modifies it repeatedly. This brings the best of:
 - Serial processing: avoids the overhead of recreating complex layouts for every frame
@@ -37,7 +59,7 @@ from parallel_animate import Animator
 # Step 1: Create a child class of parallel_animate.Animator
 class WaveAnimation(Animator):
 
-    # Step 2: Define how the plot should be setup
+    # Step 2: Define how the plot should be set up
     def setup(self):
         fig, ax = plt.subplots()
         self.x = np.linspace(0, 4 * np.pi, 200)
@@ -58,12 +80,12 @@ class WaveAnimation(Animator):
 # Step 4: Define a list of input parameters, one for each frame
 params = [{"phase": 2 * np.pi * i / 60} for i in range(60)]
 
-# Step 5: Make video in parallel
+# Step 5: Make the video in parallel
 anim = WaveAnimation()
 anim.make_video("wave.mp4", param_by_frame=params, fps=30, num_workers=4)
 ```
 
-![](assets/simple_wave_animation.gif)
+<video src="https://sibocw.github.io/parallel-matplotlib-animation/output/simple_wave_animation.mp4" width="480" autoplay loop muted playsinline controls></video>
 
 ## Usage
 This library has a single class: `parallel_animate.Animator`. To make an animation, you must create your own class inheriting from it and define the following methods:
@@ -75,25 +97,45 @@ This library has a single class: `parallel_animate.Animator`. To make an animati
 Once you have defined your animator class, there is a single method that you need to call that makes the video: **`.make_video(...)`**. It accepts the following arguments:
 
 - `output_file` (Path or str): Output video path
-- `param_by_frame` (list): List of parameters. Each element in the list is the `params` argument to be given to the `.update` call for the corresponding frame.
+- `param_by_frame` (Iterable): Iterable of parameters. Each element is the `params` argument to be given to the `.update` call for the corresponding frame. Can be a list, tuple, generator, or any other iterable. Using generators is particularly useful for large data (e.g., bitmaps) to avoid loading everything into memory at once.
 - `fps` (int): Frame rate of the output video
+- `n_frames` (int or None): Number of frames to render. If None, use the length of `param_by_frame`. If param_by_frame does not have `__len__` implemented and `n_frames` is None, the progress bar won't show completion percentage.
 - `num_workers` (int): Number of worker processes to be spawned. If -1, use all CPU cores. If -2, use all but one CPU cores, etc. If 1, no child process is created and the video is made in the main process itself. Default is -1.
-- See the docstring for `parallel_animate.animator` directly for less commonly used, optional parameters. These control logging, rendering quality, etc.
+- `video_mode` (str): Encoder selection passed to parallel-video-io: `"auto"` (default) uses the GPU encoder (FFmpeg/NVENC) when a CUDA device is available and falls back to CPU (libx264) otherwise; `"gpu"` forces NVENC and `"cpu"` forces libx264. Output is always an H.264 MP4.
+- `video_quality` (int or None), `video_preset` (str or None), `video_extra_ffmpeg_params` (list of str or None): Optional encoding-quality controls forwarded to parallel-video-io. Leave as `None` to use its sensible defaults.
+- See the docstring for `parallel_animate.animator` directly for the remaining less commonly used, optional parameters. These control logging, figure reuse, prefetching, etc.
+
+> **Note:** parallel-video-io is currently Linux-only.
+
+### Special case: frame params arriving out-of-order in `param_by_frame`
+In some cases, frames in `param_by_frame` might be out of order. We can handle these scenarios by populating `param_by_frame` with a special `parallel_animate.IndexedFrameParams` dataclass, which specifies the frame index that overrides the ordering in `param_by_frame`. This can be useful when, for example, the animator needs to draw frames that are decoded from a video, and the dataloader for that video might return frames in nondeterministic order because it's parallelized.
 
+See `examples/nondeterministic_video_loader.py` for details.
 
 ## Examples
 
-See [`src/parallel_animate/examples/`](https://github.com/sibocw/parallel-matplotlib-animation/blob/main/src/parallel_animate/examples/):
-- `simple_wave_animation.py`: The example above
-- `multi_panel_animation.py`: 5 subplots with different plot types
-- `very_complex_animation.py`: 14 subplots with GridSpec layout
+See [`examples/`](https://github.com/sibocw/parallel-matplotlib-animation/blob/main/examples/). Run all of them (except the benchmark) with `./examples/run_all.sh`.
+
+`simple_wave_animation.py`: The example above
+
+`multi_panel_animation.py`: 5 subplots with different plot types
+
+<video src="https://sibocw.github.io/parallel-matplotlib-animation/output/multi_panel_animation.mp4" width="480" autoplay loop muted playsinline controls></video>
+
+`very_complex_animation.py`: 14 subplots with GridSpec layout
+
+<video src="https://sibocw.github.io/parallel-matplotlib-animation/output/very_complex_animation.mp4" width="480" autoplay loop muted playsinline controls></video>
+
+`nondeterministic_video_loader.py`: handling frames that arrive out of order
+
+<video src="https://sibocw.github.io/parallel-matplotlib-animation/output/nondeterministic_video_loader.mp4" width="240" autoplay loop muted playsinline controls></video>
 
 
 ## Performance test
 
-A [strong scaling test](https://hpc-wiki.info/hpc/Scaling_tests#Strong_Scaling) is implemented in `src/parallel_animate/examples/scaling_test.py`. Here's the result on my 8-core (16-thread) Intel Core i9-11900K Processor:
+A [strong scaling test](https://hpc-wiki.info/hpc/Scaling_tests#Strong_Scaling) is implemented in `examples/scaling_test.py`. Here's the result on my 8-core (16-thread) Intel Core i9-11900K Processor:
 
-![](assets/scaling_graph.png)
+See the [interactive scaling figure](https://sibocw.github.io/parallel-matplotlib-animation/benchmark/) on the documentation site.
 
 The left-most blue dot indicates serial processing with resources reuse. The black line indicates ideal scaling (zero overhead) if all frames are rendered completely independently in parallel (as is the case in all parallel matplotlib animation libraries I found). Blue dots at 1+ workers are what's implemented in this library.
 

parallel_matplotlib_animation-0.1.1/PKG-INFO → parallel_matplotlib_animation-0.1.3/README.md

@@ -1,25 +1,3 @@
-Metadata-Version: 2.4
-Name: parallel-matplotlib-animation
-Version: 0.1.1
-Summary: Animate matplotlib figures into videos, in parallel but with efficient caching
-License-File: LICENSE
-Author: Sibo Wang-Chen
-Author-email: sibo.wang@epfl.ch
-Requires-Python: >=3.10
-Classifier: Programming Language :: Python :: 3
-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
-Requires-Dist: Pillow (>=11.0)
-Requires-Dist: av (>=14.0)
-Requires-Dist: matplotlib (>=3.10.0)
-Requires-Dist: numpy (>=2,<3)
-Requires-Dist: tqdm (>=4.67)
-Project-URL: Repository, https://github.com/sibocw/parallel-matplotlib-animation
-Description-Content-Type: text/markdown
-
 # parallel-matplotlib-animation
 
 Create matplotlib animations rendered to video in parallel, with efficient resources reuse.
@@ -43,7 +21,7 @@ Renders matplotlib animations by:
 1. Creating a bunch of worker processes, and creating matplotlib resources (plt.Figure, plt.Axes, artists, etc.) once per worker
 2. Distributing frames across workers via a dynamic queue
 3. Rendering the assigned frames from each worker, but updating the data only (without redrawing the whole plot from scratch) 
-4. Encoding frames to video with PyAV (very efficient FFmpeg under the hood)
+4. Encoding frames to video with [parallel-video-io](https://github.com/sibocw/parallel-video-io) (FFmpeg under the hood, with automatic GPU/NVENC acceleration when available)
 
 **Key design: Figure reuse.** In each worker process, `setup()` runs once to create the figure, then `update()` modifies it repeatedly. This brings the best of:
 - Serial processing: avoids the overhead of recreating complex layouts for every frame
@@ -59,7 +37,7 @@ from parallel_animate import Animator
 # Step 1: Create a child class of parallel_animate.Animator
 class WaveAnimation(Animator):
 
-    # Step 2: Define how the plot should be setup
+    # Step 2: Define how the plot should be set up
     def setup(self):
         fig, ax = plt.subplots()
         self.x = np.linspace(0, 4 * np.pi, 200)
@@ -80,12 +58,12 @@ class WaveAnimation(Animator):
 # Step 4: Define a list of input parameters, one for each frame
 params = [{"phase": 2 * np.pi * i / 60} for i in range(60)]
 
-# Step 5: Make video in parallel
+# Step 5: Make the video in parallel
 anim = WaveAnimation()
 anim.make_video("wave.mp4", param_by_frame=params, fps=30, num_workers=4)
 ```
 
-![](assets/simple_wave_animation.gif)
+<video src="https://sibocw.github.io/parallel-matplotlib-animation/output/simple_wave_animation.mp4" width="480" autoplay loop muted playsinline controls></video>
 
 ## Usage
 This library has a single class: `parallel_animate.Animator`. To make an animation, you must create your own class inheriting from it and define the following methods:
@@ -97,25 +75,45 @@ This library has a single class: `parallel_animate.Animator`. To make an animati
 Once you have defined your animator class, there is a single method that you need to call that makes the video: **`.make_video(...)`**. It accepts the following arguments:
 
 - `output_file` (Path or str): Output video path
-- `param_by_frame` (list): List of parameters. Each element in the list is the `params` argument to be given to the `.update` call for the corresponding frame.
+- `param_by_frame` (Iterable): Iterable of parameters. Each element is the `params` argument to be given to the `.update` call for the corresponding frame. Can be a list, tuple, generator, or any other iterable. Using generators is particularly useful for large data (e.g., bitmaps) to avoid loading everything into memory at once.
 - `fps` (int): Frame rate of the output video
+- `n_frames` (int or None): Number of frames to render. If None, use the length of `param_by_frame`. If param_by_frame does not have `__len__` implemented and `n_frames` is None, the progress bar won't show completion percentage.
 - `num_workers` (int): Number of worker processes to be spawned. If -1, use all CPU cores. If -2, use all but one CPU cores, etc. If 1, no child process is created and the video is made in the main process itself. Default is -1.
-- See the docstring for `parallel_animate.animator` directly for less commonly used, optional parameters. These control logging, rendering quality, etc.
+- `video_mode` (str): Encoder selection passed to parallel-video-io: `"auto"` (default) uses the GPU encoder (FFmpeg/NVENC) when a CUDA device is available and falls back to CPU (libx264) otherwise; `"gpu"` forces NVENC and `"cpu"` forces libx264. Output is always an H.264 MP4.
+- `video_quality` (int or None), `video_preset` (str or None), `video_extra_ffmpeg_params` (list of str or None): Optional encoding-quality controls forwarded to parallel-video-io. Leave as `None` to use its sensible defaults.
+- See the docstring for `parallel_animate.animator` directly for the remaining less commonly used, optional parameters. These control logging, figure reuse, prefetching, etc.
+
+> **Note:** parallel-video-io is currently Linux-only.
+
+### Special case: frame params arriving out-of-order in `param_by_frame`
+In some cases, frames in `param_by_frame` might be out of order. We can handle these scenarios by populating `param_by_frame` with a special `parallel_animate.IndexedFrameParams` dataclass, which specifies the frame index that overrides the ordering in `param_by_frame`. This can be useful when, for example, the animator needs to draw frames that are decoded from a video, and the dataloader for that video might return frames in nondeterministic order because it's parallelized.
 
+See `examples/nondeterministic_video_loader.py` for details.
 
 ## Examples
 
-See [`src/parallel_animate/examples/`](https://github.com/sibocw/parallel-matplotlib-animation/blob/main/src/parallel_animate/examples/):
-- `simple_wave_animation.py`: The example above
-- `multi_panel_animation.py`: 5 subplots with different plot types
-- `very_complex_animation.py`: 14 subplots with GridSpec layout
+See [`examples/`](https://github.com/sibocw/parallel-matplotlib-animation/blob/main/examples/). Run all of them (except the benchmark) with `./examples/run_all.sh`.
+
+`simple_wave_animation.py`: The example above
+
+`multi_panel_animation.py`: 5 subplots with different plot types
+
+<video src="https://sibocw.github.io/parallel-matplotlib-animation/output/multi_panel_animation.mp4" width="480" autoplay loop muted playsinline controls></video>
+
+`very_complex_animation.py`: 14 subplots with GridSpec layout
+
+<video src="https://sibocw.github.io/parallel-matplotlib-animation/output/very_complex_animation.mp4" width="480" autoplay loop muted playsinline controls></video>
+
+`nondeterministic_video_loader.py`: handling frames that arrive out of order
+
+<video src="https://sibocw.github.io/parallel-matplotlib-animation/output/nondeterministic_video_loader.mp4" width="240" autoplay loop muted playsinline controls></video>
 
 
 ## Performance test
 
-A [strong scaling test](https://hpc-wiki.info/hpc/Scaling_tests#Strong_Scaling) is implemented in `src/parallel_animate/examples/scaling_test.py`. Here's the result on my 8-core (16-thread) Intel Core i9-11900K Processor:
+A [strong scaling test](https://hpc-wiki.info/hpc/Scaling_tests#Strong_Scaling) is implemented in `examples/scaling_test.py`. Here's the result on my 8-core (16-thread) Intel Core i9-11900K Processor:
 
-![](assets/scaling_graph.png)
+See the [interactive scaling figure](https://sibocw.github.io/parallel-matplotlib-animation/benchmark/) on the documentation site.
 
 The left-most blue dot indicates serial processing with resources reuse. The black line indicates ideal scaling (zero overhead) if all frames are rendered completely independently in parallel (as is the case in all parallel matplotlib animation libraries I found). Blue dots at 1+ workers are what's implemented in this library.
 
@@ -123,4 +121,4 @@ The left-most blue dot indicates serial processing with resources reuse. The bla
 ## Unit tests
 ```bash
 python -m unittest discover -s tests
-```
+```

parallel_matplotlib_animation-0.1.3/dev/mp4_to_gif.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+
+# Convert an MP4 video to a GIF with specified scale and optional frame limit.
+# Useful for creating GIFs from rendered videos for documentation.
+# Usage:
+# ./mp4_to_gif.sh input.mp4 output.gif scale max_frames
+# Example:
+# ./mp4_to_gif.sh input.mp4 output.gif 320 100   # limit to 100 frames
+# ./mp4_to_gif.sh input.mp4 output.gif 320 0     # unlimited
+
+input_path="$1"
+output_path="$2"
+scale="$3"
+max_frames="$4"
+
+# Check arguments
+if [ $# -lt 3 ] || [ $# -gt 4 ]; then
+  echo "Usage: $0 <input_path> <output_path> <scale> [max_frames]"
+  exit 1
+fi
+
+# Set frame limit option
+frame_limit=""
+if [ -n "$max_frames" ] && [ "$max_frames" -gt 0 ]; then
+    frame_limit="-vframes $max_frames"
+fi
+
+ffmpeg -i "$input_path" $frame_limit \
+-filter_complex "fps=10,scale=${scale}:-1:flags=lanczos,split[s0][s1];[s0]palettegen=stats_mode=single[p];[s1][p]paletteuse=dither=sierra2_4a" \
+-loop 0 "$output_path"
+