User Tutorial [neuro] - Converting NIFTI to MINC Format

Updated for release version: 1.0.20-alpha

Introduction

This tutorial takes you through the process of converting your NIFTI T1-weighted anatomical images into MINC-2 format, using the nii2mnc command, for use as input to the CIVET pipeline. Sounds straightforward, but the problem is that CIVET will only accept input which is properly oriented with the MNI-152 template image (see here). Here, we will go through the steps of setting up a Pipeline for your data, determining the proper parameters to produce the data we want, and finally a complete conversion of the data set to a form that is ready for CIVET.

For this tutorial, you can download and decompress the following dataset, consisting of 5 randomly selected T1-weighted images [source]:

[link]

MINC Toolkit Installation (if necessary)

To perform this conversion, it is necessary to have the MINC Toolkit installed on your machine. MINC tools are developed for the Linux OS, so having Linux or Mac OS is a must for this tutorial. If you are using Windows, you can consider a Linux virtual environment such as the VMware Player, which is free to use. See this tutorial for the installation of the Ubuntu platform on your machine.

NIFTI headers

A NIFTI file (*.nii) header contains all the important metadata about the image, including:

  • Data type (size and format of the stored voxel values)
  • Data dimensions (how many voxels in each dimension)
  • Image dimensions (geometric length of the image axes in each direction)
  • Image origin (where first voxel is situated it in 3D space)
  • Image orientation (how the image is oriented in 3D space)

The data format is especially important to know, because if it is wrong it could result in data truncation (if the data size is too small to store the value), or excess file size (if the the data size is larger than is necessary to store the values). If we have a NIFTI file of type short, for instance, which signifies a 16-bit integer value, it would be a waste to convert this file to a MINC file of type double, which is a 64-bit floating point value. Likewise, it would be very foolish to convert a NIFTI file of type double to one of type short, which would reduce the double-precision decimal values to integers on the range [-32768, 32767] (assuming a signed short).

To figure out the data type of our NIFTI files, we can have a look with the ModelGUI Volume Panel. Select Grid > Shape: > "<-New Panel->", then Data > Create volume: > Volume File, and you will see the Volume File Dialog. Select "Nifti volumes" as the file format and browse for your NIFTI file. Once you select in, some of the file's header information will appear; specifically: the image origin; the data dimensions; the geometric dimensions; and the data type. Make a note of these for later.

Project Setup

Now we will set up our data as a ModelGUI Project, which will allow us to manipulate it with a Pipeline.

Creating a project

To create our project, open the Tree Panel and right click on the Projects node. Select "Add new" and the New Project dialog box will appear. We can give it a name, such as "NIFTI to MINC Tutorial", and then click "Browse" to navigate to the directory you downloaded above. We can specify two subdirectories for this project. The "project" directory holds general project data and metadata. We can call this "metadata". The "instances" directory is designed to point to individual subdirectories containing subject-wise data. We can call this "subjects". Select the check box beside "Allow file system updates", which grants permission to the dialog to create these two currently nonexistent subdirectories, and then click "Create". Your two subdirectories will be created. Now select the "Instance Data" tab. This shows the data structure of the instances directory; in our case our instances directory is empty, since all the images are contained together in the top directory. To create our instances, we can load them from a text file list, which is described next.

Loading subject IDs from a text file

First we need to create a text file listing each subject ID. You may or may not have such a list already; since our tutorial data lacks one, we'll have to create it. Do this from the terminal, by navigating to the tutorial directory and typing the command:

ls *.nii > metadata/subjects.txt

The resulting text file lists subject IDs but also has the ".nii" extensions, which are unwanted. You can remove these by the find/replace function of most text editors (e.g., gedit metadata/subjects.txt).

Now that we have our subject list, we can read it using the "Add list" button on the dialog box. The "instances" list will populate with the subject IDs. Clicking "Apply" and "OK" will finalize the project. Now we're ready to set up and run a pipeline.

Pipeline setup

Pipeline functionality is provided through the Pipelines Panel.

