40 matlab

Introduction

Package matlab could be loaded via the standalone binary, or in Lua with require("aprilann.matlab).

The MAT-file format belongs to Matlab software. We follow this documentation to implement this loader. Saving is not available.

Currently, only Cell Arrays, Structures, and Numeric Matrices could be loaded, all of them only in binary format. Compression is allowed. All the data must follow the guidelines described at the documentation.

Test files

We use three test files (test1.mat, test2.mat, and test3.mat) produced by the following Matlab commands:

test 1

> x = [ -1.34187  -1.77726  -1.73478  ...
> -0.932328  0.59467  0.332692 ...
> ...
> ];
> save("test1.mat", "x")

test 2

> A = [ 1 2 3; 4 5 6 ];
> B = [ 7 8 9; 10 11 12 ];
> C = { A, B };
> save("test2.mat", "C")

test 3

> X.w = 1
> X.y = 2
> X.z = 3
> save("test3.mat", "X")

Basic operations

The MAT-file could be loaded using the function matlab.read. This function shows at the screen commented lines which indicates the kind of data loaded and the name of the variables. All the Matlab variables will be allocated at a Lua table, indexed by the name of the variable.

> a_table = matlab.read("test1.mat")
> print(a_table.x)
 1.34187    -1.77726    -1.73478    ...
-0.932328    0.59467     0.332692   ...
-0.254006   -2.86238     0.877438   ...
 ...         ...         ...        ...

It is also possible to print fields of the table using the print or tostring functions. The following example shows the print function for a Cell Array.

> a_table = matlab.read("test2.mat")
> print(a_table)
C : matlab.cell_array dims [1,2]
> print(a_table.C:get(1,1))
 1           2           3         
 4           5           6         
# MatrixDouble of size [2,3] stride [3,1] ref [0x22bebe0 data= 0x2206400]
> print(a_table.C:get(1,2))
 7           8           9         
 10          11          12        
# MatrixDouble of size [2,3] stride [3,1] ref [0x239f120 data= 0x2379ed0]

Loading matrices

When a MAT-file with MAT-matrix variables is loaded, every MAT-matrix is converted to APRIL-ANN matrix objects. Five matrices are available, depending on the MAT-matrix data-type: matrix for float, matrixDouble for double, matrixInt32 for int32, matrixComplex for float complex numbers, and matrixChar for char.

Loading Cell Arrays

If any of the variables is a Cell Array, it becomes a Lua object (a table with methamethods) which has the following methods:

• table = c:dim() returns a table with the size of each dimension of the array.

• number = c:dim(number) returns the size of the given dimension (starging in 1)

• element = c:get(p1,p2,...,pn) returns the element at the position (p1,p2,...,pn), where element could be a matrix, matrixChar, matrixInt32, cell_array, or structure, depending on the class of data.

> a_table = matlab.read("test2.mat")
> print(a_table.C:get(1,1))
 1           2           3         
 4           5           6         
# Matrix of size [2,3] in row_major [0x27a0340 data= 0x26cf9c0]
> print(a_table.C:get(1,2))
 7           8           9         
 10          11          12        
# Matrix of size [2,3] in row_major [0x283c6a0 data= 0x26e4a40]

The following methods are for low-level access, which could be useful to do a loop over all the elements:

• number = c:size() returns the number of elements at the array.

• element = c:raw_get(number) returns the element at row_major sorted position number, being number between 0 and c:size()-1. The number is the position of the element if all elements where sorted as a continuous array.

• table = c:compute_coords(number) returns the coordinate position of a given raw position number. As previous method, the number must be between 0 and c:size()-1.

> a_table = matlab.read("test2.mat")
> print(a_table)
C : matlab.cell_array dims [1,2]
> C = a_table.C
> for i=0,C:size()-1 do e=C:raw_get(i)print("COORDS",unpack(C:compute_coords(i)))print(e)end
COORDS         1	1
 1           2           3         
 4           5           6         
# Matrix of size [2,3] in row_major [0x1904b20 data= 0x18c90f0]
COORDS         1	2
 7           8           9         
 10          11          12        
# Matrix of size [2,3] in row_major [0x19054e0 data= 0x18caed0]

Loading Structures

The Structures are transformed in Lua tables (as dictionaries), indexed by the name of the fields, and as values the corresponding elements. As before, the elements could be any kind of matrix, cell_array, or structure.

> a_table = matlab.read("test3.mat")
> print(a_table)
X : table
> print(a_table.X)
y : matrixDouble
z : matrixDouble
w : matrixDouble
> print(a_table.X.y)
 2         
# Matrix of size [1,1] in row_major [0xd999c0 data= 0xd99690]
> print(a_table.X.w)
 1         
# Matrix of size [1,1] in row_major [0xd99b60 data= 0xd99c20]
> print(a_table.X.z)
 3         
# Matrix of size [1,1] in row_major [0xd99d30 data= 0xd99df0]