MATLAB The Language of Technical Computing Computation Visualization Programming MAT-File Format The MathWorks Version 5
Computation Visualization Programming MAT-File Format Version 5 MATLABÆ The Language of Technical Computing
MAT-File format Introduction MAT-File formats Version 5 MAT-File format MAT-File header format 22356 Data element format Version 5 MATLAB Array Data Element Formats 10 Numeric Array and Character Array Data Element Formats.. 11 Sparse array Data Element Format Cell Array Data Element Format .22 Structure mat-file data element format MATLAB Object MAT-File Data Element Format Version 4 MAT-File format
MAT-File Format Introduction . . . . . . . . . . . . . . . . . . . . . 2 MAT-File Formats . . . . . . . . . . . . . . . . . . . 2 Version 5 MAT-File Format . . . . . . . . . . . . . . 3 MAT-File Header Format . . . . . . . . . . . . . . . . 5 Data Element Format . . . . . . . . . . . . . . . . . . 6 Version 5 MATLAB Array Data Element Formats . . . .10 Numeric Array and Character Array Data Element Formats . .11 Sparse Array Data Element Format . . . . . . . . . . . .18 Cell Array Data Element Format . . . . . . . . . . . . .22 Structure MAT-File Data Element Format . . . . . . . . .25 MATLAB Object MAT-File Data Element Format . . . . . .29 Version 4 MAT-File Format . . . . . . . . . . . . . .32
MAT-File format Introduction This document describes the internal format of matlab version 5 and Version 4 MAT-files. A MAT-file stores data in binary (not human-readable form. In MATLAB, you create MAT-files by using the save command, which writes the arrays currently in memory to a file as a continuous byte stream. By convention this file has the filename extension. mat thus the name mat-file The l oad command reads the arrays from a MAT-file into the MATLAB Most matlab users do not need to know the internal format of a mat-file ven users who must read and write MAT-files from C and Fortran programs do not need to know the MAT-file format if they use the MATLAB Application Program Interface(API). This API shields users from dependence on the details of the mat-file format However, if you need to read or write MAT-files on a system for which the MATLAB API library is not supported, you must write your own read and write outines. The MATLAB API is only available for platforms on which MATLAB is supported. This document provides the details about the MAT-file format you will need to read and write MAT-files on these systems Note Whenever possible, The MathWorks strongly advises you to use the MAT-file APi routines to read and write MAT-files. Any code you write that depends on the MAT-file format will very likely need to be rewritten when the format changes in future releases MAT-File Formats This document describes both the matlab version 5 and Version 4 MAT-file formats. The MATLAB Version 5 MAT-file format supports all the matlaB V5 array types, including multidimensional numeric arrays, character arrays sparse arrays, cell arrays, structures, and objects. Version 5 MAT-File Format"on page-3 describes this format The MATLAB Version 4 MAT-file format is a simpler format but it only supports two-dimensional matrices and character strings. "Version 4 MAT-File Format"on page -32 describes this format
MAT-File Format 2 Introduction This document describes the internal format of MATLAB ® Version 5 and Version 4 MAT-files. A MAT-file stores data in binary (not human-readable) form. In MATLAB, you create MAT-files by using the save command, which writes the arrays currently in memory to a file as a continuous byte stream. By convention, this file has the filename extension .mat; thus the name MAT-file. The load command reads the arrays from a MAT-file into the MATLAB workspace. Most MATLAB users do not need to know the internal format of a MAT-file. Even users who must read and write MAT-files from C and Fortran programs do not need to know the MAT-file format if they use the MATLAB Application Program Interface (API). This API shields users from dependence on the details of the MAT-file format. However, if you need to read or write MAT-files on a system for which the MATLAB API library is not supported, you must write your own read and write routines. The MATLAB API is only available for platforms on which MATLAB is supported. This document provides the details about the MAT-file format you will need to read and write MAT-files on these systems. Note Whenever possible, The MathWorks strongly advises you to use the MAT-file API routines to read and write MAT-files. Any code you write that depends on the MAT-file format will very likely need to be rewritten when the format changes in future releases. MAT-File Formats This document describes both the MATLAB Version 5 and Version 4 MAT-file formats. The MATLAB Version 5 MAT-file format supports all the MATLAB V5 array types, including multidimensional numeric arrays, character arrays, sparse arrays, cell arrays, structures, and objects. “Version 5 MAT-File Format” on page -3 describes this format. The MATLAB Version 4 MAT-file format is a simpler format but it only supports two-dimensional matrices and character strings. “Version 4 MAT-File Format” on page -32 describes this format
Version 5 mat-file format Version 5 mAt-file format In MATLAB Version 5, a MAT-file is made up of a 128-byte header followed by ne or more data elements. Each data element is composed of an 8-byte tag followed by the data in the element. The tag specifies the number of bytes in the data element and how these bytes should be interpreted; that is, should the bytes be read as 16-bit values, 32-bit values, floating point values or some other data type By using tags, the Version 5 MAT-file format provides quick access to individual data elements within a MAT-file. You can move through a MaT-file by finding a tag and then skipping ahead the specified number of bytes until the next tag MATLAB Version 5 MAT-File Format"on page-4 graphically illustrates this MAT-file format. The sections that follow provide more details about these MAT-file elements
Version 5 MAT-File Format 3 Version 5 MAT-File Format In MATLAB Version 5, a MAT-file is made up of a 128-byte header followed by one or more data elements. Each data element is composed of an 8-byte tag followed by the data in the element. The tag specifies the number of bytes in the data element and how these bytes should be interpreted; that is, should the bytes be read as 16-bit values, 32-bit values, floating point values or some other data type. By using tags, the Version 5 MAT-file format provides quick access to individual data elements within a MAT-file. You can move through a MAT-file by finding a tag and then skipping ahead the specified number of bytes until the next tag. “MATLAB Version 5 MAT-File Format” on page -4 graphically illustrates this MAT-file format. The sections that follow provide more details about these MAT-file elements
MAT-File format Figure 1: MATLAB Version 5 MAT-File Format tea Descriptive text(124 bytes) Version Endian Indicator Data Type Number of Bytes Data(variable size) or subelements Data t Number of Bytes Data(variable size) or subelements m鸟口m93品 umber of Bytes Data(variable size) or subelements Repeat Tagged Data Elements Until End-of-File
MAT-File Format 4 Figure 1: MATLAB Version 5 MAT-File Format Bytes 1 2 3 4 5 6 7 8 MAT-File Header (128 bytes) Descriptive text (124 bytes) Version Endian Indicator Data Type Number of Bytes Data (variable size) or subelements Data Type Number of Bytes Data Element Data Element Repeat Tagged Data Elements Until End-of-File Data Type Number of Bytes Data Element Data (variable size) or subelements Data (variable size) or subelements
Version 5 mat-file format MAT-File Header Format byte text field and two, 16-bit flag fields a 128-byte header made up of a 124 MATLAB Version 5 MAT-files begin with Header Text Field The first 124 bytes of the header can contain text data in human-readable form. This text typically provides information that describes how the mat-file was created. For example, MAT-files created by MATLAB include the following information in their headers MATLAB version Platform on which the file was created Date and time the file was created You can view the text in a MAT-file header using the cat command on UNIX systems, or the type command on a PC. The output displays the text in this part of the header. (The display of the header is followed by unreadable characters representing the binary data in the fil MATLAB 5.0 MAT-file. Pl at form: SoL2. Created on: Thu Nov 13 10:10:271997 Programming Note When creating a MAT-file, you must write data in the first four bytes of this header. MATLAB uses these bytes to determine if MAT-file uses a Version 5 format or a Version 4 format. If any of these bytes contain a zero, MAtlaB will incorrectly assume the file is a version 4 MAT-file
Version 5 MAT-File Format 5 MAT-File Header Format MATLAB Version 5 MAT-files begin with a 128-byte header made up of a 124 byte text field and two, 16-bit flag fields. Header Text Field The first 124 bytes of the header can contain text data in human-readable form. This text typically provides information that describes how the MAT-file was created. For example, MAT-files created by MATLAB include the following information in their headers: • MATLAB version • Platform on which the file was created • Date and time the file was created You can view the text in a MAT-file header using the cat command on UNIX systems, or the type command on a PC. The output displays the text in this part of the header. (The display of the header is followed by unreadable characters representing the binary data in the file.) cat my_matfile.mat MATLAB 5.0 MAT-file, Platform: SOL2, Created on: Thu Nov 13 10:10:27 1997 Programming Note When creating a MAT-file, you must write data in the first four bytes of this header. MATLAB uses these bytes to determine if a MAT-file uses a Version 5 format or a Version 4 format. If any of these bytes contain a zero, MATLAB will incorrectly assume the file is a Version 4 MAT-file
MAT-File format Header flag fields The last four bytes in the header are divided into two, 16-bit flag fields(int 16) Field Version Identifies the version of the matlab software used to create the MAT-file format. When creating a MAT-file, set this field to oxo100 Endian Contains the two characters. M and I written to the Indicator MAT-file in this order, as a 16-bit value. If, when read from the MAT-file as a 16-bit value, the characters appear in reversed order(IMrather than M). it indicates that the program reading the MAT-file must perform byte-swapping to interpret the data in the MAT-file correctly Programming Note Programs that create MAT-files always write data in their native machine format. Programs that read MAT-files are responsible for byte-swapping Data element format Each data element begins with an 8-byte tag followed immediately by the data in the element. Figure 2 shows this format. (MATLAB also supports a compressed data element format. See page-9 for more information. Figure 2: MAT-File Data Element Format By rtes Data Type Number of Bytes Ta Variable size Data
MAT-File Format 6 Header Flag Fields The last four bytes in the header are divided into two, 16-bit flag fields (int16). Programming Note Programs that create MAT-files always write data in their native machine format. Programs that read MAT-files are responsible for byte-swapping. Data Element Format Each data element begins with an 8-byte tag followed immediately by the data in the element. Figure 2 shows this format. (MATLAB also supports a compressed data element format. See page -9 for more information.) Figure 2: MAT-File Data Element Format Field Value Version Identifies the version of the MATLAB software used to create the MAT-file format. When creating a MAT-file, set this field to 0x0100. Endian Indicator Contains the two characters, M and I, written to the MAT-file in this order, as a 16-bit value. If, when read from the MAT-file as a 16-bit value, the characters appear in reversed order (IM rather than MI), it indicates that the program reading the MAT-file must perform byte-swapping to interpret the data in the MAT-file correctly. Data Type Number of Bytes Variable size Bytes 1 2 3 4 5 6 7 8 Tag Data
Version 5 mat-file format The 8-byte data element tag is composed of two, 32-bit fields Data Typ Number of Byte Data Type. The Data Type field specifies how the data in the element should be interpreted, that is, its size and format. The MAT-file format supports many data types including signed and unsigned, 8-bit, 16-bit, 32-bit, and 64-bit data types and a special data type that represents MATLAB arrays. Table 1 lists al these data types with the values used to specify them. The table also includes symbols that are used to represent these data types in the examples in this document Table 1: MAT-File Data Types AAT-File Data Type Value Symbol 8 bi t, si gned miNts 16-bit, si gned 1234 mi UI NT8 miINT16 16-bit, unsi gned mi UINT16 32-bit, si gned 32-bit, unsi gned mi NT32 I EEE 754 single format 7 I EEE 754 double format 9 mi dOuble Reserved 10 Reserved 64-bi t, si gned 12 mi INT64
Version 5 MAT-File Format 7 Tag The 8-byte data element tag is composed of two, 32-bit fields: • Data Type • Number of Bytes Data Type. The Data Type field specifies how the data in the element should be interpreted, that is, its size and format. The MAT-file format supports many data types including signed and unsigned, 8-bit, 16-bit, 32-bit, and 64-bit data types and a special data type that represents MATLAB arrays. Table 1 lists all these data types with the values used to specify them. The table also includes symbols that are used to represent these data types in the examples in this document. Table 1: MAT-File Data Types MAT-File Data Type Value Symbol 8 bit, signed 1 miINT8 8 bit, unsigned 2 miUINT8 16-bit, signed 3 miINT16 16-bit, unsigned 4 miUINT16 32-bit, signed 5 miINT32 32-bit, unsigned 6 miUINT32 IEEE 754 single format 7 miSINGLE Reserved 8 -- IEEE 754 double format 9 miDOUBLE Reserved 10 -- Reserved 11 -- 64-bit, signed 12 miINT64
MAT-File format Table 1: MAT-File Data Types MAT-File Data Type Value Symbol 64-bit, uni gned mi uInt64 14 mi matRIX (For more information about this data MATLAB Array Data Element Formats" on page.) Number of Bytes. The Number of Bytes field is a 32-bit value that specifies the number of bytes of data in the element. This value does not include the eight bytes of the data element's tag The data immediately follows the tag. The data must be aligned on 64-bit boundaries. When writing a MAT-file, if the amount of data in a data element falls short of a 64-bit boundary, you must add bytes of padding to make sure the tag of the next data element falls on a 64-bit boundary. Likewise, wher reading data from a MAT-file, be sure to account for these padding bytes Programming Note For data elements representing MATLAB arrays, (type mi MATRIX), the value of the Number of Bytes field includes padding bytes in the total. For all other MAT-file data types, the value of the Number of Bytes field does not include padding bytes Example Data Element For example, Figure 3 illustrates a data element representing an array of six 32-bit, unsigned integers: 1, 2, 3, 4, 5, 6. In the figure, the Data Type field contains the value from Table 1 that specifies unsigned, 32-bit integers (mi UI NT32). The Number of Bytes field in the data element tag contains the number of data values multiplied by the number of bytes used to represent
MAT-File Format 8 Number of Bytes. The Number of Bytes field is a 32-bit value that specifies the number of bytes of data in the element. This value does not include the eight bytes of the data element’s tag. Data The data immediately follows the tag. The data must be aligned on 64-bit boundaries. When writing a MAT-file, if the amount of data in a data element falls short of a 64-bit boundary, you must add bytes of padding to make sure the tag of the next data element falls on a 64-bit boundary. Likewise, when reading data from a MAT-file, be sure to account for these padding bytes. Programming Note For data elements representing MATLAB arrays, (type miMATRIX), the value of the Number of Bytes field includes padding bytes in the total. For all other MAT-file data types, the value of the Number of Bytes field does not include padding bytes. Example Data Element For example, Figure 3 illustrates a data element representing an array of six 32-bit, unsigned integers: 1, 2, 3, 4, 5, 6. In the figure, the Data Type field contains the value from Table 1 that specifies unsigned, 32-bit integers (miUINT32). The Number of Bytes field in the data element tag contains the number of data values multiplied by the number of bytes used to represent 64-bit, unsigned 13 miUINT64 MATLAB array 14 miMATRIX (For more information about this data type, see “Version 5 MATLAB Array Data Element Formats” on page -10.) Table 1: MAT-File Data Types MAT-File Data Type Value Symbol
Version 5 mat-file format each value. Note that this value does not include the eight bytes in the data element tag Figure 3: Example MAT-File Data Element Byte (mi UINT32 Dat a 6 Compressed Data Element Format If the data element contains between one and four bytes of data, MATLAB saves storage space by storing the data in a compressed data element format. In this format, the Data Type and Number of Bytes fields are stored as 16-bit values, freeing four bytes in the tag in which to store the data. Figure 4 illustrates this format Figure 4: Compressed Data Element Format Byte Data Type DATA Programming Note When reading a MAT-file, you can tell if you are processing a compressed data element by comparing the value of the first two bytes of the tag with the value zero(O). If these two bytes are not zero, the tag uses the compressed format. When writing a MAT-file, use of the compressed data element format is optional
Version 5 MAT-File Format 9 each value. Note that this value does not include the eight bytes in the data element tag. Figure 3: Example MAT-File Data Element Compressed Data Element Format If the data element contains between one and four bytes of data, MATLAB saves storage space by storing the data in a compressed data element format. In this format, the Data Type and Number of Bytes fields are stored as 16-bit values, freeing four bytes in the tag in which to store the data. Figure 4 illustrates this format. Figure 4: Compressed Data Element Format Programming Note When reading a MAT-file, you can tell if you are processing a compressed data element by comparing the value of the first two bytes of the tag with the value zero (0). If these two bytes are not zero, the tag uses the compressed format. When writing a MAT-file, use of the compressed data element format is optional. miUINT32 24 Bytes 1 2 3 4 5 6 7 8 Tag Data Data Type Number of Bytes 1 2 3 4 5 6 Data Type D A T A Bytes 1 2 7 3 4 5 6 8 Number of Bytes