V2.0 rc

[m-reuter]

This is a major refactoring, backward compatibility is breaking !

On command line migrate to whippersnap4 and beware of different parameter names!
For direct snap1 callers see below.

Code Refactor

• core.py has been split up into meaningful modules, complete refactoring!
• snap1 and snap4 now always return the image (e.g. for visualisation in notebooks etc)
• logging was introduced instead of print
• errors are raised instead of sys.exit
• Qt6 optional, only needed for GUI, nowhere else
• bug fixes in the whippersnap CLI (and other places)
• consistent color overlay scale for snap4 across two semis when thresholds are not specifically provided
• added EGL support for completely headless without display (!! so cool!!)
• improved Docker for headless, no wrapper needed anymore
• refactor function parameter names and allow both strings for filenames and numpy arrays for direct passing
• functions (snap1, snap4, plot3d, CLI) now accept either file paths or numpy arrays for mesh, overlay, bg_map, roi, and annotation inputs.
• can pass a tuple of (vertices, faces) arrays directly instead of a mesh file path
• Mesh inputs now support OFF, VTK, PLY, GIfTI surface files, and FreeSurfer binary surfaces.
• Overlay inputs now support ASCII, NumPy, GIfTI, FreeSurfer morph, and MGH formats.
• Parameter renaming:
  -- curvpath/--curv → bg_map/--bg-map
  -- labelpath/--label → roi/--roi
  -- meshpath/--mesh-path → mesh/--mesh
  -- overlaypath/--overlaypath → overlay/--overlay
  -- annotpath/--annotpath → annot/--annot

Python Notebooks

• plot3d was added to provide webGL based interactive viewing in ipython notebooks
• added functionality to download and run an example

Command Line Interfaces

• added whippersnap1 CLI for plotting a single mesh with overlays
• added functionality to rotate in whippersnap1 and create a video (!cool!)
• separated existing CLI into GUI (whippersnap) and the snap4 in whippersnap4 (!!<- call this now!!)
• allow CLI whippersnap GUI and other snap1 functions to load any mesh, not only from freesurfer/fastsurfer dirs
• The CLI scripts (whippersnap.py, whippersnap1.py, whippersnap4.py) now use the new parameter names.
  Example: --bg-map replaces --curv, --roi replaces --label.
• CLI can now load any triangle mesh, not just FreeSurfer surfaces.

GUI

• add mouse navigation for rotate, zoom and pan to GUI
• add snapshot via "s" key to GUI
• make GUI work on Mac

Documentation

• docstrings are added
• added ipynb tutorial, running an example brain downloaded from assets
• updated documentation and sphinx doc build, including rendering of tutorial
• All code and docs are updated to use the new function and parameter names and input conventions.

[codecov]

Codecov Report

❌ Patch coverage is 43.04058% with 1109 lines in your changes missing coverage. Please review.
✅ Project coverage is 39.92%. Comparing base (8d83c2a) to head (e58777b).
⚠️ Report is 13 commits behind head on main.

Files with missing lines	Patch %	Lines
whippersnappy/cli/whippersnap.py	0.00%	224 Missing ⚠️
whippersnappy/snap.py	21.09%	180 Missing and 7 partials ⚠️
whippersnappy/utils/image.py	11.97%	145 Missing and 2 partials ⚠️
whippersnappy/cli/whippersnap4.py	0.00%	71 Missing ⚠️
whippersnappy/cli/whippersnap1.py	0.00%	69 Missing ⚠️
whippersnappy/geometry/mesh_io.py	70.99%	39 Missing and 28 partials ⚠️
whippersnappy/gl/utils.py	57.05%	62 Missing and 5 partials ⚠️
whippersnappy/_config.py	47.66%	50 Missing and 6 partials ⚠️
whippersnappy/gl/egl_context.py	74.57%	23 Missing and 22 partials ⚠️
whippersnappy/plot3d.py	6.97%	40 Missing ⚠️
... and 10 more

Additional details and impacted files

@@            Coverage Diff             @@
##            main      #57       +/-   ##
==========================================
+ Coverage   4.97%   39.92%   +34.95%     
==========================================
  Files          6       23       +17     
  Lines        885     2124     +1239     
  Branches     127      327      +200     
==========================================
+ Hits          44      848      +804     
- Misses       838     1175      +337     
- Partials       3      101       +98     

