Introduction
Sometimes it is required that you export calculated data from one environment to another. The same thing occurred when you are working with C/C++ and also MATLAB environment. In this case, some tools must already exist to act as a bridge for both environments. MATLAB C MAT-File APIs are a group of functions for reading/writing a MAT compatible file from C/C++ environments that can be read by MATLAB. This means that if you save your variables data (result of some calculation) from MATLAB, you can read them from a C program and continue your calculation and if you compute something in your program and want to save them in a file that MATLAB can read them without any problem, you can use these APIs.
C MAT-File APIs
MATLAB C MAT-File APIs are those functions for opening a file and saving data in a compatible format for using them in MATLAB. The first step to use these functions is including mat.h header file. Notice that if you want to use MATLAB built-in functions, you must include matlab.h header file too. The second step is adding MATLAB libraries to your project. The required library is libmat.lib. If you use another MATLAB APIs, add their libraries too. For example, if you use mlfPrintMatrix
function to print matrix elements, you must add libmx.lib, libmatlb.lib and libmmfile.lib.
Below are some of basic C MAT-File APIs with their description and syntax:
MATFile *matOpen(const char *filename, const char *mode);
Arguments: filename
is name of file to open, mfp
is a pointer to MAT-file information and mode
is file opening mode.
Legal values for mode listed in Table 1:
r | Opens file for reading only; determines the current version of the MAT-file by inspecting the files and preserves the current version. |
u | Opens file for update, both reading and writing, but does not create the file if the file does not exist (equivalent to the r+ mode of fopen); determines the current version of the MAT-file by inspecting the files and preserves the current version. |
w | Opens file for writing only; deletes previous contents, if any. |
w4 | Creates a MATLAB 4 compatible MAT-file. |
Description: This function allows you to open MAT-files for reading and writing.
matOpen
opens the named file and returns a file handle, or NULL if the open fails. You must close the file by using
matClose
function.
char **matGetDir(MATFile *mfp, int *num);
Arguments: mfp
is a pointer to MAT-file information. num
is address of the variable to contain the number of mxArray
variables in the MAT-file.
Description: This function allows you to get a list of the names of the mxArray
variables contained within a MAT-file. matGetDir
returns a pointer to an internal array containing pointers to the NULL
-terminated names of the mxArrays
in the MAT-file pointed to by mfp
. The length of the internal array (number of mxArrays
in the MAT-file) is placed into num
. The internal array is allocated using a single mxCalloc
and must be freed using mxFree
when you are finished with it. matGetDir
returns NULL and sets num to a negative number if it fails. If num
is zero, mfp
contains no arrays. MATLAB variable names can be up to length mxMAXNAM
, where mxMAXNAM
is defined in the file matrix.h.
mxArray *matGetVariable(MATFile *mfp, const char *name);
mxArray *matGetNextVariable(MATFile *mfp, const char *name);
Arguments: mfp
is a pointer to MAT-file information and name
is name of mxArray
to get from MAT-file.
Description: matGetVariable
allows you to copy an mxArray
out of a MAT-file.
matGetVariable
reads the named mxArray
from the MAT-file pointed to by mfp
and returns a pointer to a newly allocated mxArray
structure, or NULL
if the attempt fails.
matGetNextVariable
allows you to step sequentially through a MAT-file and read all the mxArrays
in a single pass. The function reads the next mxArray
from the MAT-file pointed to by mfp
and returns a pointer to a newly allocated mxArray
structure. MATLAB returns the name of the mxArray
in name
.
Use matGetNextVariable
immediately after opening the MAT-file with matOpen
and not in conjunction with other MAT-file functions. Otherwise, the concept of the next mxArray
is undefined.
matGetNextVariable
returns NULL when the end-of-file is reached or if there is an error condition.
In both functions, be careful in your code to free the mxArray
created by this routine when you are finished with it.
int matPutVariable(MATFile *mfp, const char *name, const mxArray *mp);
Arguments: mfp
is a pointer to MAT-file information. name
is name of mxArray
to put into MAT-file. mp
is an mxArray pointer.
Description: This function allows you to put an mxArray
into a MAT-file. matPutVariable
writes mxArray
mp
to the MAT-file mfp
. If the mxArray
does not exist in the MAT-file, it is appended to the end. If an mxArray
with the same name already exists in the file, the existing mxArray
is replaced with the new mxArray
by rewriting the file. The size of the new mxArray
can be different than the existing mxArray
. matPutVariable
returns 0 if successful and nonzero if an error occurs.
Importing Variables Data From MATLAB
For saving variables in MATLAB, just use save
command. for example:
save myFile
By entering the above command, MATLAB will save all of variables in its workspace in a file named myFile.mat. For saving only some variable, use save command like:
save myFile X Y Z
with above command, MATLAB saves only X, Y and Z variables. Now we want to use C MAT-File APIs to read myFile.mat and extract all of saved variables. Below is our C code to doing this:
#include "stdafx.h"
#include "mat.h"
#include "matlab.h"
#pragma comment(lib, "libmat.lib")
#pragma comment(lib, "libmx.lib")
#pragma comment(lib, "libmatlb.lib")
#pragma comment(lib, "libmmfile.lib")
void main(int argc, char **argv)
{
MATFile *pmat;
const char* name=NULL;
mxArray *pa;
pmat = matOpen("myFile.mat", "r");
if (pmat == NULL)
{
printf("Error Opening File: \"%s\"\n", argv[1]);
return;
}
pa = matGetNextVariable(pmat, &name);
while (pa!=NULL)
{
printf("\nArray %s has %d dimensions.", name,
mxGetNumberOfDimensions(pa));
mlfPrintMatrix(pa);
pa = matGetNextVariable(pmat,&name);
mxDestroyArray(pa);
}
matClose(pmat);
}
Exporting Variables Data To MATLAB
It's time to do reverse task. In other hand we want to calculate something and save data to a file that MATLAB can read it. To import data from a MAT-File to MATLAB environment, one must use load command:
load myFile
Load command, load workspace variables from a file located on your disk. Following source code, define some mxArray varialbe and then save them in a file. This file can be called from MATLAB environment.
#include "stdafx.h"
#include "mat.h"
#include "matlab.h"
#pragma comment(lib, "libmat.lib")
#pragma comment(lib, "libmx.lib")
#pragma comment(lib, "libmatlb.lib")
#pragma comment(lib, "libmmfile.lib")
void main(int argc, char **argv)
{
MATFile *pmat;
double dbl1[]={1.1, 4.3, -1.6, -4, -2.75};
double dbl2[]={-4.9, 2.3, -5};
mxArray *AA, *BB, *CC;
A=mxCreateDoubleMatrix(1, 5, mxREAL);
B=mxCreateDoubleMatrix(1, 3, mxREAL);
memcpy(mxGetPr(A), dbl1, 5 * sizeof(double));
memcpy(mxGetPr(B), dbl2, 3 * sizeof(double));
C=mlfConv(A, B);
pmat=matOpen("TestVar.mat", "w");
matPutVariable(pmat, "A", A);
matPutVariable(pmat, "B", B);
matPutVariable(pmat, "C", C);
matClose(pmat);
mxDestroyArray(AA);
mxDestroyArray(BB);
mxDestroyArray(CC);
}
Enjoy!