User Tutorial - Working with Volumes

Updated for release version: 1.0.16-alpha

Introduction

This tutorial will guide you through the process of loading volumes, setting colour maps, specifying composite images, and performing some basic 2D and 3D visualization with volumes. Geometrically, a 3D volume is a box in R3 space, with data points defined at regular intervals within the box. The box and its intervals are specified by a 3D Grid object. Its spatial extents are defined by an origin point and three orthogonal vectors (S, T, and R), defining a box. Its data points are defined by three data dimensions corresponding to the S, T, and R directions; thus, a 3D Grid having a geometric S dimension of 100 mm and a data S dimension of 5 will have 20 regularly-spaced data points along the S dimension. This object is thus well-suited to represent data sampled at regular intervals from a physical field, such as an NMR image in neuroscience, or a magnetic susceptibility inversion in geophysics.

For this tutorial, you will need to download and unzip the data set located here.

Loading a volume

While a volume can be loaded from the File Panel, it is typically more convenient to load a new volume from the Volume Panel. From the Volume Panel, expand the "Grid" and "Data" categories; ensure that the "Shape" combo box is set to "<-New Volume->" (see figure). In the "Data" category, click the box beside "Volume File" and then click that button. The file dialog will appear, as below. Browse for the data you downloaded and select the file named "icbm_avg_152_t1_tal_lin.nii". Set "Has alpha" to true, and select the "greyscale" colour map. Now click "OK". The volume should be ready to load, so click "Create".

figure_1.png

If you expand the "Intensity" and "Histogram" sections, you can get a first look at the volume you've loaded. It will look as below, left. What we'd like to do, however, is see the object in 2D and 3D. To do this, create both a 2D and 3D window (see the Working with windows tutorial). For the source of the 2D window, create a horizontal section set using the Section Set Panel (see this tutorial). Once these windows are set, the volume should appear as below, right:

figure_2.png

Modifying the colour map

Our 3D image shows as a black cube, since the background voxels of the image are all black. This is a bit underwhelming, visually. Luckily, because our image has an alpha (transparency) channel, we can alter our colour map in order to make these background voxels invisible. You can do this by looking at the image and its histogram, either by changing the slider values in the "Intensity" category, or by dragging the mouse directly on the image. Left dragging modifies the contrast (width of the colour mapping window), and right dragging modifies the brightness (middle of the colour mapping window). Middle-dragging, if it is an option on your system, alters the cut-off value (alpha min), below which all values are invisible. Play with the values until they look as below, left. Additionally, we may not be satisfied with the visual contrast provided by the "greyscale" colour map. Choose another colour map from the combo box. For example, the map "nih_grey" results in the contrast as seen below, right. Click "Apply" to apply the changes to the shape object.

figure_3.png

3D rendering modes

There are two modes available for rendering in 3D. The default, which you are currently seeing, is "As volume", which displays the entire volume as a stack of images. The alternative is "As sections". If selected, this will display the current sections of all current 2D windows, assuming their source section set is part of the same shape model. To change the rendering mode, go to the Tree Panel, expand the shape node for your volume, and select "As sections" for the RenderMode attribute. The screen will now look like:

figure_4.png

Adding a data column

Now we want to add another data column to our volume. Say, for fun, we want to overlay the AAL parcellation [1] on our template image, which will inform us which anatomical region each part of the grey matter belongs to. To do this, return to the Volume Panel, and in the Data category, ensure the checkbox titled "Add column" is checked (see first figure). Click the "Volume File" button to search for the new image to load; in this case we want to load the file "aal.nii". Select the "aal" colour map and click OK. Now click "Add Column" and the data will be loaded into a new data column, which will appear in the list above (see next section).

figure_5.png

Specifying a composite image

The columns table allows you to specify which data column is current (leftmost check box). To change the current column or its colour mapping, check the box beside it in the table. As before, click the "Apply" button in the intensity category to apply the changes to the shape.

We can also display the two columns together, as a composite image. To do this, check the "Render as composite" box in the Intensity category, and then adjust the alpha levels in the columns table (see figure). The second column of check boxes in the table determines whether a data column will be part of the composite or not. When the image appears the way you want it in the preview window, click "Apply", and the 2D and 3D renderings will update to reflect the changes. Notice I've set the template image's colour map back to greyscale…

figure_6.png

Clipping

Rendering on a section is just one way to have a look inside a 3D volume. You can also use sections to clip the volume within a certain distance of the section plane. Say, for instance, we want to render the volume with its top chopped off. First of all, go back to the Tree Panel and set the rendering mode back to "As volume". Next, expand the attribute node for your section set (mine's called, originally, "New Section Set"), and enter "1000" for the "ClipDistDown" attribute. This tells the render to clip the image at 1mm above, and 1m below, the section plane (the latter being well beyond its bounds). Finally, check the "ApplyClip" attribute. The 3D shape will be updated:

figure_7.png

Note that you can now change the current section in the Section Set Panel, and the clip will change accordingly. Try scrolling through the sections to see how the image changes (as above, right).

Hint: Sections render with a transparent colour by default. You can turn this off by changing the parent Shape Set's "FillSections" attribute.

Second Hint: Section clipping can be finicky, due mostly to bugs in the rendering engine. It's a safe bet to turn clipping off while doing other things; particularly when creating or removing windows.

Masking

Querying

Data operations

References

Bibliography
1. Tzourio-Mazoyer N, Landeau B, Papathanassiou D, Crivello F, Etard O, Delcroix N, Mazoyer B, Joliot M. Automated anatomical labeling of activations in SPM using a macroscopic anatomical parcellation of the MNI MRI single-subject brain. Neuroimage. 2002 Jan;15(1):273-89. [ PubMed ]
Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License