Upgrade WhipperSnapPy from 1.3 to 2.1, simplify and streamline integration

[ClePol]

Overview

Upgrade to whippersnappy 2.0 with native EGL headless rendering, eliminating xvfb dependency and reducing Docker image size.

Changes

• Direct data passing: Surface and overlay data passed in-memory instead of via disk I/O for better performance.
• Validation checks: Added whippersnappy >= 2.0 version validation with clear error messages for users.
• Removed xvfb & dependencies: Eliminated virtual framebuffer orchestration and X11-related libraries from Docker image.

Detailed Changes

1. pyproject.toml — Version pin updated

   • whippersnappy>=1.3.1 → whippersnappy>=2.1

2. requirements.mac.txt — Version pin updated

   • whippersnappy>=1.3.1 → whippersnappy>=2.1

3. run_fastsurfer.sh — Removed xvfb orchestration

   • Removed entire maybe_xvfb block (lines 767–794)
   • Removed glfw/OpenGL/whippersnappy.core import test
   • Removed all associated warning messages
   • Simplified line 1184 by removing "${maybe_xvfb[@]}" prefix from CC module command invocation
   • Removed obsolete comment about xvfb-run wrapping
   • Note: Whippersnappy 2.1 renders headlessly via mesa—no virtual framebuffer needed

4. tools/Docker/Dockerfile — Slimmed runtime dependencies

   • Updated dependencies from: xvfb libglib2.0-0 libxkbcommon-x11-0 libgl1 libegl1 libfontconfig1 libdbus-1-3
   • To: libegl1 libgl1 libfontconfig1
   • Removed:
     • xvfb (virtual framebuffer, replaced by native EGL)
     • libglib2.0-0 (X11/GUI stack)
     • libxkbcommon-x11-0 (X11 keyboard)
     • libdbus-1-3 (D-Bus, X11-related)
   • Kept: libgl1 (OpenGL),libegl1 (EGL rendering),libfontconfig1 (font rendering for captions/colorbars)

5. CorpusCallosum/shape/mesh.py — Updated import and API call

   • Removed import OpenGL.GL pre-check (whippersnappy 2.0 manages its own GL context)
   • Changed: from whippersnappy.core import snap1 → from whippersnappy import snap1 (new top-level import)
   • Removed the except Exception handler about xvfb (no longer relevant with MESA)
   • Updated snap1() call:
     • Positional first arg → mesh=
     • overlaypath= → overlay= (new API parameter names)
     • viewmat= --> view= (API change)

6. CorpusCallosum/cc_visualization.py — Updated version references

   • Help text and warning messages: whippersnappy>=1.3.1 → whippersnappy>=2.1

7. CorpusCallosum/shape/postprocessing.py — Updated error messages

   • ImportError message: removed "glfw or OpenGL" (whippersnappy handles these internally)
   • Generic Exception message: replaced xvfb guidance with MESA/libmesa6 guidance

[ClePol]

I just remembered that some other files might also need version bumps besides pyproject.toml like mac requirements. I think the other files are auto-generated?
It would be great if you could pick up from here, since I'm not so familiar with the install / dockerization of FastSurfer.

[Copilot]

Pull request overview

This pull request upgrades the whippersnappy dependency from version 1.3 to 2.0, which introduces native EGL headless rendering capabilities. This eliminates the need for xvfb (virtual framebuffer) orchestration, simplifies the codebase, and reduces Docker image size by removing X11-related dependencies.

Changes:

• Upgraded whippersnappy version requirement from >=1.3.1 to >=2.0 across all dependency files
• Removed xvfb orchestration logic and replaced with whippersnappy version validation in run_fastsurfer.sh
• Refactored mesh snapshot generation to use whippersnappy 2.0's in-memory API instead of disk-based I/O
• Reduced Docker runtime dependencies by removing xvfb and X11-related libraries (libglib2.0-0, libxkbcommon-x11-0, libdbus-1-3)

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
pyproject.toml	Updated whippersnappy version constraint in qc optional dependencies
requirements.mac.txt	Updated whippersnappy version constraint for macOS builds
tools/Docker/Dockerfile	Removed X11 dependencies and renamed variable to reflect EGL-based rendering
run_fastsurfer.sh	Replaced xvfb orchestration with version validation logic, added error handling for version mismatches
CorpusCallosum/shape/mesh.py	Updated API to use whippersnappy 2.0's direct data passing, added version check, updated imports
CorpusCallosum/shape/postprocessing.py	Simplified mesh processing and updated error messages for EGL rendering
CorpusCallosum/cc_visualization.py	Updated version references and adapted to new API signature

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[m-reuter]

Note, in version 2.1 we will turn around again to using EGL. This is currently being tested in fsqc. My testing is complete. The reasons:

1. when logged in via ssh on a workstation with NVIDIA GPU, the missing DISPLAY would result in a fallback to osMesa which is usually not installed -> no rendering possible, even though EGL is installed and would work with GPU.
2. I realised that EGL also as CPU off screen rendering capabilities. This is now implemented. EGL is the more modern way to go and (opposed to osMesa) supports both GPU and CPU based rendering directly. Furthermore, it is more frequently already installed.

So here we need to update Docker to add only these three libraries for Whippersnappy:

    libegl1 \
    libgl1 \
    libfontconfig1 && \

Depending on the base image, one needs additional settings when enabling --gpus all for GPU support via EGL inside docker. See:

https://github.com/Deep-MI/WhipperSnapPy/blob/main/Dockerfile

But this is not necessary as it will fall back to EGL CPU based rendering. Singularity --nv works out of the box.

[dkuegler]

Note, in version 2.1 we will turn around again to using EGL. This is currently being tested in fsqc. My testing is complete. The reasons:

1. when logged in via ssh on a workstation with NVIDIA GPU, the missing DISPLAY would result in a fallback to osMesa which is usually not installed -> no rendering possible, even though EGL is installed and would work with GPU.

2. I realised that EGL also as CPU off screen rendering capabilities. This is now implemented. EGL is the more modern way to go and (opposed to osMesa) supports both GPU and CPU based rendering directly. Furthermore, it is more frequently already installed.

So here we need to update Docker to add only these three libraries for Whippersnappy:

    libegl1 \
    libgl1 \
    libfontconfig1 && \

Depending on the base image, one needs additional settings when enabling --gpus all for GPU support via EGL inside docker. See:

https://github.com/Deep-MI/WhipperSnapPy/blob/main/Dockerfile

But this is not necessary as it will fall back to EGL CPU based rendering. Singularity --nv works out of the box.

These is 1 thing that we currently do not have in FastSurfer:

• update of /usr/share/glvnd/egl_vendor.d/10_nvidia.json

[m-reuter]

These is 1 thing that we currently do not have in FastSurfer:

• update of /usr/share/glvnd/egl_vendor.d/10_nvidia.json

Without it, my Docker would not recognise the GPUs (am using python slim as base)