Difference between revisions of "OpenIGTLink/Matlab"

From NAMIC Wiki
Jump to: navigation, search
 
(39 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 +
<font color="red">We have moved this page to http://openigtlink.org/tutorials/matlabigtl.html</font>
 +
 +
 +
 
[[OpenIGTLink | &lt;&lt; OpenIGTLink]]
 
[[OpenIGTLink | &lt;&lt; OpenIGTLink]]
  
 
=About the project=
 
=About the project=
The objective of this project is to provide OpenIGTLink interface for [http://www.mathworks.com/ Matlab] / [http://www.gnu.org/software/octave/ Octave] to support research and development in image guided therapy (IGT). Matlab and Octave are widely used for prototyping image and signal processing algorithms. They also offers many powerful function set to handle matrix and coordinate data, which is useful to test and analyze coordinate data exported from tracking and robotic devices.
+
The objective of this project is to provide OpenIGTLink interface for [http://www.mathworks.com/ Matlab] / [http://www.gnu.org/software/octave/ Octave] to support research and development in image guided therapy (IGT). Matlab and Octave are widely used for prototyping image and signal processing algorithms. They also offer many powerful function sets to handle matrix and coordinate data, which is useful to test and analyze coordinate data exported from tracking and robotic devices.
The OpenIGTLink interface for Matlab / Octave allows importing and exporting several types of data that can be handled in the OpenIGTLink protocol in Matlab / Octave environment. It provides a rapid prototyping environment, which many researchers and engineers are already familiar with.
+
The OpenIGTLink interface for Matlab / Octave allows importing and exporting several types of data that can be handled in the OpenIGTLink protocol in a Matlab / Octave environment. It provides a rapid prototyping environment, which many researchers and engineers are already familiar with.
  
 
This project is a generalization of [[Projects/Slicer3/2007_Project_Week_Slicer_Matlab_Pipeline_for_scalars_and_tensors | Slicer Matlab Pipeline project]] in the 2007 NA-MIC Project Week.
 
This project is a generalization of [[Projects/Slicer3/2007_Project_Week_Slicer_Matlab_Pipeline_for_scalars_and_tensors | Slicer Matlab Pipeline project]] in the 2007 NA-MIC Project Week.
 +
 +
=Demo Videos=
 +
==Scenario 1: Push image data to 3D Slicer from Matlab console (1-way communication) ==
 +
Matlab and 3D Slicer are running on different hosts (the Matlab window is displayed using remote display). A matrix 'I' and 'M' on the Matlab console contain image data and affine transformation respectively. With just a several lines of commands on the Matlab console, the image data is transferred to the 3D Slicer through the network using OpenIGTLink.
 +
 +
[[Media:OpenIGTLink_Matlab_1way.mov]]
 +
 +
 +
==Scenario 2: Request Matlab to process image data from 3D Slicer (2-way communication)==
 +
Matlab and 3D Slicer are running on different hosts (Matlab window is displayed using remote display). On the Matlab console, an example image processing server ('example_server.m') is running. This example server basically receives an image form external software, apply a filter and return a result. Once the OpenIGTLink connection between the 3D Slicer and the Matlab is established, the example MR image is loaded into the scene on the 3D Slicer, and then pushed to the Matlab through the OpenIGTLink connection. After a few seconds, the Matlab returns the filtered image to the 3D Slicer through the same OpenIGTLink connection. The image is visualized on the 3D Slicer.
 +
 +
[[Media:OpenIGTLink_Matlab_2way.mov]]
 +
 +
==Scenario 3: Send transform (4x4 matrix) from Matlab to 3D Slicer==
 +
Matlab and 3D Slicer are running on different hosts (Matlab window is displayed using remote display). The video demonstrates to manipulate 4x4 matrix on the Matlab console and then transfer to the 3D Slicer through the network using OpenIGTLink.
 +
 +
 +
[[Media:OpenIGTLink_Matlab_tracking.mov]]
  
 
=How does it work?=
 
=How does it work?=
The OpenIGTLink Matlab interface is implemented as a set of MEX Files, which are C/C++ source codes called from Matlab. Those MEX files simply receives data from Matlab, connect to OpenIGTLink receiver, serialize the data in appropriate format using the OpenIGTLink Library, and send it to the receiver.
+
The OpenIGTLink Matlab interface is implemented as a set of MEX Files, which are C/C++ source codes called from Matlab. Those MEX files simply receive data from Matlab, connect to the OpenIGTLink receiver, serialize the data in an appropriate format using the OpenIGTLink Library, and send it to the receiver.
  
The usage of the interface is quite simple. The following example Matlab code is sending image data to the receiver waiting at port #18944 in the localhost.
+
The usage of the interface is quite simple. The following example Matlab code is sending trancking data to the receiver waiting at port #18944 on the localhost.
 +
 
 +
%%% affine transform matrix
 +
M = [1.0, 0.0, 0.0, 0.0;
 +
      0.0,-1.0, 0.0, 0.0;
 +
      0.0, 0.0, 1.0, 0.0;
 +
      0.0, 0.0, 0.0, 1.0];
 +
 +
IMGDATA.Type = 'TRANSFORM';
 +
IMGDATA.Name = 'MatlabTrans';
 +
IMGDATA.Trans = M;
 +
 +
sd = igtlopen('localhost', 18944);
 +
r = igtlsend(sd, IMGDATA);
 +
igtlclose(sd);
 +
 
 +
 
 +
For tracking data transfer:
  
 
  %%% read image data
 
  %%% read image data
Line 22: Line 61:
 
       0.0, 0.0, 1.0, 0.0;
 
       0.0, 0.0, 1.0, 0.0;
 
       0.0, 0.0, 0.0, 1.0];
 
       0.0, 0.0, 0.0, 1.0];
 +
 +
IMGDATA.Type = 'IMAGE';
 +
IMGDATA.Name = 'MatlabImage';
 +
IMGDATA.Image = I;
 +
IMGDATA.Trans = M;
 
   
 
   
 
  %%% send the image data through OpenIGTLink connection
 
  %%% send the image data through OpenIGTLink connection
 
  sd = igtlopen('localhost', 18944);
 
  sd = igtlopen('localhost', 18944);
  r = igtlsend(sd, 'MatlabImage', I, M);
+
  r = igtlsend(sd, IMGDATA);
 
  igtlclose(sd);
 
  igtlclose(sd);
  
=How to Get Started=
+
 
 +
=Download & Building OpenIGTLink Mex functions=
 +
 
 +
==For Windows Users==
 +
*You may download mex binary files for 32-bit and 64-bit Windows built by Dr. Nicolas Herlambang, Ph.D. (Aze Ltd., Japan) from the following link.
 +
**[[File:OpenIGTLinkMex_Win32.zip]] (32 bit).
 +
**[[File:OpenIGTLinkMex_Win64.zip]] (64 bit).
 +
 
 +
==For Linux Users==
 +
**[[File:OpenIGTLinkMex_Linux64.tar.gz]] (64 bit -- Built on 64-bit FC13 + Matlab 7.10.0 R2010a)
 +
 
 +
==Install the OpenIGTLink Library==
 +
The instruction can be found in [[OpenIGTLink/Library]]. We recommend to build the library as a static library. (Just to avoid a trouble that Matlab couldn't find shared objects/dynamic link library. In principle, either static or shared library works.)
 +
 
 +
==Get the Matlab OpenIGTLink interface source code==
 
The OpenIGTLink/Matlab interface is in the initial stage of development. The source code is available from NA-MIC SandBox repository at
 
The OpenIGTLink/Matlab interface is in the initial stage of development. The source code is available from NA-MIC SandBox repository at
  
   http://svn.na-mic.org/NAMICSandBox/trunk/BRPTools/MatlabIGTL
+
   http://svn.na-mic.org/NAMICSandBox/trunk/MatlabIGTL
 +
 
 +
==Build MEX files==
 +
CMake configuration (CMakeLists.txt) comes with Matlab OpenIGTLink interface. To build the interface with CMake
 +
in Linux/Mac OS X environment,
 +
 
 +
cd <working directory>
 +
svn co URL: http://svn.na-mic.org/NAMICSandBox/trunk/MatlabIGTL
 +
mkdir MatlabIGTL-build
 +
cd MatlabIGTL-build
 +
ccmake ../MatlabIGTL
 +
 
 +
This will launch Curses Interface for CMake. Press 'c' to configure and check the following parameters;
 +
*MEX_COMPILER = (path to Matlab's '''mex''' command or Octave's '''mkoctfile''')
 +
*OpenIGTLInk_DIR = (path to binary directory of OpenIGTLink)
  
Currently neither configuration script nor CMake configuration file is available. Please edit Makefile in the source directory and compile the MEX files using MEX compiler coming with Matlab. You need to have an copy of the OpenIGTLink Library to compile.
+
Then press 'g' to generate a makefile. Press 'q' to quit the CMake interface screen.
 +
Once you find '''Makefile''' in the directory, run make. Several files with extension *.mex (or *.mex<arc-name>) will be generated.
  
 
=Contact=
 
=Contact=
 
+
If you have any question, please subscribe to OpenIGTLink ML.
We are not providing a support for this software, but questions and requests are always welcome. If you have any, please contact
+
You may also contact to [[User:Tokuda|Junichi Tokuda]] for further information.
[[User:Tokuda| Junichi Tokuda]] at Brigham and Women's Hospital.
 

Latest revision as of 18:06, 7 January 2013

Home < OpenIGTLink < Matlab

We have moved this page to http://openigtlink.org/tutorials/matlabigtl.html


<< OpenIGTLink

About the project

The objective of this project is to provide OpenIGTLink interface for Matlab / Octave to support research and development in image guided therapy (IGT). Matlab and Octave are widely used for prototyping image and signal processing algorithms. They also offer many powerful function sets to handle matrix and coordinate data, which is useful to test and analyze coordinate data exported from tracking and robotic devices. The OpenIGTLink interface for Matlab / Octave allows importing and exporting several types of data that can be handled in the OpenIGTLink protocol in a Matlab / Octave environment. It provides a rapid prototyping environment, which many researchers and engineers are already familiar with.

This project is a generalization of Slicer Matlab Pipeline project in the 2007 NA-MIC Project Week.

Demo Videos

Scenario 1: Push image data to 3D Slicer from Matlab console (1-way communication)

Matlab and 3D Slicer are running on different hosts (the Matlab window is displayed using remote display). A matrix 'I' and 'M' on the Matlab console contain image data and affine transformation respectively. With just a several lines of commands on the Matlab console, the image data is transferred to the 3D Slicer through the network using OpenIGTLink.

Media:OpenIGTLink_Matlab_1way.mov


Scenario 2: Request Matlab to process image data from 3D Slicer (2-way communication)

Matlab and 3D Slicer are running on different hosts (Matlab window is displayed using remote display). On the Matlab console, an example image processing server ('example_server.m') is running. This example server basically receives an image form external software, apply a filter and return a result. Once the OpenIGTLink connection between the 3D Slicer and the Matlab is established, the example MR image is loaded into the scene on the 3D Slicer, and then pushed to the Matlab through the OpenIGTLink connection. After a few seconds, the Matlab returns the filtered image to the 3D Slicer through the same OpenIGTLink connection. The image is visualized on the 3D Slicer.

Media:OpenIGTLink_Matlab_2way.mov

Scenario 3: Send transform (4x4 matrix) from Matlab to 3D Slicer

Matlab and 3D Slicer are running on different hosts (Matlab window is displayed using remote display). The video demonstrates to manipulate 4x4 matrix on the Matlab console and then transfer to the 3D Slicer through the network using OpenIGTLink.


Media:OpenIGTLink_Matlab_tracking.mov

How does it work?

The OpenIGTLink Matlab interface is implemented as a set of MEX Files, which are C/C++ source codes called from Matlab. Those MEX files simply receive data from Matlab, connect to the OpenIGTLink receiver, serialize the data in an appropriate format using the OpenIGTLink Library, and send it to the receiver.

The usage of the interface is quite simple. The following example Matlab code is sending trancking data to the receiver waiting at port #18944 on the localhost.

%%% affine transform matrix
M = [1.0, 0.0, 0.0, 0.0;
     0.0,-1.0, 0.0, 0.0;
     0.0, 0.0, 1.0, 0.0;
     0.0, 0.0, 0.0, 1.0];

IMGDATA.Type = 'TRANSFORM';
IMGDATA.Name = 'MatlabTrans';
IMGDATA.Trans = M;

sd = igtlopen('localhost', 18944);
r = igtlsend(sd, IMGDATA);
igtlclose(sd);


For tracking data transfer:

%%% read image data
fid = fopen('igtlTestImage1.raw', 'r');
I = fread(fid, [256 256], 'uint8')';
fclose(fid);

%%% affine transform matrix
M = [1.0, 0.0, 0.0, 0.0;
     0.0,-1.0, 0.0, 0.0;
     0.0, 0.0, 1.0, 0.0;
     0.0, 0.0, 0.0, 1.0];

IMGDATA.Type = 'IMAGE';
IMGDATA.Name = 'MatlabImage';
IMGDATA.Image = I;
IMGDATA.Trans = M;

%%% send the image data through OpenIGTLink connection
sd = igtlopen('localhost', 18944);
r = igtlsend(sd, IMGDATA);
igtlclose(sd);


Download & Building OpenIGTLink Mex functions

For Windows Users

For Linux Users

Install the OpenIGTLink Library

The instruction can be found in OpenIGTLink/Library. We recommend to build the library as a static library. (Just to avoid a trouble that Matlab couldn't find shared objects/dynamic link library. In principle, either static or shared library works.)

Get the Matlab OpenIGTLink interface source code

The OpenIGTLink/Matlab interface is in the initial stage of development. The source code is available from NA-MIC SandBox repository at

 http://svn.na-mic.org/NAMICSandBox/trunk/MatlabIGTL

Build MEX files

CMake configuration (CMakeLists.txt) comes with Matlab OpenIGTLink interface. To build the interface with CMake in Linux/Mac OS X environment,

cd <working directory>
svn co URL: http://svn.na-mic.org/NAMICSandBox/trunk/MatlabIGTL
mkdir MatlabIGTL-build
cd MatlabIGTL-build
ccmake ../MatlabIGTL

This will launch Curses Interface for CMake. Press 'c' to configure and check the following parameters;

*MEX_COMPILER = (path to Matlab's mex command or Octave's mkoctfile)
*OpenIGTLInk_DIR = (path to binary directory of OpenIGTLink)

Then press 'g' to generate a makefile. Press 'q' to quit the CMake interface screen. Once you find Makefile in the directory, run make. Several files with extension *.mex (or *.mex<arc-name>) will be generated.

Contact

If you have any question, please subscribe to OpenIGTLink ML. You may also contact to Junichi Tokuda for further information.