Modules:FourDImage-Documentation-3.5

From Slicer Wiki
Jump to: navigation, search
Home < Modules:FourDImage-Documentation-3.5

Return to Slicer 3.5 Documentation

Gallery of New Features


Module Name

4D Image Module

Figure 1. Screenshot of 4D Image Module

General Information

Module Type & Category

Type: Interactive

Category: 4D

Authors, Collaborators & Contact

Module Description

The 4D Image module is designed to handle a time-series of 3D volume images (4D image), e.g. fMRI, cardiac images, dynamic contrast-enhanced (DCE) images in 3D Slicer. You can do:

  • Load and save a series of 3D volume images from a directory, which contains multiple volume images.
  • Scroll through a time-series.
  • Edit (add, delete and insert) frames in a time series.

The core component of 4D Image module is Time Series Bundle Node, which is defined in vtkMRMLTimeSeriesBundleNode.h and vtkMRMLTimeSeriesBundleNode.cxx. This special MRML node is designed to hold pointers to scalar volume nodes in the time series, and in addition, two scalar volume nodes for visualization. The two visualization scalar nodes contain byte arrays that are displayed in the 2D and 3D viewers; whenever the user scrolls the time-series, the module copies byte arrays from the scalar volume node at the current time point in the series to the nodes for visualization. This approach gives a flexibility to use the existing frame works of image processing for each scalar volume nodes in the time-series data. The reason why it holds two visualization scalar nodes is that one is used for background and the other is used for foreground for comparing two volumes at different time points.

Usage

Quick Tour of Features and Use

  • Active 4D Bundle panel: This panel allows choosing the active time series bundle node from MRML scene. If you choose "Create New TimeSeriesBundle", the module creates a time series bundle node with no volumes. You can add volumes in the Editor panel.
  • Load / Save panel: This panel is used to load and save time-series of volume images. To load a time-series of volume images, first specify the directory that contains the volumes from "Brows Input Directory" dialog box, and then press "Load Series" button.
  • Control panel: This panel provides slider user interfaces to scroll the images in time-dimension. The panel allows scrolling foreground and background images independently. The module can also automatically scroll the images with interval specified in the entry in the panel.
  • Editor panel: The panel allows editing the volume images in the time series. The users can move, insert and delete volume images.

Tutorials

This document will demonstrates:

  • Basic operations (loading, viewing and editing)
  • Importing 4D data from external software using OpenIGTLink


Basic operations (loading, viewing and editing)

Step 1: Open the module

Choose 4D Imaging in the category of "4D".

Figure 2. 4D Image Module starting screen

Step 2: Load image

Open Load / Save panel, and click Browse Input Directory button with a folder icon. Slicer will show a dialog box to choose a directory that contains volume images. After choosing a directory, press OK button on the dialog box and press Load Series button. 3D Slicer will pop up the progress window and start loading images. It takes for a while, especially if you have DICOM images in the directory.

Figure 3. A dialog box for directory selection
Figure 4. 3D Slicer shows progress window while loading a series of images from the specified directory.

Step 3: Scroll image

You can scroll the 4D image in Control panel in the module. The panel has two scroll sliders (Figure 5 (A)), which allow you to scroll in the foreground and background images independently, even if you are viewing the same time-series in both layers. The module automatically scrolls the 4D image with specified interval, when one of the automatic scroll button (Figure 5 (B)) is pressed. While scrolling, the icon on the button changes as shown in Figure 6. To stop the automatic scroll, just press the same button again.

Figure 5. Scrolling the 4D image in the time direction using Control panel
Figure 6. The icon changes while the automatic scrolling is active.

Step 4: Edit time-series

The Edit panel is used to move, insert and delete images in the time-series (Figure 7).

Figure 7. Edit panel in 4D Image module.

To move an images on the list, select an image on the list (Figure 8), and then press Move up or Move down button bellow the list (Figure 9).

Figure 8. Selecting an image to move.
Figure 9. Moving the image up by pressing Move up button.

