3.1.0 update

.clang-format

@@ -0,0 +1,6 @@
+Language: Cpp
+BasedOnStyle: LLVM
+BinPackArguments: false
+BinPackParameters: false
+PackConstructorInitializers: NextLine
+ColumnLimit: 120

.git-blame-ignore-revs

@@ -97,3 +97,8 @@ aad44d847ac48d02bb7f8badf801dbfaa0ccdac0
 #Author: MRtrixBot <[email protected]>
 #Date:   Tue Jan 3 13:42:58 2023 +0100
 #    Update Copyright notice in command docs
+
+45fc06bdf687584bf4d55140720e84c5ef517bf0
+#Author: MRtrixBot <[email protected]>
+#Date:   Thu, 17 Aug 2023 15:36:14 +0100
+#    Apply formatting for C++ using clang-format

.github/workflows/checks.yml

@@ -20,14 +20,20 @@ jobs:
     env:
       CFLAGS: -Werror
       QT_SELECT: qt5
+      SCCACHE_GHA_ENABLED: "true"
+      SCCACHE_CACHE_SIZE: "2G"
+      CXX_COMPILER_LAUNCHER: sccache
 
     steps:
     - uses: actions/checkout@v1
 
     - name: install dependencies
       run: |
          sudo apt-get update
-         sudo apt-get install clang libqt5opengl5-dev libqt5svg5-dev libglvnd-dev libeigen3-dev zlib1g-dev libfftw3-dev 
+         sudo apt-get install clang libqt5opengl5-dev libqt5svg5-dev libglvnd-dev libeigen3-dev zlib1g-dev libfftw3-dev python3-numpy
+
+    - name: Run sccache-cache
+      uses: mozilla-actions/[email protected]
 
     - name: configure
       run: ./configure -assert || { cat configure.log; false; }
@@ -36,10 +42,10 @@ jobs:
       run: ./build -nowarnings -persistent -nopaginate || { cat build.log; false; }
 
     - name: unit tests
-      run: ./run_tests units || { cat testing_units.log; false; }
+      run: ./run_tests units || { cat testing/log/units.log; false; }
 
     - name: binary tests
-      run: ./run_tests binaries || { cat testing_binaries.log; false; }
+      run: ./run_tests binaries || { cat testing/log/binaries.log; false; }
 
 
 
@@ -54,14 +60,20 @@ jobs:
       CXX: g++-9
       CFLAGS: -Werror
       QT_SELECT: qt5
+      SCCACHE_GHA_ENABLED: "true"
+      SCCACHE_CACHE_SIZE: "2G"
+      CXX_COMPILER_LAUNCHER: sccache
 
     steps:
     - uses: actions/checkout@v1
 
     - name: install dependencies
       run: |
          sudo apt-get update
-         sudo apt-get install g++-9 libqt5opengl5-dev libqt5svg5-dev libglvnd-dev libeigen3-dev zlib1g-dev libfftw3-dev 
+         sudo apt-get install g++-9 libqt5opengl5-dev libqt5svg5-dev libglvnd-dev libeigen3-dev zlib1g-dev libfftw3-dev
+
+    - name: Run sccache-cache
+      uses: mozilla-actions/[email protected]
 
     - name: configure
       run: ./configure -nooptim || { cat configure.log; false; }
@@ -70,17 +82,16 @@ jobs:
       run: ./build -nowarnings -persistent -nopaginate || { cat build.log; false; }
 
 
-
-
-
-
   macos-build:
 
     runs-on: macos-latest
 
     env:
       CFLAGS: -Werror
       PACKAGES: "qt5 eigen pkg-config fftw libpng"
+      SCCACHE_GHA_ENABLED: "true"
+      SCCACHE_CACHE_SIZE: "2G"
+      CXX_COMPILER_LAUNCHER: sccache
 
     steps:
     - uses: actions/checkout@v1
@@ -89,19 +100,23 @@ jobs:
       run: |
          brew update || brew update     # https://github.com/Homebrew/brew/issues/2491#issuecomment-294207661
          brew install $PACKAGES || brew install $PACKAGES
+         /usr/bin/python3 -m ensurepip && /usr/bin/pip3 install numpy
          brew link --force qt5
 
+    - name: Run sccache-cache
+      uses: mozilla-actions/[email protected]
+
     - name: configure
       run: ./configure -assert || { cat configure.log; false; }
 
     - name: build
       run: ./build -nowarnings -persistent -nopaginate || { cat build.log; false; }
 
     - name: unit tests
