Merge branch 'dev' into tarball_packaging

MRtrix3 · Feb 27, 2024 · ee726c7 · ee726c7
2 parents a8fe4ef + c76b256
commit ee726c7
Show file tree

Hide file tree

Showing 240 changed files with 5,870 additions and 4,794 deletions.
diff --git a/.git-blame-ignore-revs b/.git-blame-ignore-revs
@@ -101,4 +101,11 @@ aad44d847ac48d02bb7f8badf801dbfaa0ccdac0
 45fc06bdf687584bf4d55140720e84c5ef517bf0
 #Author: MRtrixBot <[email protected]>
 #Date:   Thu, 17 Aug 2023 15:36:14 +0100
-#    Apply formatting for C++ using clang-format
+#    Apply formatting for C++ using clang-format
+
+de4de955cd82065135d15383a639dd7f7373d834
+#Author: MRtrixBot <[email protected]>
+#Date:   Mon Feb 26 13:38:02 2024 +1100
+#    Disable clang-format for CLI-related code
+#    When clang-format, introduced in #2652, applied its changes to MRtrix3 code relating to the command-line interface (particularly the way that options and their arguments are concatenated through the addition operator), the resulting code was often quite ugly. This commit replaces code relating to CLI configuration (both the usage() function in cmd/*.cpp, and in definitions of options and option groups utilised by multiple commands) with manually formatted code, and includes comment fields to disable further manipulation of that code by clang-format.
+#    This commit is a refactor of 0cec87a0e59749d4e14ebf55c288067d29f868f1 generated as part of #2815, with the changes being to omit other modifications to the command documentation that are not directly related to clang-format (those changes are in the parent commit to this commit: 15e253cf6a0af83a9a0f4f9369a256d01cf90ad8), and to change authorship of the commit.
diff --git a/.github/workflows/checks.yml b/.github/workflows/checks.yml
@@ -28,7 +28,7 @@ jobs:
          sudo apt-get install clang qt6-base-dev libglvnd-dev libeigen3-dev zlib1g-dev libfftw3-dev ninja-build
 
     - name: Run sccache-cache
-      uses: mozilla-actions/[email protected].3
+      uses: mozilla-actions/[email protected].4
 
     - name: Get CMake
       uses: lukka/get-cmake@latest
@@ -79,7 +79,7 @@ jobs:
          sudo apt-get install g++-9 qt6-base-dev libglvnd-dev libeigen3-dev zlib1g-dev libfftw3-dev ninja-build
 
     - name: Run sccache-cache
-      uses: mozilla-actions/[email protected].3
+      uses: mozilla-actions/[email protected].4
 
     - name: Get CMake
       uses: lukka/get-cmake@latest
@@ -129,7 +129,7 @@ jobs:
          brew link --force qt
 
     - name: Run sccache-cache
-      uses: mozilla-actions/[email protected].3
+      uses: mozilla-actions/[email protected].4
 
     - name: Get CMake
       uses: lukka/get-cmake@latest
@@ -202,7 +202,7 @@ jobs:
             ${{env.MINGW_PACKAGE_PREFIX}}-zlib
 
       - name: Run sccache-cache
-        uses: mozilla-actions/[email protected].3
+        uses: mozilla-actions/[email protected].4
 
       - name: export sccache to msys2 shell
         run: |

diff --git a/cmd/5tt2gmwmi.cpp b/cmd/5tt2gmwmi.cpp
@@ -28,29 +28,31 @@
 using namespace MR;
 using namespace App;
 