To insert an image in the MRML scene to the time series, choose the image node from the Add node pull-down menu (Figure 10, 11), and press Add button (Figure 12).

Figure 10. The pull-down menu to choose an image to insert.
Figure 11. Choosing the image from the menu.
Figure 12. Inserting the image into the time-series by pressing Add button.

To remove an image from the time series, select the image on the list (Figure 13) and click Remove button(Figure 14).

Figure 13. Selecting an image to remove form the time-series.
Figure 14. Removing the image from the time-series by pressing Remove button.

Importing 4D data from external software using OpenIGTLink

Step 1: Setup example data and simulator to send the 4D data

Before start, please download and compile OpenIGTLink Library. The library is also available in the Slicer3-lib/OpenIGTLink-build directory.

The following tutorial uses an example client program and data are available in NA-MIC SnadBox subversion repository. In Linux and Mac OS X, you can obtain the source code and data by using the following command:

 $ svn co http://svn.na-mic.org/NAMICSandBox/trunk/4DModules/Examples Examples

I recommend to create a building directory next to the source directory. Use CMake to generate a Makefile.

 $ mkdir Examples-build
 $ cd Examples-build
 $ cmake -DOpenIGTLink_DIR=<OpenIGTLink binary directory> ../Examples

If the example program is successfully complied, you can find 4DClient in the building directory.


Step 2: Configure OpenIGTLink IF

After launching 3D Slicer on the same machine as the client program, open OpenIGTLink IF module (Figure 15) and create a connector (Figure 16).

Figure 15. OpenIGTLinkIF module in 3D Slicer.
Figure 16. Adding a connector by pressing Add button in OpenIGTLinkIF module.

Configure the connector it as a server(Figure 17). In this tutorial, we use port number 18944 (default). Then click Active check box to activate (Figure 18). The status shows Wait, once the connector becomes active.

Figure 17. Configuring the connector as a server by clicking Server check box.
Figure 18. Activating the connector by clicking Active check box. The status becomes Wait.

Step 3: Run the client program to transfer the 4D data

Run the client program from a terminal with following arguments:

$ ./4DClient localhost 18944 2 ../Examples/img/

The client program sends 5 consecutive volume images to 3D Slicer. While the client program is sending the images, the status field in OpenIGTLInkIF indicate Connected (Figure 19). After the client program stops, check the image nodes on Data module. If 3D Slicer successfully receives the volume images, it shows scalar volume nodes named Heart-00? in the scene (Figure 20).

Figure 19. The status field indicates that the client and the connector are connected.
Figure 20. The images transfered from the client are listed in Data module.

Step 4: Create and edit time-series bundle

Once you confirm that the images are in the scene, open 4D Image module and create a new bundle node by choosing Create New TimeSeriesBundle from the Active 4D Bundle pull-down menu.

Although you can manually add the images one by one as we did in the tutorial above, the module also allows specifying multiple nodes in the MRML by their name format. The format should be described in the same format used in printf() function in C. In the Import Frames frame in Editor panel, put "heart128-%03d" in Node name field and set "0" and "4" in the Range fields. Once Import button is pressed, the module adds the images into the time-series list.



Development

Dependencies

This module does not require any other module. To import 4D image through network as demonstrated in the tutorial, you need to have OpenIGTLink IF module.

Known bugs

Follow this link to the Slicer3 bug tracker.


Usability issues

Follow this link to the Slicer3 bug tracker. Please select the usability issue category when browsing or contributing.

Source code & documentation

Customize following links for your module.

Links to documentation generated by doxygen.


More Information

Acknowledgment

This work is partly supported by NIH R21CA116271-02 (PI: Hiroto Hatabu), P01CA067165 (PI: Ferenc Jolesz), U41RR019703 (PI: Ferenc Jolesz), U54EB005149 (PI: Ron Kikinis) and P41RR013218-12 (PI: Ron Kikinis).

References