-      run: ./run_tests units || { cat testing_units.log; false; }
+      run: ./run_tests units || { cat testing/log/units.log; false; }
 
     - name: binary tests
-      run: ./run_tests binaries || { cat testing_binaries.log; false; }
+      run: ./run_tests binaries || { cat testing/log/binaries.log; false; }
 
     - name: check command documentation
       run: ./docs/generate_user_docs.sh && git diff --exit-code docs/
@@ -113,40 +128,59 @@ jobs:
   windows-build:
 
     runs-on: windows-latest
+    defaults:
+      run:
+        shell: msys2 {0}
 
     env:
-      CFLAGS: -Werror
-      MSYSTEM: MINGW64
-      MSYSCON: defterm
+      # CFLAGS: -Werror
       CHERE_INVOKING: enabled_from_arguments
-      MSYS2_NOSTART: yes
+      MINGW_PACKAGE_PREFIX: mingw-w64-ucrt-x86_64
+      SCCACHE_GHA_ENABLED: "true"
+      SCCACHE_CACHE_SIZE: "2G"
+      SCCACHE_DIR: ${{ github.workspace }}/.sccache
 
     steps:
+      - uses: actions/checkout@v3
 
-    - uses: actions/checkout@v1
+      - uses: msys2/setup-msys2@v2
+        with:
+          msystem: UCRT64
+          release: false
+          install: |
+            git
+            python
+            ${{env.MINGW_PACKAGE_PREFIX}}-bc
+            ${{env.MINGW_PACKAGE_PREFIX}}-diffutils
+            ${{env.MINGW_PACKAGE_PREFIX}}-eigen3
+            ${{env.MINGW_PACKAGE_PREFIX}}-fftw
+            ${{env.MINGW_PACKAGE_PREFIX}}-gcc
+            ${{env.MINGW_PACKAGE_PREFIX}}-pkg-config
+            ${{env.MINGW_PACKAGE_PREFIX}}-qt5-base
+            ${{env.MINGW_PACKAGE_PREFIX}}-qt5-svg
+            ${{env.MINGW_PACKAGE_PREFIX}}-zlib
 
-    - name: fetch and install MSYS2
-      run: bash -c 'curl -sL https://github.com/MRtrix3/MinGW/releases/download/1.0/msys2.tar.{0,1} | tar xf -'
+      - name: Run sccache-cache
+        uses: mozilla-actions/[email protected]
 
-    - name: run qtbinpatcher
-      shell: cmd
-      run: msys64\msys2_shell.cmd -c "qtbinpatcher --qt-dir=$(dirname $(which qmake))"
+      - name: export sccache to msys2 shell
+        run: |
+          export SCCACHE_UNIX_PATH=$(cygpath -u "$SCCACHE_PATH")
+          echo "SCCACHE_UNIX_PATH=$SCCACHE_UNIX_PATH" >> $GITHUB_ENV
 
-    - name: configure
-      shell: cmd
-      run: msys64\msys2_shell.cmd -c "./configure -assert || { cat configure.log; false; }"
+      - name: configure
+        run: |
+          export CXX_COMPILER_LAUNCHER=${{env.SCCACHE_UNIX_PATH}}
+          ./configure -assert || { cat configure.log; false; }
 
-    - name: build
-      shell: cmd
-      run: msys64\msys2_shell.cmd -c "./build -nowarnings -persistent -nopaginate || { cat build.log; false; }"
+      - name: build
+        run: ./build -nowarnings -persistent -nopaginate || { cat build.log; false; }
 
-    - name: unit tests
-      shell: cmd
-      run: msys64\msys2_shell.cmd -c "./run_tests units || { cat testing_units.log; false; }"
+      - name: unit tests
+        run: ./run_tests units || { cat testing/log/units.log; false; }
 
-    - name: binary tests
-      shell: cmd
-      run: msys64\msys2_shell.cmd -c "./run_tests binaries || { cat testing_binaries.log; false; }"
+      - name: binary tests
+        run: ./run_tests binaries || { cat testing/log/binaries.log; false; }
 
 
 
@@ -164,35 +198,27 @@ jobs:
     - name: install dependencies
       run: |
          sudo apt-get update
