neuroviewer 0.1.0__tar.gz

neuroviewer-0.1.0/.gitignore

@@ -0,0 +1,37 @@
+# Python
+__pycache__/
+*.py[cod]
+*.so
+
+# Build / packaging
+build/
+dist/
+*.egg-info/
+.eggs/
+*.whl
+*.tar.gz
+
+# AppImage build
+packaging/appimage/build/
+*.AppImage
+appimagetool*
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# IDE
+.vscode/
+.idea/
+.spyproject/
+*.swp
+
+# Screenshots saved while testing
+neuroviewer_*.png
+.ruff_cache/

neuroviewer-0.1.0/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
+[Semantic Versioning](https://semver.org/).
+
+## [0.1.0] - 2026-10-15
+
+First public release.
+
+### Added
+- Desktop viewer (PySide6 + vedo/VTK) with one main view and three side views
+  (layouts 1+3, 2x2, 1x1); click a panel title or Ctrl+1..4 to swap.
+- File panel with a filtered folder tree and recursive name search.
+- Volumes: NIfTI, MGH/MGZ, Analyze, MINC, PAR/REC, reoriented to RAS+ with
+  their full affine; layers with colormap, window, opacity, threshold and
+  4D frame; FreeSurfer LUT colours for label maps.
+- 3D scene: slices, bounding box, volume rendering, FreeSurfer/GIfTI surfaces
+  (shifted to scanner RAS) and .trk/.tck streamlines.
+- Tools registry: isosurface, label surfaces, cortex and threshold point
+  clouds, point cloud from a surface, Open3D downsampling and Poisson
+  reconstruction (optional extra).
+- Time course of 4D layers at the cursor; cursor readout with label names.
+- `neuroviewer` command with `--write-config`, `--config-path`,
+  `--install-desktop` and `--version`; user config file that overrides the
+  packaged defaults.

neuroviewer-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rodrigo Debona
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

neuroviewer-0.1.0/PKG-INFO

@@ -0,0 +1,197 @@
+Metadata-Version: 2.5
+Name: neuroviewer
+Version: 0.1.0
+Summary: Freeview-like neuroimaging viewer in pure Python (PySide6 + vedo/VTK + nibabel)
+Project-URL: Homepage, https://github.com/rdneuro/neuroviewer
+Project-URL: Repository, https://github.com/rdneuro/neuroviewer
+Project-URL: Issues, https://github.com/rdneuro/neuroviewer/issues
+Project-URL: Changelog, https://github.com/rdneuro/neuroviewer/blob/main/CHANGELOG.md
+Author-email: Rodrigo Debona <r.debona@ufrj.br>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: brain,freesurfer,medical-imaging,mri,neuroimaging,nifti,tractography,vedo,viewer,vtk
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: X11 Applications :: Qt
+Classifier: Intended Audience :: Healthcare Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+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: Topic :: Scientific/Engineering :: Medical Science Apps.
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.9
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: nibabel>=5.0
+Requires-Dist: numpy>=1.24
+Requires-Dist: pyside6-essentials>=6.5
+Requires-Dist: vedo>=2024.5
+Requires-Dist: vtk>=9.2
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: twine>=5; extra == 'dev'
+Provides-Extra: open3d
+Requires-Dist: open3d>=0.17; extra == 'open3d'
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == 'test'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/rdneuro/neuroviewer/main/src/neuroviewer/resources/neuroviewer.png" width="128" alt="Neuroviewer icon">
+</p>
+
+<h1 align="center">Neuroviewer</h1>
+
+<p align="center">
+A freeview-like neuroimaging viewer written in pure Python.<br>
+PySide6 interface, vedo/VTK rendering, nibabel reading. Native desktop app, no browser, no server.
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/neuroviewer/"><img src="https://img.shields.io/pypi/v/neuroviewer.svg" alt="PyPI"></a>
+  <a href="https://pypi.org/project/neuroviewer/"><img src="https://img.shields.io/pypi/pyversions/neuroviewer.svg" alt="Python versions"></a>
+  <a href="https://github.com/rdneuro/neuroviewer/actions/workflows/tests.yml"><img src="https://github.com/rdneuro/neuroviewer/actions/workflows/tests.yml/badge.svg" alt="Tests"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT license"></a>
+</p>
+
+<!--
+Screenshot: save one with the toolbar "Screenshot" button (real T1 + aseg,
+1+3 layout) as docs/screenshot.png, commit it, then uncomment:
+<p align="center"><img src="https://raw.githubusercontent.com/rdneuro/neuroviewer/main/docs/screenshot.png" width="900" alt="Neuroviewer"></p>
+-->
+
+## Install
+
+```bash
+pip install neuroviewer              # core viewer
+pip install "neuroviewer[open3d]"    # + Open3D point-cloud tools
+```
+
+Then:
+
+```bash
+neuroviewer                          # empty window
+neuroviewer T1.mgz aseg.mgz lh.pial  # open files at start
+python -m neuroviewer                # same thing
+neuroviewer --install-desktop        # Linux: add a menu entry with icon
+```
+
+Requirements: Python 3.9+, an OpenGL-capable display. On Linux, Qt 6.5+
+needs `libxcb-cursor0` (`sudo apt install libxcb-cursor0`). A self-contained
+Linux AppImage is attached to each GitHub release.
+
+## What it does
+
+- **Files** (left): folder tree filtered to neuroimaging files, plus a
+  recursive search under the root folder (name filter such as `aseg`,
+  `*T1*.nii.gz`; blank = everything). Double click opens a file.
+- **Views** (centre): one main view and three side views (layout `1+3`,
+  `2x2` or `1x1`). Click a panel title, a toolbar button or `Ctrl+1..4` to put
+  3D / sagittal / coronal / axial in the main position.
+- **Layers** (right): one entry per volume, top of the list drawn on top.
+  Colormap, window min/max, opacity, "transparent below min", frame (4D).
+- **3D scene** (right, second tab): slices / bounding box / volume rendering
+  toggles, the **Tools** menu and the list of 3D objects (surfaces,
+  streamlines, isosurfaces, point clouds) with visibility, colour, opacity.
+- **Time course** (bottom): signal of the active 4D layer at the cursor.
+- **Status bar**: cursor in RAS mm, voxel index and value of every visible
+  layer (with the FreeSurfer label name for label maps).
+
+### Mouse and keys
+
+| where | action |
+|---|---|
+| 2D | left click / drag: move cursor; shift+left or middle drag: pan; right drag or wheel: zoom |
+| 2D | Up / PageUp, Down / PageDown: next / previous slice; `r`: fit slice |
+| 3D | left drag: rotate; middle: pan; right / wheel: zoom; **double click** on a slice or surface: move cursor; `r`: reset camera |
+
+### Formats
+
+- Volumes: `.nii`, `.nii.gz`, `.mgz`, `.mgh`, Analyze `.img/.hdr`, MINC `.mnc`, PAR/REC.
+- Surfaces: FreeSurfer `lh.pial`, `rh.white`, ... (shifted to scanner RAS with
+  `c_ras`) and GIfTI `.surf.gii`.
+- Streamlines: `.trk`, `.tck` (direction-coloured, subsampled to
+  `TRACT_MAX_STREAMLINES`).
+
+### Coordinates
+
+Everything is kept in world coordinates (scanner RAS, mm). Volumes are
+reoriented to RAS+ voxel order on load (FreeSurfer conformed `.mgz` is LIA on
+disk) and keep their full affine. The first loaded volume defines the display
+grid; every other layer is sampled onto it through its own affine, so layers
+with different resolutions or fields of view overlay correctly. Oblique
+volumes are resampled for display.
+
+Label maps are detected by file name (`aseg`, `aparc`, `ribbon`, ...) plus
+integer values. Their colours come from `$FREESURFER_HOME/FreeSurferColorLUT.txt`
+(or `FREESURFER_LUT_PATH` in the config), with generated colours as fallback.
+
+## Configuration
+
+The packaged defaults live in `neuroviewer/config.py`. Do not edit that copy;
+create your own once and edit it:
+
+```bash
+neuroviewer --write-config   # writes ~/.config/neuroviewer/config.py (Linux/macOS)
+neuroviewer --config-path    # shows where it is (%APPDATA%\neuroviewer on Windows)
+```
+
+It is plain Python with the same names (radiological convention, colours,
+layout, label hints, point-cloud size, Open3D parameters, screenshot scale,
+...). Keep only the lines you change. Set `NEUROVIEWER_CONFIG` to use another
+file. An existing file is never overwritten unless you pass `--force`.
+
+## Tools (extension point)
+
+`neuroviewer/tools.py` holds a registry. A tool is one function that receives
+a context (layers, active layer, cursor, grid, dialogs) and returns 3D objects:
+
+```python
+from neuroviewer.tools import register_tool
+
+@register_tool("My tool", "What it does.")
+def my_tool(ctx):
+    layer = ctx.require_active()
+    arr, origin, spacing = ctx.aligned(layer)
+    ...
+    return [("result name", vedo_object, "mesh")]
+```
+
+Built-in tools: isosurface, label surfaces (e.g. `17 53`), cortex point cloud
+from FreeSurfer labels, threshold point cloud, point cloud from the last
+surface, Open3D voxel downsampling and Open3D Poisson reconstruction. Open3D
+is optional; it is used as a compute engine and the result is shown in vedo.
+
+## Troubleshooting
+
+- **`Could not find the Qt platform plugin "xcb"`**: another Qt install is
+  exporting its own plugin path (Spyder/PyQt5, opencv-python, conda qt).
+  Neuroviewer resets it to the PySide6 plugins and prints the folder it used
+  (`[qt] ...`). Start it from a terminal, not from the Spyder/IPython console.
+  If it still fails, run `QT_DEBUG_PLUGINS=1 neuroviewer`.
+- **Black views on Wayland**: `QT_QPA_PLATFORM=xcb neuroviewer`.
+- **Missing `libxcb-cursor0`** (Qt 6.5+ on Linux): install it with your
+  package manager.
+
+## Development
+
+```bash
+git clone https://github.com/rdneuro/neuroviewer.git
+cd neuroviewer
+pip install -e ".[dev]"
+pytest
+```
+
+See [RELEASING.md](RELEASING.md) for the PyPI and AppImage release steps.
+
+## License
+
+MIT. See [LICENSE](LICENSE). Neuroviewer depends on PySide6 (LGPLv3), VTK
+(BSD), vedo (MIT), nibabel (MIT) and matplotlib (PSF-based); the AppImage
+redistributes them under their own licenses.

neuroviewer-0.1.0/README.md

@@ -0,0 +1,153 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/rdneuro/neuroviewer/main/src/neuroviewer/resources/neuroviewer.png" width="128" alt="Neuroviewer icon">
+</p>
+
+<h1 align="center">Neuroviewer</h1>
+
+<p align="center">
+A freeview-like neuroimaging viewer written in pure Python.<br>
+PySide6 interface, vedo/VTK rendering, nibabel reading. Native desktop app, no browser, no server.
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/neuroviewer/"><img src="https://img.shields.io/pypi/v/neuroviewer.svg" alt="PyPI"></a>
+  <a href="https://pypi.org/project/neuroviewer/"><img src="https://img.shields.io/pypi/pyversions/neuroviewer.svg" alt="Python versions"></a>
+  <a href="https://github.com/rdneuro/neuroviewer/actions/workflows/tests.yml"><img src="https://github.com/rdneuro/neuroviewer/actions/workflows/tests.yml/badge.svg" alt="Tests"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT license"></a>
+</p>
+
+<!--
+Screenshot: save one with the toolbar "Screenshot" button (real T1 + aseg,
+1+3 layout) as docs/screenshot.png, commit it, then uncomment:
+<p align="center"><img src="https://raw.githubusercontent.com/rdneuro/neuroviewer/main/docs/screenshot.png" width="900" alt="Neuroviewer"></p>
+-->
+
+## Install
+
+```bash
+pip install neuroviewer              # core viewer
+pip install "neuroviewer[open3d]"    # + Open3D point-cloud tools
+```
+
+Then:
+
+```bash
+neuroviewer                          # empty window
+neuroviewer T1.mgz aseg.mgz lh.pial  # open files at start
+python -m neuroviewer                # same thing
+neuroviewer --install-desktop        # Linux: add a menu entry with icon
+```
+
+Requirements: Python 3.9+, an OpenGL-capable display. On Linux, Qt 6.5+
+needs `libxcb-cursor0` (`sudo apt install libxcb-cursor0`). A self-contained
+Linux AppImage is attached to each GitHub release.
+
+## What it does
+
+- **Files** (left): folder tree filtered to neuroimaging files, plus a
+  recursive search under the root folder (name filter such as `aseg`,
+  `*T1*.nii.gz`; blank = everything). Double click opens a file.
+- **Views** (centre): one main view and three side views (layout `1+3`,
+  `2x2` or `1x1`). Click a panel title, a toolbar button or `Ctrl+1..4` to put
+  3D / sagittal / coronal / axial in the main position.
+- **Layers** (right): one entry per volume, top of the list drawn on top.
+  Colormap, window min/max, opacity, "transparent below min", frame (4D).
+- **3D scene** (right, second tab): slices / bounding box / volume rendering
+  toggles, the **Tools** menu and the list of 3D objects (surfaces,
+  streamlines, isosurfaces, point clouds) with visibility, colour, opacity.
+- **Time course** (bottom): signal of the active 4D layer at the cursor.
+- **Status bar**: cursor in RAS mm, voxel index and value of every visible
+  layer (with the FreeSurfer label name for label maps).
+
+### Mouse and keys
+
+| where | action |
+|---|---|
+| 2D | left click / drag: move cursor; shift+left or middle drag: pan; right drag or wheel: zoom |
+| 2D | Up / PageUp, Down / PageDown: next / previous slice; `r`: fit slice |
+| 3D | left drag: rotate; middle: pan; right / wheel: zoom; **double click** on a slice or surface: move cursor; `r`: reset camera |
+
+### Formats
+
+- Volumes: `.nii`, `.nii.gz`, `.mgz`, `.mgh`, Analyze `.img/.hdr`, MINC `.mnc`, PAR/REC.
+- Surfaces: FreeSurfer `lh.pial`, `rh.white`, ... (shifted to scanner RAS with
+  `c_ras`) and GIfTI `.surf.gii`.
+- Streamlines: `.trk`, `.tck` (direction-coloured, subsampled to
+  `TRACT_MAX_STREAMLINES`).
+
+### Coordinates
+
+Everything is kept in world coordinates (scanner RAS, mm). Volumes are
+reoriented to RAS+ voxel order on load (FreeSurfer conformed `.mgz` is LIA on
+disk) and keep their full affine. The first loaded volume defines the display
+grid; every other layer is sampled onto it through its own affine, so layers
+with different resolutions or fields of view overlay correctly. Oblique
+volumes are resampled for display.
+
+Label maps are detected by file name (`aseg`, `aparc`, `ribbon`, ...) plus
+integer values. Their colours come from `$FREESURFER_HOME/FreeSurferColorLUT.txt`
+(or `FREESURFER_LUT_PATH` in the config), with generated colours as fallback.
+
+## Configuration
+
+The packaged defaults live in `neuroviewer/config.py`. Do not edit that copy;
+create your own once and edit it:
+
+```bash
+neuroviewer --write-config   # writes ~/.config/neuroviewer/config.py (Linux/macOS)
+neuroviewer --config-path    # shows where it is (%APPDATA%\neuroviewer on Windows)
+```
+
+It is plain Python with the same names (radiological convention, colours,
+layout, label hints, point-cloud size, Open3D parameters, screenshot scale,
+...). Keep only the lines you change. Set `NEUROVIEWER_CONFIG` to use another
+file. An existing file is never overwritten unless you pass `--force`.
+
+## Tools (extension point)
+
+`neuroviewer/tools.py` holds a registry. A tool is one function that receives
+a context (layers, active layer, cursor, grid, dialogs) and returns 3D objects:
+
+```python
+from neuroviewer.tools import register_tool
+
+@register_tool("My tool", "What it does.")
+def my_tool(ctx):
+    layer = ctx.require_active()
+    arr, origin, spacing = ctx.aligned(layer)
+    ...
+    return [("result name", vedo_object, "mesh")]
+```
+
+Built-in tools: isosurface, label surfaces (e.g. `17 53`), cortex point cloud
+from FreeSurfer labels, threshold point cloud, point cloud from the last
+surface, Open3D voxel downsampling and Open3D Poisson reconstruction. Open3D
+is optional; it is used as a compute engine and the result is shown in vedo.
+
+## Troubleshooting
+
+- **`Could not find the Qt platform plugin "xcb"`**: another Qt install is
+  exporting its own plugin path (Spyder/PyQt5, opencv-python, conda qt).
+  Neuroviewer resets it to the PySide6 plugins and prints the folder it used
+  (`[qt] ...`). Start it from a terminal, not from the Spyder/IPython console.
+  If it still fails, run `QT_DEBUG_PLUGINS=1 neuroviewer`.
+- **Black views on Wayland**: `QT_QPA_PLATFORM=xcb neuroviewer`.
+- **Missing `libxcb-cursor0`** (Qt 6.5+ on Linux): install it with your
+  package manager.
+
+## Development
+
+```bash
+git clone https://github.com/rdneuro/neuroviewer.git
+cd neuroviewer
+pip install -e ".[dev]"
+pytest
+```
+
+See [RELEASING.md](RELEASING.md) for the PyPI and AppImage release steps.
+
+## License
+
+MIT. See [LICENSE](LICENSE). Neuroviewer depends on PySide6 (LGPLv3), VTK
+(BSD), vedo (MIT), nibabel (MIT) and matplotlib (PSF-based); the AppImage
+redistributes them under their own licenses.

neuroviewer-0.1.0/RELEASING.md

@@ -0,0 +1,45 @@
+# Releasing
+
+## One-time setup
+
+1. **Create the GitHub repository** `rdneuro/neuroviewer` and push `main`.
+2. **Reserve the PyPI name with trusted publishing** (no API token needed):
+   on <https://pypi.org/manage/account/publishing/>, add a *pending
+   publisher* with
+   - PyPI project name: `neuroviewer`
+   - Owner: `rdneuro`, Repository: `neuroviewer`
+   - Workflow name: `release.yml`
+   - Environment name: `pypi`
+3. On GitHub, *Settings > Environments*, create an environment called `pypi`
+   (optionally require your approval before each upload).
+
+## Every release
+
+1. Bump `__version__` in `src/neuroviewer/__init__.py`.
+2. Add the section to `CHANGELOG.md`.
+3. Check locally:
+   ```bash
+   pip install -e ".[dev]"
+   pytest
+   python -m build && twine check --strict dist/*
+   ```
+4. Commit, tag and push:
+   ```bash
+   git commit -am "Release 0.1.1"
+   git tag v0.1.1
+   git push origin main --tags
+   ```
+5. The `Release` workflow checks that the tag matches `__version__`,
+   publishes the wheel and sdist to PyPI and attaches
+   `Neuroviewer-<version>-x86_64.AppImage` to the GitHub release.
+
+## Manual upload (fallback)
+
+```bash
+python -m build
+twine upload --repository testpypi dist/*   # optional dry run on TestPyPI
+twine upload dist/*
+```
+
+PyPI never accepts the same version twice, so a broken upload needs a new
+version number (for example 0.1.1), not a re-upload.

neuroviewer-0.1.0/packaging/appimage/README.md

@@ -0,0 +1,28 @@
+# AppImage
+
+A single-file Linux build that bundles its own Python and every dependency.
+Users download it, `chmod +x`, and run it; nothing is installed.
+
+```bash
+bash packaging/appimage/build_appimage.sh          # from this source tree
+bash packaging/appimage/build_appimage.sh --pypi   # from the PyPI release
+PY_VERSION=3.11 bash packaging/appimage/build_appimage.sh
+```
+
+How it works: [python-appimage](https://github.com/niess/python-appimage)
+downloads a relocatable manylinux Python AppImage, `pip install`s the
+Neuroviewer wheel into it (PySide6-Essentials, VTK, vedo, nibabel, numpy,
+matplotlib come along as binary wheels), and the script adds the small X11
+libraries Qt 6.5+ needs (`libxcb-cursor` and three helpers) before packing
+with appimagetool.
+
+Notes:
+
+- The GitHub workflow `.github/workflows/release.yml` builds it on Ubuntu
+  22.04 for every `v*` tag and attaches it to the GitHub release.
+- Target machines need glibc 2.28 or newer (Ubuntu 20.04+, Debian 10+,
+  RHEL/Rocky 8+) and a working OpenGL driver. The driver always comes from the
+  host; it is never bundled.
+- Running an AppImage needs FUSE 2 (`libfuse2` / `libfuse2t64` on Ubuntu).
+  Without it: `./Neuroviewer-*.AppImage --appimage-extract-and-run`.
+- Expected size: roughly 200-300 MB (VTK and Qt are most of it).

neuroviewer-0.1.0/packaging/appimage/build_appimage.sh

@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+# Build Neuroviewer-<version>-x86_64.AppImage with python-appimage.
+#
+#   bash packaging/appimage/build_appimage.sh            # from the local source tree
+#   bash packaging/appimage/build_appimage.sh --pypi     # from the published PyPI release
+#
+# Environment:
+#   PY_VERSION   Python inside the AppImage (default 3.12)
+#
+# Needs: python3 with pip, internet access (GitHub for the python-appimage base
+# image and appimagetool, PyPI for the wheels). Build on the OLDEST distro you
+# want to support (e.g. Ubuntu 22.04): the bundled X11 fallback libraries are
+# copied from the build machine. The result needs glibc >= 2.28 on the target
+# (PySide6 wheels are manylinux_2_28) and the host's OpenGL driver.
+set -euo pipefail
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "${HERE}/../.." && pwd)"
+PY_VERSION="${PY_VERSION:-3.12}"
+FROM_PYPI=0
+[[ "${1:-}" == "--pypi" ]] && FROM_PYPI=1
+
+VERSION="$(sed -n 's/^__version__ = "\(.*\)"/\1/p' "${ROOT}/src/neuroviewer/__init__.py")"
+BUILD="${HERE}/build"
+RECIPE="${BUILD}/neuroviewer"
+echo "[appimage] Neuroviewer ${VERSION} | Python ${PY_VERSION} | source: $([[ ${FROM_PYPI} == 1 ]] && echo PyPI || echo local tree)"
+
+rm -rf "${BUILD}"
+mkdir -p "${RECIPE}"
+
+python3 -m pip install --quiet --upgrade "python-appimage>=1.4" build
+
+# ------------------------------------------------------------------ recipe
+if [[ ${FROM_PYPI} == 1 ]]; then
+    echo "neuroviewer==${VERSION}" > "${RECIPE}/requirements.txt"
+else
+    python3 -m build --wheel --outdir "${BUILD}/dist" "${ROOT}"
+    WHEEL="$(ls "${BUILD}"/dist/neuroviewer-"${VERSION}"-*.whl)"
+    echo "${WHEEL}" > "${RECIPE}/requirements.txt"
+fi
+cp "${HERE}/entrypoint.sh" "${RECIPE}/entrypoint.sh"
+cp "${ROOT}/src/neuroviewer/resources/neuroviewer.desktop" "${RECIPE}/neuroviewer.desktop"
+cp "${ROOT}/src/neuroviewer/resources/neuroviewer.png" "${RECIPE}/neuroviewer.png"
+sed -e "s/@VERSION@/${VERSION}/" -e "s/@DATE@/$(date +%Y-%m-%d)/" \
+    "${HERE}/neuroviewer.appdata.xml" > "${RECIPE}/neuroviewer.appdata.xml"
+
+# ------------------------------------------------------------------ AppDir
+cd "${BUILD}"
+python3 -m python_appimage build app --no-packaging -p "${PY_VERSION}" "${RECIPE}"
+APPDIR="${BUILD}/Neuroviewer-$(uname -m)"
+[[ -d "${APPDIR}" ]] || { echo "[appimage] AppDir not found: ${APPDIR}"; exit 1; }
+
+# X11 fallback libraries for Qt >= 6.5 (often missing on minimal installs).
+EXTRA="${APPDIR}/usr/lib/neuroviewer-extra"
+mkdir -p "${EXTRA}"
+for lib in libxcb-cursor.so.0 libxcb-image.so.0 libxcb-render-util.so.0 libxcb-util.so.1; do
+    src="$(ldconfig -p | awk -v l="${lib}" '$1 == l && tolower($0) ~ /x86-64|aarch64/ {print $NF; exit}')"
+    if [[ -n "${src}" ]]; then
+        cp -L "${src}" "${EXTRA}/"
+        echo "[appimage] bundled ${lib}"
+    else
+        echo "[appimage] WARNING: ${lib} not found on the build machine (apt install libxcb-cursor0); not bundled"
+    fi
+done
+
+# Trim what a viewer never needs (tests, caches, Qt translations stay).
+find "${APPDIR}/opt" -type d -name "__pycache__" -prune -exec rm -rf {} +
+find "${APPDIR}/opt" -type d \( -name "tests" -o -name "test" \) -path "*site-packages/*" -prune -exec rm -rf {} + || true
+
+# ------------------------------------------------------------------ pack
+OUT="Neuroviewer-${VERSION}-$(uname -m).AppImage"
+python3 - "${APPDIR}" "${OUT}" <<'EOF'
+import sys
+from python_appimage.appimage import build_appimage
+build_appimage(sys.argv[1], destination=sys.argv[2])
+EOF
+mv "${OUT}" "${ROOT}/${OUT}"
+chmod +x "${ROOT}/${OUT}"
+echo "[appimage] done: ${ROOT}/${OUT} ($(du -h "${ROOT}/${OUT}" | cut -f1))"

neuroviewer-0.1.0/packaging/appimage/entrypoint.sh

@@ -0,0 +1,8 @@
+#! /bin/bash
+# AppImage entry point (python-appimage template; {{ ... }} is filled at build time).
+# The fallback libraries (libxcb-cursor and friends, needed by Qt >= 6.5 on X11)
+# go first in the search path only for this process; -I isolates the bundled
+# Python from the user's site-packages and PYTHONPATH (no clash with a Spyder
+# or conda Qt installation).
+export LD_LIBRARY_PATH="${APPDIR}/usr/lib/neuroviewer-extra${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}"
+{{ python-executable }} -I -m neuroviewer "$@"

neuroviewer-0.1.0/packaging/appimage/neuroviewer.appdata.xml

@@ -0,0 +1,34 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<component type="desktop-application">
+  <id>io.github.rdneuro.neuroviewer</id>
+  <metadata_license>CC0-1.0</metadata_license>
+  <project_license>MIT</project_license>
+  <name>Neuroviewer</name>
+  <summary>Freeview-like neuroimaging viewer in pure Python</summary>
+  <description>
+    <p>
+      Neuroviewer opens NIfTI, MGH/MGZ, Analyze, MINC and PAR/REC volumes,
+      FreeSurfer and GIfTI surfaces and .trk/.tck streamlines, with a main 3D
+      view and sagittal, coronal and axial views that swap on click.
+    </p>
+    <p>
+      Layers keep their full affine in scanner RAS coordinates, label maps use
+      the FreeSurfer colour table, and a tools menu builds isosurfaces, label
+      surfaces and point clouds.
+    </p>
+  </description>
+  <launchable type="desktop-id">neuroviewer.desktop</launchable>
+  <url type="homepage">https://github.com/rdneuro/neuroviewer</url>
+  <url type="bugtracker">https://github.com/rdneuro/neuroviewer/issues</url>
+  <developer id="io.github.rdneuro">
+    <name>Rodrigo Debona</name>
+  </developer>
+  <categories>
+    <category>Science</category>
+    <category>MedicalSoftware</category>
+  </categories>
+  <content_rating type="oars-1.1"/>
+  <releases>
+    <release version="@VERSION@" date="@DATE@"/>
+  </releases>
+</component>