Christopher C. Hulbert
Contents
1. This option specifies the prefix where zlib is installed with hdf5 DIR This option specifies the prefix where the HDF5 software is installed with default file ver 4 5 7 3 This option sets the default MAT file version that will be used when writing The default file version is used by the Mat Create macro and the Mat CreateVer function when MAT FT DEFAULT is used for the version argument with libdir suffix suffix This option specifies a suffix to apply to library directories when installing and looking for dependent libraries i e HDF5 and zlib For example some multi arch Linux distributions install 64 bit libraries into lib64 and 32 bit libraries into lib 12 MATIO 3 3 Visual Studio A visual studio solution is provided as visual studio matio sln The solution is set up to build a DLL of the matio library libmatio dll and matdump tool in release mode and as sumes HDF5 is available in the directory specified by the HDF5 DIR environment variable The build was tested with the HDF5 visual studio pre built Windows binaries including zlib 3 4 Testsuite A testsuite is available when building with the GNU autotools To run the testsuite First configure and build matio After building run make check to run the testsuite If matio was built without zlib the compressed variable tests will be skipped If built without HDF5 the tests for version 7 3 MAT files will be skipped If the path to the MATLAB application was2. INCLUDING BUT NOT LIMITED TO PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES LOSS OF USE DATA OR PROFITS OR BUSINESS INTERRUPTION HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY WHETHER IN CONTRACT STRICT LIABILITY OR TORT INCLUDING NEGLIGENCE OR OTHERWISE ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE 1 2 Incompatible Changes from 1 3 This version has changes that break compatability with the 1 3 versions of the matio soft ware This section lists these changes and how existing code should be modified to handle these changes 1 dims field of matvar_t structure changed to size_t MEM_CONSERVE preprocessor definition removed BY_NAME and BY_INDEX renamed Added MAT_ prefix to enumerations of matio compression OU COS As Changed name of structure for complex split format data from struct ComplexSplit to struct mat complex split t Changed name of sparse data structure from sparse t to mat sparse t 7 Changed meaning of memory conservation for cell arrays and structures 2 MATIO Each of these changes are described in the remaining sections and as necessary include recommendations to upgrade existing code for compatability with this version 1 2 1 Type Change for Dimensions Array The existing dims field of the matvar_t structure was an int which limited the maximum size of a dimension to 2 In version 1 5 the type was changed to size t which allows a variable
3. MAT C DOUBLE MAT T DOUBLE 2 dims amp z2 MAT F COMPLEX Mat VarSetStructFieldByName matvar z 1 field Mat VarWrite matfp matvar MAT COMPRESSION NONE Mat VarFree matvar Mat Close matfp return EXIT SUCCESS Chapter 3 Building matio 11 3 Building matio 3 1 Quick Build Guide The primary method for building the software is using configure followed by make After building the testsuite can be executed to test the software using make check See Section 3 4 Testsuite page 12 The software can be installed using make install For example tar zxf matio X Y Z tar gz cd matio X Y Z configure make make check make install 3 2 Configure Options enable mat73 yes no This flag enables disables the support for version 7 3 MAT files The option only makes sense if built with HDF5 as support for version 7 3 files will be disabled if HDF5 is not available enable extended sparse yes Enable extended sparse matrix data types not supported in MATLAB MAT LAB only supports double precision sparse data With this flag matio will read sparse data with other types i e single precision and integer types with matlab DIR This option specifies the directory DIR with the matlab program With this option the testsuite will check that the MAT files written by matio can be read into MATLAB see Section Section 3 4 Testsuite page 12 for more information about the testsuite with zlib DIR
4. names 1 2 4 Memory Conservation with Cells and Structures Previous versions of matio would still free fields of structures and elements of cell arrays even if created with memory conservation flag set In the latest version of matio the fields cell elements are not free d if the structure was created with the MAT F DONT COPY DATA flag This is useful if the fields elements are referenced by another variable such as the case when they are indices of a larger array i e Mat VarGetStructs Mat VarGetStructsLinear Chapter 2 Quick Start 3 2 Quick Start 2 1 Opening and Creating MAT Files This section will show how to create a new MAT file open an existing MAT file for read and read write access and close the MAT file The key functions in working with MAT files include e Mat Open e Mat CreateVer and e Mat Close The following example program shows how to open a MAT file where the filename is the first argument to the program include lt stdlib h gt include lt stdio h gt finclude matio h int main int argc char argv 1 mat t matfp matfp Mat Open argv 1 MAT ACC RDONLY if NULL matfp fprintf stderr Error opening MAT file Z s n argv 1 return EXIT FAILURE Mat_Close matfp return EXIT SUCCESS The Mat CreateVer creates a new MAT file or overwrites and existing file with a specific version The matio library can write version 5 MAT files version 5 files with variable
5. DOUBLE MAT T DOUBLE 2 dims y 0 if NULL cell element fprintf stderr Error creating cell element variable n Mat VarFree cell array Mat Close matfp return EXIT FAILURE Mat_VarSetCell cell_array 1 cell_element cell element Mat VarCreate NULL MAT C DOUBLE MAT T DOUBLE 2 dims amp z MAT F COMPLEX if NULL cell element fprintf stderr Error creating cell element variable n Mat VarFree cell array Mat Close matfp return EXIT FAILURE Mat VarSetCell cell array 2 cell element Mat VarWrite matfp cell array MAT COMPRESSION NONE Mat VarFree cell array Chapter 2 Quick Start 9 Mat Close matfp return EXIT SUCCESS 2 3 3 Writing Structure Arrays Structure arrays are multidimensional arrays where each element of the array contains mul tiple data items as named fields The fields of a structure can be accessed by name or index A field can be a variable of any type e g numeric structure cell arrays etc The preferred method to create a structure array is using the Mat VarCreateStruct func tion After creating the structure array the Mat VarSetStructFieldByName and Mat VarSetStructFieldByIndex functions can be used to set the fields of the structure array to a variable The example below shows how to create a 2 x 1 structure array with the fields z y and z include lt stdlib h gt include lt stdio h gt include matio h int main int argc char arg
6. MATIO User Manual for version 1 5 April 2012 Christopher C Hulbert Copyright C 2011 2012 Christopher C Hulbert All rights reserved Redistribution and use in source texinfo and compiled forms HTML PDF PostScript RIF and so forth with or without modification are permitted provided that the following conditions are met 1 Redistributions of source code texinfo must retain the above copyright notice this list of conditions and the following disclaimer as the first lines of this file unmodified 2 Redistributions in compiled form PDF PostScript RTF and other formats must reproduce the above copyright notice this list of conditions and the following disclaimer in the documentation and or other materials provided with the distribution THIS DOCUMENTATION IS PROVIDED BY CHRISTOPHER C HULBERT AS IS AND ANY EXPRESS OR IMPLIED WARRANTIES INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED IN NO EVENT SHALL CHRISTOPHER C HULBERT OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT INDIRECT INCIDENTAL SPECIAL EXEMPLARY OR CONSEQUENTIAL DAMAGES INCLUDING BUT NOT LIMITED TO PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES LOSS OF USE DATA OR PROFITS OR BUSINESS INTERRUPTION HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY WHETHER IN CONTRACT STRICT LIABILITY OR TORT INCLUDING NEGLIGENCE OR OTHERWISE ARISING IN ANY WAY OUT OF THE USE OF THIS DOCUMEN
7. TATION EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE Table of Contents 1 IrbrolueblOB 221292 diee e e DRE te OR ea 1 1 1 About and Licensing YYY Y FF Y FR eee es 1 1 2 Incompatible Changes from 1 3 9VI FY Y eee 1 1 2 1 Type Change for Dimensions ArTay V udd 2 1 2 2 Removed Preprocessor Flag to Conserve Memory 2 1 2 3 Renamed Structure Field Lookup Enumerations 2 1 2 4 Memory Conservation with Cells and Structures 2 2 nck SUELOS oor YC PERS e WR Y EFO 3 2 1 Opening and Creating MAT Fil 8 VV YY YY ee eee 3 2 2 Reading Variables in a MAT Fil amp YFY Y Y Yu 4 2 2 1 Reading a Variable by Name YYFY Y au 4 2 2 2 Iterating Over Variables in a MAT Fil amp 5 2 39 Writing Vauables ece esee eee edt ER d he i 6 2 3 1 Writing Numeric Arrays ssssessssseeee eee eee 6 2 3 2 Writing Cell Arrays VY Y Y e ri 2 3 8 Writing Structure Arrays V Y YF Y ud 9 3 Building mato eod YRU DYRO 11 3 1 Quick Build Guid FFY Y FF FFF eee 11 3 2 Configure Options lsssssessssssseeee eme 11 3 9 Vistial Studio iiis cete dade pP ELE YDD GOD ERG e ers 12 SE MEI Iu gss a a a Un yden do y AS 12 4 MATLAB Variable Structure 13 4 1 VariableInformation VYYY FF FFF ne 13 4 1 1 Sparse Matrix Variable8 YVVYY Y FY ua 13 4 1 2 Structure
8. Variabl S YYYY Y YF Y RY ee eee 13 4 1 3 Cell Variables ud RY YW E GAN EG Vad 14 Chapter 1 Introduction 1 1 Introduction 1 1 About and Licensing The matio software contains a library for reading and writing MATLAB MAT files The ma tio library libmatio is the primary interface for creating opening MAT files and writing reading variables This matio software is provided with the Simplified BSD License reproduced below The license allows for commercial proprietary and open source derivative works Copyright 2011 2012 Christopher C Hulbert All rights reserved Redistribution and use in source and binary forms with or without modification are permitted provided that the following conditions are met 1 Redistributions of source code must retain the above copyright notice this list of conditions and the following disclaimer 2 Redistributions in binary form must reproduce the above copyright notice this list of conditions and the following disclaimer in the documentation and or other materials provided with the distribution THIS SOFTWARE IS PROVIDED BY CHRISTOPHER C HULBERT AS IS AND ANY EXPRESS OR IMPLIED WARRANTIES INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED IN NO EVENT SHALL CHRISTOPHER C HULBERT OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT INDIRECT INCIDENTAL SPECIAL EXEMPLARY OR CONSEQUENTIAL DAMAGES
9. compression if built with zlib and an HDF5 format MAT file introduced in MATLAB version 7 3 The format of the MAT file is specified by the third argument The short example below creates a version 5 file named matfile5 mat and an HDF5 format MAT file named matfile73 mat finclude lt stdlib h gt include lt stdio h gt include matio h int main int argc char argv mat_t matfp 4 MATIO matfp Mat CreateVer matfileb mat NULL MAT FT MAT5 if NULL matfp fprintf stderr Error creating MAT file matfile5 mat n return EXIT FAILURE Mat Close matfp matfp Mat CreateVer matfile73 mat NULL MAT FT MAT73 if NULL matfp fprintf stderr Error creating MAT file V matfile73 matN Nn return EXIT FAILURE Mat_Close matfp return EXIT SUCCESS 2 2 Reading Variables in a MAT File This section introduces the functions used to read variables from a MAT file The matio li brary has functions for reading variable information only e g name rank dimensions type etc reading information and data and reading data from previously obtained informa tion Reading information and data in seperate function calls provides several conveniences including e Querying the names of variables in a file without reading data e heading only some fields of a structure or elements of a cell array and e other actions where the variable data is not needed 2 2 1 Reading a Variable by Na
10. dNext and Mat VarReadNextInfo The short example shown below opens a MAT file and iterates over the variables in the file printing the variable name include lt stdlib h gt include lt stdio h gt include matio h int main int argc char argv mat_t matfp matvar t matvar matfp Mat Open argv 1 MAT ACC RDONLY if NULL matfp fprintf stderr Error opening MAT file s0 argv 1 return EXIT FAILURE while matvar Mat VarReadNextInfo matfp NULL printf s n matvar gt name 6 MATIO Mat VarFree matvar matvar NULL Mat Close matfp return EXIT SUCCESS 2 3 Writing Variables A variable can be saved in a MAT file using the Mat_VarWrite function which has three arguments the MAT file to write the variable to a MATLAB variable structure and a third option used to control write options The variable structure can be filled in manually or created from helper routines such as Mat_VarCreate Note that MATLAB and thus matio has no concept of a rank 1 array i e vector The minimum rank of an array is 2 i e matrix A vector is simply a matrix with one dimension length of 1 2 3 1 Writing Numeric Arrays Numeric arrays can be either real or complex Complex arrays are encapsulated in the struct mat_complex_split_t data structure that contains a pointer to the real part of the data and a pointer to the imaginary part of the data The example program below writes two real va
11. le In MATLAB a global variable is available in all scopes e g base workspace function etc 4 1 1 Sparse Matrix Variables If a variable s class type is sparse the data field of the MATLAB variable structure is a pointer to the sparse matrix structure mat sparse t The sparse matrix structure stores the non zero elements of the matrix in compressed column format 4 1 2 Structure Variables If the MATLAB variable structure s class type is MAT C STRUCT the data type field should be MAT T STRUCT The data field of the variable structure is an pointer to an array of matvar t The length of the array is numel x n fields where numel is the number of elements in the structure array product of dimensions array and nfields is the number of fields in the structure The order of the variables in the array is first by field and then by structure index For example for a 2 x 1 structure array with 3 fields field1 field2 and field3 data field of the structure variable is ordered as s 1 fieldi s 1 field2 s 1 field3 s 2 fieldi s 2 field2 s 2 field3 14 MATIO 4 1 3 Cell Variables If the MATLAB variable structure s class type is MAT C CELL the data type field should be MAT T CELL The data field of the variable structure is a pointer to an array of matvar_t The length of the array is product of the dimensions array Each element of the cell array can be a different type
12. me If the name if the variable is known the Mat VarRead and Mat VarReadInfo functions can be used The Mat VarRead function reads both the information and data for a variable and the Mat VarReadInfo reads information only The short example below reads a named variable from a MAT file and checks that the variable is a complex double precision vector include lt stdlib h gt include lt stdio h gt include matio h int main int argc char argv mat_t matfp matvar t matvar matfp Mat Open argv 1 MAT ACC RDONLY if NULL matfp 1 Chapter 2 Quick Start 9 fprintf stderr Error opening MAT file s0 argv 1 return EXIT FAILURE matvar Mat VarReadInfo matfp x if NULL matvar i fprintf stderr Variable x not found or error reading MAT file n else 1 if matvar gt isComplex fprintf stderr Variable x is not complex n if matvar gt rank 2 matvar gt dims 0 gt 1 amp amp matvar dims 1 gt 1 fprintf stderr Variable x is not a vector n Mat VarFree matvar Mat Close matfp return EXIT SUCCESS 2 2 2 Iterating Over Variables in a MAT File For some applications the name of the variable may not be known ahead of time For example if the user needs to select a variable of interest a list of variables should be obtained Like reading a variable by name there are two functions that will read the next variable in the MAT file Mat VarRea
13. ng Cell Arrays Cell arrays are multidimensional arrays whos elements can be any class of variables e g numeric structure cell arrays etc To create a cell array pass an array of matvar_ t Detailed information on the MATLAB variable structure for cell arrays is given in Section 4 1 3 Cell Variables page 14 The following example shows how to create a 3x1 cell array include lt stdlib h gt include lt stdio h gt include matio h int main int argc char argv mat_t matfp matvar t cell array cell element size t dims 2 10 1 double x 10 1 2 3 4 5 6 7 8 9 10 y 10 11 12 13 14 15 16 17 18 19 20 struct mat_complex_split_t z x y MATIO matfp Mat CreateVer test mat NULL MAT FT DEFAULT if NULL matfp fprintf stderr Error creating MAT file test mat n return EXIT FAILURE y dims 0 3 dims 1 1 cell array Mat VarCreate a MAT C CELL MAT T CELL 2 dims NULL O if NULL cell array fprintf stderr Error creating variable for a n Mat Close matfp return EXIT FAILURE dims O 10 dims 1 1 cell element Mat VarCreate NULL MAT C DOUBLE MAT T DOUBLE 2 dims x 0 if NULL cell element fprintf stderr Error creating cell element variable n Mat VarFree cell array Mat Close matfp return EXIT FAILURE Mat VarSetCell cell array 0 cell element cell element Mat VarCreate NULL MAT C
14. not specified with matlab the write tests will fail if matio cannot read the file and skip if matio can read the file The write tests will pass if MATLAB is available and can also read the file To report matio testsuite failures compress the testsuite log file in the test sub directory of the build directory Upload the compressed log file along with a bug report see Section 1 4 for information on reporting bugs Chapter 4 MATLAB Variable Structure 13 4 MATLAB Variable Structure 4 1 Variable Information When a MATLAB variable is read or created all of the information about the variable e g name dimensions etc are stored in the MATLAB variable structure type matvar t name Nul terminated string that is the name of the variable The name may be NULL e g for elements of a cell array so the field should be checked prior to use rank The number of dimensions of the variable The minimum rank is 2 dims An array of the number of elements in each dimensions of the variable class type Indicates the class of the variable e g double precision structure cell etc data type Indicates the type of the data stored in the data field of the MATLAB variable structure isComplex is non zero if the variable is a complex valued numeric array isLogical is non zero of the variable should be interpreted as logical i e zero for false non zero for true isGlobal is non zero if the variable should be a global variab
15. of length 2 on 32 bit systems but 29 1 on 64 bit system To upgrade to version 1 5 all existing code should ensure the use of dims allows for size_t and that any use of the Mat VarCreate function passes an array of type size t and not int Not upgrading to size t is likely to produce segmentation faults on systems where sizeof size t sizeof int 1 2 2 Removed Preprocessor Flag to Conserve Memory Previous versions of the matio library had a preprocessor macro MEM CONSERVE that was passed as an option to Mat VarCreate to tell the library to only store a pointer to the data variable instead of creating a copy of the data Copies of scalars or small arrays are not critical but for large arrays is necessary In version 1 5 this macro has been changed to the enumeration value MAT F DONT COPY DATA A quick search replace can quickly upgrade any references to MEM CONSERVE Alternatively since MAT F DONT COPY DATA has the same value as MEM CONSERVE software using matio can simply define MEM CONSERVE to 1 1 2 3 Renamed Structure Field Lookup Enumerations The BY NAME and BY INDEX enumerations are used by Mat VarGetStructField to indicate if the field is retrieved by its name or by its index in the list of fields To bring these into a matio namespace and hopefully avoid conflicts these have been renamed to MAT BY NAME and MAT BY INDEX A quick search replace operation should be able to correct existing code that uses the old
16. riables x and y and one complex variable z whos real and imaginary parts are the x and y variables respectively Note the MAT F COMPLEX argument passed to Mat VarCreate for z to indicate a complex variable include lt stdlib h gt include lt stdio h gt include matio h int main int argc char argv 1 mat t matfp matvar t matvar size t dims 2 10 1 double x 10 4 1 2 3 4 5 6 7 8 9 10 y 10 11 12 13 14 15 16 17 18 19 20 struct mat_complex_split_t z x y matfp Mat_CreateVer test mat NULL MAT_FT_DEFAULT if NULL matfp fprintf stderr Error creating MAT file test mat n return EXIT_FAILURE matvar Mat_VarCreate x MAT_C_DOUBLE MAT_T_DOUBLE 2 dims x 0 if NULL matvar fprintf stderr Error creating variable for x n Chapter 2 Quick Start else 1 Mat VarWrite matfp matvar COMPRESSION NONE Mat VarFree matvar matvar Mat VarCreate y MAT C DOUBLE MAT T DOUBLE 2 dims y 0 if NULL matvar fprintf stderr Error creating variable for y n else 1 Mat VarWrite matfp matvar COMPRESSION NONE Mat VarFree matvar matvar Mat VarCreate z MAT C DOUBLE MAT T DOUBLE 2 dims amp z MAT F COMPLEX if NULL matvar fprintf stderr Error creating variable for z n else 1 Mat VarWrite matfp matvar COMPRESSION NONE Mat VarFree matvar Mat Close matfp return EXIT SUCCESS 2 3 2 Writi
17. v t mat t matfp matvar t matvar field size_t dims 2 10 1 struct dims 2 2 1 double x1 10 1 2 3 4 5 6 7 8 9 10 x2 10 11 12 13 14 15 16 17 18 19 20 y1 10 21 22 23 24 25 26 27 28 29 30 y2 10 31 32 33 34 35 36 37 38 39 40 struct mat complex split t zi x1 y1 z2 x2 y2 const char fieldnames 3 x y z unsigned nfields 3 matfp Mat CreateVer test mat NULL MAT FT DEFAULT if NULL matfp fprintf stderr Error creating MAT file test mat n return EXIT FAILURE matvar Mat VarCreateStruct a 2 struct_dims fieldnames nfields if NULL matvar fprintf stderr Error creating variable for a n Mat Close matfp return EXIT FAILURE 10 MATIO structure index O field Mat VarCreate NULL MAT C DOUBLE MAT T DOUBLE 2 dims x1 0 Mat VarSetStructFieldByName matvar x 0 field field Mat VarCreate NULL MAT C DOUBLE MAT T DOUBLE 2 dims y1 0 Mat VarSetStructFieldByName matvar y 0 field field Mat VarCreate NULL MAT C DOUBLE MAT T DOUBLE 2 dims amp z1 MAT F COMPLEX Mat VarSetStructFieldByName matvar z 0 field structure index 1 field Mat VarCreate NULL MAT C DOUBLE MAT T DOUBLE 2 dims x2 0 Mat VarSetStructFieldByName matvar x 1 field field Mat VarCreate NULL MAT C DOUBLE MAT T DOUBLE 2 dims y2 0 Mat VarSetStructFieldByName matvar y 1 field field Mat VarCreate NULL
Download Pdf Manuals
Related Search