NA-MIC

National Alliance for Medical Image Computing

http://www.na-mic.org

MatlabBridge Extension
Andras Lasso1, Jean-Christophe FillionRobin2, Kevin Wang3, Gabor Fichtinger1
11Laboratory

for Percutaneous Surgery, Queens University, Canada

2Kitware
3University Health Network, Toronto, ON, Canada

[email protected]
2013, All Rights Reserved

Learning Objective
This tutorial demonstrates how 3D Slicer can be
used to run Matlab functions and visualize the
processing results in
3D Slicer, using the
MatlabBridge
extension.

National Alliance for Medical Image Computing

http://www.na-mic.org

2013, All Rights Reserved

Pre-requisites
Matlab installed
A nightly release of 3D Slicer
installed.
Download the 3D Slicer installer
package from the nightly build row at:
http://www.slicer.org/pages/Downloads/

National Alliance for Medical Image Computing

http://www.na-mic.org

2013, All Rights Reserved

Platforms
Windows: fully supported

Linux: not tested extensively,

check this page for the current status
Mac: not tested extensively,
check this page for the current status
National Alliance for Medical Image Computing
http://www.na-mic.org

2013, All Rights Reserved

Overview
1.
2.
3.
4.

Install and configure

Create a simple Matlab module
Use your Matlab module
Customize your Matlab module

National Alliance for Medical Image Computing

http://www.na-mic.org

2013, All Rights Reserved

1.1 Install and configure

National Alliance for Medical Image Computing

http://www.na-mic.org

2013, All Rights Reserved

1.2 Install and configure

National Alliance for Medical Image Computing

http://www.na-mic.org

2013, All Rights Reserved

1.3 Install and configure

National Alliance for Medical Image Computing

http://www.na-mic.org

2013, All Rights Reserved

1.4 Install and configure

Note: MatlabBridge
modules appear
under Developer
Tools / Matlab
category in the
module list
Start the Matlab
Module Generator
module
National Alliance for Medical Image Computing
http://www.na-mic.org

2013, All Rights Reserved

1.5 Install and configure

1. Verify that the

path to Matlab is
correct

2. Click here to change the

default location of the
Matlab executable
National Alliance for Medical Image Computing
http://www.na-mic.org

2013, All Rights Reserved

2.1 Create a Matlab module

Start the Matlab

Module Generator
module
National Alliance for Medical Image Computing
http://www.na-mic.org

2013, All Rights Reserved

2.2 Create a Matlab module

1. Enter your module name into
the Module name box:
My First Matlab Module

2. Click Generate
module button

National Alliance for Medical Image Computing

http://www.na-mic.org

2013, All Rights Reserved

2.3 Create a Matlab module

Note: status of the module generation and the
file path of the generated files are shown in the
textbox

National Alliance for Medical Image Computing

http://www.na-mic.org

2013, All Rights Reserved

2.4 Create a Matlab module

Each Matlab module consists of three files:
Matlab script (*.m): the Matlab function that Slicer calls,
this file has to be customized by the user to perform all
the necessary data input, processing, and output
Module descriptor (*.xml): this XML file defines the
graphical user interface that will be displayed for the
module in 3D Slicer, this file has to be customized for
the specific Matlab function
Module proxy (*.bat): this file is generated once and
need not to be changed

National Alliance for Medical Image Computing

http://www.na-mic.org

2013, All Rights Reserved

2.5 Create a Matlab module

Generated module descriptor: MyFirstMatlabModule.xml
Description of the module (category, title, etc.)
<?xml version="1.0" encoding="utf-8"?>
<executable> <category>Matlab</category> <title>My First Matlab Module</title>
<parameters> <label>Processing Parameters</label>

Input numerical value

<integer> <label>Threshold</label> <longflag>threshold</longflag> </integer>

</parameters>
<parameters> <label>IO</label>
<image> <label>Input Volume</label> <longflag>inputvolume</longflag>
<channel>input</channel> </image>

Input image

<image> <label>Output Volume</label> <longflag>outputvolume</longflag>

<channel>output</channel> </image>

Output image

</parameters>
<parameters> <label>Output</label>

Two output numerical values

<double> <label>Minimum</label> <name>min</name> <channel>output</channel> </double>