Flag	Coverage Δ
unittests	39.92% <43.04%> (+34.95%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

This PR is a v2.0 refactor of WhipperSnapPy that reorganizes the codebase into clearer subpackages (geometry/gl/utils), expands supported inputs (file paths + NumPy arrays, more mesh/overlay formats), and adds new notebook/CLI/documentation workflows, including headless EGL rendering.

Changes:

• Introduces new geometry IO/resolver pipeline (mesh/overlay readers + resolve_* + prepare_geometry*) and new GL package with EGL headless fallback.
• Adds notebook-focused functionality (plot3d, sample dataset fetch, tutorial notebook) plus new/updated CLIs (whippersnap1, whippersnap4).
• Updates packaging, docs, Docker, and CI (extras, Sphinx+nbsphinx, Ruff/pydocstyle, Python version matrix).

Reviewed changes

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

Show a summary per file

File	Description
whippersnappy/utils/types.py	Moves enums into utils with expanded docstrings.
whippersnappy/utils/image.py	Adds image/text helpers (colorbar creation, captions, bundled font loading).
whippersnappy/utils/datasets.py	Adds sample subject download/caching utility via GitHub release assets.
whippersnappy/utils/colormap.py	Refactors colormap helpers and overlay preprocessing with logging/errors.
whippersnappy/utils/_config.py	Removes old utils-level sys-info module (relocated to top-level).
whippersnappy/utils/init.py	Exposes utils submodules via __all__.
whippersnappy/types.py	Removes old top-level enums module (relocated to utils.types).
whippersnappy/plot3d.py	Adds pythreejs-based interactive 3D viewer for notebooks.
whippersnappy/gui/config_app.py	Updates GUI config window docstrings / cleans metadata comments.
whippersnappy/gui/init.py	Exports ConfigWindow from GUI subpackage.
whippersnappy/gl/views.py	Adds canonical view matrices/presets under new gl package.
whippersnappy/gl/utils.py	Adds core GL helpers (VAO/VBO, context creation with EGL fallback, capture, render).
whippersnappy/gl/shaders.py	Centralizes GLSL sources for desktop GL and WebGL/Three.js.
whippersnappy/gl/egl_context.py	Implements EGL pbuffer + FBO headless OpenGL context.
whippersnappy/gl/camera.py	Adds camera/projection/model/transform helpers.
whippersnappy/gl/_platform.py	Bootstraps PyOpenGL platform selection (EGL on headless Linux).
whippersnappy/gl/init.py	Re-exports GL helpers at package level.
whippersnappy/geometry/surf_name.py	Adds helper to detect surface basename in a subject directory.
whippersnappy/geometry/prepare.py	Introduces new geometry preparation pipeline (array-first + file wrapper).
whippersnappy/geometry/overlay_io.py	Adds overlay readers for TXT/CSV/NPY/NPZ/GIfTI + dispatcher.
whippersnappy/geometry/mesh_io.py	Adds mesh readers for OFF/VTK/PLY/GIfTI surface + dispatcher.
whippersnappy/geometry/inputs.py	Adds resolver layer (resolve_mesh/overlay/bg_map/roi/annot) and routing.
whippersnappy/geometry/freesurfer_io.py	Improves docs/structure around FreeSurfer binary IO (derived from nibabel).
whippersnappy/geometry/init.py	Defines geometry subpackage API and layered architecture docs.
whippersnappy/commands/sys_info.py	Expands sys-info command docstring and behavior delegation.
whippersnappy/cli/whippersnap4.py	Adds/updates 4-view batch CLI entrypoint around snap4.
whippersnappy/cli/whippersnap1.py	Adds single-mesh snapshot + rotation-video CLI around snap1/snap_rotate.
whippersnappy/_version.py	Adds fallback version when running from source tree (not installed).
whippersnappy/_config.py	Moves/extends sys-info helper to top-level and adds pyproject fallback parsing.
whippersnappy/init.py	Updates public API exports, headless GL env setup, and package docs.
tutorials/whippersnappy_tutorial.ipynb	Adds tutorial notebook demonstrating snap1/snap4/plot3d/snap_rotate.
tests/test_overlay_io.py	Adds tests for overlay IO + resolver routing behavior.
tests/test_mesh_io.py	Adds tests for mesh IO + resolve_mesh routing including GIfTI surfaces.
tests/test_config.py	Updates import path for sys-info helper test.
tests/test_array_inputs.py	Adds tests for array-input pathways through resolvers and geometry prep.
tests/data/tetra.off	Adds bundled OFF sample used by mesh IO tests.
pyproject.toml	Bumps version to 2.x, adjusts deps/extras, adds scripts, enables package data, updates tooling config.
doc/tutorials/whippersnappy_tutorial.ipynb	Adds docs stub linking to tutorial notebook.
doc/tutorials/index.rst	Adds Tutorials section and toctree entry.
doc/index.rst	Switches landing page to include README via MyST and adds new toctree entries.
doc/conf.py	Adds MyST + nbsphinx setup, mocking, excludes, and doc build adjustments.
doc/api/snap.rst	Adds API docs for whippersnappy.snap.
doc/api/plot3d.rst	Adds API docs for whippersnappy.plot3d.
doc/api/index.rst	Refactors API index structure into explicit toctree.
doc/api/cli.rst	Adds API docs for CLI modules.
doc/_templates/autosummary/function.rst	Removes minigallery directive from autosummary template.
doc/README.md	Adds docs stub linking to repo README.
doc/DOCKER.md	Adds docs stub linking to repo DOCKER guide.
README.md	Major rewrite reflecting v2 features, new CLIs, extras, and headless EGL support.
Dockerfile	Updates container to python-slim base, EGL libs, installs [video], defaults entrypoint to whippersnap4.
DOCKER.md	Adds detailed Docker usage guide for headless EGL workflows.
.github/workflows/pytest.yml	Updates Python matrix, installs EGL libs on Ubuntu, adjusts pytest invocation.
.github/workflows/doc.yml	Updates doc build (Python 3.13, deps, caching sample data, artifact upload tweaks).
.github/workflows/code-style.yml	Updates to Python 3.13, runs Ruff, codespell action, and enables pydocstyle.
.github/workflows/build.yml	Updates Python matrix and adds EGL libs install on Ubuntu.
.codespellignore	Removes standalone ignore file in favor of pyproject codespell config.

---

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

[Copilot]

Pull request overview

Copilot reviewed 60 out of 62 changed files in this pull request and generated no new comments.

---

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