Slicer3:FAQ

User FAQ : installation & general use

Is slicer3 ready for end users yet?

Yes! See the home page.

DLL Problems on Windows

I just download the 3D Slicer binaries for Windows and unpacked it. When I doubleclicked the file "slice2-win32-x86.ext", it gave out the error message can't find package vtk while executing "package require vtk" invoked from within "set::SLICER(VTK_VERSION) [package require vtk]" (file "C:/slicer2/Base/tck/Go.tck" line 483).

We've seen this sort of thing happen when you have incompatible dll's installed. E.g. so programs will install a vtkCommon.dll into your window system folder and windows tries to use it instead of the one that comes with windows. You could try doing a search for vtk*.dll in your system and remove or rename any that are not in slicer as a test.

User FAQ : registration

How do I fix a wrong image orientation? / My image appears upside down / facing the wrong way / I have incorrect/missing axis orientation

• Problem: My image appears upside down / flipped / facing the wrong way / I have incorrect/missing axis orientation
• Explanation: Slicer presents and interacts with images in physical space, which differs from the way the image is stored by a separate transform that defines how large the voxels are and how the image is oriented in space, e.g. which side is left or right. This information is stored in the image header, and different image file formats have different ways of storing this information. If Slicer supports the image format, it should read the information in the header and display the image correctly. If the image appears upside down or with distorted aspect ratio etc, then the image header information is either missing or incorrect.
• Fix: You can correct the voxel dimensions and the image origin in the Info tab of the Volumes module, and you can reorient images via the Transforms module. Reorientation however will work only if the incorrect orientation involves rotation or translation. If axes are flipped (e.g. if left & right are flipped because the x-axis direction is defined incorrectly), then there is no tool in Slicer to alter that. This is by design; Slicer does not want to offer tools to (inadvertedly) manipulate image information that should be static and could lead to misrepresented image data.
• However fixing incorrect orientations such as flipped axes is not that hard and can be done with the help of Slicer:

1. load the image into slicer (Load Volume, Add Data,Load Scene..)

2. save the image back out as NRRD (.nhdr) format.

3. open the .nhdr with a text editor of your choice. You should see a line that looks like this:

 space: left-posterior-superior
 sizes: 448 448 128
 space directions: (0.5,0,0) (0,0.5,0) (0,0,0.8)

4. the three brackets ( ) represent the coordinate axes as defined in the space line above, i.e. the first one is left-right, the second anterior-posterior, and the last inferior-superior. To flip an axis place a minus sign in front of the respective number, which is the voxel dimension. E.g. to flip left-right, change the line to

 space directions: (-0.5,0,0) (0,0.5,0) (0,0,0.8)

5. alternatively if the entire orientation is wrong, i.e. coronal slices appear in the axial view etc., you may easier just change the space field to the proper orientation. Note that Slicer uses RAS space by default, i.e. first (x) axis = left-right, second (y) axis = posterior-anterior, third (z) axis = inferior-superior

6. save & close the edited .nhdr file and reload the image in slicer to see if the orientation is now correct.

How do I fix incorrect voxel size / aspect ratio of a loaded image volume?

