parallel-matplotlib-animation 0.1.0__tar.gz → 0.1.2__tar.gz

parallel_matplotlib_animation-0.1.2/.claude/settings.local.json

@@ -0,0 +1,12 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(python *)",
+      "Bash(python3.13 -c \"import numpy; print\\(numpy.__version__\\)\")",
+      "Bash(.venv/bin/python *)",
+      "Bash(gh pr *)",
+      "Bash(gh auth *)",
+      "WebFetch(domain:github.com)"
+    ]
+  }
+}

parallel_matplotlib_animation-0.1.2/.gitignore

@@ -0,0 +1,308 @@
+example_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.0/README.md → parallel_matplotlib_animation-0.1.2/PKG-INFO

@@ -1,3 +1,18 @@
+Metadata-Version: 2.4
+Name: parallel-matplotlib-animation
+Version: 0.1.2
+Summary: Animate matplotlib figures into videos, in parallel but with efficient caching
+Project-URL: Repository, https://github.com/sibocw/parallel-matplotlib-animation
+Author-email: Sibo Wang-Chen <sibo.wang@epfl.ch>
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: av>=14.0
+Requires-Dist: matplotlib>=3.10.0
+Requires-Dist: numpy<3,>=2
+Requires-Dist: pillow>=11.0
+Requires-Dist: tqdm>=4.67
+Description-Content-Type: text/markdown
+
 # parallel-matplotlib-animation
 
 Create matplotlib animations rendered to video in parallel, with efficient resources reuse.
@@ -63,7 +78,7 @@ anim = WaveAnimation()
 anim.make_video("wave.mp4", param_by_frame=params, fps=30, num_workers=4)
 ```
 
-![](assets/simple_wave_animation.gif)
+<img src="assets/simple_wave_animation.gif" width="480"/>
 
 ## 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,18 +90,34 @@ 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.
 
+### 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 `src/parallel_animate/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
+
+`simple_wave_animation.py`: The example above
+
+`multi_panel_animation.py`: 5 subplots with different plot types
+
+<img src="assets/multi_panel_animation.gif" width="480"/>
+
+`very_complex_animation.py`: 14 subplots with GridSpec layout
+
+<img src="assets/very_complex_animation.gif" width="480"/>
+
+`nondeterministic_video_loader.py`: handling frames that arrive out of order
+
+<img src="assets/nondeterministic_video_loader.gif" width="240"/>
 
 
 ## Performance test

parallel_matplotlib_animation-0.1.0/PKG-INFO → parallel_matplotlib_animation-0.1.2/README.md

@@ -1,24 +1,3 @@
-Metadata-Version: 2.4
-Name: parallel-matplotlib-animation
-Version: 0.1.0
-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)
-Description-Content-Type: text/markdown
-
 # parallel-matplotlib-animation
 
 Create matplotlib animations rendered to video in parallel, with efficient resources reuse.
@@ -84,7 +63,7 @@ anim = WaveAnimation()
 anim.make_video("wave.mp4", param_by_frame=params, fps=30, num_workers=4)
 ```
 
-![](assets/simple_wave_animation.gif)
+<img src="assets/simple_wave_animation.gif" width="480"/>
 
 ## 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:
@@ -96,18 +75,34 @@ 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.
 
+### 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 `src/parallel_animate/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
+
+`simple_wave_animation.py`: The example above
+
+`multi_panel_animation.py`: 5 subplots with different plot types
+
+<img src="assets/multi_panel_animation.gif" width="480"/>
+
+`very_complex_animation.py`: 14 subplots with GridSpec layout
+
+<img src="assets/very_complex_animation.gif" width="480"/>
+
+`nondeterministic_video_loader.py`: handling frames that arrive out of order
+
+<img src="assets/nondeterministic_video_loader.gif" width="240"/>
 
 
 ## Performance test
@@ -122,4 +117,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.2/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"
+

{parallel_matplotlib_animation-0.1.0 → parallel_matplotlib_animation-0.1.2}/pyproject.toml

@@ -1,9 +1,9 @@
 [project]
 name = "parallel-matplotlib-animation"
-version = "0.1.0"
+version = "0.1.2"
 description = "Animate matplotlib figures into videos, in parallel but with efficient caching"
 authors = [
-    {name = "Sibo Wang-Chen",email = "sibo.wang@epfl.ch"}
+    { name = "Sibo Wang-Chen", email = "sibo.wang@epfl.ch" }
 ]
 readme = "README.md"
 requires-python = ">=3.10"
@@ -15,9 +15,12 @@ dependencies = [
     "Pillow>=11.0",
 ]
 
-[tool.poetry]
-packages = [{include = "parallel_animate", from = "src"}]
+[project.urls]
+Repository = "https://github.com/sibocw/parallel-matplotlib-animation"
 
 [build-system]
-requires = ["poetry-core>=2.0.0,<3.0.0"]
-build-backend = "poetry.core.masonry.api"
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/parallel_animate"]

parallel_matplotlib_animation-0.1.2/src/parallel_animate/__init__.py

@@ -0,0 +1 @@
+from .animator import Animator, IndexedFrameParams