Documentation/Nightly/Extensions/MatlabBridge

For the latest Slicer documentation, visit the read-the-docs.

Introduction and Acknowledgements

Author: Andras Lasso (PerkLab, Queen's University), Jean-Christophe Fillion-Robin (Kitware), Kevin Wang (Radiation Medicine Program, Princess Margaret Hospital, University Health Network Toronto)
Contact: Andras Lasso, <email>lasso@cs.queensu.ca</email>
Project website: http://www.slicerrt.org
License: Slicer license

SparKit   NA-MIC

Extension Description

MatlabBridge is an extension of 3D Slicer to allow running Matlab functions directly in 3D Slicer. Highlights: The extension allows running of Matlab functions directly from 3D Slicer: it takes the input from the data loaded into Slicer and visualizes the results in Slicer right after the execution is completed If you change any input on the GUI (and the “AutoRun” option is enabled) the bridge automatically re-runs the Matlab script with the updated parameters and shows the new results If you change your Matlab function then you can re-run the function and see the updated results with a single click The graphical user interface is generated automatically from a standard command-line interface definition XML file (no GUI programming needed) You can get started quickly by generating a skeleton Matlab function and interface definition XML file using the Matlab Module Generator module No building of 3D Slicer or MEX files, etc. are needed – the only requirements are to download and install 3D Slicer with the MatlabBridge extension and have Matlab on your computer The Matlab module behaves exactly as any other command-line-interface module, the Matlab engine is started automatically in the background (and it is kept running in the background so that you don’t have to wait for Matlab startup each time you run your function) Demo videos: Creating and using a Matlab module Editing and debugging a Matlab module

Modules

• Matlab Module Generator (in the module list: Developer Tools / Matlab)
• Matlab Commander (in the module list: Developer Tools / Matlab)

Use Cases

• 

  Example Matlab module user interface in Slicer

• 

  Matlab Bridge modules appear under the Developer Tools / Matlab category

• 

  A skeleton Matlab script can be created and installed using the Matlab module generator.

• 

  The Matlab Commander allows running any commands from the user interface or from another Slicer module.

Tutorials

Example: Implementing a simple image thresholding and statistics module in Matlab

• Install the MatlabBridge extension
• Open the Developer Tools / Matlab / Matlab Module Generator module
• Specify the path to your Matlab.exe (such as c:\Program Files\MATLAB\R2012a\bin\matlab.exe)
• Enter your module name, such as MyThresholder and click Generate module. Take note of the file paths shown in the status window.
• Edit your MyThresholder.m file to implement the algorithm and computations. Example:

function outputParams=MatlabModuleTemplate(inputParams)

img=cli_imageread(inputParams.unnamed{1});

outputParams.min=min(min(min(img.pixelData)));
outputParams.max=max(max(max(img.pixelData)));

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

cli_imagewrite(inputParams.unnamed{2}, img); 

• Edit the generated skeleton MyThresholder.xml file that describes your algorithm inputs and outputs. Slicer will automatically generate the graphical user interface to be able to specify the inputs and display the outputs.
  • See specification of the XML file here: Slicer3:Execution_Model_Documentation
  • Many example XML files are available here: https://github.com/Slicer/Slicer/tree/master/Modules/CLI
  • A few complete Matlab module examples are here: https://subversion.assembla.com/svn/slicerrt/trunk/MatlabBridge/src/Examples/

Example:

<?xml version="1.0" encoding="utf-8"?>
<executable>
  <category>Matlab</category>
  <title>MyThresholder</title>
  <description><![CDATA[Perform a simple image processing and image statistics computation in Matlab.]]></description>
  <version>0.0.0.1</version>
  <documentation-url>http://www.slicer.org/slicerWiki/index.php/Documentation/Nightly/Extensions/SlicerRT</documentation-url>
  <license/>
  <contributor>Andras Lasso (PerkLab)</contributor>
  <acknowledgements><![CDATA[SparKit is a project funded by Cancer Care Ontarioand the Ontario Consortium for Adaptive Interventions in Radiation Oncology (OCAIRO) to provide free, open-source toolset for radiotherapy and related image-guided interventions.]]></acknowledgements>
  <parameters>
    <label>Processing Parameters</label>
    <description><![CDATA[Parameters for the processing]]></description>
    <integer>
      <name>threshold</name>
      <longflag>--threshold</longflag>
      <description><![CDATA[All voxels below this value will be set to zero]]></description>
      <label>Threshold</label>
      <default>50</default>
      <constraints>
        <minimum>-2000</minimum>
        <maximum>5000</maximum>
        <step>5</step>
      </constraints>      
    </integer>
  </parameters>
  <parameters>
    <label>IO</label>
    <description><![CDATA[Input/output parameters]]></description>
    <image>
      <name>inputVolume</name>
      <label>Input Volume</label>
      <channel>input</channel>
      <index>0</index>
      <description><![CDATA[Input volume to be filtered]]></description>
    </image>
    <image>
      <name>outputVolume</name>
      <label>Output Volume</label>
      <channel>output</channel>
      <index>1</index>
      <description><![CDATA[Output filtered]]></description>
    </image>
  </parameters>
  <parameters>
    <label>Output</label>
    <description>Matlab command output</description>
    <double>
      <name>min</name>
      <label>Minimum</label>
      <channel>output</channel>
      <default></default>
      <description><![CDATA[Image mininum]]></description>
    </double>    
    <double>
      <name>max</name>
      <label>Maximum</label>
      <channel>output</channel>
      <default></default>
      <description><![CDATA[Image maximum]]></description>
    </double>    
  </parameters>
</executable>

• Restart Slicer
• Download the MRIHead image sample using the Download Sample Data module
• Open the Matlab / MyThresholder module
• Select the MRIHead image as input, create a new volume as output, click Apply
• Click AutoRun at the bottom of the module user interface then change the threshold value with the slider, the processed image will be updated automatically

References

• Overview of issues and enhancement requests

Information for Developers

See some information on the design of the module at the 2013 Summer Project week wiki.