MATLAB® The Language of Technical Computing MAT-File Format Version 7 How to Contact The MathWorks: www.mathworks.com Web comp.soft-sys.matlab Newsgroup [email protected] Technical support [email protected] Product enhancement suggestions [email protected] Bug reports [email protected] Documentation error reports [email protected] Order status, license renewals, passcodes [email protected] Sales, pricing, and general information 508-647-7000 Phone 508-647-7001 Fax The MathWorks, Inc. Mail 3 Apple Hill Drive Natick, MA 01760-2098 For contact information about worldwide offices, see the MathWorks Web site. MAT-File Format  COPYRIGHT 1984 - 2004 by The MathWorks, Inc. The software described in this document is furnished under a license agreement. The software may be used or copied only under the terms of the license agreement. No part of this manual may be photocopied or repro- duced in any form without prior written consent from The MathWorks, Inc. FEDERAL ACQUISITION: This provision applies to all acquisitions of the Program and Documentation by, for, or through the federal government of the United States. By accepting delivery of the Program or Documentation, the government hereby agrees that this software or documentation qualifies as commercial computer software or commercial computer software documentation as such terms are used or defined in FAR 12.212, DFARS Part 227.72, and DFARS 252.227-7014. Accordingly, the terms and conditions of this Agreement and only those rights specified in this Agreement, shall pertain to and govern the use, modification, reproduction, release, performance, display, and disclosure of the Program and Documentation by the federal government (or other entity acquiring for or through the federal government) and shall supersede any conflicting contractual terms or conditions. If this License fails to meet the government's needs or is inconsistent in any respect with federal procurement law, the government agrees to return the Program and Documentation, unused, to The MathWorks, Inc. MATLAB, Simulink, Stateflow, Handle Graphics, and Real-Time Workshop are registered trademarks, and TargetBox is a trademark of The MathWorks, Inc. Other product or brand names are trademarks or registered trademarks of their respective holders. Printing History: June 1999 Online only New for MATLAB 5.3 (Release 11) November 2000 PDF only MATLAB 6.0 (Release 12) June 2001 PDF only MATLAB 6.1 (Release 12.1) July 2002 PDF only MATLAB 6.5 (Release 13) January 2003 PDF only MATLAB 6.5.1 (Release 13 SP1) June 2004 PDF only MATLAB 7.0 (Release 14) 1 MAT-File Format Introduction (p.1-2) Describes Level 5 and Level 4 MAT-files and how to access them. Level 5 MAT-File Format (p.1-4) Describes the internal format of MAT-files that are compatible with MATLAB® versions 5 and up. Level 5 MATLAB Array Data Shows how to use the Array data type to represent all types of Element Formats (p.1-14) MATLAB arrays. Level 4 MAT-File Format (p.1-36) Describes the internal format of MAT-files that are compatible with MATLAB versions 4 and earlier. 1 MAT-File Format Introduction This document describes the internal format of MATLAB ®Level 4 and Level 5 MAT-files. Level 4 MAT-files are compatible with versions of MATLAB up to Version 4. Level 5 MAT-files are compatible with MATLAB Versions 5 and up. You can read and write Level 4 MAT-files with the later versions of MATLAB, but when writing a MAT-file under these circumstances, you need to specify a switch in the save or matOpen command line to tell MATLAB that the MAT-file is at Level 4. A MAT-file stores data in binary (not human-readable) form. In MATLAB, you create MAT-files using the save function, 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 function 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 MAT-file interface. This interface shields users from dependence on the details of the MAT-file format. Note See “Importing and Exporting Data” in the MATLAB External Interfaces documentation for information on the MAT-file interface. See “C [or Fortran] MAT-File Functions” in the MATLAB External Interfaces Reference documentation for information on the functions available with this interface. However, if you need to read or write MAT-files on a system that does not support the MAT-file interface, you must write your own read and write routines. The MAT-file interface 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. 1-2 Introduction Note Whenever possible, The MathWorks strongly advises you to use the MAT-file interface functions to read and write MAT-files. Any code you write that depends on the MAT-file format may need to be rewritten when the format changes in future releases. MAT-File Formats This document describes both Level 5 and Level 4 MAT-file formats. The Level 5 MAT-file format supports all the array types supported in MATLAB versions 5 and up, including multidimensional numeric arrays, character arrays, sparse arrays, cell arrays, structures, and objects. “Level 5 MAT-File Format” on page1-4 describes this format. The Level 4 MAT-file format is a simpler format but it only supports two-dimensional matrices and character strings. “Level 4 MAT-File Format” on page1-36 describes this format. 1-3 1 MAT-File Format Level 5 MAT-File Format Level 5 MAT-files are 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 Level 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 Level 5 MAT-File Format” on page1-5 graphically illustrates this MAT-file format. The sections that follow provide more details about these MAT-file elements. This section covers the following topics: •“MATLAB Level 5 MAT-File Format” on page1-5 (cid:127)“MAT-File Header Format” on page1-6 (cid:127)“Data Element Format” on page1-8 (cid:127)“Data Compression” on page1-11 1-4 Level 5 MAT-File Format Figure 1-1: MATLAB Level 5 MAT-File Format Bytes 1 2 3 4 5 6 7 8 M A Descriptive text (116 bytes) T -F ile H e a d e r (1 2 8 b y te s ) Subsys Data Offset Subsys Data Offset Version Endian Indicator Data Type Number of Bytes D a ta E Data (variable size) or subelements le m e n t Data Type Number of Bytes D a ta E Data (variable size) or subelements le m e n t Data Type Number of Bytes D a ta E Data (variable size) or subelements le m e n t Repeat Tagged Data Elements Until End-of-File 1-5 1 MAT-File Format MAT-File Header Format Level 5 MAT-files begin with a 128-byte header made up of a 124 byte text field and two, 16-bit flag fields. This section covers the following topics: (cid:127)“Header Text Field” on page1-6 (cid:127)“Header Subsystem Data Offset Field” on page1-7 (cid:127)“Header Flag Fields” on page1-7 Header Text Field The first 116 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: (cid:127)Level of the MAT-file (value equals 1 for Level 5) (cid:127)Platform on which the file was created (cid:127)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 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 Level 5 format or a Level 4 format. If any of these bytes contain a zero, MATLAB will incorrectly assume the file is a Level 4 MAT-file. 1-6 Level 5 MAT-File Format Header Subsystem Data Offset Field Bytes 117 through 124 of the header contain an offset to subsystem-specific data in the MAT-file. All zeros or all spaces in this field indicate that there is no subsystem-specific data stored in the file. Header Flag Fields The last four bytes in the header are divided into two, 16-bit flag fields (int16). Field Value Version When creating a MAT-file, set this field to 0x0100. 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 (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. Note Programs that create MAT-files always write data in their native machine format. Programs that read MAT-files are responsible for byte-swapping. 1-7 1 MAT-File Format Data Element Format Each data element begins with an 8-byte tag followed immediately by the data in the element. Figure1-2 shows this format. (MATLAB also supports a compressed data element format. See page 1-10 for more information.) Figure 1-2: MAT-File Data Element Format Bytes 1 2 3 4 5 6 7 8 Data Type Number of Bytes Tag Variable size Data This section covers the following topics: (cid:127)“The Tag Field” on page1-8 (cid:127)“The Data Field” on page1-10 (cid:127)“Small Data Element Format” on page1-10 (cid:127)“Example Data Element” on page1-11 The Tag Field The 8-byte data element tag is composed of two, 32-bit fields: (cid:127)Data Type (cid:127)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, a special data type that represents MATLAB arrays, Unicode encoded character data, and data stored in compressed format. Table1-1 lists all these data types with the values used to specify them. The table also includes 1-8