Modules:OpenIGTLinkIF-Documentation-3.4
Return to Slicer 3.4 Documentation
Module Name
OpenIGTLink IF
General Information
Module Type & Category
Type: Interactive
Category: IGT
Authors, Collaborators & Contact
- Junichi Tokuda, Ph.D.: SPL, Brigham and Women's Hospital
- Haiying Liu, Brigham and Women's Hospital
- Nobuhiko Hata, Ph.D.: SPL, Brigham and Women's Hospital
Module Description
The OpenIGTLink Interface Module is a program module for network communication with external software / hardware using OpenIGTLink protocol. The module provides following features:
- Data import: The module can import position, linear transform and image data from OpenIGTLink-compliant software to the MRML scene.
- Data export: The module can export linear transform and image data from the MRML scene to external software.
- Multi-connection: The module can manage multiple OpenIGTLink connections at the same time.
- Locator visualization: The user can choose one of linear transforms in the MRML scene to visualize its position and orientation in the 3D space.
- Slice driving: The module can control volume re-slicing plane based on linear transform in the MRML scene.
Usage
Example Applications and Use Cases
- MRI-compatible Robot System (BRP Project between BWH, Johns Hopkins University and Acoustic MedSystems Inc., "Enabling Technologies for MRI-Guided Prostate Interventions")
- The 3D Slicer was connected to the MRI-compatible Robot by using OpenIGTLinkIF to send target position and to get current robot position. It was also connected to the MRI scanner to control scan plane for real-time image and receive MR images from the scanner.
- Neurosurgical Robot Project(Nagoya Institute of Technology, Japan)
- The 3D Slicer was connected to the optical tracking system (Optotrak, Northern Digital Inc.) to acquire current position of the end-effector of the robot.
Quick Tour of Features and Use
- Connectors:
- Connector panel is used to add, delete and edit connectors.
- Data I/O Configurations:
- Visualization / Slice Control:
Tutorials
- Tutorial 1: Importing Tracking Data from Tracking Simulator
- Tutorial 2: Importing Image Data from Imaging Simulator
- Tutorial 3: Reslicing 3D volume by tracking tool
- Tutorial 4: Exporting transform data from 3D Slicer using OpenIGTLink to external software
Tutorial 1: Importing Tracking Data from Tracking Simulator
Step 1: Simulators
First, we prepare simulators to test connections between the 3D Slicer and external programs. The simulators come with The OpenIGTLink Library. You can also obtain the binaries from the following links:
- For Linux (x86, 32-bit).
- For Linux (x86, 64-bit).
- For Windows (32-bit).
- For Mac OS X (x86)
- For Mac OS X (PPC).
Step 2: 3D Slicer
The OpenIGTLink Interface module is included in the nightly release. The binaries can be found at Download page for Slicer Nightly Build. If you interested in building by your self, please see Bulid Instructions.
Step 3: Connecting the Tracker Client
Before connect the simulator to the 3D Slicer, we configure the OpenIGTLink Interface as a "server" by the following steps:
1. Select "OpenIGTLinkIF" from "Modules:" menu. The OpenIGTLink IF will show up on the 3D Slicer window.
2. Open "Connectors" frame, and press "Add" button below the "Connectors" list to add a new connector
3. Once the connector is created, choose "Server" check box in the "Type" option, then clinck "Active" check box. Now the Slicer is ready to accept connections through Open IGT Link.
If the "Status" column in the connector list indicates that the connector is waiting, it is ready to connect the client program to the 3D Slicer.
Step 4: Visualizing the tracking data
1. Open "Visualization / Slice Control", and choose "Tracker (TRANSFORM)" from "Locator Source" menu.
2. Then click "Show Locator" check button. The locator model shows up and move around in the 3D view.
Tutorial 2: Importing Image Data from Imaging Simulator
Step 1-3: Setting up 3D Slicer and simulators
Follow Step 1-3 in Tutorial 1.
Step 4: Connecting the Imager Client
To connect the tracking simulator, open a terminal (Linux and Mac) or command prompt (Windows), move to the directory containing simulator programs downloaded in Step 1, and run it. If you built the OpenIGTLink library by yourself, the binaries for the example programs (simulators) are in <OpenIGTLink-build>/bin.
$ cd <simulator directory>
To send dummy image data to the Slicer running on localhost with frame rate of 10 fps, run ImagerClieant.
$ ./ImagerClient localhost 18944 10 <sample image directory>
The sample images comes with the simulator program. If you build the OpenIGTLink library, the sample images are located in <source directory>/Examples/Imager/img/. If you are using binary version of the simulator, the sample images are in "img/" directory.
As we have seen in Tutorial 1, the "Status" column indicates "ON", if the client program connects to the 3D Slicer. If the image data is correctly received, "IMAGE" data shows up in the Data I/O Configuration tree (in the Data I/O configuration tab).
Step 5: Visualize the received image in the 2D viewer
Once the image is successfully imported to MRML, you can display it in the 2D and 3D viewers by the following steps. In the "Visualization" section, choose real-time image source from "RT image source" drop-down menu, after you receive the first image from the client. The name of image source is defined by the name of the OpenIGTLink message. In case of the example program, this is "ImagerClient".
Then choose image plane driver from red pull-down menu bellow the "RT image source" menu. You will see the real-time image in the 2D image viewer.
Step 6: Visualize the received image in the 3D viewer
Check the "Orient" button bellow the image plane driver menu (indicated by red circle (1) in the screenshot bellow). If you activate the reslice image in the 3D viewer by clicking the button with "eye" icon in the 2D image viewer panel (indicated by red circle (2) in the screenshot bellow) , you can see the real-time image at the scanning plane in the 3D viewer.
Tutorial 3: Reslicing 3D volume by tracking tool
Step 1-4: Setting up 3D Slicer and tracking simulators
Follow Step 1-4 in Tutorial 1.
Step 4: Loading volume data
See Data loading documentation page.
Step 5: Reslice in Axial/Sagittal/Coronal
Goto "Visualization / Slice Control" section in the OpenIGTLink IF module and choose "Locator" from image plane driver drop-down menu (or just simply press "Locator All" button to turn all menus to Locator. You will see the section(s) of the volumes at the needle tip in Axial / Sagittal / Coronal plane in the 2D viwer(s). You may also be able to see them in the 3D space by clicking the "eye" buttons in the 2D viewer panels. (NOTE: Reslicing function usually increases the CPU load. Low tracking frame rate (say 1-2 fps) is recommended.)
Step 6: Reslice in parallel and perpendicular to the tracking tool
To cut the volume in parallel or perpendicular to the tracking tool, check "Orient" bellow the driver drop-down menues in the "Visualization" section.
Tutorial 4: Exporting transform data from 3D Slicer using OpenIGTLink to external software
Step 1: Preparing client software to receive transform data
Please follow the Step 1 in Tutorial 1. The package contains ReceiveClient, which receives OpenIGTLink transform messages through the network and displays their value on the console.
Step 2: Creating a transform node
The OpenIGTLink IF module can export any linear transform node in the scene. In this tutorial, we manually create a linear transform node from the Transforms module.
To create a linear transform node, open the Transforms module, and choose "Create New LinearTransform" from the "Transform Node" drop-down menu.
Step 3: Setting up the connector
Before connect the simulator to the 3D Slicer, we configure the OpenIGTLink Interface as a "server" by the following steps:
1. Select "OpenIGTLinkIF" from "Modules:" menu. The OpenIGTLink IF will show up on the 3D Slicer window.
2. Open "Connectors" frame, and press "Add" button below the "Connectors" list to add a new connector
3. Once the connector is created, choose "Server" check box in the "Type" option, then clinck "Active" check box. Now the Slicer is ready to accept connections through Open IGT Link.
If the "Status" column in the connector list indicates that the connector is waiting, it is ready to connect the client program to the 3D Slicer.
Step 4: Export configuration
You can specify the transform node to export through OpenIGTLink in "Data I/O Configuration" section in the OpenIGTLink module.
The Data I/O Setting shows a list of connectors in a tree widget. In this tree, names of the connecters are listed as second-level branches. Each connector has "IN" and "OUT" branches to bundle MRML nodes that hold importing and exporting data. The OpenIGTLink IF module monitors MRML nodes listed in "OUT branches, and if a node is updated, the OpenIGTLink detects the update, generates OpenIGTLink message and send it through the connector. So if you want to export MRML data from Slicer through a specific connector, you simply add the MRML node in the "OUT" branch of the connector.
If you successfully follow the previous step of this tutorial, you will see the name of the connector created in the previous step (Step 3) in the tree. To add a MRML node to the "OUT" branch, right-click the "OUT" branch to pull down a menu of currently available MRML node for exporting in the scene (See the right screenshot bellow). You can choose one of them by clinking an item on the menu.
Step 5: Connecting the Receive Client
Open a terminal window, go to the directory that contains the ReceiveClient command and run the following command:
# ./ReceiveClient <hostname> <port number>
The default port number is 18944.
If the client software successfully connect to 3D Slicer, the status in the OpenIGTLink IF module changes to "Connected."
Step 6: Exporting linear transform
Now the OpenIGTLink IF module is monitoring the linear transform node you have specified. To export data, simply go to the "Transforms" module and change values in the linear transform using slider interfaces. You should see ReceiveClient outputs 4x4 matrices exported from the linear transform node.
Development
Dependencies
The OpenIGTLink IF module requires The OpenIGTLink Library. The library comes with the binary package of 3D Slicer 3.4. If you build Slicer by yourself, Slicer3/Script/getbuildtest.tcl will download and build the library in Slicer3-lib directory automatically.
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
See ViweCV page for the source code.
Links to documentation generated by doxygen.
More Information
Acknowledgment
This work is supported by 1R01CA111288, 5U41RR019703, 5P01CA067165, 1R01CA124377, 5P41RR013218, 5U54EB005149, 5R01CA109246 from NIH. This study is also in part supported by NSF 9731748, CIMIT, Intelligent Surgical Instruments Project of METI (Japan).
References
- Tokuda J, Fischer GS, Papademetris X, Yaniv Z, Ibanez L, Cheng P, Liu H, Blevins J, Arata J, Golby A, Kapur T, Pieper S, Burdette EC, Fichtinger G, Tempany CM, Hata N, OpenIGTLink: An Open Network Protocol for Image-Guided Therapy Environment, Int J Med Robot Comput Assist Surg, 2009 (In print)
