prefer EGL over osMesa, add EGL surfaceless via llvmpipe and only EGL in docker with GPU or CPU

DOCKER.md

@@ -1,10 +1,15 @@
-# Docker Guide
+# Docker / Singularity Guide
 
-The Docker image provides a fully headless rendering environment.  By default
-it uses [OSMesa](https://docs.mesa3d.org/osmesa.html) (Mesa's CPU software
-renderer) — no display server, `xvfb`, or GPU required.  If a GPU render
-device is available, pass `--device /dev/dri/renderD128` to enable EGL GPU
-rendering instead; `libegl1` is already included in the image.
+The Docker image provides a fully headless rendering environment using
+**EGL** — no display server or `xvfb` required.
+
+- **CPU rendering (default):** EGL falls back to Mesa's llvmpipe software
+  renderer automatically.  No GPU or special flags needed.
+- **GPU rendering (NVIDIA):** 
+  - For **Docker**, pass `--gpus all` and EGL selects the
+    GPU via the NVIDIA Container Toolkit. 
+  - For **Singularity/Apptainer**, pass `--nv` (NVIDIA) enables GPU
+    rendering via EGL automatically.
 
 The default entry point is `whippersnap4` (four-view batch rendering).
 `whippersnap1` (single-view snapshot and rotation video) can be invoked by
@@ -42,6 +47,26 @@ docker run --rm --init \
   -o /output/snap4.png
 ```
 
+### With NVIDIA GPU (faster rendering)
+
+Pass `--gpus all` to let EGL use the GPU via the NVIDIA Container Toolkit:
+
+```bash
+docker run --rm --init \
+  --gpus all \
+  -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
+```
+
+> **Note:** Requires the [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html)
+> installed on the host (`nvidia-ctk --version` to verify).
+
 ### With an annotation file instead of an overlay
 
 ```bash
@@ -181,6 +206,37 @@ parent directory to retrieve them on the host.
 
 ---
 
+## Singularity / Apptainer
+
+The same image can be used with Singularity or Apptainer.
+
+**CPU rendering** (default — no GPU needed):
+```bash
+singularity exec \
+  -B /path/to/subject:/subject \
+  -B /path/to/output:/output \
+  whippersnappy.sif \
+  whippersnap4 \
+    -lh /subject/surf/lh.thickness \
+    -rh /subject/surf/rh.thickness \
+    -sd /subject -o /output/snap4.png
+```
+
+**GPU rendering** — pass `--nv` (NVIDIA) or `--rocm` (AMD); EGL selects
+the GPU automatically:
+```bash
+singularity exec --nv \
+  -B /path/to/subject:/subject \
+  -B /path/to/output:/output \
+  whippersnappy.sif \
+  whippersnap4 \
+    -lh /subject/surf/lh.thickness \
+    -rh /subject/surf/rh.thickness \
+    -sd /subject -o /output/snap4.png
+```
+
+---
+
 ## Notes
 
 - The `--init` flag is recommended so that signals (e.g. `Ctrl-C`) are handled
@@ -189,18 +245,22 @@ parent directory to retrieve them on the host.
   not root.
 - The interactive GUI (`whippersnap`) is **not** available in the Docker image —
   it requires a display server and PyQt6, which are not installed.
-- **Default rendering** uses **OSMesa** (Mesa's CPU software renderer, provided
-  by the `libosmesa6` system package). No GPU or `/dev/dri/` device needed.
-- **GPU rendering via EGL** works out of the box — `libegl1` is included in the
-  image.  Pass the render device into the container and WhipperSnapPy will
-  automatically prefer EGL over OSMesa when `/dev/dri/renderD*` is accessible:
-  ```bash
-  docker run --rm --init \
-    --device /dev/dri/renderD128 \
-    -v /path/to/subject:/subject \
-    -v /path/to/output:/output \
-    whippersnappy \
-    -lh /subject/surf/lh.thickness -rh /subject/surf/rh.thickness \
-    -sd /subject -o /output/snap4.png
+- **Docker CPU rendering** (default — no GPU needed): EGL uses Mesa's llvmpipe
+  software renderer.  The log will show:
+  ```
+  EGL context active — CPU software rendering (llvmpipe (...), ...)
+  ```
+- **Docker GPU rendering** (`--gpus all`, NVIDIA only): EGL uses the NVIDIA GPU
+  driver injected by the NVIDIA Container Toolkit.  The log will show:
+  ```
+  EGL context active — GPU rendering (...)
+  ```
+- **Singularity GPU rendering** with `--nv` uses EGL with the NVIDIA GPU
+  driver injected by Singularity.  The log will show:
   ```