+// clang-format off
 void usage() {
 
   AUTHOR = "Robert E. Smith ([email protected])";
 
   SYNOPSIS = "Generate a mask image appropriate for seeding streamlines on the grey matter-white matter interface";
 
   REFERENCES
-  +"Smith, R. E.; Tournier, J.-D.; Calamante, F. & Connelly, A. " // Internal
-   "Anatomically-constrained tractography:"
-   "Improved diffusion MRI streamlines tractography through effective use of anatomical information. "
-   "NeuroImage, 2012, 62, 1924-1938";
+    + "Smith, R. E.; Tournier, J.-D.; Calamante, F. & Connelly, A. " // Internal
+      "Anatomically-constrained tractography:"
+      " Improved diffusion MRI streamlines tractography through effective use of anatomical information. "
+      "NeuroImage, 2012, 62, 1924-1938";
 
   ARGUMENTS
-  +Argument("5tt_in", "the input 5TT segmented anatomical image").type_image_in() +
-      Argument("mask_out", "the output mask image").type_image_out();
+    + Argument ("5tt_in", "the input 5TT segmented anatomical image").type_image_in()
+    + Argument ("mask_out", "the output mask image").type_image_out();
 
   OPTIONS
-  +Option("mask_in",
-          "Filter an input mask image according to those voxels that lie upon the grey matter - white matter boundary. "
-          "If no input mask is provided, the output will be a whole-brain mask image calculated using the anatomical "
-          "image only.") +
-      Argument("image", "the input mask image").type_image_in();
+    + Option("mask_in", "Filter an input mask image according to those voxels that lie upon the grey matter - white matter boundary. "
+                        "If no input mask is provided, "
+                        "the output will be a whole-brain mask image calculated using the anatomical image only.")
+      + Argument ("image", "the input mask image").type_image_in();
+
 }