-         sudo apt-get install pylint python3-sphinx sphinx-rtd-theme-common python3-recommonmark python3-sphinx-rtd-theme python3-pip
-         pip3 install sphinx-notfound-page
-
+         sudo apt-get install pylint python3-sphinx sphinx-rtd-theme-common python3-recommonmark python3-sphinx-rtd-theme python3-pip python3-sphinx-notfound-page
 
     - name: check syntax
       run: ./check_syntax || { cat syntax.log; false; }
 
-    - name: pylint (Python 3)
+    - name: pylint
       run: |
          echo "__version__ = 'pylint testing' #pylint: disable=unused-variable" > ./lib/mrtrix3/_version.py
-         PYTHON=python3 ./run_pylint || { cat pylint.log; false; }
+         ./run_pylint || { cat pylint.log; false; }
 
     - name: check copyright headers
       run: ./update_copyright && git diff --exit-code
 
     - name: check building of documentation
       run: python3 -m sphinx -n -N -W -w sphinx.log docs/ tmp/
 
-    - name: install build dependencies
-      run: sudo apt-get install python2 clang libqt5opengl5-dev libqt5svg5-dev libglvnd-dev libeigen3-dev zlib1g-dev libfftw3-dev
-
-    - name: check configure with Python 2
-      run: python2 ./configure || { cat configure.log; false; }
-
-    - name: check build with Python 2
-      run: python2 ./build -dryrun || { cat build.log; false; }
-
-    - name: check configure with Python 3
-      run: python3 ./configure || { cat configure.log; false; }
-
-    - name: check build with Python 3
-      run: python3 ./build -dryrun || { cat build.log; false; }
+    - name: clang-format check
+      uses: DoozyX/[email protected]
+      with:
+        source: '.'
+        extensions: 'h,cpp'
+        clangFormatVersion: 16
+        # Ignore third party headers
+        exclude: './core/file/json.h ./core/file/nifti1.h ./core/file/nifti2.h'

.github/workflows/wipecache.yml

@@ -0,0 +1,30 @@
+name: Wipe Github Actions cache
+on: workflow_dispatch
+
+jobs:
+  cleanup:
+    permissions: write-all
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v3
+
+      - name: Cleanup
+        run: |
+          gh extension install actions/gh-actions-cache
+
+          REPO=${{ github.repository }}
+
+          echo "Fetching list of cache key"
+          cacheKeysForPR=$(gh actions-cache list -R $REPO | cut -f 1 )
+
+          ## Setting this to not fail the workflow while deleting cache keys. 
+          set +e
+          echo "Deleting caches..."
+          for cacheKey in $cacheKeysForPR
+          do
+              gh actions-cache delete $cacheKey -R $REPO --confirm
+          done
+          echo "Done"
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -31,6 +31,7 @@ build.*
 /dev/
 /bin/
 /tmp/
+/compiled_docs/
 /.vscode/
 .cproject
 .idea
@@ -50,8 +51,12 @@ build.*
 testing.log
 testing/build.log
 testing/bin/
+testing/log/
 testing/src/project_version.cpp
 testing/src/project_version.h
 .__tmp.log
 .check_syntax.tmp
 .check_syntax2.tmp
+*.venv
+__pycache__
+.DS_Store

.pre-commit-config.yaml

@@ -0,0 +1,10 @@
+default_language_version:
+  python: python3
+repos:
+  - repo: https://github.com/pre-commit/mirrors-clang-format
+    rev: v16.0.4
+    hooks:
+      - id: clang-format
+        name: clang-format
+        types_or: [c++]
+        language: python

CONTRIBUTING.md

@@ -307,6 +307,33 @@ A few explicit notes on such:
    introduce Windows-style newline characters ("`CR LF`" / "`\r\n`")
    will need to be edited accordingly.
 
