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 |
mxSINGLE_CLASS | float |
mxINT8_CLASS | smallint |
mxUINT8_CLASS | smallint |
mxINT16_CLASS | smallint |
mxUINT16_CLASS | smallint |
mxINT32_CLASS | smallint |
mxUINT32_CLASS | bigint |
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>