Difference between revisions of "Documentation/Nightly/Extensions/MatlabBridge"

From Slicer Wiki
Jump to: navigation, search
 
(29 intermediate revisions by 2 users not shown)
Line 2: Line 2:
 
<!-- ---------------------------- -->
 
<!-- ---------------------------- -->
 
{{documentation/{{documentation/version}}/module-header}}
 
{{documentation/{{documentation/version}}/module-header}}
−
<!-- ---------------------------- -->
 
 
<!-- ---------------------------- -->
 
<!-- ---------------------------- -->
 
{{documentation/{{documentation/version}}/module-section|Introduction and Acknowledgements}}
 
{{documentation/{{documentation/version}}/module-section|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)<br>
+
Author: Andras Lasso (PerkLab, Queen's University), Jean-Christophe Fillion-Robin (Kitware), Kevin Wang (Princess Margaret Cancer Centre), Gabor Fichtinger (PerkLab, Queen's University)<br>
 
Contact: Andras Lasso, <email>lasso@cs.queensu.ca</email><br>
 
Contact: Andras Lasso, <email>lasso@cs.queensu.ca</email><br>
 
Project website: http://www.slicerrt.org<br>
 
Project website: http://www.slicerrt.org<br>
Line 13: Line 12:
 
|{{collaborator|logo|namic}}|NA-MIC
 
|{{collaborator|logo|namic}}|NA-MIC
 
|{{collaborator|logo|perklab}}|PerkLab
 
|{{collaborator|logo|perklab}}|PerkLab
 +
|{{collaborator|logo|ocairo}}|OCAIRO
 
}}
 
}}
−
 
  
 
<!-- ---------------------------- -->
 
<!-- ---------------------------- -->
Line 33: Line 32:
  
 
Demo videos:
 