• Problem: My image appears distorted / stretched / with incorrect aspect ratio
• Explanation: Slicer presents and interacts with images in physical space, which differs from the way the image is stored by a set of separate information that represents the physical "voxel size" and the direction/spatial orientation of the axes. If the voxel dimensions are incorrect or missing, the image will be displayed in a distorted fashion. This information is stored in the image header. If the information is missing, a default of isotropic 1 x 1 x 1 mm size is assumed for the voxel.
• Fix: You can correct the voxel dimensions and the image origin in the Info tab of the Volumes module. If you know the correct voxel size, enter it in the fields provided and hit RETURN after each entry. You should see the display update immediately. Ideally you should try to maintain the original image header information from the point of acquisition. Sometimes this information is lost in format conversion. Try an alternative converter or image format if you know that the voxel size is correctly stored in the original image. Alternatively you can try to edit the information in the image header, e.g. save the volume as (NRRD (.nhdr) format and open the ".nhdr" file with a text editor.

How do I register images that are very far apart / do not overlap

• Problem: when you place one image in the background and another in the foreground, the one in the foreground will not be visible (entirely) when switching bak & forth
• Explanation:Slicer chooses the field of view (FOV) for the display based on the image selected for the background. The FOV will therefore be centered around what is defined in that image's origin. If two images have origins that differ significantly, they cannot be viewed well simultaneously.
• Fix: recenter one or both images as follows:

1. Go to the Volumes module,

2. Select the image to recenter from the Actrive Volume menu

3. Select the Info tab.

4. Click the Center Volume button. You will notice how the image origin numbers displayed above the button change. If you have the image selected as foreground or background, you may see it move to a new location.

5. Repeat steps 2-4 for the other image volumes

6. From the slice view menu, select Fit to Window

7. Images should now be roughly in the same space. Note that this re-centering is considered a change to the image volume, and Slicer will mark the image for saving next time you select Save.

How do I register a DWI image dataset to a structural reference scan? (Cookbook)

• Problem: The DWI/DTI image is not in the same orientation as the reference image that I would like to use to locate particular anatomy; the DWI image is distorted and does not line up well with the structural images
• Explanation: DWI images are often acquired as EPI sequences that contain significant distortions, particularly in the frontal areas. Also because the image is acquired before or after the structural scans, the subject may have moved in between and the position is no longer the same.
• Fix: obtain a baseline image from the DWI sequence, register that with the structural image and then apply the obtained transform to the DTI tensor. The two chief issues with this procedure deal with the difference in image contrast between the DWI and the structural scan, and with the common anisotropy of DWI data.
• you can find example cases of DWI registration in the Slicer Registration Case Library, which includes example datasets and step-by-step instructions. Find an example closest to your scenario and perform the registration steps recommended there.

Overall Strategy

1. if voxel size ratios are 1.5 or greater:
   1. Resample the T2 reference to isotropic voxel size:Resample Volume module or Resample Scalar/Vector/DWI Volume module
   2. Resample the DWI (not DTI) to isotropic voxel size: Resample Scalar/Vector/DWI Volume module. Note that depending on the size of the original DWI, the isotropic volumes can become very large files. Make sure you have sufficient RAM and disk space available.
2. Extract the baseline and DTI from the isotropic DWI: Diffusion Tensor Estimation module. Also select to generate a mask image.
3. Register the DWI baseline scan to the reference. Preferred structural reference is a T2-weighted scan. If no T2 is available use the next closest contrast.
   1. If initial misalignment (rotation/translation) is significant (more than ~20% of the FOV), consider a preliminary manual alignment first, using the Transforms module. If the final target is a T1 but a T2 is available, use the T2 as reference for the DWI, but then perform a second T2-T1 or T1-T2 registration.
   2. try BRAINSfit module as first method of choice
   3. masking is recommended for better results. We have a mask for the DWI but not the T2 reference. To obtain a mask for the reference
      • you can either perform a prelim. registration without masking, then apply this transform to the DWI mask
      • you can obtain a mask from another scan (e.g.T1, via the skull stripping or other segmentation tool) and perform a registration to the reference
      • you can try and obtain a mask for the reference directly, via
4. Resample the DTI tensor with above transform, using the dedicated Resample DTIVolume module.

Procedures

• Note: below the step-by-step cookbook from a typical DWI case in the Slicer Registration Case Library. This assumes a T2 reference. If voxel anisotropy is not a concern, you may skip phases I-III.
• Phase I: resample T2 to isotropic voxel size

1. 1. original T2 has 0.5 x 0.5 x 3 mm voxel size, which we resample to 1 x 1 x 1 mm
   2. open Filtering / Resample Scalar Volume module
   3. Spacing: enter 1,1,1
   4. Interpolation: check hamming
   5. Input Volume: select T2raw, Output Volume: create new, rename to "T2"
   6. click: Apply

• Phase II: Manually align DWI_raw to T2

1. open Data module
2. in MRML tree, select the "Scene" node, then right click & select "Insert Transform Node"
3. click on MRML Node Inspector and rename Xform node to "Xf0_DWI_init"
4. drag DWI_raw into the "Xf0_DWI_init" node
5. go to "Transforms" module
6. select T2 as background and DWI_raw as foreground, set fading slider halfway
7. manually adjust transform to align the two volumes, particularly LR rotation and IS translation
8. Save
9. go to Filtering / Resample Scalar/Vector/DWI module
10. Input Volume: "DWI_raw", Reference Volume: "T2", Output Volume: "create new Diffusion Weighted Volume", rename to "DWI_Xf0"
11. Transform Node: select "Xf0_DWI_Init"
12. Click: Apply
13. this will correct both the initial misalignment and the anisotropy
14. save new DWI_Xf0 to disk
15. depending on RAM of your machine, consider deleting the original DWI_raw node

• Phase III: DWI -> DTI

1. open "Diffusion Tensor Estimation" module
2. Input DWI Volume: DWI_Xf0, Output DTI Volume: create new, rename to "DTI"
3. Output Baseline: create new, rename to "DTI_base"
4. Otsu Threshold Mask: create new, rename to "DTI_mask"
5. Estimation Parameters: reduce Otsu Omega Threshold" to 0.3
6. check boxes for Remove Islands and Apply Mask
7. Click: Apply

• Phase IV: Register DTI (unmasked)

1. open Registration : BrainsFit module (presets: Xf1_DTI-T2_unmasked)
   1. Registration Phases:
   2. set T2 as fixed and DTI_base as moving image
      1. select/check Initialize GeometryCenter Align
      2. select/check Include Rigid registration phase
      3. select/check Include ScaleVersor3D registration phase
      4. select/check Include Affine registration phase
      5. select/check Include BSpline registration phase
   3. Output Settings:
      1. select a new transform "Slicer BSpline Transform", rename to "Xf1_DTI-T2_unmasked"
      2. select a new volume "Output Image Volume, rename to "DT_base_Xf1"
   4. Registration Parameters: increase Number Of Samples to 200,000
   5. Registration Parameters: set Number Of Grid Subdivisions to 5,5,3
   6. Leave all other settings at default
   7. click: Apply; runtime < 1 min.

• Phase V: Resample DTI_mask (presets: DTI_mask_Xf1)
  • we use the above Xform to produce a mask for the T2.

1. Open Resample Scalar/Vector/DWI Volume module
   1. Input Volume: DTI_mask; Output volume: create new volume, rename to "DTI_mask_Xf1"
   2. Transform Node: "Xf1_DTI-T2_unmasked"
   3. select/check: output-to-input
   4. Interpolation Type: select: nn
   5. click: Apply
   6. Go to Volumes module, select the new "DTI_mask_Xf1", in the Info tab, check the Labelmap box

• Phase VI:REGISTER DTI TO T2 with masking

1. open Registration : BrainsFit module (presets: Xf2_DTI-T2_masked)
   1. set T2_Xf1 as fixed and DTI_baseline as moving image
      1. select/check Include Rigid registration phase
      2. select/check Include ScaleVersor3D registration phase
      3. select/check Include Affine registration phase
      4. select/check Include BSpline registration phase
   2. Output BSpline Transform: create new , rename to "Xf2_DTI-T2_masked"
   3. Output Volume: create new, rename to "DTI_base_Xf2"
   4. Registration Parameters: increase Number Of Samples to 200,000
   5. Registration Parameters: set Number Of Grid Subdivisions to 7,7,5
   6. Control of Mask Processing
      1. select/check: ROI (rightmost box)
      2. Input Fixed Mask: select "DTI_mask_Xf1"
      3. Input Moving Mask: select "DTI_mask"
   7. Leave all other settings at default
   8. click: Apply; runtime < 1 min.

• Phase VII: Resample DTI

1. Load the combined transform (Add Data)
2. Open the Resample DTI Volume module (found under: All Modules)
   1. Input Volume: select DTI
   2. Output Volume: select New DTI Volume, rename to DTI_Xf2
   3. Reference Volume: select T2
   4. Transform Parameters: select transform "Xf2_DTI-T2_masked
   5. check box: output-to-input
   6. Leave all other settings at defaults
   7. Click Apply; runtime ~ 2 min.
3. Go to the Volumes module, select the newly produced DTI_Xf2 volume
4. under the Display tab, select Color Orientation from the Scalar Mode menu
5. set T1 as background and new DTI_Xf2 volume as foreground
6. Set fade slider to see DTI overlay onto the T2 image

Caveats

• In the BRAINSfit registration step
  • if images are not already closely aligned, check boxes to include "Rigid" & "ScaleVersor3D" phases
  • always check boxes for "Affine" and "BSpline" phases
  • remember to select "Slicer BSpline Transform" and "Output Image Volume" in Output Settings
  • reduce default grid size settings to 5,5,5 or similar, depending on level of distortion
  • increase sample points to 200,000
  • registration will take 2-4 minutes, depending on CPU and grid size setting
  • upon completion: drag the result volume back out from the result transform node to avoid confusion: since the transform contains a BSpline, moving a volume inside the node will not show an effect
  • when using masks: remember that 2 masks for both fixed and moving are required. The moving mask usually comes from the DTI estimation, the fixed mask can be obtained separately or via a prior (unmasked) registration that then allows to resample the DTI mask and thus produce a fixed mask.
• DTI resampling
  • if the DTI has voxel anisotropy of ratio 3 or greater, consider isotropic resampling of DWI first (see * case 3 for details.
  • use the dedicated Resample DTI Volume node (under All Modules)
  • in the 'Resample DTI Volume, make sure to check the "output-to-input" box in the Transform Parameters box. This will execute the affine transform first and the BSpline second.
  • always set a Reference Volume. This will be the T1 or T2 baseline to which the DTI is registered. Check the resolution of the reference: if the image is very large (e.g. 512 x 512 x 100 etc.) you may get memory problems trying to resample the 4D tensor volume. In that case first subsample the reference scan (e.g. to 1x1x1) and the resample the DTI into this new space
  • validate the resulting resampled DTI using Color Orientation in the Volumes/Display settings. Make sure the FOV is not clipped and there is no "color cast" indicating blurring artifacts from anisotropic DTI voxels.

Can I manually adjust or correct a registration?

• Problem: obtained registration is insufficient
• Explanation: The automated registration algorithms (except for fiducial and surface registration) in Slicer operate on image intensity and try to move images so that similar image content is aligned. This is influenced by many factors such as image contrast, resolution, voxel anisotropy, artifacts such as motion or intensity inhomogeneity, pathology etc, the initial misalignment and the parameters selected for the registration.
• Fix: you can adjust/correct an obtained registration manually, within limits. As outlined below. Your first try however should be to obtain a better automated registration by changing some of the input and/parameters and then re-run. Some guidelines on this are listed here.
  • Manual Adjustment: If the transform is linear, i.e. a rigid or affine transform, you can access the rigid components (translation and rotation) of that transform via the Transforms module.
    • 1. In the Data module, drag the image volume inside the registration transform node
      2. Select the views so that the volume is displayed in the slice views
      3. Go to the Transforms module and adjust the translation and rotation sliders to adjust the current position. To get a finer degree of control, enter smaller numbers for the translation limits and enter rotation angles numerically in increments of a few degrees at a time

What's the difference between the various registration methods listed in Slicer?

Most of the registration modules use the same underlying ITK registration algorithm for cost function and optimization, but differ in implementation on parameter selection, initialization and the type of image toward which they have been tailored. To help choose the best one for you based on the method or available options, an overview of all registration methods incl. a comparison matrix can be found here.
To help choose based on a particular image type and content, you will find many example cases incl. step-by-step instructions and discussions on the particular registration challenges in the Slicer Registration Library. The library is organized in several different ways, e.g. consult this sortable table with all cases and the method used.
There is also a brief overview within Slicer that helps distinguish: Select the Registration Welcome option at the top of the Modules/Registration menu.

What's the purpose of masking / VOI in registration?

• Problem: What does the masking option in some of the registration modules accomplish ?
• Explanation: The masking option is a very effective tool to focus the registration onto the image content that is most important. It is often the case that the alignment of the two images is more important in some areas than others. Masking provides the opportunity to specify those regions and make the algorithm ignore the image content outside the mask. This does not mean that the rest is not registered, but rather that it moves along passively, i.e. areas outside the mask do not actively contribute to the cost function that determines the quality of the match. Note the mask defines the areas to include, i.e. to exclude a particular region, build a mask that contains the entire object/image except that region.
• Note: masking within the registration is different from feeding a masked/stripped image as input, where areas of no interest have been erased. Such masking can still produce valuable results and is a viable option if the module in question does not provide a direct masking option. But direct masking by erasing portions of the image content can produce sharp edges that registration methods can lock onto. If the edge becomes dominant then the resulting registration will be only as good as the accuracy of the masking. That problem does not occur when using masking option within the module.
• The following modules currently (v.3.6.1) provide masking:
  • BRAINSFit
    • found under: Masking Options tab
    • requires mask for both fixed and moving image
    • has option to automatically generate masks
    • some initialization modes (CenterOfHeadAlign) will not work in conjunction with masks
  • Expert Automated Registration
    • found under: Advanced Registration Parameters tab
    • requires mask for fixed image only
  • Robust Multiresolution Affine
    • found under: Optional tab
    • requires mask for fixed image only
    • provides option to define a mask as a box ROI
  • BRAINSDemonWarp
    • found under: Mask Options tab
    • requires mask for both fixed and moving image
    • has option to automatically generate masks

Developer FAQ

Where can I find out about writing code for slicer3?

The Developers page has lots of information.