{"id":15573040,"url":"https://github.com/ami-iit/matio-cpp","last_synced_at":"2025-07-21T05:05:56.399Z","repository":{"id":39995777,"uuid":"281162455","full_name":"ami-iit/matio-cpp","owner":"ami-iit","description":"A C++ wrapper of the matio library, with memory ownership handling, to read and write .mat files.","archived":false,"fork":false,"pushed_at":"2025-02-27T15:51:24.000Z","size":6698,"stargazers_count":66,"open_issues_count":5,"forks_count":10,"subscribers_count":15,"default_branch":"master","last_synced_at":"2025-05-20T09:05:36.590Z","etag":null,"topics":["cmake","cpp","cpp14","cxx","cxx14","eigen","hdf5","mat","mat-files","matio","matio-cpp","matlab","matlab-mat","matlab-matrix","ndimensional-arrays","octave"],"latest_commit_sha":null,"homepage":"https://ami-iit.github.io/matio-cpp/","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ami-iit.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-07-20T15:59:12.000Z","updated_at":"2025-05-14T22:26:27.000Z","dependencies_parsed_at":"2023-02-12T03:30:38.487Z","dependency_job_id":"fa81b140-e15c-4afd-8b4a-0dbed3f7003c","html_url":"https://github.com/ami-iit/matio-cpp","commit_stats":{"total_commits":233,"total_committers":4,"mean_commits":58.25,"dds":0.0858369098712446,"last_synced_commit":"f30bce77cd214f0fa8a2c8fc75799957d85eaa9f"},"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/ami-iit/matio-cpp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ami-iit%2Fmatio-cpp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ami-iit%2Fmatio-cpp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ami-iit%2Fmatio-cpp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ami-iit%2Fmatio-cpp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ami-iit","download_url":"https://codeload.github.com/ami-iit/matio-cpp/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ami-iit%2Fmatio-cpp/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266242072,"owners_count":23898102,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cmake","cpp","cpp14","cxx","cxx14","eigen","hdf5","mat","mat-files","matio","matio-cpp","matlab","matlab-mat","matlab-matrix","ndimensional-arrays","octave"],"created_at":"2024-10-02T18:10:15.164Z","updated_at":"2025-07-21T05:05:56.376Z","avatar_url":"https://github.com/ami-iit.png","language":"C++","readme":"# matio-cpp \u003ca href=\"https://isocpp.org\"\u003e\u003cimg src=\"https://img.shields.io/badge/standard-C++14-blue.svg?style=flat\u0026logo=c%2B%2B\" alt=\"C++ Standard\" /\u003e\u003c/a\u003e \n\n**``matio-cpp``** is a C++ wrapper for the [``matio``](https://github.com/tbeu/matio) library, automatically dealing with memory allocation and deallocation.\nIt can be used for reading and writing binary MATLAB `.mat` files from C++, without the need to access or rely on MATLAB's own shared libraries.\n\n# Overview\n\n- [Installation](#installation)\n- [Inclusion](#inclusion)\n- [Supported Data Types](#supported-data-types)\n- [Example of usage](#example-of-usage)\n- [Known limitations](#known-limitations)\n- [Similar projects](#similar-projects)\n\n# Installation\n## Dependencies\n\nThe depencies are [``CMake``](https://cmake.org/) (minimum version 3.10) and [``matio``](https://github.com/tbeu/matio). While we suggest to follow the build instructions provided in the [``matio`` home page](https://github.com/tbeu/matio), it can also installed from common package managers:\n- Linux: ``sudo apt install libmatio-dev``\n- Linux, macOS, Windows, via [``conda-forge``](https://conda-forge.org/): ``conda install -c conda-forge libmatio``\n\n[`Eigen`](https://eigen.tuxfamily.org/index.php) is an optional dependency. If available, some conversions are defined.\n\nFor running the tests, it is necessary to install [`Catch2`](https://github.com/catchorg/Catch2). Where supported, [``valgrind``](https://valgrind.org/) can be installed to check for memory leaks.\n\n## Linux/macOS\n```sh\ngit clone https://github.com/ami-iit/matio-cpp\ncd matio-cpp\nmkdir build \u0026\u0026 cd build\ncmake ../\nmake\n[sudo] make install\n```\nNotice: `sudo` is not necessary if you specify the `CMAKE_INSTALL_PREFIX`. In this case it is necessary to add in the `.bashrc` or `.bash_profile` the following lines:\n```sh\nexport matioCpp_DIR=/path/where/you/installed/\n```\n## Windows\nWith IDE build tool facilities, such as Visual Studio:\n```sh\ngit clone https://github.com/ami-iit/matio-cpp\ncd matio-cpp\nmkdir build \u0026\u0026 cd build\ncmake ..\ncmake --build . --target ALL_BUILD --config Release\ncmake --build . --target INSTALL --config Release\n```\n\nIn order to allow CMake finding ``matio-cpp``, it is necessary that the installation folder is in the ``PATH``.\n\n# Inclusion\n\n  ``matio-cpp`` provides native CMake support which allows the library to be easily used in CMake projects\n\n  In order to use ``matio-cpp`` in your project, add the following in your ``CMakeLists.txt``\n```cmake\nfind_package(matioCpp REQUIRED)\n\n# ...\n\ntarget_link_libraries(yourTarget PRIVATE matioCpp::matioCpp)\n```\n\n# Supported Data Types\n``matio-cpp`` can handle the following data types:\n- ``Element``, like ``double``, ``int``, ...\n-  ``String``\n-  ``Vector``, i.e. 1-dimensional arrays of primitive types\n-  ``MultiDimensionalArray``, i.e. n-dimensional arrays of primitive types\n-  ``CellArray``,  i.e. n-dimensional arrays of generic types\n-  ``Struct``, i.e. a collection of name/variable pairs\n-  ``StructArray``, i.e. n-dimensional arrays of ``Structs``\n\nAll these types can be read/written from/to ``.mat`` files.\n\n# Example of usage\n\nRead a ``.mat`` file\n```c++\n#include \u003cmatioCpp/matioCpp.h\u003e\n\n// ...\n\nmatioCpp::File input(\"input.mat\");\n// You can check if input is open with the isOpen() method\nmatioCpp::CellArray cellArray = input.read(\"cell_array\").asCellArray(); //Read a Cell Array named \"cell_array\"\nmatioCpp::Element\u003cdouble\u003e doubleVar = cellArray({1,2,3}).asElement\u003cdouble\u003e(); //Get the element in the cell array at position (1,2,3) (0-based), casting it as a double Element\ndoubleVar = 3.14; //Set the doubleVar to a new value\nassert(cellArray({1,2,3}).asElement\u003cdouble\u003e()() == 3.14); //Also the original cell array is modified, but not in the file.\n\n```\n\nWrite a ``.mat`` file\n```c++\n#include \u003cmatioCpp/matioCpp.h\u003e\n\n// ...\n\nmatioCpp::File file = matioCpp::File::Create(\"test.mat\"); //If the file already exists, use the same cnstructor as the example above\n\nstd::vector\u003cdouble\u003e in = {2.0,4.0,6.0,8.0};\nmatioCpp::Vector\u003cdouble\u003e out(\"test_vector\");\nout = in;\nfile.write(out);\n\nmatioCpp::String testString(\"string_name\");\ntestString = \"string content\";\nfile.write(testString);\n\n```\n\nIt is possibile to convert common types to ``matioCpp`` types with the function ``matioCpp::make_variable``. Examples:\n```c++\nstd::vector\u003cdouble\u003e stdVec = {1.0, 2.0, 3.0, 4.0, 5.0};\nauto toMatioVec = matioCpp::make_variable(\"test\", stdVec);\n\nstd::array\u003cfloat,3\u003e array = {1.0, 2.0, 3.0};\nauto toMatioArray = matioCpp::make_variable(\"test\", array);\n\nint classicalArray[] = {1, 2, 3};\nauto toMatioClassic = matioCpp::make_variable(\"test\", matioCpp::make_span(classicalArray, 3));\n\nstd::string string(\"something\");\nauto toMatioString = matioCpp::make_variable(\"name\", string);\n\nstd::vector\u003cbool\u003e vecOfBool = {true, false, true};\nauto toVecofBool = matioCpp::make_variable(\"vecOfBool\", vecOfBool);\n\nauto matioDouble = matioCpp::make_variable(\"double\", 5.0);\n\nauto matioBool = matioCpp::make_variable(\"bool\", true);\n\nauto matioInt = matioCpp::make_variable(\"int\", 2);\n\nauto matioChar = matioCpp::make_variable(\"char\", 'f');\n\nstd::vector\u003cstd::string\u003e stringVector = {\"Huey\", \"Dewey\", \"Louie\"};\nauto matioCell = matioCpp::make_variable(\"stringVector\", stringVector);\n```\nIf ``eigen`` is available, it is also possible to convert from and to ``eigen`` types:\n```c++\nmatioCpp::Vector\u003cdouble\u003e vector(\"vector\", 5);                                               \nEigen::VectorXd eigenVec = matioCpp::to_eigen(vector);                                      \nmatioCpp::MultiDimensionalArray\u003cfloat\u003e matioCppMatrix(\"matrix\"); \n\nEigen::MatrixXf toEigenMatrix = matioCpp::to_eigen(matioCppMatrix);\n\nEigen::Matrix3f eigenMatrix;                                                    \neigenMatrix \u003c\u003c 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0;                     \nauto toMatioMatrix = matioCpp::make_variable(\"testMatrix\", eigenMatrix);        \nEigen::Vector3i eigenVec;      \neigenVec \u003c\u003c 2, 4, 6;                                                            \nauto toMatioEigenVec = matioCpp::make_variable(\"testEigen\", eigenVec);          \n```\nIt is also possible to slice a ``MultiDimensionalArray`` into an Eigen matrix:\n```c++\nstd::vector\u003cfloat\u003e tensor(12);\nfor (size_t i = 0; i \u003c 12; ++i)\n{\n    tensor[i] = i + 1.0;\n}\n\nmatioCpp::MultiDimensionalArray\u003cfloat\u003e matioCppMatrix2(\"matrix\", { 2, 2, 3 }, tensor.data());\n\n/*\nSo we have a tensor of the type\n| 1  3 | | 5 7 | |  9 11 |\n| 2  4 | | 6 8 | | 10 12 |\n*/\n\nEigen::MatrixXf slice1 = matioCpp::to_eigen(matioCppMatrix2, { -1, -1, 0 }; //Equivalent to the Matlab operation matioCppMatrix2(:,:,1)\n/* \nObtain\n| 1  3 |\n| 2  4 |\n*/\n\nEigen::MatrixXf slice2 = matioCpp::to_eigen(matioCppMatrix2, { 1, -1, -1 }; //Equivalent to the Matlab operation matioCppMatrix2(2,:,:)\n/*\nObtain\n| 2 6 10|\n| 4 8 12|\n*/\n\nEigen::MatrixXf slice3 = matioCpp::to_eigen(matioCppMatrix2, { -1, 0, 0 }; //Equivalent to the Matlab operation matioCppMatrix2(:,1,1)\n/*\nObtain\n| 1 |\n| 2 |\n*/\n```\nIn the slice, the value `-1` means that the entire dimension is taken.\n\n``matioCpp`` also exploits [``visit_struct``](https://github.com/garbageslam/visit_struct) to parse C++ structs into ``matioCpp`` structs. Example:\n```c++\nstruct testStruct\n{\n    int i{1};\n    double d{2.0};\n    std::string s{\"test\"};\n    std::vector\u003cdouble\u003e stdVec = {1.0, 2.0, 3.0, 4.0, 5.0};\n    int* notSupported = nullptr;\n    std::vector\u003cstd::string\u003e stringVector = {\"Huey\", \"Dewey\", \"Louie\"};\n    std::vector\u003cbool\u003e vecOfBool = {true, false, true};\n};\nVISITABLE_STRUCT(testStruct, i, d, s, stdVec, vecOfBool, stringVector);\n\n//----------\n\ntestStruct s;\nmatioCpp::Struct automaticStruct = matioCpp::make_variable(\"testStruct\", s);\n```\n\n# Example\nYou can check the example in the ``example`` folder on how to include and use ``matioCpp``.\n\n# Known Limitations\n - Complex arrays are not yet supported\n - Cannot read timeseries from a ``.mat`` file (this is a ``matio`` limitation https://github.com/tbeu/matio/issues/99)\n - Cannot read string arrays from a ``.mat`` file (this is a ``matio`` limitation https://github.com/tbeu/matio/issues/98)\n - Cannot read strings in a ``Struct`` from a ``.mat`` file (this is a ``matio`` limitation related to https://github.com/tbeu/matio/issues/98)\n\n# Similar Projects\n- [``eigen-matio``](https://github.com/tesch1/eigen-matio)\n- [``matiopp``](https://github.com/bmc-labs/matiopp)\n- [``matiocpp``](https://github.com/joka90/matiocpp)\n- [``matiocpp``(2)](https://github.com/ldobinson/matiocpp)\n\n## Maintainers\n* Stefano Dafarra ([@S-Dafarra](https://github.com/S-Dafarra))\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fami-iit%2Fmatio-cpp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fami-iit%2Fmatio-cpp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fami-iit%2Fmatio-cpp/lists"}