MATLAB Scripting


Learn
Topics
Introduction
Getting Started
User Guides
Tutorials
Tips and Tricks
Presentations
Plugins
Techniques
All Techniques
Colocalization
Deconvolution
Registration
Segmentation
Stitching
Tracking
Visualization
Scripting
Overview
Parameters
Basics of script writing
Batch processing
Script Editor
Auto Imports
Templates
Running headlessly
Comparisons
Toolbox
Multithreading in Clojure
Multithreading in JavaScript
Chess in Jython
Languages
BeanShell
Groovy
ImageJ Macro
JavaScript
Lisp (Clojure)
MATLAB
Python (Jython)
R (Renjin)
Ruby (JRuby)
Scala

ImageJ-MATLAB is an extension which:

  • Translates data between ImageJ images and MATLAB matrices.
  • Enables execution of MATLAB scripts from inside ImageJ's Script Editor.
  • Lets you launch ImageJ and interact with it from inside MATLAB.
  • Allows developers to write additional plugins which extend these capabilities in new directions.

Contents

MATLAB tutorial for ImageJ

Prerequisites

  • Add the ImageJ-MATLAB update site. See Following an update site for more detail.
    1. You go to Fiji > Update...
    2. Once checking status is done, open Manage update sites
    3. Tick ImageJ-MATLAB
    4. And then click Apply changes on ImageJ Updater
    5. This will literally update and replace the existing, non-functional ImageJ.m file in the scripts folder with the genuine one.
  • You will need to install your own licensed copy of MATLAB. All that is provided with ImageJ are adapters for evaluating scripts written in ImageJ to MATLAB, and converters between ImageJ and MATLAB data structures.
  • Prior to MATLAB R2017b, MATLAB ships with Java 7, but ImageJ requires Java 8. You will need to change your MATLAB installation to use Java 8, by following the instructions for your platform: Windows, macOS or Linux. If you run MATLAB R2017b and later, you don't need to do this, as it ships and uses Java 8 already.
    • The command version -java will return the current Java version used by MATLAB
  • If you're new to MATLAB, first check out Mathworks' getting started guide.
  • If you're familiar with the MATLAB language but haven't written .m scripts before, look through the script examples.

Creating MATLAB scripts inside ImageJ

Using the Script Editor you will be able to select MATLAB from the language menu. You can also install and run .m scripts via the standard script plugin infrastructure.

Actually running a MATLAB script from ImageJ is effectively like calling eval on the script's contents. The script will be evaluated as such in a remote MATLAB instance (which will be launched automatically, if needed). Note that only scripts, not functions, can be evaluated in this way. See the MATLAB documentation for an explanation of these concepts.

Options for controlling the startup of MATLAB, or killing existing MATLAB processes (e.g. if hidden) can be accessed via:

   Edit  ▶  Options  ▶  MATLAB...

NB: because the script is being passed from ImageJ to a remote MATLAB, MATLAB will not have access to ImageJ's classpath. Objects can be passed as variables to MATLAB (e.g. by using @ annotation) but only if they are valid MATLAB classes or specially handled classes.

For example, by default all MatlabNumericArrays will be converted to matrices within MATLAB. We also support auto-conversion of ImageJ Datasets out of the box, which can be read in by scripts using "@matrix" parameters:

% @matrix data
% @OUTPUT net.imagej.Dataset rval
% @OUTPUT net.imagej.Dataset mask

% Performs dilation with a 3x3 square,
% operating on the active dataset
% Outputs the dilated mask and the original image
% with the mask applied.

rval = uint8(data); % convert to uint8
rval = mat2gray(rval); % normalize data
mask = im2bw(rval,0.5); % make logical mask
se = strel('square',3); % create structure to use in dilation
mask = imdilate(mask,se); % perform dilation on the mask
rval(~mask) = 0; % subtract mask from original dataset

This script will take the active Dataset, set it as an array variable named "data" in MATLAB, and set the matrixSum output value to the sum of the first three dimensions of the dataset. Scripts requiring ImageJ classes without auto-conversion support should launch ImageJ from within MATLAB.


Global state

MATLAB retains state (e.g. declared variables) as commands are executed, and ImageJ makes no special effort to clean up after a script. So whether running internally or communicating externally with MATLAB, state will be available to and persist after script execution. Thus one can, for example, write scripts in ImageJ referencing variables declared in MATLAB, without actually initializing them in the script.

Passing Objects

The caveat to global state is that, when running ImageJ externally, ImageJ and MATLAB run in separate JVMs. As a result, most objects can not be passed between the two. This makes Datasets (and arrays) the currency that is passed between these applications.

Return values

Most of the ImageJ scripting languages have implicit return values. As mentioned above, ImageJ will only execute true scripts, which do not have return values (in the MATLAB functional sense). There is a similar concept in the ans variable, which automatically gets the return value of executed statements if they are not explicitly assigned. However, due to the global nature of the ImageJ-MATLAB script language, it is not necessarily clear if ans was set by the script or a pre-existing command. Thus the decision was made that ImageJ-MATLAB scripts will never implicitly return a value. Instead, the @OUTPUT annotation should always be used - even for ans, as shown here:

% @OUTPUT double[] ans

% This trivial script demonstrates the use of
% the "ans" variable in the SciJava-MATLAB
% script language.

% Unassigned statements in MATLAB are automatically
% assigned to "ans". However, these scripts will not
% return "ans" unless it is explicitly requested as
% an output parameter.

0

Importing classes

