How to write Matlab Code for ImarisXT: a Short Tutorial
Michael Liebling, 10 October, 2005
In this short tutorial (actually, it rather is a reminder), we build a Matlab script to threshold the first section, and time-point of an Imaris volume dataset—not very useful by itself, but sufficiently simple to fit on one page—using the ImarisXT COM Interface to Imaris.
Two steps are required to write and install new Matlab code to be used with ImarisXT:
1) Write an m-file containing the matlab code. Save it in a place that is in the PATH of Matlab (alternatively, adjust Matlab's PATH variable).
2) In Imaris, modify the Tools configuration file (Preferences → Tools → Export...) to add a menu item, or a button to Imaris in order to execute the new code.
Below are the details for the two points:
1) Edit your m-file in your favorite editor and save the file as ImarisXTThreshold.m.
% ImarisXTThreshold
% A function to threshold the voxels of the first plane
% and first timepoint of an imaris dataset.
% Michael Liebling, April 2005
function ImarisXTThreshold(aImarisID,varargin) % ID corresponds to Imaris instance
switch nargin
case 1 % The function was called using an Imaris Menu
vImarisServer = actxserver('ImarisServer.Server');
vImarisApplication = vImarisServer.GetObject(aImarisID);
case 2 % The function was called from within Matlab
if strcmp(varargin{1},'debug') % in debug mode we have 2 args.
vImarisApplication = aImarisID;
else
error('Unexpected argument.')
end
otherwise
error('Wrong number of arguments.');
end
% We have the user input the values required by our program
prompt={'Threshold','Set voxels below threshold to:'};
name='Threshold Parameters';numlines=1; defaultanswer={'0','255'};
% We retrieve the answers
answer=inputdlg(prompt,name,numlines,defaultanswer);
thresh=str2num(answer{1}); % Threshold
val=uint8(str2num(answer{2})); % Value to which we change the voxels
vimage = BPGetImarisImage(vImarisApplication, 1, 1); % Retrieve the data
vimage(vimage < thresh) = val; % Threshold the data
BPSetImarisImage(vImarisApplication,vimage,1,1) % Put the data back
The functions BPGetImarisImage and BPSetImarisImage are available in the Matlab script files distributed on the ImarisXT webpages.
While you write your Matlab code, debug it, etc. you may want to stay within Matlab, i.e. not call the function from within Imaris. To do this, you will have to issue (at the Matlab prompt) the following command that starts Imaris and returns a handle:
vImarisApplication = actxserver('Imaris.Application');
vImarisApplication.mVisible = true;
This handle will let you interact with Imaris from within Matlab, e.g. to have it load data for you, etc. A good way to get an idea of what is possible from there, is to write
vImarisApplication.<TAB>
on the Matlab command line (press the <TAB> key). Several options appear that allow you to access data, have Imaris open files, etc. The different functions and variables are documented on the Imaris 4.5 COM Interface Documentation.
To call our function from within Matlab, we simply set the debug flag:
ImarisXTThreshold(vImarisApplication,'debug');
2) To add a menu to the Imaris window: In Imaris, go to Preferences → Tools → Export...
Save the file somewhere, then edit it, adding the following lines to the XML configuration file
<Item name="ImarisXTThreshold">
<Command>Matlab::ImarisXTThreshold(%i)</Command>
</Item>
Finally, import the modified file, by selecting Preferences → Tools → Import...
Acknowledgements
This document was created from notes I took during two tutorial lessons given by Peter Majer, Bitplane AG.
Copyright and Disclaimer
Copyright © 2005 Michael Liebling
IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, OF ANY KIND WHATSOEVER, ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF HE HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
THE COPYRIGHT HOLDER SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE AND ACCOMPANYING DOCUMENTATION IS PROVIDED "AS IS". THE COPYRIGHT HOLDER HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
