MATLAB functions

VisBio has the ability to interface with MATLAB. If you have a routine written in MATLAB, you can set up a MATLAB function data object that takes an existing data object as input and generates output data by calling its associated MATLAB function for each image plane.

Configuring MATLAB for use with VisBio

To connect to MATLAB, VisBio must be launched from within the MATLAB environment. To make this possible, follow these steps:
  1. Start MATLAB.
  2. At the prompt, type:
    edit classpath.txt
  3. Scroll to the bottom of the file, and append one line for each of VisBio's JAR files. These files can be found in your VisBio folder (on Mac OS X, option-click the VisBio icon and choose "Show package contents" from the menu, then navigate into Contents, Resources, Java to find the JAR files). On each line, put the full path of one JAR file. For example, if you are running Windows and installed VisBio to "C:\Program Files\VisBio" you would add the following lines:
    C:\Program Files\VisBio\bio-formats.jar
    C:\Program Files\VisBio\commons-httpclient-2.0-rc2.jar
    C:\Program Files\VisBio\commons-logging.jar
    C:\Program Files\VisBio\forms-1.0.4.jar
    C:\Program Files\VisBio\ij.jar
    C:\Program Files\VisBio\looks-1.2.2.jar
    C:\Program Files\VisBio\ome-java.jar
    C:\Program Files\VisBio\visad-lite.jar
    C:\Program Files\VisBio\visbio.jar
    C:\Program Files\VisBio\xmlrpc-1.2-b1.jar
  4. Save the file and close the editor.
  5. Restart MATLAB to apply the classpath changes.
The above steps need only be performed once.

Launching VisBio from within MATLAB

Once you have configured the classpath as described above, change the MATLAB working directory to your VisBio folder, then type "visbio" to launch VisBio. For example, if you are running Windows and installed VisBio to "C:\Program Files\VisBio" you could type the following at the MATLAB prompt:
cd 'C:\Program Files\VisBio'
visbio

After VisBio starts up, check the System panel. The MATLAB library should show a version number (if it says "Missing" then something went wrong). You should also see "MATLAB function" listed as an option beneath the "Add >" button on the Data panel.

Calling a MATLAB function from VisBio

First, import your dataset as described in the Importing a dataset from disk topic. Select your data from the list, then click the "Add >" button and choose "MATLAB function" from the popup menu.

Type in your function's name, then choose a name for the MATLAB object. VisBio will create another data object, a child of your original dataset, that represents the results of the function. VisBio will call your MATLAB function for each image plane of the parent data object.

Writing a MATLAB function for use in VisBio

VisBio expects MATLAB functions to be declared in a specific way. Your function's declaration should be as follows:
function [result] = fname(pix, params)
where "fname" is the name of your function, "pix" is a 3D array of pixels dimensioned (Y, X, N), and "params" is a vector of any additional numeric parameters needed for your algorithm.

VisBio calls the function in three distinct ways. First, it calls "fname([ ], [ ])" to retrieve a list of parameters and their default values. It expects to get back a cell array of 1x2 cell arrays, with the first element containing a string indicating the parameter's name, and the second element containing a double-precision floating point value indicating its default value. See the convert.m example script for an illustration.

Secondly, VisBio calls "fname([ ], [Y X N A B C ...])" where Y, X and N represent the dimensions of an input image (X by Y resolution with N range components) and A, B, C, etc., are parameter values for the function. VisBio expects to get back a vector of length 3 containing the Y, X and N dimensions of the output image that would be produced were an actual image to be passed in with the specified parameters. The purpose of requiring this functionality is to provide VisBio with a way to predict how big the output images will be for a given set of input images with certain parameter values. Note that VisBio requires that all output images be dimensioned the same for each given set of image dimensions and parameters.

Lastly, VisBio makes the actual call of "fname(pix, params)" to obtain the result for a given image plane with the specified parameters.

VisBio comes with several example functions (files with extension .m, other than visbio.m and vbget.m), which should serve to illustrate the proper structure. It is probably easiest to begin with one of them, edit as desired, and save to a new file.

See also: