Merge remote-tracking branch 'origin/master' into dwi_metadata_master

.github/workflows/releases.yml

@@ -0,0 +1,137 @@
+name: Releases
+
+on:
+  workflow_dispatch:
+    inputs:
+      branch:
+        description: 'Branch to release from'
+        required: true
+        default: 'dev'
+
+jobs:
+  linux-release:
+    runs-on: ubuntu-20.04
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+          ref: ${{ github.event.inputs.branch }}
+
+      - name: Set env vars
+        id: envs
+        run: |
+          commit_sha=$(git rev-parse HEAD)
+          date=$(date +%Y_%m_%d)
+          echo "commit_sha=$commit_sha" >> $GITHUB_OUTPUT
+          echo "date=$date" >> $GITHUB_OUTPUT
+          echo "output_name=mrtrix3-linux-$commit_sha-$date" >> $GITHUB_OUTPUT
+
+      - name: Install Eigen3
+        run: |
+          git clone https://gitlab.com/libeigen/eigen.git && cd eigen && git checkout 3.4.0
+          cmake -B build && cmake --build build
+          sudo cmake --install build
+
+      - name: Install Qt 6
+        uses: jurplel/install-qt-action@v3
+        with:
+          version: '6.7.0'
+          set-env: true
+
+      - name: Run build
+        run: |
+          ./packaging/package-linux-tarball.sh .
+          mv mrtrix.tar.gz ${{ steps.envs.outputs.output_name }}.tar.gz
+
+      - name: Upload release artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: ${{ steps.envs.outputs.output_name }}
+          path: ${{ steps.envs.outputs.output_name }}.tar.gz
+
+  macos-release:
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+          ref: ${{ github.event.inputs.branch }}
+
+      - name: Set env vars
+        id: envs
+        run: |
+          commit_sha=$(git rev-parse HEAD)
+          date=$(date +%Y_%m_%d)
+          echo "commit_sha=$commit_sha" >> $GITHUB_OUTPUT
+          echo "date=$date" >> $GITHUB_OUTPUT
+          echo "output_name=mrtrix3-macos-$commit_sha-$date" >> $GITHUB_OUTPUT
+
+      - name: Install deps
+        run: brew install numpy cmake qt eigen pkg-config fftw libpng ninja
+
+      - name: Run build
+        run: |
+          cd ./packaging/macos
+          ./build ${{ github.event.inputs.branch }}
+          mv ./mrtrix3-macos-${{ github.event.inputs.branch }}.tar.xz ../../${{ steps.envs.outputs.output_name }}.tar.xz
+
+      - name: Upload release artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: ${{ steps.envs.outputs.output_name }}
+          path: ${{ steps.envs.outputs.output_name }}.tar.xz
+
+  windows-release:
+    runs-on: windows-latest
+    defaults:
+      run:
+        shell: msys2 {0}
+
+    env:
+      MINGW_PACKAGE_PREFIX: mingw-w64-ucrt-x86_64
+
+    steps:
+      - uses: msys2/setup-msys2@v2
+        with:
+          msystem: UCRT64
+          install: |
+            git
+            python
+            ${{env.MINGW_PACKAGE_PREFIX}}-bc
+            ${{env.MINGW_PACKAGE_PREFIX}}-cmake
+            ${{env.MINGW_PACKAGE_PREFIX}}-diffutils
+            ${{env.MINGW_PACKAGE_PREFIX}}-eigen3
+            ${{env.MINGW_PACKAGE_PREFIX}}-fftw
+            ${{env.MINGW_PACKAGE_PREFIX}}-gcc
+            ${{env.MINGW_PACKAGE_PREFIX}}-libtiff
+            ${{env.MINGW_PACKAGE_PREFIX}}-ninja
+            ${{env.MINGW_PACKAGE_PREFIX}}-pkg-config
+            ${{env.MINGW_PACKAGE_PREFIX}}-qt6-base
+            ${{env.MINGW_PACKAGE_PREFIX}}-qt6-svg
+            ${{env.MINGW_PACKAGE_PREFIX}}-zlib
+
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+          ref: ${{ github.event.inputs.branch }}
+
+      - name: Set env vars
+        id: envs
+        run: |
+          commit_sha=$(git rev-parse HEAD)
+          date=$(date +%Y_%m_%d)
+          echo "commit_sha=$commit_sha" >> $GITHUB_OUTPUT
+          echo "date=$date" >> $GITHUB_OUTPUT
+          echo "output_name=mrtrix3-windows-$commit_sha-$date" >> $GITHUB_OUTPUT
+
+      - name: Run build
+        run: |
+          cd packaging/mingw
+          ./run.sh ${{ steps.envs.outputs.commit_sha }} mrtrix3
+          mv mingw*.tar.zst ../../../${{ steps.envs.outputs.output_name }}.tar.zst
+
+      - name: Upload release artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: ${{ steps.envs.outputs.output_name }}
+          path: ${{ steps.envs.outputs.output_name }}.tar.zst

