MATLAB MEX Interface

MATLAB has the capacity to run functions written in C. This functionality is provided by the MATLAB MEX interface. We wrote MATLAB MEX wrappers around the OMEIS client C library to give MATLAB users easy access to OMEIS data.

We haven't yet written MEX wrappers around all OMEIS library functions. The functions with MEX wrappers have the [MATLAB] designation in our documentation.

MEX C files must allocate dynamic memory using the MATLAB memory manager, i.e. by calling the mxMalloc and mxFree functions. mxMalloc registers the returned heap space with the MATLAB memory management facility. The memory management facility automatically deallocates all of the MEX-file's memory parcels when control returns to the MATLAB prompt. This is very important for preventing memory leaks.

One implication of MEX wrapped functions is that the underlying omeis client library must be compiled against MATLAB headers and libraries in order to use mxMalloc and mxFree for memory allocation. There are configure flags that do all of the requisite changes to the library.

Examples

MATLAB deals with types such as double, single, uint8, int16 etc. whilst OMEIS is concerned with bpp, isSigned, and isFloat. The MATLABtoOMEISDatatype utility M-file translates between the conventions.

im = uint8(255*sin(meshgrid(1:512,1:512)));
head = MATLABtoOMEISDatatype(class(im));
[head.dx head.dy head.dz head.dc head.dt] = size(im);

head = 
          bp: 1
    isSigned: 0
     isFloat: 0
          dx: 512
          dy: 512
          dz: 1
          dc: 1
          dt: 1

Very much analogous to the omeis-http function of the same name, openConnectionOMEIS returns a struct containing the URL and SessionKey. This struct must be passed as the first parameter to other MEX functions.

is = openConnectionOMEIS('http://localhost/cgi-bin/omeis');

is = 
           url: 'http://localhost/cgi-bin/omeis'
    sessionkey: '00000'

Create a new set of pixels according to the dimensions and pixel type specified in the head struct. The provisional PixelsID is returned.

id = newPixels(is, head)

id =
     6

Upload the MATLAB array as pixels into the OMEIS server. Returns the number of pixels set.

setPixels (is, id, im)

>> setPixels (is, id, im)
ans =
      262144

finishPixels must be called before the pixels can be read. The final PixelsID is returned. This is usually the same as the provisional PixelsID except when the exact same pixels (based on SHA1 digest) were already uploaded into OMEIS.

n_id = finishPixels(is, id)

n_id =
     6

Use pixelsInfo to get the SHA1 digest and other information about pixels stored on OMEIS.

pixelsInfo(is, n_id)

ans = 
            dx: 512
            dy: 512
            dz: 1
            dc: 1
            dt: 1
            bp: 1
       isFloat: 0
      isSigned: 0
    isFinished: 1
          sha1: '9f60206299cd1b28f3c378cb1ce7bf0c8e47b549'

And for situations where you want to access the pixels on OMEIS :

am = getPixels (is, n_id);

For an example MATLAB script illustrating usage of this library see src/matlab/OMEIS/main_script.m .