V2.0 rc

.github/workflows/build.yml

@@ -15,7 +15,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu, macos, windows]
-        python-version: ["3.9", "3.10", "3.11", "3.12"]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
     name: ${{ matrix.os }} - py${{ matrix.python-version }}
     runs-on: ${{ matrix.os }}-latest
     defaults:
@@ -28,6 +28,9 @@ jobs:
         uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
+      - name: Install system OpenGL/EGL libraries (Ubuntu)
+        if: matrix.os == 'ubuntu'
+        run: sudo apt-get install -y --no-install-recommends libegl1 libgl1
       - name: Install dependencies
         run: |
           python -m pip install --progress-bar off --upgrade pip setuptools wheel

.github/workflows/code-style.yml

@@ -15,10 +15,11 @@ jobs:
     steps:
       - name: Checkout repository
         uses: actions/checkout@v6
-      - name: Setup Python 3.10
+      - name: Setup Python 3.13
         uses: actions/setup-python@v6
         with:
-          python-version: '3.10'
+          python-version: '3.13'
+          cache: 'pip'
       - name: Install dependencies
         run: |
           python -m pip install --progress-bar off --upgrade pip setuptools wheel
@@ -27,10 +28,5 @@ jobs:
         run: ruff check .
       - name: Run codespell
         uses: codespell-project/actions-codespell@master
-        with:
-          check_filenames: true
-          check_hidden: true
-          skip: './.git,./build,./.mypy_cache,./.pytest_cache'
-          ignore_words_file: ./.codespellignore
-      # - name: Run pydocstyle
-      #   run: pydocstyle .
+      - name: Run pydocstyle
+        run: pydocstyle .

.github/workflows/doc.yml

@@ -20,30 +20,35 @@ jobs:
         uses: actions/checkout@v6
         with:
           path: ./main
-      - name: Setup Python 3.10
+      - name: Setup Python 3.13
         uses: actions/setup-python@v6
         with:
-          python-version: '3.10'
-      - name: Install Linux dependencies
-        if: runner.os == 'Linux'
+          python-version: '3.13'
+          cache: pip
+      - name: Install system dependencies
         run: |
-          sudo apt update
           sudo apt-get update
-          sudo apt-get -y install libgl1 libegl1
-          sudo apt install libxcb-cursor0
+          sudo apt-get -y install libgl1 libegl1 libxcb-cursor0 pandoc
       - name: Install package
         run: |
           python -m pip install --progress-bar off --upgrade pip setuptools wheel
           python -m pip install --progress-bar off main/.[doc]
       - name: Display system information
         run: whippersnappy-sys_info --developer
+      - name: Cache WhipperSnapPy sample data
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/whippersnappy
+          key: sample-data-sub-rs-data-v1.0
       - name: Build doc
         run: TZ=UTC sphinx-build ./main/doc ./doc-build/dev -W --keep-going
       - name: Upload documentation
         uses: actions/upload-artifact@v6
         with:
           name: doc-dev
-          path: ./doc-build/dev
+          path: |
+            doc-build/dev
+            !doc-build/dev/.doctrees
 
   deploy:
     if: github.event_name == 'push'

.github/workflows/pytest.yml

@@ -19,7 +19,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu, macos, windows]
-        python-version: ["3.9", "3.10", "3.11", "3.12"]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
     name: ${{ matrix.os }} - py${{ matrix.python-version }}
     runs-on: ${{ matrix.os }}-latest
     defaults:
@@ -32,14 +32,17 @@ jobs:
         uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
+      - name: Install system OpenGL/EGL libraries (Ubuntu)
+        if: matrix.os == 'ubuntu'
+        run: sudo apt-get install -y --no-install-recommends libegl1 libgl1
       - name: Install package
         run: |
           python -m pip install --progress-bar off --upgrade pip setuptools wheel
           python -m pip install --progress-bar off .[test]
       - name: Display system information
         run: whippersnappy-sys_info --developer
       - name: Run pytest
-        run: pytest whippersnappy --cov=whippersnappy --cov-report=xml --cov-config=pyproject.toml
+        run: pytest tests --cov=whippersnappy --cov-report=xml --cov-config=pyproject.toml
       - name: Upload to codecov
         if: ${{ matrix.os == 'ubuntu' && matrix.python-version == '3.10' && github.repository == 'Deep-MI/WhipperSnapPy' }}
         uses: codecov/codecov-action@v5

DOCKER.md

