Personal tools
  • We're Hiring!

You are here: Home Documentation Previous versions OME Server Developer XML Schemas Analysis Modules MATLAB Handler

MATLAB Handler

The Matlab handler uses ExecutionInstructions from an Analysis Module's XML declaration to convert OME semantic type attributes into a format expected by the MATLAB function that implements the module. Since the Matlab handler is only applicable to labs that use MATLAB, it is an optional OME component that you can choose to install.

In the modules' XML description, ModuleType should be OME::Analysis::Handlers::MatlabHandler and ProgramName refers to the name of the MATLAB function that implements the algorithm. The Matlab handler assumes all user defined .m files can be found in the directory selected during installation as "Matlab .m src directory." That directory is by default, /OME/matlab but can be modified post-install with ome configure. Save your .m files there.

Data Types

MATLAB functions have access to all data that is managed by OME. As is discussed on the Defining New STs web-page, image pixels are stored in OMEIS and attributes are stored in a Postgress DB. This requires that there be an established equivalence between MATLAB data-types and Postgress/OMEIS data-types. This mapping is summarised in Tables 1 and 2.

mxCHAR_CLASS string
mxLOGICAL_CLASS boolean
mxDOUBLE_CLASS double
mxSINGLE_CLASS float
mxINT8_CLASS smallint
mxUINT8_CLASS smallint
mxINT16_CLASS smallint
mxUINT16_CLASS smallint
mxINT32_CLASS smallint
mxUINT32_CLASS bigint
mxINT64_CLASS bigint
Table 1: Mapping from MATLAB to Semantic Element data-types for Postgress stored attributes
mxSINGLE_CLASS float
mxINT8_CLASS smallint
mxUINT8_CLASS smallint
mxINT16_CLASS smallint
mxUINT16_CLASS smallint
mxINT32_CLASS smallint
mxUINT32_CLASS bigint
Table 2: Mapping from MATLAB to Semantic Element data-types for OMEIS pixels attributes

The Matlab handler does strong data-type checking i.e. mismatches are considered to be errors. The ConvertToDataType XML tag is used for explicit type-casting and specifies the MATLAB data-type the script input/output should be converted to in MATLAB e.g:

<PixelsArray FormalInput="Pixels Plane Slice" ConvertToDatatype="single"/>

Execution Instructions Syntax

<ExecutionInstructions> has two important parts <FunctionInputs> and the <FunctionOutputs>. These blocks are a set of <Input> and <Output> tags that describe each of the function's inputs or outputs and their order corresponds to the order they will be passed and retrieved from the function. MATLAB functions that return a variable number of outputs are not supported by the Matlab handler.

Scalar Inputs and Outputs

  • <Input><Scalar InputLocation="FormalInput.SE"/></Input>: the handler passes the value of the the Formal Inputs's Semantic Element as an input into the function.
  • <Output><Scalar OutputLocation="FormalOutput.SE"/></Output>: the function's output value is stored as a new attribute's Semantic Element.
  • <Input><ConstantScalar Value="X"/></Input>: is a mechanism by which the input to the Matlab function can be hard-coded in XML to a specific value.

Vector Outputs

We often want to take a vector outputted from a Matlab function and use it to define attributes. The VectorDecoder syntax allows us to do exactly that with vectors that have constant dimensions.

In the <FormalOutput> block you use <Output><Vector DecodeWith="VectorName"/></Output> to associate a VectorDecoder with the output. You define how the vector's components map to new attribute's semantic elements using a series of <Element Index="X" OutputLocation="FormalOutput.SemanticElement"/> tags. For example we use the following VectorDecoder block in src/xml/OME/Analysis/HaralickFeatures.ome:

<VectorDecoder ID="Haralick_Output_Vector">
        <Element Index="1"  OutputLocation="Angular Second Moment.ASM"/>
        <Element Index="2"  OutputLocation="Contrast.Contrast"/>
        <Element Index="3"  OutputLocation="Correlation.Correlation"/>
        <Element Index="4"  OutputLocation="Variance.Variance"/>
        <Element Index="5"  OutputLocation="Inverse Difference Moment.IDM"/>
        <Element Index="6"  OutputLocation="Sum Average.SumAvg"/>
        <Element Index="7"  OutputLocation="Sum Variance.SumVar"/>
        <Element Index="8"  OutputLocation="Sum Entropy.SumEntropy"/>
        <Element Index="9"  OutputLocation="Entropy.Entropy"/>
        <Element Index="10" OutputLocation="Difference Entropy.DiffEntropy"/>
        <Element Index="11" OutputLocation="Difference Variance.DiffVar"/>
        <Element Index="12" OutputLocation="First Measure of Correlation.MeasCorr1"/>
        <Element Index="13" OutputLocation="Second Measure of Correlation.MeasCorr2"/>
        <Element Index="14" OutputLocation="Maximal Correlation Coefficient.MaxCorrCoef"/>
        </VectorDecoder>

Pixels Inputs and Outputs

The Matlab handler makes it very easy to take Pixels from OMEIS and pass them as a 5D XYZCT array into the function. This array has some type (e.g. uint8, uint16, double) which corresponds to how the data is stored in OMEIS. The FormalInput/Outputs's Semantic Type must either be or inherit from Pixels.

  • <Input><PixelsArray FormalInput="FormalInputName"/></Input>
  • <Output><PixelsArray FormalOutput="FormalOutputName"/></Output>
Document Actions