Difference between revisions of "Modules:OpenIGTLinkIF"

From Slicer Wiki
Jump to: navigation, search
m (Text replacement - "\[http:\/\/www\.slicer\.org\/slicerWiki\/index\.php\/([^ ]+) ([^]]+)]" to "$2")
 
(70 intermediate revisions by one other user not shown)
Line 1: Line 1:
 
[[Documentation|Return to Slicer Documentation]]
 
[[Documentation|Return to Slicer Documentation]]
__NOTOC__
+
<!--__NOTOC__-->
 +
 
 
===Module Name===
 
===Module Name===
MyModule
+
OpenIGTLink IF
  
 +
<center>
 
{|
 
{|
|[[Image:screenshotBlank.png|thumb|280px|Caption 1]]
+
|[[Image:Module_OopenIGTLinkIF_screenshot1.png|thumb|360px|Screenshot shows GUI of OpenIGTLink IF during volume reslicing based on the tracking data imported from the external program through OpenIGTLink.]]
|[[Image:screenshotBlank.png|thumb|280px|Caption 2]]
+
|[[Image:Module_OopenIGTLinkIF_NIT_robot.jpg|thumb|360px|Prototype integration of a neurosurgical robot and Slicer3 using OpenIGTLink, Junpei Arata and Hideo Fujimoto, Nagoya Institute of Technology, Japan]]
|[[Image:screenshotBlank.png|thumb|280px|Caption 3]]
 
 
|}
 
|}
 +
</center>
  
 
== General Information ==
 
== General Information ==
Line 18: Line 20:
  
 
===Authors, Collaborators & Contact===
 