.github/workflows/weekly_sanitizers.yml

@@ -28,7 +28,7 @@ jobs:
     - name: install dependencies
       run: |
          sudo apt-get update
-         sudo apt-get install clang llvm qt6-base-dev libglvnd-dev libeigen3-dev zlib1g-dev libfftw3-dev ninja-build
+         sudo apt-get install clang llvm qt6-base-dev libglvnd-dev libeigen3-dev zlib1g-dev libfftw3-dev ninja-build python3-numpy
 
     - name: Run sccache-cache
       uses: mozilla-actions/[email protected]
@@ -56,7 +56,7 @@ jobs:
       run: cmake --build build
 
     - name: binary tests
-      run: cd build && ctest -R bin --output-on-failure
+      run: cd build && ctest -L binary --output-on-failure
 
     - name: unit tests
-      run: cd build && ctest -R unit --output-on-failure
+      run: cd build && ctest -L unittest --output-on-failure

bin/for_each

@@ -48,6 +48,9 @@ def usage(cmdline): #pylint: disable=unused-variable
   cmdline.add_example_usage('Testing the command string substitution',
                             'for_each -test * : mrconvert IN PRE.mif',
                             'By specifying the -test option, the script will print to the terminal the results of text substitutions for all of the specified inputs, but will not actually execute those commands. It can therefore be used to verify that the script is receiving the intended set of inputs, and that the text substitutions on those inputs lead to the intended command strings.')
+  cmdline.add_example_usage('Utilising shell operators within the command substitution',
+                            'for_each * : tensor2metric IN/dwi.mif - "|" tensor2metric - -fa IN/fa.mif',
+                            'In this example, if the double-quotes were NOT placed around the pipe operator, then the shell would take the sum total output of the for_each script and pipe that to a single invocation of the tensor2metric command. Since in this example it is instead desired for the pipe operator to be a part of the command string that is executed multiple times by the for_each script, it must be escaped using double-quotes.')
   cmdline.add_argument('inputs',   help='Each of the inputs for which processing should be run', nargs='+')
   cmdline.add_argument('colon',    help='Colon symbol (":") delimiting the for_each inputs & command-line options from the actual command to be executed', type=str, choices=[':'])
   cmdline.add_argument('command',  help='The command string to run for each input, containing any number of substitutions listed in the Description section', type=str)

bin/mrtrix3.py

@@ -15,7 +15,6 @@
 # For more details, see http://www.mrtrix.org/.
 
 import os, sys
-from distutils.spawn import find_executable
 
 try:
   # since importlib code below only works on Python 3.5+

cmd/mrcalc.cpp

