OME-Matlab Connector

Tom Macura (April 2007)

MATLAB is a high-level, interactive, programming environment for numerical computation. With its companion toolboxes MATLAB provides more than a 1000 built-in mathematical, statistical, and engineering functions. Since MATLAB supports programming language constructs e.g. looping, conditional logic, and functions, it is easy to implement novel algorithms as MATLAB scripts to leverage built-in functions.

MATLAB has an estimated 300,000+ users and has become the dominant language for numerical computing in many scientific and engineering communities.

We've used the MathWorks MATLAB External API to develop a strong coupling between OME and MATLAB.

• Algorithms implemented as MATLAB scripts can be wrapped-up, by defining in XML their data interfaces, into OME Analysis Modules and linked together to form Analysis Chains. OME MATLAB Analysis Modules are executed by the Analysis Engine through the Matlab Handler.
• We wrote MEX bindings to the omeis-http client library that make pixels stored in OMEIS accessible in the MATLAB interactive environment.

Prerequisites Check

If you would like to install the optional OME/MATLAB Connector you must have a recent version of MATLAB installed on the computer running the OME server. MATLAB versions 6.5 and 7.0-7.4 are known to successfully work with OME. We have most experience using MATLAB that is licensed on a per user-basis with the lmstart daemon, although OME is also known to work with the Student Edition.

Before attempting to install the OME/MATLAB connector, please verify that MATLAB is installed and correctly configured -- especially with regard to the MATLAB licensed user. If chains will be executed via command-line ome execute then the system user executing ome must be a MATLAB licensed user. If you want chains to be executable via the web interface, the Apache user (e.g. www or apache) must be licensed to run MATLAB.

The best way to test your MATLAB configuration is to attempt executing MATLAB as the appropriate (i.e. MATLAB licensed) user from the server's command-line.

[ome.grc.nia.nih.gov:~] igg% matlab -nojvm -nodisplay

  > M A T L A B >
  Copyright 1984-2004 The MathWorks, Inc.
  Version 7.0.1.24704 (R14) Service Pack 1
  September 13, 2004
  
  
  To get started, type one of these: helpwin, helpdesk, or demo.
  For product information, visit www.mathworks.com.
  
  >> 

N.B: The OME installer uses which matlab to auto-detect specifics of your MATLAB install. Hence it is preferable to modify the PATH environment variable to include the path to the MATLAB executable rather than specify the full-path on the command-line.

Install process

The Matlab Perl API (specifically the Matlab Handler defined in MatlabHandler.pm) is a set of Perl bindings defined in Matlab.xs and compiled at install time against the proprietary MATLAB Engine and MX Array Manipulation C libraries from MathWorks. If you are missing MATLAB or MATLAB isn't properly configured, the OME install will fail at this point.

---------------------------
  Optional OME-MATLAB Setup
  ---------------------------
  
  (All verbose information logged in /var/tmp/OME/install/MatlabTask.log)
  
  Testing MATLAB configuration 
  \_ Checking if user tmacur1 is licensed to run /usr/local/matlab_74/bin/matlab [SUCCESS].
  
  MATLAB Perl API configuration:
  Install MATLAB Perl API?: yes
  MATLAB User: tmacur1
  MATLAB Path: /usr/local/matlab_74
  MATLAB Exec: /usr/local/matlab_74/bin/matlab
  MATLAB Exec Flags: -nodisplay -nojvm
  Config MATLAB for dev?: no
  MATLAB .m files Path: /OME/matlab
  
  Are these values correct ? [y/n]: y
  \_ Double checking if user tmacur1 is licensed to run /usr/local/matlab_74/bin/matlab [SUCCESS].
  \_ Gathering information about your MATLAB installation
  Matlab Vers: 7.4.0.336
  Matlab Arch: glnx86
  Matlab Root: /usr/local/matlab_74
  Include: -I/usr/local/matlab_74/extern/include
  Lib:     -L/usr/local/matlab_74/bin/glnx86 -lmx -leng -lut -lmat -licudata -licui18n -licuuc -lustdio -lz
  
  Installing MATLAB Perl API 
  \_ Configuring [SUCCESS].
  \_ Compiling [SUCCESS].
  \_ Testing [SUCCESS].
  \_ Installing [SUCCESS].
  Installing MEX Interface to omeis-http
  \_ Configuring omeis-http with MATLAB bindings [SUCCESS].
  \_ Compiling omeis-http with MATLAB bindings [SUCCESS].
  Installing OME MATLAB .m files 
  \_ Writing ome-Matlab.h[SUCCESS].
  \_ Compiling MEX files [SUCCESS].
  \_ Installing [SUCCESS].

Once the OME install has finished, you can test your OME/MATLAB connector by attempting to execute a test Analysis Chain: src/xml/OME/Tests/HistogramEqualizationChain.xml. The Histogram Equalization module, src/xml/OME/Analysis/Filter/HistogramEqualization.ome, is a wrapper for the image processing toolbox MATLAB command histeq.

Post Install Configuration

The dynamically linked libraries search path needs to be modified to point to MATLAB's libraries.

In Linux, write the path to the MATLAB's libraries (e.g. /usr/local/matlab_74/bin/glnx86/) in /etc/ld.so.conf.d/matlab.conf (matlab.conf is a new file) and run /sbin/ldconfg.

On the Mac, the path to MATLAB's libraries is modified by the DYLD_LIBRARY_PATH environment variable. Define that variable (e.g. export DYLD_LIBRARY_PATH='/Applications/MATLAB704/bin/mac') in your ~/.profile file.

FAQ

• The OME/MATLAB connector install might fail because of the following compilation error (this message is written to MatlabTask.log):

   /usr/local/matlab_74/extern/include/tmwtypes.h:704: error: two or more data types in declaration specifiers
        /usr/local/matlab_74/extern/include/tmwtypes.h:704: warning: useless type name in empty declaration

  The solution is to add #include <stdbool.h> to tmwtypes.h.

  Newer versions of the gcc complier (gcc-4.x) are C99 compliant. Previous C standards didn't define the boolean type and so various incompatible methods were used to simulate the booleans. In the C99 standard the bool keyword is defined in its own header (stdbool.h).