Short Description
Low-level library for reading and writing Matlab .mat files. This library also provides tools to convert the 5D Icy sequences into the Matlab data structure, which is basically a n-dimensional (nD) array. This plugin is only a library. Please install the 'Matlab importer' and 'Matlab exporter' plugins if you need to perform import and export operations on Matlab .mat files through the GUI; to use these features within the Blocks plugin framework, please install 'Matlab blocks'.Documentation
This plugin provides both low-level tools for reading and writing Matlab .mat files as well as conversion tools between the 5D Icy sequences and the Matlab data structure, which is basically a n-dimensional (nD) array. It is divided into 3 main packages:
- plugins.ylemontag.matlabio.lib.* : low-level tools for reading and writing Matlab .mat files. See the code documentation of the MatFileReader and MatFileWriter classes for more details.
- plugins.ylemontag.matlabio.* : conversion layer between the Matlab data structure (nD arrays) and the Icy data structure (5D sequences). See the code documentation of the MatlabImporter and MatlabExporter classes for more details.
- plugins.ylemontag.matlabio.gui.* : useful SWING and Icy components related to the objects defined in plugins.ylemontag.matlabio.* .
Low-level read/write library for Matlab .mat files
The classes defined in the subpackage plugins.ylemontag.matlabio.lib.* provide low-level tools for reading and writing Matlab .mat files. This subpackage is completely Icy-independent.
This low-level tasks used to be done by the JMatIO library in the early versions of the plugin. However, in order to fix the limitation of this library (such as reading files bigger than 2GB), the low-level layer has been completely re-written. Therefore, the plugin does not depend on JMatIO anymore.
Conversion between 5D Icy sequences and nD Matlab arrays
The main problem encountered by the conversion layer between the Matlab data structure (nD arrays) and the Icy data structure (5D sequences) is to determine which dimension of a given Matlab nD array corresponds to the X dimension of the corresponding Icy sequence, which one corresponds to the Y dimension, which one corresponds to the Z dimension, and so on. There is no canonical way to establish this correspondence, so the user has to specify it before any conversion operation ; in the java code, this correspondence is defined by a DimensionMapping object.
The second problem encountered is to determine what to do with complex-valued Matlab arrays. The MatlabImporter class proposes 3 modes to import this kind of data: import only the real part, only the imaginary part, or import both. In the latter case, the number of channels in the resulting Icy sequence is two times bigger than the size the Matlab array along the corresponding dimension: the even channels hold the real part of the imported data, while the odd channels hold the imaginary part.
To make things clearer, consider the following example:
Input: 512 x 256 x 3 complex-valued Matlab array || || DimensionMapping: map dimension 1 to Y, dimension 2 to X, dimension 3 to C || Complex import mode: import both the real and the imaginary part ||/ / Output: sequence with size X = 256, size Y = 512 and size C = 6
In the resulting sequence, channel 0 holds the real part of input(:,:,1), channel 1 holds the imaginary part of input(:,:,1), channel 2 holds the real part of input(:,:,2), and so on. Some complex specific operations on this kind of sequences are provided by the Complex toolbox plugin.
Finally, one should mention that conversion between Matlab data structure and Icy sequences preserves the underlying datatype: double-valued arrays are converted into double-valued sequences, unsigned 8 bit-valued arrays to unsigned 8 bit-valued sequences, etc.
