search

tbeu / matio

MATLAB MAT File I/O Library
https://matio.sourceforge.io
BSD 2-Clause "Simplified" License
330 stars 97 forks source link
c file-format hdf5 mat-files matlab zlib

readme

MATIO

MATLAB MAT file I/O library

Status

pre-commit.ci Status Build Status Build Status Coverity Scan Build Status Coverage Status Build Status FreeBSD Build Status CodeQL Packaging status Fuzzing Status Open Hub Conan Center Vcpkg Version

Table of Contents

  1. Introduction
  2. Building
  3. License

1.0 Introduction

Matio is an open-source C library for reading and writing binary MATLAB MAT files. This library is designed for use by programs/libraries that do not have access or do not want to rely on MATLAB's shared libraries.

1.1 Contact

You can contact the maintainer through email at t-beu@users.sourceforge.net.

1.2 Acknowledgements

The following people/organizations have helped in the development of matio through patches, bug reports, and/or testing:

1.3 Contributing

If you are interested in collaborations, contact the maintainer via email (see section 1.1).

1.4 Questions and Reporting Bugs

Questions can be asked using the forums on the sourceforge site hosting matio.

Bugs, enhancements, etc. should be submitted using one of the trackers on the sourceforge page.

2.0 Building

This section describes how to build matio. Section 2.1 describes the dependencies, section 2.2 how to build/test matio, and section 2.3 documents the platforms matio has been tested on.

2.1 Dependencies

Matio has two optional dependencies. These are not required for the software to work, but without them some files may be unreadable. Zlib is required to read/write level 5 MAT files that use compression. HDF5 is required to work with newer MAT files that use the HDF5-format files.

2.1.1 zlib

To support compressed MAT files, zlib version ≥ 1.2.3 is required. The zlib software can be downloaded from http://zlib.net/.

2.1.2 HDF5

Support for MAT file version 7.3 requires the HDF5 library. This library can be downloaded from https://www.hdfgroup.org/. Matio requires HDF5 version ≥ 1.8.x. Neither deprecated HDF5 1.6.x API functions nor HDF5 higher-level functions are called.

For Windows, the pre-compiled binaries can be used which also include a DLL of zlib to satisfy the zlib dependency. For Ubuntu, sudo apt install libhdf5-dev should work fine.

2.2 Building matio

2.2.1 Quick Build Guide

The primary method for building the software is with GNU autotools using configure followed by make. After building, the testsuite can be executed to test the software using make check. The software can be installed using make install. For example,

git clone git://git.code.sf.net/p/matio/matio
cd matio
git submodule update --init  # for datasets used in unit tests
./autogen.sh
./configure
make
make check
make install

If any of the tests in the testsuite fail, you should report the failure using the tracker (see section 1.4). You should attach the generated testsuite.log file to the bug report.

2.2.2 Configure Options

The configure script used to build the software takes a number of options. This section describes the key options.

2.2.3 CMake build system

The CMake build system is supported as an alternative build system, which usually consists of three steps for configuration, build and installation, for example,

git clone git://git.code.sf.net/p/matio/matio
cd matio
cmake .
cmake --build .
cmake --install .

The following matio specific options for building with CMake are available.

To help CMake find the HDF5 libraries, set environment variable HDF5_DIR to the cmake/hdf5 directory (containing hdf5-config.cmake) inside the HDF5 build or installation directory, or call cmake with -DHDF5_DIR="dir/to/hdf5/cmake/hdf5". Alternatively call CMake with -DCMAKE_PREFIX_PATH="dir/to/hdf5/cmake". See the HDF5 instructions for more information. Using hdf5-config is recommended over using CMake's built-in FindHDF5, especially for static builds. CMake 3.10 or later is recommended.

2.2.4 Visual Studio

Visual Studio solutions are provided as matio_vs2008.sln for VS2008 and as matio.sln for VS2010 (and newer). The Debug and Release configurations of both solutions are set up to build a DLL of the matio library (libmatio.dll) and the matdump tool and assume HDF5 is available in the directory specified by the HDF5_DIR environment variable. It is assumed that the shared libraries of HDF5 (and zlib) are available. If the static libraries of HDF5 (and zlib) are installed/built the macro H5_BUILT_AS_STATIC_LIB needs to be defined (instead of H5_BUILT_AS_DYNAMIC_LIB). Furthermore, the Release Lib configuration of the VS2010 solution is set up to build a static LIB of the matio library (libmatio.lib) and assumes that the static libraries of HDF5 (and zlib) are installed/built.

2.2.5 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 was 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).

2.3 Platforms

The library has been tested/used on Linux, Windows, and OS X including both little-endian and big-endian architecture.

3.0 License

This software is provided under a Simplified BSD license. See the COPYING file for details on the license.

MATLAB is a registered trademark of The MathWorks, Inc.