To reference Java classes from MATLAB you will need to import them.


When running ImageJ externally, MATLAB will not have ImageJ classes in its classpath - so they can not simply be imported. Although MATLAB does support editing its classpath this is NOT recommended, as the classes loaded by MATLAB will not be the same as those loaded in ImageJ.

Instead, you can launch ImageJ inside MATLAB and have it take care of managing the class loading for you. MATLAB then supports the use of import statements to simplify class names.


Running ImageJ within MATLAB



The ImageJ update site provides an ImageJ.m script that will start up an ImageJ instance inside a running MATLAB application. Launching the script is the same as for Miji:

addpath('/Applications/Fiji.app/scripts') % Update for your ImageJ installation as appropriate
ImageJ;

Now, you should see a new ImageJ instance shows up as a window. ImageJ launched from MATLAB.png

In your MATLAB base workspace, you'll find a variable IJM, which is a net.imagej.matlab.ImageJMATLABCommands Java object.

  • IJM.getDataset() will create a MATLAB array from the active ImageJ image using its window title as the variable name (. will be escaped with _).
  • IJM.getDatasetAs(name) will create a MATLAB array from the active ImageJ image using the variable name name (as string).
  • IJM.show(name) will display an image in ImageJ out of a MATLAB array specified by variable name name (as string).


In the MATLAB command window, you'll see something like this:

--------------------------------------------------------------
ImageJ-MATLAB 0.7.2: MATLAB to ImageJ Interface
--------------------------------------------------------------
JVM> Version: 1.8.0_144
JVM> Total amount of memory: 370176 Kb
JVM> Amount of free memory: 122756 Kb

-- Welcome to ImageJ-MATLAB --
ImageJ-MATLAB consists of an extensible set of commands for passing information between ImageJ and MATLAB.
See the individual sections below for a list of available commands.

For more information and examples see:
	http://imagej.net/MATLAB-Scripting

--- MATLAB Command Plugins ---

-- ImageJ MATLAB commands --

Usage: IJM.[command]
	help - prints a brief description of available commands
	getDataset - creates a MATLAB matrix from the active ImageJ image
	getDatasetAs(name) - creates a MATLAB matrix from the active ImageJ image, and assigns it to the specified variable name
	show(name) - takes the MATLAB matrix with the specified name and displays it as an image



--------------------------------------------------------------
Status> ImageJ is running.
--------------------------------------------------------------


The startup process automatically injects the ImageJ classpath into the MATLAB classpath, merging the two. At this point, you'll have a working ImageJ and can now run MATLAB scripts as normal with access to the full unified classpath.

Limitations

Specific to IJM.show()

  • A multi (>2) dimentional image or multi channel image is treated as a stack of single channel images irrespective of the dimensions.
  • Also, data is always handled as 32bit per channel.

Common Limitations

  • Although the first and second dimensions, respectively, of MATLAB array are treated as rows (Y)and columns (X) in MATLAB, the first and second dimensions of an array are treated as X and Y, respectively, in ImageJ. The axes are transposed by IJM.show(name), IJM.getDataset(), IJM.getDatasetAs(name). (See discussion here for details)
  • At the moment, there isn't an explicit way to quit the ImageJ instance from MATLAB (If you find a way, please report to ImageJ forum).
  • IJM object is always added to the MATLAB base workspace. In order to access IJM methods from within a MATLAB function, you'll need to use assignin and evalin (see here for details)

Examples

The following Java commands work in MATLAB command window to open a sample image in ImageJ.

imp = ij.IJ.openImage("http://imagej.nih.gov/ij/images/boats.gif");
imp.show()

Boats screenshot.png


The following will open a MATLAB array data as an image in ImageJ. Note that the X and Y of the image is transposed in ImageJ in the second image (see Limitations of IJM.show() above).

corn_gray = imread('corn.tif',3);
imshow(corn_gray); % show in MATLAB
IJM.show('corn_gray'); % show in ImageJ
corn_gray_tp = corn_gray'; % transpose array
IJM.show('corn_gray_tp'); % show in ImageJ properly

Corn gray matlab.png Corn gray.png Corn gray transposed.png

A more general solution to this issue of X-Y transposition can be achieved by permute function of MATLAB. But please beware of memory demands by permute.

% I is a MATLAB array with 2 or more dimensions
order = [{2, 1}, num2cell(3:ndims(I))];
I2 = permute(I,[order{:}]);
IJM.show(I2) % this will show an image in proper X and Y


Additionally, the Scripting-MATLAB library also includes an extensible MATLAB command framework. This allows for the creation of utility classes that will be automatically populated into MATLAB variables for easy access. For example, you could use ImageJ to open a dataset and perform thresholding (or any other processing steps), then in MATLAB use the IJM.getDatasetAs(name) command to set the active dataset as a MATLAB matrix variable with a specified name, for further analysis.

For example, instead of using a script as described above, we could achieve the same result by executing the following commands in the MATLAB prompt:

IJM.getDatasetAs('data') % import the image as a MATLAB matrix
rval = uint8(data); % convert to uint8
rval = mat2gray(rval); % normalize data
mask = im2bw(rval,0.5); % make logical mask
se = strel('square',3); % create structure to use in dilation
mask = imdilate(mask,se); % perform dilation on the mask
rval(~mask) = 0; % subtract mask from original dataset
IJM.show('rval') % display the rval array in ImageJ
IJM.show('mask') % display the mask array in ImageJ

Source

Video presentation

Publication

See also