Demo videos:
−
* [http://screencast.com/t/veVw16jB3uk Creating and using a Matlab module]
+
* [https://youtu.be/dFNbt1sIdqQ Creating and using a Matlab module]
−
* [http://screencast.com/t/LcdrCx9l0 Editing and debugging a Matlab module]
+
* [https://youtu.be/8LijOcv3GDY Editing and debugging a Matlab module]
 +
 
 +
Tutorial: [[Media:MatlabBridgeTutorial.pdf|How to create, run, customize Matlab modules]]
  
 
|
 
|
Line 42: Line 43:
 
{{documentation/{{documentation/version}}/extension-section|Modules}}
 
{{documentation/{{documentation/version}}/extension-section|Modules}}
  
−
*[[Documentation/{{documentation/version}}/Modules/MatlabModuleGenerator|Matlab Module Generator]]
+
*[[Documentation/{{documentation/version}}/Modules/MatlabModuleGenerator|Matlab Module Generator]] (in the module list: Developer Tools / Matlab)
−
*[[Documentation/{{documentation/version}}/Modules/MatlabCommander|Matlab Commander]]
+
*[[Documentation/{{documentation/version}}/Modules/MatlabCommander|Matlab Commander]] (in the module list: Developer Tools / Matlab)
  
 
<!-- ---------------------------- -->
 
<!-- ---------------------------- -->
Line 57: Line 58:
 
<!-- ---------------------------- -->
 
<!-- ---------------------------- -->
 
{{documentation/{{documentation/version}}/extension-section|Tutorials}}
 
{{documentation/{{documentation/version}}/extension-section|Tutorials}}
−
 
+
*'''[[Media:MatlabBridgeTutorial.pdf|Comprehensive MatlabBridge tutorial: how to create, run, customize Matlab modules]]'''
−
==Example: Implementing a simple image thresholding and statistics module in Matlab==
+
*[https://github.com/PerkLab/SlicerMatlabBridge/tree/master/Examples/ A few example modules]
−
 
+
* [[documentation/{{documentation/version}}/Developers/SlicerExecutionModel#XML_Schema|Specification of module descriptor XML file]]
−
* Install the MatlabBridge extension
+
* Demo video: [https://youtu.be/dFNbt1sIdqQ Creating and using a Matlab module]
−
* Open the Developer Tools / Matlab / Matlab Module Generator module
+
* Demo video: [https://youtu.be/8LijOcv3GDY Editing and debugging a Matlab 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:
 
−
 
 
−
<pre>
 
−
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);
 
−
</pre>
 
−
 
 
−
* 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:
 
−
 
 
−
<pre>
 
−
<?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>
 
−
</pre>
 
−
 
 
−
* 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
 
−
 
 
 
<!-- ---------------------------- -->
 
<!-- ---------------------------- -->
 +
<!--
 
{{documentation/{{documentation/version}}/extension-section|Similar Extensions}}
 
{{documentation/{{documentation/version}}/extension-section|Similar Extensions}}
 +
-->
 +
<!-- ---------------------------- -->
 +
<!--
 +
{{documentation/{{documentation/version}}/extension-section|References}}
 +
-->
  
 
<!-- ---------------------------- -->
 
<!-- ---------------------------- -->
−
{{documentation/{{documentation/version}}/extension-section|References}}
+
{{documentation/{{documentation/version}}/extension-section|Information for Developers}}
 +
* Source code: https://github.com/PerkLab/SlicerMatlabBridge/tree/master/
 +
* Issue tracker:  [https://github.com/PerkLab/SlicerMatlabBridge/issues open issues and enhancement requests]
 +
* Design overview: [https://github.com/PerkLab/SlicerMatlabBridge/raw/master/Docs/MatlabBridgeDesign.pptx].
 +
* Running Matlab modules without accessing a Matlab license: You can run your Matlab modules on a computer that does not have Matlab license by using the Matlab Compiler.
 +
** On the development computer (with Matlab and Matlab Compiler license) create an executable (let's call it MyModuleCollection.exe) with the Matlab Compiler:
 +
*** include all the MatlabBridge CommandServer functions (https://github.com/PerkLab/SlicerMatlabBridge/tree/master/MatlabCommander/commandserver) as Shared Resources
 +
*** include your custom .m files (including the .m file that the slicer module generator creates) as Shared Resources
 +
*** choose cli_commandserver.m as "Main File"
 +
** Installation on the target computer (a self-contained executable can be created as described on the [[Documentation/Labs/CustomSlicerGenerator]] page):
 +
*** Copy the MyModuleCollection.exe to the target computer (it can be anywhere, but make sure it's not in a directory that is listed in Slicer additional module paths)
 +
*** Install Slicer
 +
*** Install MatlabBridge extension
 +
*** Set the location of your Matlab module proxy (.bat file or shell script) and CLI descriptor (.xml) files as additional module paths in Slicer
 +
** Running on the target computer:
 +
*** Start MyModuleCollection.exe (anytime ''before'' you start Slicer)
 +
*** Start Slicer
 +
* Tested with Matlab R2009b, R2012a, and R2013a on Windows7.
  
−
* [https://www.assembla.com/spaces/dG15GuCs4r4l4UeJe5cbCb/tickets/report/u783013 Overview of issues and enhancement requests]
+
<!-- ---------------------------- -->
 +
{{documentation/{{documentation/version}}/extension-section|Troubleshooting}}
 +
* Problem: When I try to run my Matlab module, the Matlab process does not start (Matlab window does not appear on the taskbar)
 +
** Solution [on Windows Vista/7/8]: Please go to the Matlab module generator module and in the “Matlab executable” editbox set the path to your “.../bin/matlab.exe” (not to "activate_matlab.exe" or other exe files in the Matlab program directory or any file in the bin/win64 directory).
 +
** Solution [on Mac OS X]: Please go to the Matlab module generator module and in the “Matlab executable” editbox set the path to your “/Applications/MATLAB.app/bin/matlab” (instead of MATLAB.app you may have MATLAB_<Release>.app, where <Release> is the MATLAB Release's version, i.e., R2009a, R2012b, etc.).
 +
* Problem: When I try to run my Matlab module, the Matlab process starts (Matlab window appears on the taskbar and it displays the message "Starting OpenIGTLink command server at port 4100 Waiting for client connections..."), but the Matlab module execution fails (in the Slicer error log the "igtl::ClientSocket (...): Failed to connect to server 127.0.0.1:4100" message is displayed)
 +
** Solution [on Windows Vista/7/8]: Firewall settings prevent Matlab-Slicer communication. Please add a firewall exception by the following steps:
 +
**# Start ''cmd.exe'' as administrator (open the Windows Start menu, type "cmd", hit Ctrl + Shift + Enter)
 +
**# Click ''Yes'', if a dialog box appears asking "''Do you want to allow the following program to make changes to this computer?''"
 +
**# Enter the following command: ''netsh firewall add portopening tcp 4100 MatlabBridge''
 +
** Solution [on Mac OS X]: Firewall settings prevent Matlab-Slicer communication. Please disable firewal or add a firewall exception.
 +
* Problem: module execution is not completed
 +
** Solution: make sure you've selected .../MATLAB/.../bin/matlab.exe as Matlab executable (and not .../MATLAB/.../bin/win64/MATLAB.exe)
 +
* I would like to add breakpoints and do step-by-step debugging in Matlab
 +
** Solution:
 +
*** Start Matlab normally (with the full user interface)
 +
*** Load your Matlab script files, add breakpoints
 +
*** Start the MatlabBridge command server in Matlab by running ''cli_commandserver''
 +
**** Location of ''cli_commandserver.m'' script: <SlicerExtensionDirectory>/MatlabBridge/lib/Slicer-4.3/cli-modules/commandserver (for example, C:/Users/myusername/AppData/Roaming/NA-MIC/Extensions-23549/MatlabBridge/lib/Slicer-4.3/cli-modules/commandserver)
 +
**** Where is <SlicerExtensionDirectory>? Open the 'Matlab Module Generator' module in Slicer, it shows ''Matlab script directory''. <SlicerExtensionDirectory> is the parent directory of ''Matlab script directory''.
 +
*** Run your module in Slicer. Matlab will stop at the specified breakpoints and you can observer variables and do step-by-step debugging.
 +
* Error when trying to run a Matlab module in a slicelet
 +
** Solution: do not add --no-main-window to SlicerLauncherSettings.ini but pass it to Slicer.exe on the command line instead
  
 
<!-- ---------------------------- -->
 
<!-- ---------------------------- -->
−
{{documentation/{{documentation/version}}/extension-section|Information for Developers}}
 
−
See some information on the design of the module at the [http://www.na-mic.org/Wiki/index.php/2013_Summer_Project_Week:CLI_Matlab 2013 Summer Project week wiki].
 
  
 
<!-- ---------------------------- -->
 
<!-- ---------------------------- -->
 
{{documentation/{{documentation/version}}/extension-footer}}
 
{{documentation/{{documentation/version}}/extension-footer}}
 
<!-- ---------------------------- -->
 
<!-- ---------------------------- -->

Latest revision as of 04:45, 20 June 2018

Home < 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 (Princess Margaret Cancer Centre), Gabor Fichtinger (PerkLab, Queen's University)
Contact: Andras Lasso, <email>lasso@cs.queensu.ca</email>
Project website: http://www.slicerrt.org
License: Slicer license

SparKit  
NA-MIC  
OCAIRO  

Extension Description

MatlabBridgeLogo.png

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:

Tutorial: How to create, run, customize Matlab modules

Modules

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

Information for Developers

  • Source code: https://github.com/PerkLab/SlicerMatlabBridge/tree/master/
  • Issue tracker: open issues and enhancement requests
  • Design overview: [1].
  • Running Matlab modules without accessing a Matlab license: You can run your Matlab modules on a computer that does not have Matlab license by using the Matlab Compiler.
    • On the development computer (with Matlab and Matlab Compiler license) create an executable (let's call it MyModuleCollection.exe) with the Matlab Compiler:
    • Installation on the target computer (a self-contained executable can be created as described on the Documentation/Labs/CustomSlicerGenerator page):
      • Copy the MyModuleCollection.exe to the target computer (it can be anywhere, but make sure it's not in a directory that is listed in Slicer additional module paths)
      • Install Slicer
      • Install MatlabBridge extension
      • Set the location of your Matlab module proxy (.bat file or shell script) and CLI descriptor (.xml) files as additional module paths in Slicer
    • Running on the target computer:
      • Start MyModuleCollection.exe (anytime before you start Slicer)
      • Start Slicer
  • Tested with Matlab R2009b, R2012a, and R2013a on Windows7.

Troubleshooting

  • Problem: When I try to run my Matlab module, the Matlab process does not start (Matlab window does not appear on the taskbar)
    • Solution [on Windows Vista/7/8]: Please go to the Matlab module generator module and in the “Matlab executable” editbox set the path to your “.../bin/matlab.exe” (not to "activate_matlab.exe" or other exe files in the Matlab program directory or any file in the bin/win64 directory).
    • Solution [on Mac OS X]: Please go to the Matlab module generator module and in the “Matlab executable” editbox set the path to your “/Applications/MATLAB.app/bin/matlab” (instead of MATLAB.app you may have MATLAB_<Release>.app, where <Release> is the MATLAB Release's version, i.e., R2009a, R2012b, etc.).
  • Problem: When I try to run my Matlab module, the Matlab process starts (Matlab window appears on the taskbar and it displays the message "Starting OpenIGTLink command server at port 4100 Waiting for client connections..."), but the Matlab module execution fails (in the Slicer error log the "igtl::ClientSocket (...): Failed to connect to server 127.0.0.1:4100" message is displayed)
    • Solution [on Windows Vista/7/8]: Firewall settings prevent Matlab-Slicer communication. Please add a firewall exception by the following steps:
      1. Start cmd.exe as administrator (open the Windows Start menu, type "cmd", hit Ctrl + Shift + Enter)
      2. Click Yes, if a dialog box appears asking "Do you want to allow the following program to make changes to this computer?"
      3. Enter the following command: netsh firewall add portopening tcp 4100 MatlabBridge
    • Solution [on Mac OS X]: Firewall settings prevent Matlab-Slicer communication. Please disable firewal or add a firewall exception.
  • Problem: module execution is not completed
    • Solution: make sure you've selected .../MATLAB/.../bin/matlab.exe as Matlab executable (and not .../MATLAB/.../bin/win64/MATLAB.exe)
  • I would like to add breakpoints and do step-by-step debugging in Matlab
    • Solution:
      • Start Matlab normally (with the full user interface)
      • Load your Matlab script files, add breakpoints
      • Start the MatlabBridge command server in Matlab by running cli_commandserver
        • Location of cli_commandserver.m script: <SlicerExtensionDirectory>/MatlabBridge/lib/Slicer-4.3/cli-modules/commandserver (for example, C:/Users/myusername/AppData/Roaming/NA-MIC/Extensions-23549/MatlabBridge/lib/Slicer-4.3/cli-modules/commandserver)
        • Where is <SlicerExtensionDirectory>? Open the 'Matlab Module Generator' module in Slicer, it shows Matlab script directory. <SlicerExtensionDirectory> is the parent directory of Matlab script directory.
      • Run your module in Slicer. Matlab will stop at the specified breakpoints and you can observer variables and do step-by-step debugging.
  • Error when trying to run a Matlab module in a slicelet
    • Solution: do not add --no-main-window to SlicerLauncherSettings.ini but pass it to Slicer.exe on the command line instead
Retrieved from "https://www.slicer.org/w/index.php?title=Documentation/Nightly/Extensions/MatlabBridge&oldid=59117"