+// clang-format on
 
 class Processor {
 

diff --git a/cmd/5tt2vis.cpp b/cmd/5tt2vis.cpp
@@ -32,36 +32,46 @@ using namespace App;
 #define VALUE_DEFAULT_CSF 0.15
 #define VALUE_DEFAULT_PATH 2.0
 
+// clang-format off
 void usage() {
 
   AUTHOR = "Robert E. Smith ([email protected])";
 
-  SYNOPSIS = "Generate an image for visualisation purposes from an ACT 5TT segmented anatomical image";
+  SYNOPSIS = "Generate an image for visualisation purposes"
+             " from an ACT 5TT segmented anatomical image";
 
   ARGUMENTS
-  +Argument("input", "the input 4D tissue-segmented image").type_image_in() +
-      Argument("output", "the output 3D image for visualisation").type_image_out();
+  + Argument ("input",  "the input 4D tissue-segmented image").type_image_in()
+  + Argument ("output", "the output 3D image for visualisation").type_image_out();
 
   OPTIONS
 
-  +Option("bg", "image intensity of background (default: " + str(VALUE_DEFAULT_BG, 2) + ")") +
-      Argument("value").type_float(0.0, 1.0)
+  + Option ("bg", "image intensity of background"
+                  " (default: " + str(VALUE_DEFAULT_BG, 2) + ")")
+    + Argument ("value").type_float (0.0, 1.0)
 
-      + Option("cgm", "image intensity of cortical grey matter (default: " + str(VALUE_DEFAULT_CGM, 2) + ")") +
-      Argument("value").type_float(0.0, 1.0)
+  + Option ("cgm", "image intensity of cortical grey matter"
+                   " (default: " + str(VALUE_DEFAULT_CGM, 2) + ")")
+    + Argument ("value").type_float (0.0, 1.0)
 
-      + Option("sgm", "image intensity of sub-cortical grey matter (default: " + str(VALUE_DEFAULT_SGM, 2) + ")") +
-      Argument("value").type_float(0.0, 1.0)
+  + Option ("sgm", "image intensity of sub-cortical grey matter"
+                   " (default: " + str(VALUE_DEFAULT_SGM, 2) + ")")
+    + Argument ("value").type_float (0.0, 1.0)
 
-      + Option("wm", "image intensity of white matter (default: " + str(VALUE_DEFAULT_WM, 2) + ")") +
-      Argument("value").type_float(0.0, 1.0)
+  + Option ("wm", "image intensity of white matter"
+                  " (default: " + str(VALUE_DEFAULT_WM, 2) + ")")
+    + Argument ("value").type_float (0.0, 1.0)
 
-      + Option("csf", "image intensity of CSF (default: " + str(VALUE_DEFAULT_CSF, 2) + ")") +
-      Argument("value").type_float(0.0, 1.0)
+  + Option ("csf", "image intensity of CSF"
+                   " (default: " + str(VALUE_DEFAULT_CSF, 2) + ")")
+    + Argument ("value").type_float (0.0, 1.0)
+
+  + Option ("path", "image intensity of pathological tissue"
+                    " (default: " + str(VALUE_DEFAULT_PATH, 2) + ")")
+    + Argument ("value").type_float (0.0, 10.0);
 
-      + Option("path", "image intensity of pathological tissue (default: " + str(VALUE_DEFAULT_PATH, 2) + ")") +
-      Argument("value").type_float(0.0, 10.0);
 }
+// clang-format on
 
 void run() {
 

diff --git a/cmd/5ttcheck.cpp b/cmd/5ttcheck.cpp
@@ -31,18 +31,23 @@ using namespace App;
 
 #define MAX_ERROR 0.001
 
-void usage() {
+// clang-format off
+void usage()
+{
   AUTHOR = "Robert E. Smith ([email protected])";
 
-  SYNOPSIS = "Thoroughly check that one or more images conform to the expected ACT five-tissue-type (5TT) format";
+  SYNOPSIS = "Thoroughly check that one or more images conform "
+             "to the expected ACT five-tissue-type (5TT) format";
 
   ARGUMENTS
-  +Argument("input", "the 5TT image(s) to be tested").type_image_in().allow_multiple();
+  + Argument ("input", "the 5TT image(s) to be tested").type_image_in().allow_multiple();
 
   OPTIONS
-  +Option("voxels", "output mask images highlighting voxels where the input does not conform to 5TT requirements") +
-      Argument("prefix").type_text();
+  + Option ("voxels", "output mask images highlighting voxels "
+                      "where the input does not conform to 5TT requirements")
+    + Argument ("prefix").type_text();
 }
+// clang-format on
 
 void run() {
   const std::string voxels_prefix = get_option_value<std::string>("voxels", "");

diff --git a/cmd/5ttedit.cpp b/cmd/5ttedit.cpp
@@ -27,35 +27,42 @@
 using namespace MR;
 using namespace App;
 
+// clang-format off
 void usage() {
 
   AUTHOR = "Robert E. Smith ([email protected])";
 
-  SYNOPSIS = "Manually set the partial volume fractions in an ACT five-tissue-type (5TT) image using mask images";
+  SYNOPSIS = "Manually set the partial volume fractions"
+             " in an ACT five-tissue-type (5TT) image"
+             " using mask images";
 
   ARGUMENTS
-  +Argument("input", "the 5TT image to be modified").type_image_in() +
-      Argument("output", "the output modified 5TT image").type_image_out();
+  + Argument ("input",  "the 5TT image to be modified").type_image_in()
+  + Argument ("output", "the output modified 5TT image").type_image_out();
 
   OPTIONS
-  +Option("cgm", "provide a mask of voxels that should be set to cortical grey matter") +
-      Argument("image").type_image_in()
+  + Option ("cgm", "provide a mask of voxels that should be set to cortical grey matter")
+    + Argument ("image").type_image_in()
 
-      + Option("sgm", "provide a mask of voxels that should be set to sub-cortical grey matter") +
-      Argument("image").type_image_in()
+  + Option ("sgm", "provide a mask of voxels that should be set to sub-cortical grey matter")
+    + Argument ("image").type_image_in()
 
-      + Option("wm", "provide a mask of voxels that should be set to white matter") + Argument("image").type_image_in()
+  + Option ("wm", "provide a mask of voxels that should be set to white matter")
+    + Argument ("image").type_image_in()
 
-      + Option("csf", "provide a mask of voxels that should be set to CSF") + Argument("image").type_image_in()
+  + Option ("csf", "provide a mask of voxels that should be set to CSF")
+    + Argument ("image").type_image_in()
 
-      + Option("path", "provide a mask of voxels that should be set to pathological tissue") +
-      Argument("image").type_image_in()
+  + Option ("path", "provide a mask of voxels that should be set to pathological tissue")
+    + Argument ("image").type_image_in()
+
+  + Option ("none", "provide a mask of voxels that should be cleared"
+                    " (i.e. are non-brain);"
+                    " note that this will supersede all other provided masks")
+    + Argument ("image").type_image_in();
 
-      + Option("none",
-               "provide a mask of voxels that should be cleared (i.e. are non-brain); note that this will supersede "
-               "all other provided masks") +
-      Argument("image").type_image_in();
 }
+// clang-format on
 
 class Modifier {
 public:

diff --git a/cmd/afdconnectivity.cpp b/cmd/afdconnectivity.cpp
@@ -29,65 +29,80 @@ using namespace MR;
 using namespace MR::DWI;
 using namespace App;
 
+// clang-format off
 void usage() {
-  AUTHOR = "David Raffelt ([email protected]) and Robert E. Smith ([email protected])";
 
-  SYNOPSIS = "Obtain an estimate of fibre connectivity between two regions using AFD and streamlines tractography";
+  AUTHOR = "David Raffelt ([email protected])"
+           " and Robert E. Smith ([email protected])";
 
-  DESCRIPTION
-  +"This estimate is obtained by determining a fibre volume (AFD) occupied by the pathway "
-   "of interest, and dividing by the streamline length."
-
-      + "If only the streamlines belonging to the pathway of interest are provided, then "
-        "ALL of the fibre volume within each fixel selected will contribute to the result. "
-        "If the -wbft option is used to provide whole-brain fibre-tracking (of which the pathway of "
-        "interest should contain a subset), only the fraction of the fibre volume in each fixel "
-        "estimated to belong to the pathway of interest will contribute to the result."
-
-      + "Use -quiet to suppress progress messages and output fibre connectivity value only."
-
-      + "For valid comparisons of AFD connectivity across scans, images MUST be intensity "
-        "normalised and bias field corrected, and a common response function for all subjects "
-        "must be used."
+  SYNOPSIS = "Obtain an estimate of fibre connectivity between two regions"
+             " using AFD and streamlines tractography";
 
-      + "Note that the sum of the AFD is normalised by streamline length to "
-        "account for subject differences in fibre bundle length. This normalisation results in a measure "
-        "that is more related to the cross-sectional volume of the tract (and therefore 'connectivity'). "
-        "Note that SIFT-ed tract count is a superior measure because it is unaffected by tangential yet unrelated "
-        "fibres. However, AFD connectivity may be used as a substitute when Anatomically Constrained Tractography "
-        "is not possible due to uncorrectable EPI distortions, and SIFT may therefore not be as effective."
+  DESCRIPTION
+  + "This estimate is obtained by determining a fibre volume (AFD)"
+    " occupied by the pathway of interest,"
+    " and dividing by the streamline length."
+
+  + "If only the streamlines belonging to the pathway of interest are provided,"
+    " then ALL of the fibre volume within each fixel selected will contribute to the result."
+    " If the -wbft option is used to provide whole-brain fibre-tracking"
+    " (of which the pathway of interest should contain a subset),"
+    " only the fraction of the fibre volume in each fixel"
+    " estimated to belong to the pathway of interest"
+    " will contribute to the result."
+
+  + "Use -quiet to suppress progress messages and output fibre connectivity value only."
+
+  + "For valid comparisons of AFD connectivity across scans,"
+    " images MUST be intensity normalised and bias field corrected,"
+    " and a common response function for all subjects must be used."
+
+  + "Note that the sum of the AFD is normalised by streamline length"
+    " to account for subject differences in fibre bundle length."
+    " This normalisation results in a measure that is more related to"
+    " the cross-sectional volume of the tract"
+    " (and therefore 'connectivity')."
+    " Note that SIFT-ed tract count is a superior measure"
+    " because it is unaffected by tangential yet unrelated fibres."
+    " However, AFD connectivity may be used as a substitute"
+    " when Anatomically Constrained Tractography is not possible due to uncorrectable EPI distortions,"
+    " and SIFT may therefore not be as effective."
+
+  + "Longer discussion regarding this command can additionally be found at: "
+    "https://mrtrix.readthedocs.io/en/" MRTRIX_BASE_VERSION "/concepts/afd_connectivity.html "
+    "(as well as in the relevant reference).";
 
-      + "Longer discussion regarding this command can additionally be found at: "
-        "https://mrtrix.readthedocs.io/en/" MRTRIX_BASE_VERSION "/concepts/afd_connectivity.html "
-        "(as well as in the relevant reference).";
 
   REFERENCES
-  +"Smith, R. E.; Raffelt, D.; Tournier, J.-D.; Connelly, A. " // Internal
-   "Quantitative Streamlines Tractography: Methods and Inter-Subject Normalisation. "
-   "Open Science Framework, https://doi.org/10.31219/osf.io/c67kn.";
+  + "Smith, R. E.; Raffelt, D.; Tournier, J.-D.; Connelly, A. " // Internal
+    "Quantitative Streamlines Tractography: Methods and Inter-Subject Normalisation. "
+    "Open Science Framework, https://doi.org/10.31219/osf.io/c67kn.";
+
 
   ARGUMENTS
-  +Argument("image", "the input FOD image.").type_image_in()
+  + Argument ("image", "the input FOD image.").type_image_in()
 
-      + Argument("tracks", "the input track file defining the bundle of interest.").type_tracks_in();
+  + Argument ("tracks", "the input track file defining the bundle of interest.").type_tracks_in();
 
   OPTIONS
-  +Option("wbft",
-          "provide a whole-brain fibre-tracking data set (of which the input track file "
-          "should be a subset), to improve the estimate of fibre bundle volume in the "
-          "presence of partial volume") +
-      Argument("tracks").type_tracks_in()
-
-      + Option("afd_map", "output a 3D image containing the AFD estimated for each voxel.") +
-      Argument("image").type_image_out()
-
-      + Option("all_fixels",
-               "if whole-brain fibre-tracking is NOT provided, then if multiple fixels within "
-               "a voxel are traversed by the pathway of interest, by default the fixel with the "
-               "greatest streamlines density is selected to contribute to the AFD in that voxel. "
-               "If this option is provided, then ALL fixels with non-zero streamlines density "
-               "will contribute to the result, even if multiple fixels per voxel are selected.");
+  + Option ("wbft", "provide a whole-brain fibre-tracking data set"
+                    " (of which the input track file should be a subset)"
+                    ", to improve the estimate of fibre bundle volume in the presence of partial volume")
+    + Argument ("tracks").type_tracks_in()
+
+  + Option ("afd_map", "output a 3D image containing the AFD estimated for each voxel.")
+    + Argument ("image").type_image_out()
+
+  + Option ("all_fixels", "if whole-brain fibre-tracking is NOT provided,"
+                          " then if multiple fixels within a voxel are traversed by the pathway of interest,"
+                          " by default the fixel with the greatest streamlines density"
+                          " is selected to contribute to the AFD in that voxel."
+                          " If this option is provided,"
+                          " then ALL fixels with non-zero streamlines density will contribute to the result,"
+                          " even if multiple fixels per voxel are selected.");
+
 }
+// clang-format on
 
 using value_type = float;
 using DWI::Tractography::Mapping::SetDixel;