===Authors, Collaborators & Contact===
* Junichi Tokuda: SPL, Brigham and Women's Hospital
+
* [http://www.na-mic.org/Wiki/index.php/User:Tokuda Junichi Tokuda]: SPL, Brigham and Women's Hospital
* Haiying Liu: SPL, Brigham and Women's Hospital
+
* Nobuhiko Hata: SPL, Brigham and Women's Hospital
  
 
===Module Description===
 
===Module Description===
The OpenIGTLink Interface Module is a program module that can handle network communications between  3D Slicer and external software / hardware using [http://www.na-mic.org/Wiki/index.php/OpenIGTLink OpenIGTLink] protocol. The module provides following functions:
+
The OpenIGTLink Interface Module is a program module for network communication with external software / hardware using [http://www.na-mic.org/Wiki/index.php/OpenIGTLink OpenIGTLink] protocol. The module provides following features:
  
*Data import: The module can import position, linear transform and image data from [http://www.na-mic.org/Wiki/index.php/OpenIGTLink/List| OpenIGTLink-compliant software / hardware] to the [http://www.na-mic.org/Wiki/index.php/NA-MIC/Projects/NA-MIC_Kit/MRML| MRML]] scene.
+
*Data import: The module can import position, linear transform and image data from [http://www.na-mic.org/Wiki/index.php/OpenIGTLink/List| OpenIGTLink-compliant software] to the [http://www.na-mic.org/Wiki/index.php/NA-MIC/Projects/NA-MIC_Kit/MRML| MRML] scene.
*Data export: The module can export linear transform and image data from 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.
 
*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.
 
*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.
 
*Slice driving: The module can control volume re-slicing plane based on linear transform in the MRML scene.
 +
 +
[[image:Slicer3_OpenIGTLinkIF_Architecture.png|thumb|center|500px|The figure shows an example schematic diagram where multiple devices are communicating with 3D Slicer through the OpenIGTLink Interface. Each connector is assigned to one of the external devices for TCP/IP connection. The connectors serve as interfaces between the external devices and the MRML scene to convert an OpenIGTLink message to a MRML node or vice versa. ]]
  
 
== Usage ==
 
== Usage ==
  
===Examples, Use Cases & Tutorials===
+
===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.
 +
 
 +
===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 [http://www.na-mic.org/Wiki/index.php/OpenIGTLink/Library The OpenIGTLink Library]. You can also obtain the binaries from the following links:
 +
* [http://wiki.na-mic.org/Wiki/images/8/8a/OpenIGTLinkExamples_Linux_x86_32.tgz For Linux (x86, 32-bit)].
 +
* [http://wiki.na-mic.org/Wiki/images/2/2e/OpenIGTLinkExamples_Linux_x86_64.tgz  For Linux (x86, 64-bit)].
 +
* [http://wiki.na-mic.org/Wiki/images/6/6d/OpenIGTLinkExamples_Win_x86_32.zip For Windows (32-bit)].
 +
* [http://www.na-mic.org/Wiki/images/3/3d/OpenIGTLinkExamples_Darwin_x86.tgz For Mac OS X (x86)]
 +
* [[Media:OpenIGTLinkExamples_Darwin_ppc.tgz |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 [http://www.slicer.org/DownloadSlicer.php/Nightly Download page for Slicer Nightly Build]. If you interested in building by your self, please see [[Slicer3:Build_Instructions|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.
 +
 
 +
[[Image:Slicer3_OpenIGTLinkIF__Startup.png|thumb|center|600px|]]
 +
 
 +
2. Open "Connectors" frame, and press "Add" button below the "Connectors" list to add a new connector
 +
 
 +
<center>
 +
{|
 +
|[[Image:Slicer3_OpenIGTLinkIF__Connectors.png|thumb|center|320px|]]
 +
|[[Image:Slicer3_OpenIGTLinkIF__Connectors_add.png|thumb|center|320px|]]
 +
|}
 +
</center>
 +
 
 +
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.
 +
 
 +
[[Image:Slicer3_OpenIGTLinkIF_Server_wait.png|thumb|center|320px|]]
 +
 
 +
 
 +
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.
 +
 
 +
<center>
 +
{|
 +
|[[Image:Slicer3_OpenIGTLinkIF_Visualization.png|thumb|center|320px|]]
 +
|[[Image:Slicer3_OpenIGTLinkIF_Visualization_locator_source.png|thumb|center|360px|]]
 +
|}
 +
</center>
 +
 
 +
 
 +
2. Then click "Show Locator" check button. The locator model shows up and move around in the 3D view.
 +
 
 +
[[Image:Slicer3_OpenIGTLinkIF_Visualization_locator.png|thumb|center|600px|]]
 +
 
 +
 
 +
===Tutorial 2: Importing Image Data from Imaging Simulator===
  
* Note use cases for which this module is especially appropriate, and/or link to examples.
+
====Step 1-3: Setting up 3D Slicer and simulators====
* Link to examples of the module's use
+
Follow Step 1-3 in Tutorial 1.
* Link to any existing tutorials
+
 
 +
====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====
 +
Once the image is successfully imported to MRML, you can display it in the 2D and 3D viewers.
 +
 
 +
 
 +
<br>
  
 
===Quick Tour of Features and Use===
 
===Quick Tour of Features and Use===
List all the panels in your interface, their features, what they mean, and how to use them. For instance:
+
* '''Connectors:'''
 +
** Connector panel is used to add, delete and edit connectors.
 +
* '''Data I/O Configurations:'''
 +
* '''Visualization / Slice Control:'''
  
* '''Input panel:'''
+
<br>
* '''Parameters panel:'''
 
* '''Output panel:'''
 
* '''Viewing panel:'''
 
  
 
== Development ==
 
== Development ==
  
 
===Dependencies===
 
===Dependencies===
 
+
The OpenIGTLink IF module requires [http://svn.na-mic.org/NAMICSandBox/trunk/OpenIGTLink The OpenIGTLink Library].
Other modules or packages that are required for this module's use.
+
The library is downloaded and built in Slicer3-lib directory automatically when you run Slicer3/Script/getbuildtest.tcl.
  
 
===Known bugs===
 
===Known bugs===
 
+
Follow this [http://na-mic.org/Mantis/main_page.php link] to the Slicer3 bug tracker.
Follow this [http://na-mic.org/Mantis/main_page.php link] to the Slicer3 bug tracker.  
 
 
 
 
 
  
 
===Usability issues===
 
===Usability issues===
Line 72: Line 152:
  
 
===Acknowledgment===
 
===Acknowledgment===
Include funding and other support here.
+
This work is supported by 1R01CA111288, 5U41RR019703, 5P01CA067165, 1R01CA124377,  5P41RR013218, 5U54EB005149, 5R01CA109246 from NIH. Its contents are solely the responsibility of the authors and do not necessarily represent the official views of the NIH.
  
 
===References===
 
===References===
Publications related to this module go here. Links to pdfs would be useful.
+
In revew ...

Latest revision as of 02:34, 27 November 2019

Home < Modules:OpenIGTLinkIF

Return to Slicer Documentation

Module Name

OpenIGTLink IF

Screenshot shows GUI of OpenIGTLink IF during volume reslicing based on the tracking data imported from the external program through OpenIGTLink.
Prototype integration of a neurosurgical robot and Slicer3 using OpenIGTLink, Junpei Arata and Hideo Fujimoto, Nagoya Institute of Technology, Japan

General Information

Module Type & Category

Type: Interactive

Category: Base

Authors, Collaborators & Contact

  • Junichi Tokuda: SPL, Brigham and Women's Hospital
  • Nobuhiko Hata: 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.
The figure shows an example schematic diagram where multiple devices are communicating with 3D Slicer through the OpenIGTLink Interface. Each connector is assigned to one of the external devices for TCP/IP connection. The connectors serve as interfaces between the external devices and the MRML scene to convert an OpenIGTLink message to a MRML node or vice versa.

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.

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:

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.

Slicer3 OpenIGTLinkIF Startup.png

2. Open "Connectors" frame, and press "Add" button below the "Connectors" list to add a new connector

Slicer3 OpenIGTLinkIF Connectors.png
Slicer3 OpenIGTLinkIF Connectors add.png

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.

Slicer3 OpenIGTLinkIF Server wait.png


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.

Slicer3 OpenIGTLinkIF Visualization.png
Slicer3 OpenIGTLinkIF Visualization locator source.png


2. Then click "Show Locator" check button. The locator model shows up and move around in the 3D view.

Slicer3 OpenIGTLinkIF Visualization locator.png


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

Once the image is successfully imported to MRML, you can display it in the 2D and 3D viewers.



Quick Tour of Features and Use

  • Connectors:
    • Connector panel is used to add, delete and edit connectors.
  • Data I/O Configurations:
  • Visualization / Slice Control:


Development

Dependencies

The OpenIGTLink IF module requires The OpenIGTLink Library. The library is downloaded and built in Slicer3-lib directory automatically when you run Slicer3/Script/getbuildtest.tcl.

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 supported by 1R01CA111288, 5U41RR019703, 5P01CA067165, 1R01CA124377, 5P41RR013218, 5U54EB005149, 5R01CA109246 from NIH. Its contents are solely the responsibility of the authors and do not necessarily represent the official views of the NIH.

References

In revew ...