|
|
|
Command-line Usage | |
|---|
Commands are generally issued by typing the command name, followed by a series of arguments and options separated by white spaces. MRtrix applications will typically require at least one argument (usually an image specifier), and may need to be tuned in some way using command line options (described here). The various arguments and options accepted by a particular command are described in the list of MRtrix commands, and on each command's built-in help page, which can be viewed by running the command with the -help option. For example:
> mrinfo -help
mrinfo: part of the MRtrix package
PURPOSE: display header information
SYNTAX: mrinfo [ options ] image [ image ... ]
image the input image.
OPTIONS:
-grad file write DW gradient scheme to file
"file": the DW gradient scheme file.
-dicom print all DICOM entries.
-csa print all CSA entries (Siemens DICOM only.
-info display information messages.
-quiet do not display information messages or progress status.
-debug display debugging messages.
-help display this information page and exit.
-version display version information and exit.
To understand command-line arguments and options, consider the mrconvert command:
> mrconvert image.img -vox 1,1,2.5 out.mif mrconvert: copying data... 100%
In this example, mrconvert is the command name, image.img is the first argument, out.mif is the second argument, -vox is an option, and 1,1,2.5 is an additional argument required by the -vox option. This command converts the Analyse format image image.img into the MRtrix format image out.mif, overriding the original voxel size to 1 × 1 × 2.5 mm.
In order to find out how to use a particular program, you can use the -help option to display that program's help page (see Standard options).
Note that since arguments are assumed to be separated by white space, filenames containing a space need to be treated with special care to avoid them being interpreted as two arguments instead of one. There are several ways to avoid this problem: the filename can be enclosed in inverted commas, or each white space can be escaped with a preceeding backslash ('\'). For example, if there is a file named 'an example filename.img', then the following commands are all valid and equivalent:
> mrinfo 'an example filename.img' > mrinfo "an example filename.img" > mrinfo an\ example\ filename.img
Unix only: note also that commands and filenames are case-sensitive. If a command you issued fails, check its spelling and case.
Command line options may be supplied to modify the behaviour of a program, or to supply additional information. A command-line option consists of one or more minus signs immediately followed by the option name. Options will often require additional arguments to operate correctly, in which case these must be specified immediately after the option itself.
The following example illustrates an option modifying the behaviour of a program:
> mrconvert -info /data/DICOM_folder/ out.img mrconvert [INFO]: opening image "/data/DICOM_folder/"... mrconvert [INFO]: initialising DICOM dictionary mrconvert: scanning DICOM folder /data/DICOM_folder/" - ok mrconvert: reading DICOM series "t1_mpr_0.9 iso hres"... 100% mrconvert [INFO]: loading image "VOLUNTEER(000366) [MR] t1_mpr_0.9 iso hres"... mrconvert [INFO]: creating image "poo.mif"... mrconvert: copying data... 100% mrconvert [INFO]: closing image "VOLUNTEER(000366) [MR] t1_mpr_0.9 iso hres"... mrconvert [INFO]: closing image "./poo.mif"...
In this example, the -info option tells the program to display additional information while processing.
The following example illustrates the case of an option requiring an additional argument to specify additional information:
> threshold image.img -percent 20 -invert mask.img threshold: finding min/max... 100% threshold: thresholding at intensity 266.8... 100%
In this example, the -percent option tells the threshold program to threshold at the 20% level, and the -invert option causes it to invert the results. This will produce the binary mask image mask.img, where pixels are set to one if the original intensities were less than 20% of the maximum pixel intensity in image.img, and set to zero otherwise.
MRtrix programs will accept shortened option names as long as there are no ambiguities. For example, the following command is equivalent to that above:
> threshold image.img --p 20 -inv mask.img threshold: finding min/max... 100% threshold: thresholding at intensity 266.8... 100%
However, the following command will fail:
> threshold image.img -p 20 -i mask.img threshold: several matches possible for option "i": "invert", "info"
since threshold accepts two different options that both start with 'i'.
All MRtrix programs understand the following options:
| Option | Action |
|---|---|
| -info | display information messages. |
| -quiet | do not display information messages or progress status. |
| -debug | display debugging messages. |
| -help | display the program's information page and exit. |
| -version | display version information and exit. |
To find out how to use a program, including the required number of arguments and all valid options, type the program name followed by the -help option. This will display that program's help page.
Many MRtrix applications understand sequences of numbers and can operate according to the sequence specified. For example, you may only need a few series from a data set. In this case, you could use the mrconvert command and specify the series you need as follows:
> mrconvert -coord 3 0:3,8,10 dwi.mif dwi-[].img
In this example, mrconvert will select from the image data set dwi.mif the series specified by the number sequence 0:3,8,10, corresponding to the numbers 0, 1, 2, 3, 8 & 10 (this assumes that the series axis is axis 3). The output images will be stored as a set of numbered Analyse format images, named dwi-0.img, dwi-1.img, etc. (the 'square brackets' syntax used here is explained below).
Note that a number sequence cannot contain any spaces, since it would then be interpreted as two arguments (see Basic usage). The syntax consists of a comma-separated list of any of the following items:
The square brackets used in the example above (dwi-[].img) are used to indicate a numbered sequence of images that should be interpreted as a single data set (e.g. a fMRI time series). In the previous case, the sequence was left empty, leaving the program to automatically number the filenames accordingly. These images can be accessed using a similar syntax. For example:
> mrinfo dwi-[].img
will access all matching images as a 4-dimensional data set (assuming each of the individual images contains a 3D data set). If only one of the images is of interest, it can be accessed by specifying its filename as normal without the use of square brackets:
> mrinfo dwi-1.img
Finally, to access a data set formed from a subset of the images, insert the appropriate number sequence within the square brackets:
> mrinfo dwi-[1,3].img
Note that when using number sequences to specify a filename, any leading zeros in the number field will be ignored. For example, the images dwi-1.img and dwi-001.img will both be matched by the identifier dwi-[1].img.
The output of one program can be fed straight through to the input of another program via pipes in a single command. The appropriate syntax is illustrated in this example:
> dwi2tensor /data/DICOM_folder/ - | tensor2vector - ev.mif dwi2tensor: scanning DICOM folder "/data/DICOM_folder/" - ok dwi2tensor: reading DICOM series "diff60_b3000_2.3_iPat2+ADC"... 100% dwi2tensor: DICOM image contains mosaic files - reformating... 100% dwi2tensor: converting DW images to tensor image... 100% tensor2vector: generating major eigenvector map... 100%
This command will execute the following actions:
The two stages of the pipeline are separated by the '|' symbol, which indicates to the system that the output of the first command is to be used as input for the next command. The image that is to be fed to or from the pipeline is specified for each program using a single dash '-' where the image would normally be specified as an argument.
For this to work properly, it is important to know which arguments each program will interpret as input images, and which as output images. For example, this command will fail:
> dwi2tensor - /data/DICOM_folder/ | tensor2vector - ev.mif
In this example, dwi2tensor will hang waiting for input data (its first argument should be the input DWI data set). This will also cause tensor2vector to hang while it waits for dwi2tensor to provide some input.
The procedure used in MRtrix to feed data sets down a pipeline is somewhat different from the more traditional use of pipes. Given the large amounts of data typically contained in a data set, the 'standard' practice of feeding the entire data set through the pipe would be prohibitively inefficient. MRtrix applications access the data via memory-mapping (when this is possible), and do not need to explicitly copy the data into their own memory space. When using pipes, MRtrix applications will simply generate a temporary file and feed its filename through to the next stage once their processing is done. The next program in the pipeline will then simply read this filename and access the corresponding file. The latter program is then responsible for deleting the temporary file once its processing is done.
This implies that any errors during processing may result in undeleted temporary files. These will normally be created within the current directory with a filename of the form mrtrix-XXXXXX.xyz. If a piped command has failed, and no other MRtrix programs are currently running, these can be safely deleted.
Such pipelines are not limited to two programs. Complex operations can be perfomed in one command using this technique. Here is a longer example:
> dwi2tensor /data/DICOM_folder/ - | tensor2vector - - | mrmult - mask.img - | mrview - dwi2tensor: scanning DICOM folder "/data/DICOM_folder/" - ok dwi2tensor: reading DICOM series "diff60_b3000_2.3_iPat2+ADC"... 100% dwi2tensor: DICOM image contains mosaic files - reformating... 100% dwi2tensor: converting DW images to tensor image... 100% tensor2vector: generating major eigenvector map... 100% mrmult: multiplying... 100%
This command will execute the following actions:
|
|
|
top | |
|---|