The MRtrix3 Python script library

In addition to the principal binary commands in MRtrix3, which are written in the C++ language, MRtrix3 also now includes a number of Python scripts for performing common image processing tasks that can be achieved through a combination of existing commands. These make use of a relatively simple Python module library, which provide a certain level of convenience and consistency for building such scripts (e.g. help pages formatted identically to the MRtrix3 binary commands; command-line parsing; creation, use and deletion of temporary scratch directory; control over command-line verbosity; various convenience functions).

It is hoped that in addition to growing in complexity and capability over time, this library may also be of assistance to users when building their own processing scripts, rather than the use of e.g. Bash. It is typically easiest to commence construction of such a script by making a copy of an existing functional script from the MRtrix3 bin/ directory, and then editing the contents to suit your needs.

Executing a script that uses the MRtrix3 libraries

If you wish to be able to use such a script (either written by yourself, or perhaps provided to you externally from the main MRtrix3 package), there are two options that you must choose from in order for execution of that script to be possible:

  1. Place the script file within the bin/ directory of your MRtrix3 installation. The same mechanism that is used within those Python scripts provided with MRtrix3 for locating and loading the MRtrix3 Python libraries will be invoked for this script also, as long as the relevant code is present (see point 2.1 below).

  2. If you wish to be able to place the executable Python script anywhere on your file system, there are two additional steps required:

    1. In the Python scripts provided with MRtrix3, you will consistently find the following code snippet:

      # Make the corresponding MRtrix3 Python libraries available
      import inspect, os, sys
      LIB_FOLDER = os.path.realpath(os.path.join(os.path.dirname(os.path.realpath(inspect.getfile(inspect.currentframe()))), os.pardir, 'lib'))
      if not os.path.isdir(LIB_FOLDER):
        sys.stderr.write('Unable to locate MRtrix3 Python libraries')
        sys.exit(1)
      sys.path.insert(0, LIB_FOLDER)
      

      You will need to delete this piece of code from your script file. This code allows Python to locate and load the MRtrix3 Python libraries based on their location on the file system relative to the script currently being executed, which is assumed to be in the MRtrix3 bin/ directory. Since this is not the case for option 2 described here, it needs to be removed.

    2. Since Python is not able to locate these libraries automatically in this usage scenario, it is necessary for you to manually provide Python with the information regarding their whereabouts. This can be done using the environment variable PYTHONPATH:

      $ export PYTHONPATH=/home/user/mrtrix3/lib:$PYTHONPATH
      $ ./my_script [arguments] (options)
      

      (Replace the path to the MRtrix3 “lib” directory in the example above with the location of your own installation)

Writing a script using the MRtrix3 libraries

To come if there is sufficient demand for it…