+-  In C++, we use [clang-format](https://clang.llvm.org/docs/ClangFormat.html) 16
+   to ensure that all C++ code is formatted using the same conventions.
+   To comply with this requirement, we recommend that you install a local git hook
+   using [pre-commit](https://pre-commit.com/):
+
+   - Install `pre-commit` via `pip install pre-commit` (or via your OS package manager).
+
+   - Run `pre-commit install` in the source directory of MRtrix. 
+     NOTE: you may need to add the pip scripts folder to your `PATH` 
+     (you can check where pip has installed the package using `pip show pre-commit`).
+
+   This procedure will install a local git hook to ensure that all of your commits
+   are correctly formatted. If this isn't the case, the commits will fail and an 
+   automatic formatting of the staged changes will be applied. You will then have 
+   to commit those changes again.
+
+   Alternatively, you may wish to configure your editor to automatically format 
+   your code using `clang-format`. We also provide a Python script in the top level directory
+   called `clang-format-all` that can format all C++ code in the repository. You can run
+   this to format your code before committing it. The script also allows you to
+   specify a custom `clang-format` binary by using the `--executable` flag.
+
+   NOTE: If you are using a version of `clang-format` that is different from the one
+   used by the CI (currently version 16), your code may be formatted differently and thus
+   fail our CI tests. We recommend that you use the same version of `clang-format` as the
+   CI to avoid this issue.
+
 -  In Python, variable / class / module names are enforced through
    `pylint`. Script "`run_pylint`" in the *MRtrix3* root directory
    will test any code modifications against these expectations.

Dockerfile

@@ -21,7 +21,6 @@ RUN apt-get -qq update \
         libpng-dev \
         libqt5opengl5-dev \
         libqt5svg5-dev \
-        libtiff5-dev \
         qt5-default \
         zlib1g-dev \
     && rm -rf /var/lib/apt/lists/*
@@ -77,7 +76,6 @@ RUN apt-get -qq update \
         libqt5svg5 \
         libqt5widgets5 \
         libquadmath0 \
-        libtiff5 \
         python3-distutils \
     && rm -rf /var/lib/apt/lists/*
 

README.md

@@ -18,8 +18,8 @@ You can address all *MRtrix3*-related queries there, using your GitHub or Google
 ## Quick install
 
 1. Install dependencies by whichever means your system uses. 
-   These include: Python (>=2.6), a C++ compiler with full C++11 support (`g++` 4.9 or later, `clang++`), 
-   Eigen (>=3.2.8), zlib, OpenGL (>=3.3), and Qt (>=4.8, or at least 5.1 on MacOSX).
+   These include: Python3, a C++ compiler with full C++11 support (`g++` 4.9 or later, `clang++`), 
+   Eigen (>=3.2.8), zlib, OpenGL (>=3.3), and Qt (>=5.5).
 
 2. Clone Git repository and compile:
 

Singularity

@@ -39,10 +39,10 @@ Include: apt
     apt-get update && apt-get upgrade -y
 
 # Runtime requirements
-    apt-get update && apt-get install -y --no-install-recommends dbus dc less libfftw3-bin liblapack3 libpng16-16 libqt5network5 libqt5widgets5 libtiff5 python3 python3-distutils zlib1g
+    apt-get update && apt-get install -y --no-install-recommends dbus dc less libfftw3-bin liblapack3 libpng16-16 libqt5network5 libqt5widgets5 python3 python3-distutils zlib1g
 
 # Build requirements
-    apt-get update && apt-get install -y --no-install-recommends build-essential ca-certificates curl git libeigen3-dev libfftw3-dev libgl1-mesa-dev libpng-dev libqt5opengl5-dev libqt5svg5-dev libtiff5-dev qt5-qmake qtbase5-dev-tools wget zlib1g-dev
+    apt-get update && apt-get install -y --no-install-recommends build-essential ca-certificates curl git libeigen3-dev libfftw3-dev libgl1-mesa-dev libpng-dev libqt5opengl5-dev libqt5svg5-dev qt5-qmake qtbase5-dev-tools wget zlib1g-dev
 
 # Neuroimaging software / data dependencies
     # Download minified ART ACPCdetect (V2.0).
@@ -62,7 +62,7 @@ Include: apt
     cd /opt/mrtrix3 && ./configure && ./build -persistent -nopaginate && rm -rf testing/ tmp/ && cd ../../
 
 # apt cleanup to recover as much space as possible
-    apt-get remove -y build-essential ca-certificates curl git libeigen3-dev libfftw3-dev libgl1-mesa-dev libpng-dev libqt5opengl5-dev libqt5svg5-dev libtiff5-dev qt5-qmake qtbase5-dev-tools wget zlib1g-dev && apt-get autoremove -y && apt-get clean && rm -rf /var/lib/apt/lists/*
+    apt-get remove -y build-essential ca-certificates curl git libeigen3-dev libfftw3-dev libgl1-mesa-dev libpng-dev libqt5opengl5-dev libqt5svg5-dev qt5-qmake qtbase5-dev-tools wget zlib1g-dev && apt-get autoremove -y && apt-get clean && rm -rf /var/lib/apt/lists/*
 
 # Configure DBus to facilitate mrview execution
     dbus-uuidgen