minc-tools Process Library

A Process Library is a set of pipeline process specifications corresponding to a single library or toolkit, such as the MINC Toolkit or the FMRIB Software Library (FSL). A Pipeline Process is a single command which is specified by a set of parameters which that command recognizes. In our case, we want to use the MINC Toolkit library. To have a look at this library, expand the This should come standard with your ModelGUI installation, expand Processes and select "minc-tools" as the library. All the minc-tools processes will be listed below it. The ones we are interested in here are: "nii2mnc", which converts from NIFTI to MINC format; and "mincpik", which outputs section images and help identify whether our images are properly oriented.

One important step must be done at this point. Each library can be associated with an Environment, which refers to the system environment variables available to a process when it runs. If your MINC setup was done as above, the commands we need will be located in the opt directory, and will likely not be available with the default system environment. Normally, the environment is set using the shell script /opt/minc/minc-toolkit-config.sh. To set up our pipeline library correctly, we can copy/paste from the environment after running this script. To do this, open a new terminal window and type:

source /opt/minc/minc-toolkit-config.sh

Now type:

echo $PATH

Right click and copy the result. Back in ModelGUI, click the "Environment.." button and then "Add". Under Name type "PATH", and under Value paste the copied PATH variable with Ctrl-V.

Do the same with the system variable "LD_LIBRARY_PATH". Your dialog box should look something like this:

Click "OK". You may now want to save the environment permanently. To do this click "Save", and navigate to the pipeline_process_libraries subdirectory of your ModelGUI installation folder. Select "minc-tools.proclib" and click "Save". Done.

Pipeline processes

Now we can set up our pipeline. To create a new pipeline, expand General and click "Create". Name the new pipeline "nii2mnc_tutorial" and click "OK".

We want two processes: the first to perform the conversion, and the second to generate an output image that we can use to check the results (see also this page). Expand Pipeline, select the nii2mnc_tutorial pipeline you just created, and click "Append New". This opens the Pipeline Process Instance Settings dialog box. A pipeline process instance is simply a process for which the parameters have been specified.

Select "minc-tools" as the library and "nii2mnc" as the process. Check the "Input from file" box, and type the following text beside it:

{root}/{instance}.nii

An explanation is in order… For any parameter value, the curly braces { and } are special characters which can be used to specify parts of the parameter value which can be assigned from the project. Here, "{root}" gets replaced with the root directory of our project (i.e., the tutorial directory), and "{instance}" gets replaced by an instance — or subject — ID. The sequences "{project_dir}" and "{instances_dir}" can also be used.

For the output file, type:

{root}/mnc/{instance}.mnc

Since we know that our image has the data type short, check the "short" parameter, under "Apply". Also apply the outputfile parameter (which is an optional parameter). Now click "OK", and your process instance appears in pipeline tree.

Our second process is "mincpik". Click "Append new" and set up that process is the same way. Check the "Input from file" box, and type "{root}/mnc/{instance}.mnc". Check the "Output to file" box and type "{root}/pik/{instance}.png". Apply the "triplanar" parameter and the "outputfile" parameter, and click "OK".

We now have a pipeline to convert our data. If you want, you can now save this pipeline to file, using General > Save.

Our final step is to create the "mnc" and "pik" directories specified in these parameters, under the project folder.

Test run

We're now ready to test our pipeline. First, we want to assign our project to our pipeline. Expand Project and check "Assign project". The subject IDs from the project will appear in the Instances list, with check boxes beside them. For the pipeline execution, only those subjects which are selected are processed. For our test run we only want to check the processing on a single subject, so let's select only the first one.

Under Pipeline, check the "Serial instances" box.

Before we launch, we'll want a Console window to see what's going on. In the ModelGUI display panel, right-click and select Add window > Console. The screen will turn black and will display any console output generated by ModelGUI.

We're ready to go, so click "Launch". If all is well, the output should look like:

You should also see a MINC file in the {root}/mnc directory, and a png file in the {root}/pik directory.

Parameter tweaking

Full run

Moving forward

Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License