@@ -0,0 +1,170 @@
+# Docker Guide
+
+The Docker image provides a fully headless rendering environment with EGL
+off-screen support. No display server or `xvfb` is required.
+
+The default entry point is `whippersnap4` (four-view batch rendering).
+`whippersnap1` (single-view snapshot and rotation video) can be invoked by
+overriding the entry point.
+
+---
+
+## Building the image
+
+From the repository root:
+
+```bash
+docker build --rm -t whippersnappy -f Dockerfile .
+```
+
+---
+
+## Running — four-view batch rendering (`whippersnap4`)
+
+`whippersnap4` renders lateral and medial views of both hemispheres and writes
+a single composed PNG image.
+
+Mount your local directories into the container and pass the in-container paths
+as arguments:
+
+```bash
+docker run --rm --init \
+  -v /path/to/subject:/subject \
+  -v /path/to/output:/output \
+  --user $(id -u):$(id -g) \
+  whippersnappy \
+  -lh /subject/surf/lh.thickness \
+  -rh /subject/surf/rh.thickness \
+  -sd /subject \
+  -o /output/snap4.png
+```
+
+### With an annotation file instead of an overlay
+
+```bash
+docker run --rm --init \
+  -v /path/to/subject:/subject \
+  -v /path/to/output:/output \
+  --user $(id -u):$(id -g) \
+  whippersnappy \
+  --lh_annot /subject/label/lh.aparc.annot \
+  --rh_annot /subject/label/rh.aparc.annot \
+  -sd /subject \
+  -o /output/snap4_annot.png
+```
+
+### With a caption and custom thresholds
+
+```bash
+docker run --rm --init \
+  -v /path/to/subject:/subject \
+  -v /path/to/output:/output \
+  --user $(id -u):$(id -g) \
+  whippersnappy \
+  -lh /subject/surf/lh.thickness \
+  -rh /subject/surf/rh.thickness \
+  -sd /subject \
+  --fthresh 2.0 --fmax 4.0 \
+  --caption "Cortical thickness" \
+  -o /output/snap4_thickness.png
+```
+
+### All `whippersnap4` options
+
+```
+docker run --rm whippersnappy --help
+```
+
+---
+
+## Running — single-view snapshot (`whippersnap1`)
+
+Override the entry point with `--entrypoint whippersnap1`:
+
+```bash
+docker run --rm --init \
+  --entrypoint whippersnap1 \
+  -v /path/to/subject:/subject \
+  -v /path/to/output:/output \
+  --user $(id -u):$(id -g) \
+  whippersnappy \
+  --mesh /subject/surf/lh.white \
+  --overlay /subject/surf/lh.thickness \
+  --bg-map /subject/surf/lh.curv \
+  --view left \
+  --fthresh 2.0 --fmax 4.0 \
+  -o /output/snap1.png
+```
+
+### All `whippersnap1` options
+
+```bash
+docker run --rm --entrypoint whippersnap1 whippersnappy --help
+```
+
+---
+
+## Running — 360° rotation video (`whippersnap1 --rotate`)
+
+`whippersnap1 --rotate` renders a full 360° rotation video and writes an
+`.mp4`, `.webm`, or `.gif` file.  `imageio-ffmpeg` is bundled in the image —
+no system ffmpeg is required.
+
+### MP4 (H.264, recommended)
+
+```bash
+docker run --rm --init \
+  --entrypoint whippersnap1 \
+  -v /path/to/subject:/subject \
+  -v /path/to/output:/output \
+  --user $(id -u):$(id -g) \
+  whippersnappy \
+  --mesh /subject/surf/lh.white \
+  --overlay /subject/surf/lh.thickness \
+  --bg-map /subject/surf/lh.curv \
+  --rotate \
+  --rotate-frames 72 \
+  --rotate-fps 24 \
+  -o /output/rotation.mp4
+```
+
+### Animated GIF (no ffmpeg needed)
+
+```bash
+docker run --rm --init \
+  --entrypoint whippersnap1 \
+  -v /path/to/subject:/subject \
+  -v /path/to/output:/output \
+  --user $(id -u):$(id -g) \
+  whippersnappy \
+  --mesh /subject/surf/lh.white \
+  --overlay /subject/surf/lh.thickness \
+  --rotate \
+  --rotate-frames 36 \
+  --rotate-fps 12 \
+  -o /output/rotation.gif
+```
+
+---
+
+## Path mapping summary
+
+| Host path | Container path | Purpose |
+|-----------|---------------|---------|
+| `/path/to/subject` | `/subject` | FreeSurfer subject directory (contains `surf/`, `label/`) |
+| `/path/to/output` | `/output` | Directory where output files are written |
+
+All output files are written to the container path you pass via `-o`; mount the
+parent directory to retrieve them on the host.
+
+---
+
+## Notes
+
+- The `--init` flag is recommended so that signals (e.g. `Ctrl-C`) are handled
+  correctly inside the container.
+- `--user $(id -u):$(id -g)` ensures output files are owned by your host user,
+  not root.
+- The interactive GUI (`whippersnap`) is **not** available in the Docker image —
+  it requires a display server and PyQt6, which are not installed.
+

Dockerfile

@@ -1,18 +1,18 @@
-FROM ubuntu:20.04
+FROM python:3.11-slim
 
-# Install packages
 RUN apt-get update && apt-get install -y --no-install-recommends \
-    python3 pip xvfb libglib2.0-0 libxkbcommon-x11-0 libgl1 libegl1 \
-    libfontconfig1 libdbus-1-3 && \
-  apt clean && \
-  rm -rf /var/libs/apt/lists/* /tmp/* /var/tmp/*
+    libegl1 \
+    libgl1 \
+    libglib2.0-0 \
+    libfontconfig1 \
+    libdbus-1-3 && \
+  apt-get clean && \
+  rm -rf /var/lib/apt/lists/*
 
-# Install python packages
 RUN pip install --upgrade pip
-RUN pip install pyopengl glfw pillow numpy pyrr PyQt6
 
 COPY . /WhipperSnapPy
-RUN pip install /WhipperSnapPy
+RUN pip install /WhipperSnapPy[video]
 
-ENTRYPOINT ["xvfb-run","whippersnap"]
+ENTRYPOINT ["whippersnap4"]
 CMD ["--help"]