<double> <label>Maximum</label> <name>max</name> <channel>output</channel> </double>
</parameters>
</executable>
National Alliance for Medical Image Computing
http://www.na-mic.org

2013, All Rights Reserved

2.6 Create a Matlab module

Geenerated Matlab script: MyFirstMatlabModule.m
% Example function that returns the minimum and maximum voxel
% value in a volume and performs thresholding operation
% on the volume.
function outputParams = MyFirstMatlabModule( inputParams )
img=cli_imageread(inputParams.inputvolume); Input image
outputParams.min=min(min(min(img.pixelData))); Two output numerical values
outputParams.max=max(max(max(img.pixelData)));
Input numerical value
img.pixelData=(double(img.pixelData)>inputParams.threshold)*100;
cli_imagewrite(inputParams.outputvolume, img); Output image

National Alliance for Medical Image Computing

http://www.na-mic.org

2013, All Rights Reserved

3.1 Use your Matlab module

1. Exit 3D Slicer
2. Start 3D Slicer
Module graphical user
interfaces are created
when Slicer is started.
So, we need to restart
Slicer to see the new
module.
National Alliance for Medical Image Computing
http://www.na-mic.org

2013, All Rights Reserved

3.2 Use your Matlab module

Matlab modules work
exactly the same way
as other CommandLine Interface (CLI)
Slicer modules.
Click Download
Sample Data module
to load some sample
data that we will
process.
National Alliance for Medical Image Computing
http://www.na-mic.org

2013, All Rights Reserved

3.3 Use your Matlab module

Click Download MRHead

National Alliance for Medical Image Computing

http://www.na-mic.org

2013, All Rights Reserved

3.4 Use your Matlab module

Open our new,

generated Matlab
module.
It is shown in the
Matlab category.
Click on the module
name to start.
National Alliance for Medical Image Computing
http://www.na-mic.org

2013, All Rights Reserved

3.5 Use your Matlab module

Select Input Volume:

MRHead

National Alliance for Medical Image Computing

http://www.na-mic.org

2013, All Rights Reserved

3.6 Use your Matlab module

Select Output Volume:

Create new Volume

National Alliance for Medical Image Computing

http://www.na-mic.org

2013, All Rights Reserved

3.7 Use your Matlab module

Click Apply button to run the

module
The first time the Apply button is clicked you may have to
wait for Matlab to start.
National Alliance for Medical Image Computing
http://www.na-mic.org

2013, All Rights Reserved

3.8 Use your Matlab module

1. Change the
Threshold value

2. Click the Apply

button to re-run
the module

National Alliance for Medical Image Computing

http://www.na-mic.org

2013, All Rights Reserved

3.9 Use your Matlab module

If an error occurs during the execution of the Matlab
function: open the error log in Slicer (View / Error log or
ctrl-0) or open the Matlab window to see the error message.
1. Set the Output
Volume to None

3. Status is Completed
with errors.
Press ctrl-0 to see
the error log.
National Alliance for Medical Image Computing
http://www.na-mic.org

2. Click the Apply button to

re-run the module
2013, All Rights Reserved

3.10 Use your Matlab module

Enable the AutoRun
feature to avoid the 2. Change the input
need of clicking
parameters
Apply each time an
input parameter is
changed.
1. Click AutoRun
After each change the Matlab function is executed automatically with
the new parameters, and the new results are updated on the screen.
National Alliance for Medical Image Computing
http://www.na-mic.org

2013, All Rights Reserved

3.11 Use your Matlab module

By using AutoRun, a
pipeline of many preprocessing and postprocessing filters and
visualization methods
can be constructed!

Choose the output of a CLI

module as the input of the
subsequent processing module
Enable AutoRun on modified
input option of AutoRun
Enable AutoRun
National Alliance for Medical Image Computing
http://www.na-mic.org

Input
volume
Gaussian Blur
Image Filter
Input
fiducial
point

My First Matlab
Module

Simple Region
Growing
Segmentation
Model
Maker

Output
model

CheckerBoard
Filter
Output
comparison
volume
2013, All Rights Reserved

3.12 Use your Matlab module

If any input or
processing
parameter is
changed,
then the
pipeline is
refreshed
and the
updated
results are
displayed.
National Alliance for Medical Image Computing
http://www.na-mic.org