@@ -910,6 +910,7 @@ void run () {
       else if (opt->is ("nthreads")) ++n;
       else if (opt->is ("force") || opt->is ("info") || opt->is ("debug") || opt->is ("quiet"))
         continue;
+      else if (opt->is ("config")) n+=2;
 
 #define SECTION 3
 #include "mrcalc.cpp"

cmd/mrdegibbs.cpp

@@ -43,11 +43,17 @@ void usage ()
     "you should run denoising before this command to not alter the noise structure, "
     "which would impact on dwidenoise's performance."
 
+    + "For best results, any form of filtering performed by the scanner should be disabled, whether "
+    "performed in the image domain or k-space. This includes elliptic filtering and other filters that "
+    "are often applied to reduce Gibbs ringing artifacts. While this method can still safely be applied "
+    "to such data, some residual ringing artefacts may still be present in the output."
+
     + "Note that this method is designed to work on images acquired with full k-space coverage. "
-    "Running this method on partial Fourier ('half-scan') data may lead to suboptimal and/or biased "
-    "results, as noted in the original reference below. There is currently no means of dealing with this; "
-    "users should exercise caution when using this method on partial Fourier data, and inspect its output "
-    "for any obvious artefacts. ";
+    "If this method is executed on data acquired with partial Fourier (eg. \"half-scan\") acceleration, "
+    "it may not fully remove all ringing artifacts, "
+    "and you may observe residuals of the original artifact in the partial Fourier direction. "
+    "Nonetheless, application of the method is still considered safe and worthwhile. "
+    "Users are however encouraged to acquired full-Fourier data where possible.";
 
 
   ARGUMENTS

cmd/mrgrid.cpp

@@ -107,7 +107,7 @@ void usage ()
   + OptionGroup ("Pad and crop options (no image interpolation is performed, header transformation is adjusted)")
     + Option   ("as", "pad or crop the input image on the upper bound to match the specified reference image grid. "
                 "This operation ignores differences in image transformation between input and reference image.")
-    + Argument ("reference image").type_image_in ()
+    + Argument ("reference_image").type_image_in ()
 
     + Option   ("uniform", "pad or crop the input image by a uniform number of voxels on all sides")
     + Argument ("number").type_integer ()

cmd/mrinfo.cpp

@@ -52,7 +52,7 @@ const OptionGroup FieldExportOptions = OptionGroup ("Options for exporting image
 void usage ()
 {
 
-  AUTHOR = "J-Donald Tournier ([email protected]) and Robert E. Smith ([email protected])";
+  AUTHOR = "J-Donald Tournier ([email protected]) and Robert E. Smith ([email protected])";
 
   SYNOPSIS = "Display image header information, or extract specific information from the header";
 

core/file/mmap.cpp

@@ -112,9 +112,10 @@ namespace MR
           delayed_writeback = true;
         }
 
-        if (fsbuf.f_type == 0xff534d42 /* CIFS */|| fsbuf.f_type == 0x6969 /* NFS */ || 
-            fsbuf.f_type == 0x65735546 /* FUSE */ || fsbuf.f_type == 0x517b /* SMB */ || 
-            fsbuf.f_type == 0x47504653 /* GPFS */ || fsbuf.f_type == 0xbd00bd0 /* LUSTRE */
+        if (fsbuf.f_type == 0xff534d42 /* CIFS */ || fsbuf.f_type == 0x6969 /* NFS */ ||
+            fsbuf.f_type == 0x65735546 /* FUSE */ || fsbuf.f_type == 0x517b /* SMB */ ||
+            fsbuf.f_type == 0x47504653 /* GPFS */ || fsbuf.f_type == 0xbd00bd0 /* LUSTRE */ ||
+            fsbuf.f_type == 0x1021997 /* 9P (WSL) */
 
 #ifdef MRTRIX_MACOSX
             || fsbuf.f_type == 0x0017 /* OSXFUSE */

core/formats/pipe.cpp

@@ -64,7 +64,7 @@ namespace MR
         return false;
 
       if (isatty (STDOUT_FILENO))
-        throw Exception ("attempt to pipe image to standard output (this will leave temporary files behind)");
+        throw Exception ("cannot create output piped image: no command connected at other end of pipe to receive that image");
 
       H.name() = File::create_tempfile (0, "mif");
 

core/progressbar.cpp

@@ -188,7 +188,7 @@ namespace MR
       // unable to determine nature of stderr; assuming socket
       stderr_to_file = false;
     else
-      stderr_to_file = S_ISREG (buf.st_mode);
+      stderr_to_file = S_ISREG (buf.st_mode) || S_ISFIFO (buf.st_mode);
 
 
 

docs/reference/commands/for_each.rst

@@ -61,6 +61,12 @@ Example usages
 
     By specifying the -test option, the script will print to the terminal the results of text substitutions for all of the specified inputs, but will not actually execute those commands. It can therefore be used to verify that the script is receiving the intended set of inputs, and that the text substitutions on those inputs lead to the intended command strings.
 
+-   *Utilising shell operators within the command substitution*::
+
+        $ for_each * : tensor2metric IN/dwi.mif - "|" tensor2metric - -fa IN/fa.mif
+
+    In this example, if the double-quotes were NOT placed around the pipe operator, then the shell would take the sum total output of the for_each script and pipe that to a single invocation of the tensor2metric command. Since in this example it is instead desired for the pipe operator to be a part of the command string that is executed multiple times by the for_each script, it must be escaped using double-quotes.
+
 Options
 -------
 

docs/reference/commands/mrdegibbs.rst

@@ -25,7 +25,9 @@ This application attempts to remove Gibbs ringing artefacts from MRI images usin
 
 This command is designed to run on data directly after it has been reconstructed by the scanner, before any interpolation of any kind has taken place. You should not run this command after any form of motion correction (e.g. not after dwifslpreproc). Similarly, if you intend running dwidenoise, you should run denoising before this command to not alter the noise structure, which would impact on dwidenoise's performance.
 
-Note that this method is designed to work on images acquired with full k-space coverage. Running this method on partial Fourier ('half-scan') data may lead to suboptimal and/or biased results, as noted in the original reference below. There is currently no means of dealing with this; users should exercise caution when using this method on partial Fourier data, and inspect its output for any obvious artefacts. 
+For best results, any form of filtering performed by the scanner should be disabled, whether performed in the image domain or k-space. This includes elliptic filtering and other filters that are often applied to reduce Gibbs ringing artifacts. While this method can still safely be applied to such data, some residual ringing artefacts may still be present in the output.
+
+Note that this method is designed to work on images acquired with full k-space coverage. If this method is executed on data acquired with partial Fourier (eg. "half-scan") acceleration, it may not fully remove all ringing artifacts, and you may observe residuals of the original artifact in the partial Fourier direction. Nonetheless, application of the method is still considered safe and worthwhile. Users are however encouraged to acquired full-Fourier data where possible.
 
 Options
 -------

docs/reference/commands/mrgrid.rst

@@ -72,7 +72,7 @@ Regridding options (involves image interpolation, applied to spatial axes only)
 Pad and crop options (no image interpolation is performed, header transformation is adjusted)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
--  **-as reference image** pad or crop the input image on the upper bound to match the specified reference image grid. This operation ignores differences in image transformation between input and reference image.
+-  **-as reference_image** pad or crop the input image on the upper bound to match the specified reference image grid. This operation ignores differences in image transformation between input and reference image.
 
 -  **-uniform number** pad or crop the input image by a uniform number of voxels on all sides
 

docs/reference/commands/mrinfo.rst

@@ -130,7 +130,7 @@ Tournier, J.-D.; Smith, R. E.; Raffelt, D.; Tabbara, R.; Dhollander, T.; Pietsch
 
 
 
-**Author:** J-Donald Tournier ([email protected]) and Robert E. Smith ([email protected])
+**Author:** J-Donald Tournier ([email protected]) and Robert E. Smith ([email protected])
 
 **Copyright:** Copyright (c) 2008-2024 the MRtrix3 contributors.
 

lib/mrtrix3/path.py

@@ -21,13 +21,18 @@
 
 
 import ctypes, errno, inspect, os, random, string, subprocess, time
-from distutils.spawn import find_executable
 # Function can be used in isolation if potentially needing to place quotation marks around a
 #   filesystem path that is to be included as part of a command string
 try:
   from shlex import quote
 except ImportError:
   from pipes import quote
+# Distutils removed in 3.12, but shutil.which not available in 2.7
+try:
+  from shutil import which as find_executable
+except ImportError:
+  from distutils.spawn import find_executable
+
 from mrtrix3 import CONFIG
 from mrtrix3.utils import STRING_TYPES
 

lib/mrtrix3/run.py

@@ -17,10 +17,15 @@
 # pylint: disable=unspecified-encoding
 
 import collections, itertools, os, shlex, signal, string, subprocess, sys, tempfile, threading
-from distutils.spawn import find_executable
 from mrtrix3 import ANSI, BIN_PATH, COMMAND_HISTORY_STRING, EXE_LIST, MRtrixBaseError, MRtrixError
 from mrtrix3.utils import STRING_TYPES
 
+# Distutils removed in 3.12, but shutil.which not available in 2.7
+try:
+  from shutil import which as find_executable
+except ImportError:
+  from distutils.spawn import find_executable
+
 IOStream = collections.namedtuple('IOStream', 'handle filename')
 
 
@@ -473,7 +478,7 @@ def finalise_temp_file(iostream):
   if shared.get_scratch_dir():
     with shared.lock:
       with open(os.path.join(shared.get_scratch_dir(), 'log.txt'), 'a') as outfile:
-        outfile.write(cmdstring + '\n')
+        outfile.write(' '.join(cmdsplit) + '\n')
 
   return CommandReturn(return_stdout, return_stderr)
 

src/dwi/fmls.cpp

@@ -82,7 +82,7 @@ namespace MR {
           }
         }
 
-        opt = get_options ("fmls_merge_ratio");
+        opt = get_options ("fmls_lobe_merge_ratio");
         if (opt.size())
           segmenter.set_lobe_merge_ratio (default_type(opt[0][0]));