MRtrix3 · Lestropie · Feb 19, 2024 · Feb 19, 2024 · Feb 19, 2024 · Feb 19, 2024
diff --git a/.github/workflows/checks.yml b/.github/workflows/checks.yml
@@ -214,3 +214,6 @@ jobs:
 
     - name: check building of documentation
       run: python3 -m sphinx -n -N -W -w sphinx.log docs/ tmp/
+
+    - name: check interface documentation
+      run: ./interfaces/generate_interfaces.sh && git diff --exit-code
diff --git a/interfaces/generate_interfaces.sh b/interfaces/generate_interfaces.sh
@@ -0,0 +1,52 @@
+#!/bin/bash
+
+# Copyright (c) 2008-2023 the MRtrix3 contributors.
+#
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at http://mozilla.org/MPL/2.0/.
+#
+# Covered Software is provided under this License on an "as is"
+# basis, without warranty of any kind, either expressed, implied, or
+# statutory, including, without limitation, warranties that the
+# Covered Software is free of defects, merchantable, fit for a
+# particular purpose or non-infringing.
+# See the Mozilla Public License v. 2.0 for more details.
+#
+# For more details, see http://www.mrtrix.org/.
+
+
+mrtrix_root=$( cd "$(dirname "${BASH_SOURCE}")"/../ ; pwd -P )
+export PATH=$mrtrix_root/bin:"$PATH"
+export LC_ALL=C
+
+cmdlist=""
+for n in `find "${mrtrix_root}"/cmd/ -name "*.cpp"`; do
+  cmdlist=$cmdlist$'\n'`basename $n`
+done
+for n in `find "${mrtrix_root}"/bin/ -type f -print0 | xargs -0 grep -l "import mrtrix3"`; do
+  cmdlist=$cmdlist$'\n'`basename $n`
+done
+
+legacy_root="${mrtrix_root}/interfaces/legacy"
+rm -rf "${legacy_root}"
+mkdir "${legacy_root}"
+for n in `echo "$cmdlist" | sort`; do
+  cmdname=${n%".cpp"}
+  cmdpath=$cmdname
+  case $n in *.cpp)
+    if [ "$OSTYPE" == "cygwin" ] || [ "$OSTYPE" == "msys" ] || [ "$OSTYPE" == "win32" ]; then
+      cmdpath=${cmdpath}'.exe'
+    fi
+  esac
+  if `grep -q "algorithm\.get_module" "${mrtrix_root}/bin/${cmdpath}"`; then
+    mkdir $legacy_root/$cmdname
+    $cmdpath __print_full_usage__ > $legacy_root/$cmdname/$cmdname
+    algorithms=`grep "ARGUMENT algorithm 0 0 CHOICE" $legacy_root/$cmdname/$cmdname | cut -d" " -f 6-`
+    for a in $algorithms; do
+      $cmdpath $a __print_full_usage__ > $legacy_root/$cmdname/$a
+    done
+  else
+    $cmdpath __print_full_usage__ > $legacy_root/$cmdname
+  fi
+done
diff --git a/interfaces/legacy/5tt2gmwmi b/interfaces/legacy/5tt2gmwmi
@@ -0,0 +1,28 @@
+Generate a mask image appropriate for seeding streamlines on the grey matter-white matter interface
+ARGUMENT 5tt_in 0 0 IMAGEIN
+the input 5TT segmented anatomical image
+ARGUMENT mask_out 0 0 IMAGEOUT
+the output mask image
+OPTION mask_in 1 0
+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 0 0 IMAGEIN
+the input mask image
+OPTION info 1 0
+display information messages.
+OPTION quiet 1 0
+do not display information messages or progress status; alternatively, this can be achieved by setting the MRTRIX_QUIET environment variable to a non-empty string.
+OPTION debug 1 0
+display debugging messages.
+OPTION force 1 0
+force overwrite of output files (caution: using the same file as input and output might cause unexpected behaviour).
+OPTION nthreads 1 0
+use this number of threads in multi-threaded applications (set to 0 to disable multi-threading).
+ARGUMENT number 0 0 INT 0 9223372036854775807
+OPTION config 1 1
+temporarily set the value of an MRtrix config file entry.
+ARGUMENT key 0 0 TEXT
+ARGUMENT value 0 0 TEXT
+OPTION help 1 0
+display this information page and exit.
+OPTION version 1 0
+display version information and exit.
diff --git a/interfaces/legacy/5tt2vis b/interfaces/legacy/5tt2vis
@@ -0,0 +1,42 @@
+Generate an image for visualisation purposes from an ACT 5TT segmented anatomical image
+ARGUMENT input 0 0 IMAGEIN
+the input 4D tissue-segmented image
+ARGUMENT output 0 0 IMAGEOUT
+the output 3D image for visualisation
+OPTION bg 1 0
+image intensity of background (default: 0)
+ARGUMENT value 0 0 FLOAT 0 1
+OPTION cgm 1 0
+image intensity of cortical grey matter (default: 0.5)
+ARGUMENT value 0 0 FLOAT 0 1
+OPTION sgm 1 0
+image intensity of sub-cortical grey matter (default: 0.75)
+ARGUMENT value 0 0 FLOAT 0 1
+OPTION wm 1 0
+image intensity of white matter (default: 1)
+ARGUMENT value 0 0 FLOAT 0 1
+OPTION csf 1 0
+image intensity of CSF (default: 0.15)
+ARGUMENT value 0 0 FLOAT 0 1
+OPTION path 1 0
+image intensity of pathological tissue (default: 2)
+ARGUMENT value 0 0 FLOAT 0 10
+OPTION info 1 0
+display information messages.
+OPTION quiet 1 0
+do not display information messages or progress status; alternatively, this can be achieved by setting the MRTRIX_QUIET environment variable to a non-empty string.
+OPTION debug 1 0
+display debugging messages.
+OPTION force 1 0
+force overwrite of output files (caution: using the same file as input and output might cause unexpected behaviour).
+OPTION nthreads 1 0
+use this number of threads in multi-threaded applications (set to 0 to disable multi-threading).
+ARGUMENT number 0 0 INT 0 9223372036854775807
+OPTION config 1 1
+temporarily set the value of an MRtrix config file entry.
+ARGUMENT key 0 0 TEXT
+ARGUMENT value 0 0 TEXT
+OPTION help 1 0
+display this information page and exit.
+OPTION version 1 0
+display version information and exit.
diff --git a/interfaces/legacy/5ttcheck b/interfaces/legacy/5ttcheck
@@ -0,0 +1,25 @@
+Thoroughly check that one or more images conform to the expected ACT five-tissue-type (5TT) format
+ARGUMENT input 0 1 IMAGEIN
+the 5TT image(s) to be tested
+OPTION voxels 1 0
+output mask images highlighting voxels where the input does not conform to 5TT requirements
+ARGUMENT prefix 0 0 TEXT
+OPTION info 1 0
+display information messages.
+OPTION quiet 1 0
+do not display information messages or progress status; alternatively, this can be achieved by setting the MRTRIX_QUIET environment variable to a non-empty string.
+OPTION debug 1 0
+display debugging messages.
+OPTION force 1 0
+force overwrite of output files (caution: using the same file as input and output might cause unexpected behaviour).
+OPTION nthreads 1 0
+use this number of threads in multi-threaded applications (set to 0 to disable multi-threading).
+ARGUMENT number 0 0 INT 0 9223372036854775807
+OPTION config 1 1
+temporarily set the value of an MRtrix config file entry.
+ARGUMENT key 0 0 TEXT
+ARGUMENT value 0 0 TEXT
+OPTION help 1 0
+display this information page and exit.
+OPTION version 1 0
+display version information and exit.
diff --git a/interfaces/legacy/5ttedit b/interfaces/legacy/5ttedit
@@ -0,0 +1,42 @@
+Manually set the partial volume fractions in an ACT five-tissue-type (5TT) image using mask images
+ARGUMENT input 0 0 IMAGEIN
+the 5TT image to be modified
+ARGUMENT output 0 0 IMAGEOUT
+the output modified 5TT image
+OPTION cgm 1 0
+provide a mask of voxels that should be set to cortical grey matter
+ARGUMENT image 0 0 IMAGEIN
+OPTION sgm 1 0
+provide a mask of voxels that should be set to sub-cortical grey matter
+ARGUMENT image 0 0 IMAGEIN
+OPTION wm 1 0
+provide a mask of voxels that should be set to white matter
+ARGUMENT image 0 0 IMAGEIN
+OPTION csf 1 0
+provide a mask of voxels that should be set to CSF
+ARGUMENT image 0 0 IMAGEIN
+OPTION path 1 0
+provide a mask of voxels that should be set to pathological tissue
+ARGUMENT image 0 0 IMAGEIN
+OPTION none 1 0
+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 0 0 IMAGEIN
+OPTION info 1 0
+display information messages.
+OPTION quiet 1 0
+do not display information messages or progress status; alternatively, this can be achieved by setting the MRTRIX_QUIET environment variable to a non-empty string.
+OPTION debug 1 0
+display debugging messages.
+OPTION force 1 0
+force overwrite of output files (caution: using the same file as input and output might cause unexpected behaviour).
+OPTION nthreads 1 0
+use this number of threads in multi-threaded applications (set to 0 to disable multi-threading).
+ARGUMENT number 0 0 INT 0 9223372036854775807
+OPTION config 1 1
+temporarily set the value of an MRtrix config file entry.
+ARGUMENT key 0 0 TEXT
+ARGUMENT value 0 0 TEXT
+OPTION help 1 0
+display this information page and exit.
+OPTION version 1 0
+display version information and exit.
diff --git a/interfaces/legacy/5ttgen/5ttgen b/interfaces/legacy/5ttgen/5ttgen
@@ -0,0 +1,36 @@
+Generate a 5TT image suitable for ACT
+5ttgen acts as a "master" script for generating a five-tissue-type (5TT) segmented tissue image suitable for use in Anatomically-Constrained Tractography (ACT). A range of different algorithms are available for completing this task. When using this script, the name of the algorithm to be used must appear as the first argument on the command-line after "5ttgen". The subsequent compulsory arguments and options available depend on the particular algorithm being invoked.
+Each algorithm available also has its own help page, including necessary references; e.g. to see the help page of the "fsl" algorithm, type "5ttgen fsl".
+ARGUMENT algorithm 0 0 CHOICE freesurfer fsl gif hsvs
+OPTION -nocrop 1 0
+Do NOT crop the resulting 5TT image to reduce its size (keep the same dimensions as the input image)
+OPTION -sgm_amyg_hipp 1 0
+Represent the amygdalae and hippocampi as sub-cortical grey matter in the 5TT image
+OPTION -nocleanup 1 0
+do not delete intermediate files during script execution, and do not delete scratch directory at script completion.
+OPTION -scratch 1 0
+manually specify the path in which to generate the scratch directory.
+ARGUMENT /path/to/scratch/ 0 0 DIROUT
+OPTION -continue 1 0
+continue the script from a previous execution; must provide the scratch directory path, and the name of the last successfully-generated file.
+ARGUMENT ScratchDir 0 0 VARIOUS
+ARGUMENT LastFile 0 0 VARIOUS
+OPTION -info 1 0
+display information messages.
+OPTION -quiet 1 0
+do not display information messages or progress status. Alternatively, this can be achieved by setting the MRTRIX_QUIET environment variable to a non-empty string.
+OPTION -debug 1 0
+display debugging messages.
+OPTION -force 1 0
+force overwrite of output files.
+OPTION -nthreads 1 0
+use this number of threads in multi-threaded applications (set to 0 to disable multi-threading).
+ARGUMENT number 0 0 INT 0 9223372036854775807
+OPTION -config 1 0
+temporarily set the value of an MRtrix config file entry.
+ARGUMENT key 0 0 TEXT
+ARGUMENT value 0 0 TEXT
+OPTION -help 1 0
+display this information page and exit.
+OPTION -version 1 0
+display version information and exit.
diff --git a/interfaces/legacy/5ttgen/freesurfer b/interfaces/legacy/5ttgen/freesurfer
@@ -0,0 +1,40 @@
+Generate the 5TT image based on a FreeSurfer parcellation image
+ARGUMENT input 0 0 IMAGEIN
+The input FreeSurfer parcellation image (any image containing "aseg" in its name)
+ARGUMENT output 0 0 IMAGEOUT
+The output 5TT image
+OPTION -lut 1 0
+Manually provide path to the lookup table on which the input parcellation image is based (e.g. FreeSurferColorLUT.txt)
+ARGUMENT file 0 0 FILEIN
+OPTION -nocrop 1 0
+Do NOT crop the resulting 5TT image to reduce its size (keep the same dimensions as the input image)
+OPTION -sgm_amyg_hipp 1 0
+Represent the amygdalae and hippocampi as sub-cortical grey matter in the 5TT image
+OPTION -nocleanup 1 0
+do not delete intermediate files during script execution, and do not delete scratch directory at script completion.
+OPTION -scratch 1 0
+manually specify the path in which to generate the scratch directory.
+ARGUMENT /path/to/scratch/ 0 0 DIROUT
+OPTION -continue 1 0
+continue the script from a previous execution; must provide the scratch directory path, and the name of the last successfully-generated file.
+ARGUMENT ScratchDir 0 0 VARIOUS
+ARGUMENT LastFile 0 0 VARIOUS
+OPTION -info 1 0
+display information messages.
+OPTION -quiet 1 0
+do not display information messages or progress status. Alternatively, this can be achieved by setting the MRTRIX_QUIET environment variable to a non-empty string.
+OPTION -debug 1 0
+display debugging messages.
+OPTION -force 1 0
+force overwrite of output files.
+OPTION -nthreads 1 0
+use this number of threads in multi-threaded applications (set to 0 to disable multi-threading).
+ARGUMENT number 0 0 INT 0 9223372036854775807
+OPTION -config 1 0
+temporarily set the value of an MRtrix config file entry.
+ARGUMENT key 0 0 TEXT
+ARGUMENT value 0 0 TEXT
+OPTION -help 1 0
+display this information page and exit.
+OPTION -version 1 0
+display version information and exit.
diff --git a/interfaces/legacy/5ttgen/fsl b/interfaces/legacy/5ttgen/fsl
@@ -0,0 +1,45 @@
+Use FSL commands to generate the 5TT image based on a T1-weighted image
+ARGUMENT input 0 0 IMAGEIN
+The input T1-weighted image
+ARGUMENT output 0 0 IMAGEOUT
+The output 5TT image
+OPTION -t2 1 0
+Provide a T2-weighted image in addition to the default T1-weighted image; this will be used as a second input to FSL FAST
+ARGUMENT image 0 0 IMAGEIN
+OPTION -mask 1 0
+Manually provide a brain mask, rather than deriving one in the script
+ARGUMENT image 0 0 IMAGEIN
+OPTION -premasked 1 0
+Indicate that brain masking has already been applied to the input image
+OPTION -nocrop 1 0
+Do NOT crop the resulting 5TT image to reduce its size (keep the same dimensions as the input image)
+OPTION -sgm_amyg_hipp 1 0
+Represent the amygdalae and hippocampi as sub-cortical grey matter in the 5TT image
+OPTION -nocleanup 1 0
+do not delete intermediate files during script execution, and do not delete scratch directory at script completion.
+OPTION -scratch 1 0
+manually specify the path in which to generate the scratch directory.
+ARGUMENT /path/to/scratch/ 0 0 DIROUT
+OPTION -continue 1 0
+continue the script from a previous execution; must provide the scratch directory path, and the name of the last successfully-generated file.
+ARGUMENT ScratchDir 0 0 VARIOUS
+ARGUMENT LastFile 0 0 VARIOUS
+OPTION -info 1 0
+display information messages.
+OPTION -quiet 1 0
+do not display information messages or progress status. Alternatively, this can be achieved by setting the MRTRIX_QUIET environment variable to a non-empty string.
+OPTION -debug 1 0
+display debugging messages.
+OPTION -force 1 0
+force overwrite of output files.
+OPTION -nthreads 1 0
+use this number of threads in multi-threaded applications (set to 0 to disable multi-threading).
+ARGUMENT number 0 0 INT 0 9223372036854775807
+OPTION -config 1 0
+temporarily set the value of an MRtrix config file entry.
+ARGUMENT key 0 0 TEXT
+ARGUMENT value 0 0 TEXT
+OPTION -help 1 0
+display this information page and exit.
+OPTION -version 1 0
+display version information and exit.
diff --git a/interfaces/legacy/5ttgen/gif b/interfaces/legacy/5ttgen/gif
@@ -0,0 +1,37 @@
+Generate the 5TT image based on a Geodesic Information Flow (GIF) segmentation image
+ARGUMENT input 0 0 IMAGEIN
+The input Geodesic Information Flow (GIF) segmentation image
+ARGUMENT output 0 0 IMAGEOUT
+The output 5TT image
+OPTION -nocrop 1 0
+Do NOT crop the resulting 5TT image to reduce its size (keep the same dimensions as the input image)
+OPTION -sgm_amyg_hipp 1 0
+Represent the amygdalae and hippocampi as sub-cortical grey matter in the 5TT image
+OPTION -nocleanup 1 0
+do not delete intermediate files during script execution, and do not delete scratch directory at script completion.
+OPTION -scratch 1 0
+manually specify the path in which to generate the scratch directory.
+ARGUMENT /path/to/scratch/ 0 0 DIROUT
+OPTION -continue 1 0
+continue the script from a previous execution; must provide the scratch directory path, and the name of the last successfully-generated file.
+ARGUMENT ScratchDir 0 0 VARIOUS
+ARGUMENT LastFile 0 0 VARIOUS
+OPTION -info 1 0
+display information messages.
+OPTION -quiet 1 0
+do not display information messages or progress status. Alternatively, this can be achieved by setting the MRTRIX_QUIET environment variable to a non-empty string.
+OPTION -debug 1 0
+display debugging messages.
+OPTION -force 1 0
+force overwrite of output files.
+OPTION -nthreads 1 0
+use this number of threads in multi-threaded applications (set to 0 to disable multi-threading).
+ARGUMENT number 0 0 INT 0 9223372036854775807
+OPTION -config 1 0
+temporarily set the value of an MRtrix config file entry.
+ARGUMENT key 0 0 TEXT
+ARGUMENT value 0 0 TEXT
+OPTION -help 1 0
+display this information page and exit.
+OPTION -version 1 0
+display version information and exit.