2013, All Rights Reserved

4.1 Customize your Matlab

module
Example: We would like to introduce one more input
parameter, Fill value. It is a simple numerical value
specifying the value that will be set in the output volume
for the values that are above the chosen threshold.

National Alliance for Medical Image Computing

http://www.na-mic.org

2013, All Rights Reserved

4.2 Customize your Matlab

module
Add the following lines in a <parameters> section in the
MyFirstMatlabModule.xml file:
<integer>
<label>Fill value</label>
<description>
<![CDATA[Voxels above the threshold will be set to this value]]>
</description>
<longflag>fillvalue</longflag>
<default>200</default>
<constraints>
<minimum>-1000</minimum>
<maximum>1000</maximum>
<step>5</step>
</constraints>
</integer>

National Alliance for Medical Image Computing

http://www.na-mic.org

2013, All Rights Reserved

4.3 Customize your Matlab

module
Update the Matlab function: replace the line
img.pixelData=(double(img.pixelData)>inputParams.threshold)*100;

by
img.pixelData=(double(img.pixelData)>inputParams.threshold)*inputParams.fillvalue;

Restart Slicer to see the updated module graphical user

interface and try the module.

National Alliance for Medical Image Computing

http://www.na-mic.org

2013, All Rights Reserved

4.4 Customize your Matlab

module
The new
parameter
appears in
the user
interface.

National Alliance for Medical Image Computing

http://www.na-mic.org

2013, All Rights Reserved

4.5 Customize your Matlab

module
If the fill value
is negative
then the values
above the
threshold value
will appear
darker.

1. Set the Fill value to

a negative number
2. Click Apply

National Alliance for Medical Image Computing

http://www.na-mic.org

2013, All Rights Reserved

4.6 Customize your Matlab

module
Modifying and testing the Matlab function: simply edit the
.m file, save the file, then click Apply on the module GUI
in Slicer to re-run the module (no need to restart Slicer)
Setting a breakpoint in the Matlab function:
Option A: stop the command server in Matlab (ctrlc), add breakpoints in the Matlab GUI, restart the
cli_commandserver Matlab function
Option B: execute a Matlab message using the
MatlabCommander module, for example:
dbstop in c:\Users\MyUsername\AppData\Roaming\NA-MIC\ExtensionsNNNNN\MatlabModules\MyModule.m

National Alliance for Medical Image Computing

http://www.na-mic.org

2013, All Rights Reserved

4.7 Customize your Matlab

module
More information for customizing the XML file:
Complete specification of the XML file
XML files of all the core Slicer CLI modules
A few more Matlab module examples
Fill around seeds: fills region in a volume around
point positions marked in Slicer
Landmark registration: computes a linear transform
between two point sets marked in Slicer
Matlab Bridge parameter passing test: example for
using different kind of input and output parameters
National Alliance for Medical Image Computing
http://www.na-mic.org

2013, All Rights Reserved

Conclusion

Slicer can be used for running Matlab functions using a

convenient graphical user interface.

Matlab modules behave exactly as any other

command-line interface (CLI) module.

Automatic update feature (AutoRun) allows quick

visualization of the processing results whenever any
input or processing parameter is changed.

Existing Slicer modules can be used for importing data,

pre-processing, post-processing, and visualization.
National Alliance for Medical Image Computing
http://www.na-mic.org

2013, All Rights Reserved

More information
Extension documentation page:
http://www.slicer.org/slicerWiki/index.php/Documentation/Nightly/Extensions/MatlabBridge

Add/view bug reports and feature requests at:

https://www.assembla.com/spaces/dG15GuCs4r4l4UeJe5cbCb/tickets/report/u783013

Project webpage: http://www.slicerrt.org/

PerkLab webpage: http://perk.cs.queensu.ca
Email contact: Andras Lasso ([email protected])

National Alliance for Medical Image Computing

http://www.na-mic.org

2013, All Rights Reserved

Acknowledgments
Cancer Care Ontario
SparKit
(Software Platform and Adaptive
Radiotherapy Kit)
National Alliance for Medical
Image Computing
NIH U54EB005149
National Alliance for Medical Image Computing
http://www.na-mic.org

2013, All Rights Reserved