+  EGL context active — GPU rendering (...)
+  ```
+
+
+
 

Dockerfile

@@ -1,20 +1,29 @@
 FROM python:3.11-slim
 
-# libosmesa6  — OSMesa CPU software renderer (default headless path, no GPU needed)
-# libegl1      — EGL dispatch library; enables GPU rendering when /dev/dri/renderD*
-#                is passed via --device (e.g. docker run --device /dev/dri/renderD128)
-# libgl1       — base OpenGL dispatch library required by PyOpenGL
-# libglib2.0-0, libfontconfig1, libdbus-1-3 — runtime deps for Pillow / font rendering
+# Suppress Mesa's shader-cache warning ("Failed to create //.cache …") that
+# appears when running as a non-standard user inside Docker where $HOME is
+# unset or points to a non-writable directory.
+ENV MESA_SHADER_CACHE_DISABLE=1
+
+# In order to find NVIDIA GPUs (--gpus all)
+ENV NVIDIA_VISIBLE_DEVICES=all
+ENV NVIDIA_DRIVER_CAPABILITIES=all
+
+# libegl1     — GLVND EGL dispatch library (routes to GPU or Mesa llvmpipe)
+# libgl1      — base OpenGL dispatch library required by PyOpenGL
+# libfontconfig1 — runtime deps for Pillow / font rendering
 RUN apt-get update && apt-get install -y --no-install-recommends \
-    libosmesa6 \
     libegl1 \
     libgl1 \
-    libglib2.0-0 \
-    libfontconfig1 \
-    libdbus-1-3 && \
+    libfontconfig1 && \
   apt-get clean && \
   rm -rf /var/lib/apt/lists/*
 
+# Register the NVIDIA EGL ICD so libEGL finds the GPU driver
+RUN mkdir -p /usr/share/glvnd/egl_vendor.d && \
+    echo '{"file_format_version":"1.0.0","ICD":{"library_path":"libEGL_nvidia.so.0"}}' \
+    > /usr/share/glvnd/egl_vendor.d/10_nvidia.json
+
 RUN pip install --upgrade pip
 
 COPY . /WhipperSnapPy

README.md

@@ -33,20 +33,23 @@ For interactive 3D in Jupyter notebooks:
 pip install 'whippersnappy[notebook]'
 ```
 
-Off-screen (headless) rendering on **Linux** uses a three-path fallback:
-1. **GLFW invisible window** — used when a display is available (`DISPLAY` set).
-2. **EGL** (GPU, no display needed) — used when no display is detected and a
-   GPU render device (`/dev/dri/renderD*`) is accessible with `libEGL` installed
-   (`libegl1` on Debian/Ubuntu).  This is the recommended path for SSH servers
-   with a GPU — no `DISPLAY`, `xvfb`, or OSMesa required.
-3. **OSMesa** (CPU software renderer) — final fallback; requires
-   `sudo apt-get install libosmesa6` (Debian/Ubuntu) or
-   `sudo dnf install mesa-libOSMesa` (RHEL/Fedora).
+Off-screen (headless) rendering on **Linux** uses **EGL** with Mesa's llvmpipe
+CPU software renderer — no GPU or display server required.  The log reports:
+```
+EGL context active — CPU software rendering (llvmpipe (...), ...)
+```
+When a GPU is accessible (native install, Docker with `--gpus all`, or
+Singularity with `--nv`), EGL selects it automatically:
+```
+EGL context active — GPU rendering (...)
+```
+OSMesa (`libosmesa6`) is a last-resort CPU fallback used only when EGL
+itself cannot initialise (e.g. `libegl1` not installed).
 
 On **Windows**, GLFW creates an invisible window; a GPU driver is sufficient.
 On **macOS**, a real display connection is required (NSGL does not support
 headless rendering).
-See the <a href="DOCKER.md">Docker guide</a> for headless Linux usage.
+See the <a href="DOCKER.md">Docker/Singularity guide</a> for container usage.
 
 ## Command-Line Usage
 
