Imaris XTension User Guide
User Manual:
Open the PDF directly: View PDF 
.
Page Count: 12
1 What is an XTension?
XTensions are user-created plug-ins for ImarisXT. They allow you to run functions that Imaris does not
have built into it already as well as create your own functionality within Imaris.
2 Running Imaris XTensions
2.1 Imaris License
In order to run Imaris XTensions, you will need a working Imaris license.
2.2 MATLAB Runtime Compiler
To run XTensions written in MATLAB (which is most of them) you will need a MATLAB Runtime Compiler.
No MATLAB license is required to download or use the MATLAB Runtime Compiler. This can be
downloaded from mathworks.com/products/compiler/matlab-runtime.html. Imaris XTensions require
you to download and install the R2018b (9.5) version of the MATLAB Runtime Compiler.
Once you have downloaded the MATLAB Runtime Compiler, you should run the installer with all of the
default options.
After you have run the installer, you will have to point Imaris to where the runtime compiler is. To do
this, in Imaris, go to File -> Preferences -> Custom Tools. Next to where it says “Matlab Runtime MCR”
click “Add” to point to the path where you saved the MCR. When prompted, point it to Program
Files/MATLAB/MATLAB Runtime/v95 and click “Select Folder”.
2.3 Using XTensions
To view available XTensions in Imaris, go into Surpass and click the Image Processing dropdown.
MATLAB XTensions will be visible with a MATLAB logo next to them. When Imaris is properly connected
to MATLAB, this logo will be in color. Otherwise it will be grayed out. Imaris will come with certain
XTensions already installed and available to you.
2.4 Adding Custom XTensions
When you have a MATLAB XTension in the form of a .exe file, you can add it to the XTensions Imaris can
see. In order to do this, you will have to move the .m file into a folder where Imaris is looking for
XTensions. To see where Imaris looks for XTensions, go to File -> Preferences -> Custom Tools.
Where it says “XTension Folders”, it will show the path to the folders it looks in when looking for
XTensions. You can move your .m file into a folder it is already looking at. Modifying the folder it’s
looking at can sometimes require administrative privileges. If this is the case and you do not have
administrative privileges, you can add the folder your .m file is already in to where Imaris looks by using
the “Add” button.
Once you have this path pointing to the folder with the Imaris XTension(s) you want to use, restart
Imaris and the custom XTension(s) will appear in the dropdown menu with the other XTensions.
3 Spectral Unmixing XTension
3.1 XTension code
The Spectral Unmixing XTension written and maintained by the Multiphoton Research Core is available
on Box here: https://rochester.app.box.com/file/363188048106 and on GitHub here:
https://github.com/tristan-mcrae-rochester/Multiphoton-Image-
Analysis/blob/master/Spectral%20Unmixing/Code/XTSpectralUnmixing.exe
Download the XTSpectralUnmixing.exe file linked above from either source and save it to your
computer.
The spectral unmixing application also requires a matching XML file to be saved in the same folder. The
XML file for XTSpectralUnmixing is available for download in the box here:
https://rochester.app.box.com/file/363271106451 and on github here: https://github.com/tristan-
mcrae-rochester/Multiphoton-Image-
Analysis/blob/master/Spectral%20Unmixing/Code/XTSpectralUnmixing.XML
Using the instructions from section 2.4, point Imaris to the location where you saved the XTension.
3.2 Running the XTension
The Spectral Unmixing XTension can be found under Image Processing -> Spectral Unmixing
After you select Spectral Unmixing, you will be prompted to choose your unmixing method. Currently
only k-means unmixing is supported in this XTension but other methods will be available in the future
for different unmixing scenarios.
After selecting k-means, you will then be asked how about a number of options:
How many fluorophores you want to unmix (including background) – The number of clusters the
algorithm will create. This is the “k” in k-means. A good starting point is to select every channel for
unmixing and ask it to unmix however many fluorophores were present during imaging +1 for a
background cluster. If there are some channels that you know already only include one fluorophore, you
can reduce the number of fluorophores you want to unmix by one. Note! This is different than previous
versions where a background cluster was automatically added behind the scenes. If, after unmixing, it
seems like there are still multiple fluorophores contained in some of the output channels, you can
increase the number of fluorophores you ask it to unmix. This will have the effect of adding more
clusters to k-means. If done successfully, this will result in two or more clusters that represent the same
fluorophore but no clusters that represent multiple fluorophores.
Select which channels to unmix - Any channel whose box you check will be included in the unmixing and
any unchecked channel will simply be preserved in the final image. If there are some channels that you
know already only include one fluorophore, you can uncheck their box.
Number of replicates – Runs k-means multiple times and uses the best result. More replicates will
improve clustering quality at the expense of taking longer. There tends to be diminishing returns with
number of replicates. I recommend starting with something around 25 and changing it as needed for
faster or higher quality results.
Representative timestep to base clustering on – In order to speed up clustering, clusters are defined
based one 2D slice of your data and then applied to the rest of your data afterwards. Choose a timestep
where you can see all of the different structures and colors. This number indexes from 1. If you only
have one timestep, put 1 here.
Representative slice to base clustering on – Same as representative timestep but for an axial slice.
Cluster based on Ratio of Channels (instead of absolute channel values) – Scales intensity values in each
pixel so that the sum of all channels for a given pixel is 1. Checking this box will group together pixels
with similar color but different absolute intensity.
Allow multiple fluorophores per pixel – Select if you want each pixel to be able to belong to multiple
output clusters. Implements fuzzy c-means instead of k-means.
Infer channel names – Select if you want the output clusters to be named and colored according to the
original names their channels had in Imaris. This will not necessarily work in cases where fluorophores
overlap and double checking the names it gives channels is recommended.
The progress of k-means will be displayed in a window which will pop up automatically after a minute or
so when you start the XTension.
3.3 Cleaning up the Results
After running, the Spectral Unmixing XTension will automatically return the results to Imaris. If you don’t
use the “infer channel names” option, Imaris won’t automatically know how to color or scale the
channels so you may have some weird looking outputs at first. This is easily fixable with some manual
adjustment.
You can manually change the appearance of the channels with Imaris’s Display Adjustment tool which
can be brought up with ctrl+d on Windows or with Edit -> Show Display Adjustment. Here you can adjust
channel intensities and turn off the background channel by unchecking it’s box.
To make your new channels reflect the colors of the old ones, you can click on “Channel #” and then use
the “Base Color” tab of the ensuing pop-up to change the color. Do this for each channel whose display
color you want to change. It won’t change the data, just its display in Imaris. If you have multiple clusters
for the same fluorophore, this is a good time to combine them visually by setting them to be the same
color.
4 Other useful XTensions
4.1 An online community where user-created XTensions are created and discussed can be found here:
http://open.bitplane.com/ If you are looking for functionality that Imaris doesn’t already have, this is a
good place to check to see if there is a solution.
4.2 You can also integrate XTensions from Python or Fiji / ImageJ into Imaris. They are generally less
popular and worse documented than MATLAB XTensions but they are a possibility.
