Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/openmeeg/matio-openmeeg

clone of matio lib used in OpenMEEG
https://github.com/openmeeg/matio-openmeeg

Last synced: about 1 month ago
JSON representation

clone of matio lib used in OpenMEEG

Awesome Lists containing this project

README 

        
MATIO - MATLAB MAT file I/O library



Table of Contents

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

1.0 Introduction

  1.1 Contact

  1.2 Acknowledgements

  1.3 Contributing

  1.4 Questions and Reporting Bugs

2.0 Dependencies

  2.1 zlib

  2.1 HDF-5

3.0 Platforms

4.0 Building with autoconf

  4.1 Quick Build Guide

  4.2 Configure Options

  4.3 Testsuite

5.0 Visual Studio

6.0 Building with cmake

  6.1 Quick Build Guide

  6.2 Configure Options

7.0 License



1.0 Introduction

    matio is an open-source library for reading/writing 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 library.

    Section 2 documents the dependencies and section 3 the platforms on which

    matio has been tested.

    Build can be made using either autoconf (recommended) or cmake (experimental),

    see sections 4 and 5 respectively.



    1.1 Contact

        You can contact me (Christopher Hulbert) through email at

        [email protected].



    1.2 Acknowledgements

        The following people/organizations have helped in the development of

        matio through patches, bug reports, and/or testing:

          * Jacco van Beek

          * SGI in support of Interactive Supercomputing, Inc.

          * Scilab (http://www.scilab.org/)

          * Steven Leibman 

          * OpenMEEG (http://www-sop.inria.fr/athena/software/OpenMEEG/)



    1.3 Contributing

        Part of my reason for releasing this software is I have many other

        projects to work on and have many features I would still like to

        implement. If you make changes, I would appreciate your contributions

        and more than likely will include them in future releases. If you are

        interested in collaborations, contact me via email (see Section 1.1).



    1.4 Questions and Reporting Bugs

        Questions can be askes using the forums on the sourceforge site hosting

        matio (http://sourceforge.net/projects/matio/forums).



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

        on the sourceforge page

        (http://sourceforge.net/tracker/?group_id=176643).



2.0 Matio 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 1.2.3 or greater 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 The HDF Group website

          (http://www.hdfgroup.org/). MATIO requires HDF5 version 1.8.x,

          and must be built with default API version 1.8 (i.e.

          '--with-default-api-version=v18').



        For windows, the pre-compiled binaries can be used which also

        include a DLL of zlib to satisfy the zlib dependency.



3.0 Platforms

    The library has been tested/used on Linux, Windows, OS X, and AIX

    including both little-endian and big-endian architecture.



4.0 Building with autoconf



    This is currently the recommended way to build matio as it is the one that

    got tested the most.



    This section describes how to build matio with autoconf. Section 4.1

    describes how to build/test matio, and Section 4.2 the options that

    can be used to modify the build.



    4.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'. 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



        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.



    4.2 Configure Options

        The configure script used to build the software takes a number of

        options. This section describes the key options.



            * --enable-mat73=yes

                This flag en/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. MATLAB 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. Without

                this, the test will only check that matio can read the file

                written and if successful the test will be skipped. If matio

                can not read the file, the test will fail.

            * --with-zlib=DIR

                This option specifies the prefix where zlib is installed

                (see Section 2.1.1 for information about zlib).

            * --with-hdf5=DIR

                This option specifies the prefix where the HDF5 software is

                installed (see Section 2.1.2 for information about HDF5).

            * --with-default-file-ver=version

                This option sets the default MAT file version (4,5,7.3) 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.



    4.3 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).



5.0 Building with 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 assumes 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.



6.0 Building with cmake



    This section describes how to build matio using the cmake build system.

    This is rather new and should be considered experimental, but has the 

    nice property that the same instructions can be used on all supported

    platforms. Section 5.1 describes how to build/test matio, and Section 5.2

    the options that can be used to modify the build. This build type can be

    used on all platforms.



    6.1 Quick Build Guide

        The primary method for building the software is using 'ccmake'

        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,

            $ tar zxf matio-X.Y.Z.tar.gz

            $ mkdir matio-X.Y.Z-build

            $ cmake ../matio-X.Y.Z

            $ make

            $ make test

            $ 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.



    6.2 Configure Options

        cmake also allows you to change the way matio is built ny tweaking several

        options. Those options can be passed to the cmake command line with the

        syntax -D OPTION=VALUE, or you can use a graphic interface.



        To use the graphic interface, use the same instructions as in 5.1 but

        replacing the line "cmake ../matio-X.Y.Z" by "ccmake ../matio-X.Y.Z".

        This will give you a graphic interface where you can change several

        options. See the cmake manual for the interface documentation.

        The remaining of this section details the main options that can be

        tweaked.



7.0 License

    This software is provided under a Simplified BSD license. See the COPYING

    file for details on the license.