@@ -217,8 +220,8 @@ See `tutorials/whippersnappy_tutorial.ipynb` for complete notebook examples.
 
 ## Docker
 
-The Docker image provides a fully headless rendering environment using
-OSMesa (CPU software renderer) — no display server, `xvfb`, or GPU required.
+The Docker image provides a fully headless rendering environment using EGL —
+CPU software rendering by default, GPU rendering with `--gpus all` (NVIDIA).
 See <a href="DOCKER.md"><strong>DOCKER.md</strong></a> for details.
 
 ## API Documentation

whippersnappy/cli/whippersnap.py

@@ -720,22 +720,21 @@ def run():
     # ------------------------------------------------------------------
     if QApplication is None:
         print(
-            "ERROR: Interactive mode requires PyQt6. "
+            "Error: Interactive mode requires PyQt6. "
             "Install with: pip install 'whippersnappy[gui]'",
             file=sys.stderr,
         )
-        raise RuntimeError(
-            "Interactive mode requires PyQt6. "
-            "Install with: pip install 'whippersnappy[gui]'"
-        )
+        sys.exit(1)
 
     try:
         from ..gui import ConfigWindow  # noqa: PLC0415
     except ModuleNotFoundError as e:
-        raise RuntimeError(
-            "Interactive mode requires PyQt6. "
-            "Install with: pip install 'whippersnappy[gui]'"
-        ) from e
+        print(
+            f"Error: Interactive mode requires PyQt6 ({e}). "
+            "Install with: pip install 'whippersnappy[gui]'",
+            file=sys.stderr,
+        )
+        sys.exit(1)
 
     current_fthresh_ = args.fthresh
     current_fmax_    = args.fmax
@@ -756,18 +755,22 @@ def run():
 
     # show_window creates the GLFW window, sets up a QTimer render loop,
     # then calls app.exec() — returns when either window is closed.
-    show_window(
-        mesh=mesh_path,
-        overlay=overlay,
-        annot=args.annot,
-        bg_map=bg_map,
-        roi=roi,
-        invert=args.invert,
-        specular=args.specular,
-        view=view,
-        app=app,
-        config_window=config_window,
-    )
+    try:
+        show_window(
+            mesh=mesh_path,
+            overlay=overlay,
+            annot=args.annot,
+            bg_map=bg_map,
+            roi=roi,
+            invert=args.invert,
+            specular=args.specular,
+            view=view,
+            app=app,
+            config_window=config_window,
+        )
+    except (RuntimeError, FileNotFoundError) as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
 
 
 if __name__ == "__main__":

whippersnappy/cli/whippersnap1.py

@@ -43,12 +43,12 @@
 import argparse
 import logging
 import os
+import sys
 import tempfile
 
 import numpy as np
 
 if __name__ == "__main__" and __package__ is None:
-    import sys
     os.execv(sys.executable, [sys.executable, "-m", "whippersnappy.cli.whippersnap1"] + sys.argv[1:])
 
 from .. import snap1, snap_rotate
@@ -309,8 +309,11 @@ def run():
                 ambient=args.ambient,
             )
             log.info("Snapshot saved to %s (%dx%d)", outpath, img.width, img.height)
-    except (RuntimeError, FileNotFoundError, ValueError, ImportError) as e:
+    except ValueError as e:
         parser.error(str(e))
+    except (RuntimeError, FileNotFoundError, ImportError) as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
 
 
 if __name__ == "__main__":

whippersnappy/cli/whippersnap4.py

@@ -16,12 +16,12 @@
 import argparse
 import logging
 import os
+import sys
 import tempfile
 
 import numpy as np
 
 if __name__ == "__main__" and __package__ is None:
-    import sys
     os.execv(sys.executable, [sys.executable, "-m", "whippersnappy.cli.whippersnap4"] + sys.argv[1:])
 
 from .. import snap4
@@ -210,8 +210,11 @@ def run():
         logger.info(
             "Snapshot saved to %s (%dx%d)", args.output_path, img.width, img.height
         )
-    except (RuntimeError, FileNotFoundError, ValueError) as e:
+    except ValueError as e:
         parser.error(str(e))
+    except (RuntimeError, FileNotFoundError) as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
 
 
 if __name__ == "__main__":