新手指南：5分钟安装npy-matlab，让MATLAB直接读写NumPy .npy文件

新手指南：5分钟安装npy-matlab，让MATLAB直接读写NumPy .npy文件

【免费下载链接】npy-matlabExperimental code to read/write NumPy .NPY files in MATLAB项目地址: https://gitcode.com/gh_mirrors/np/npy-matlab

📌npy-matlab是一个开源的 MATLAB 工具包，让你无需任何 Python 环境，就能在 MATLAB 中直接读取和写入 NumPy 的 .npy 格式文件。对于需要在 MATLAB 与 Python 之间频繁交换数据的新手来说，它是最省事的桥梁方案。

一、为什么需要 npy-matlab？

很多新手都会遇到同一个问题：Python 端（PyTorch、Pandas、OpenCV 等）习惯用.npy格式保存数组，而 MATLAB 原生只能读.mat文件。传统做法是装一个 Python 环境来回转换，繁琐又占资源。

npy-matlab 的思路很简单：直接用 MATLAB 原生函数解析 NPY 文件头和数据块，实现零依赖互操作。✅

它由以下几部分组成：

二、最快安装方法：两步搞定 🚀

npy-matlab 没有任何第三方依赖，安装 = 克隆仓库 + 添加搜索路径，5 分钟内可以完成。

第 1 步：克隆项目

在终端执行（仓库地址）：

git clone https://gitcode.com/gh_mirrors/np/npy-matlab

第 2 步：加入 MATLAB 搜索路径

启动 MATLAB，把仓库内的npy-matlab/目录加入路径并保存：

addpath('你的路径/npy-matlab/npy-matlab'); savepath

💡 提示：addpath只添加内层的npy-matlab/子目录即可（那里存放全部 .m 脚本）；savepath让设置永久生效，重启 MATLAB 无需重复操作。

三、核心用法：readNPY 与 writeNPY 怎么用？

安装完成后，整个工作流只需要两行函数调用。

写入 .npy 文件

a = rand(5,4,3); % 任意 MATLAB 数组 writeNPY(a, 'a.npy'); % 写出为标准 NPY 文件

读取 .npy 文件

b = readNPY('a.npy'); % 读回数组，与 a 完全一致

readNPY内部会自动解析文件头（调用readNPYheader.m），按数据类型和维度正确还原数组，还支持大端/小端字节序与 C-order/Fortran-order 两种存储顺序的维度转换——这点比很多手写脚本要可靠。

支持的数据类型

⚠️注意事项：当前项目定位为实验性代码，存在以下限制：

• 只能读取上述固定数据类型的 N 维数组（不支持字符串、对象数组等）
• 写出时固定为小端序 + Fortran 列主序、NPY 1.0 版本
• 形状按 MATLAB 约定输出，例如(10, 1)而非(10,)

四、进阶技巧：解析文件头与内存映射 🧠

1. 只解析文件头（不加载数据）

当你只需要知道数组形状和类型时，用readNPYheader.m最轻量：

[shape, dtype, fortranOrder, littleEndian, headerLen, version] = readNPYheader('data.npy');

2. 超大文件：用 memmapfile 零拷贝读取

仓库提供了一个经典案例examples/exampleMemmap.m：对 Python 默认保存（C-order）的大文件，用memmapfile做内存映射、再反转维度即可按需读取，避免一次性载入内存：

f = memmapfile(filename, 'Format', {dataType, shape(end:-1:1), 'd'}, 'Offset', totalHeaderLength);

这对处理图像、体素数据等大体积 .npy 文件非常实用。

3. 已有 .dat 裸数据？直接"套壳"成 .npy

datToNPY.m可以在不读入数据的前提下，为二进制文件拼接一个合法的 NPY 头，快速把.dat转成.npy，适合大文件场景。

五、如何验证安装成功：运行自带测试 🧪

项目自带三层测试，建议安装后跑一遍确认环境正常：

• tests/test_readNPY.m—— MATLAB 端读写测试脚本
• tests/npy.ipynb—— Python 端对照测试（验证读出的数据与 Python 写入一致）
• tests/test_npy_roundtrip.py—— 自动化往返测试（roundtrip）
• tests/data/目录 —— 内置 chelsea 图像与正弦波数据（float32/64、int8~64、uint8~64 全类型覆盖），可直接用作你的测试素材

最简验证方式：

a = rand(5,4,3); writeNPY(a, 'a.npy'); b = readNPY('a.npy'); disp(sum(a(:)==b(:))); % 输出 60 即表示读写完全一致

六、总结：适合谁用？

npy-matlab 用不到 200 行纯 MATLAB 代码，解决了"MATLAB 读不了 .npy"这个高频痛点。现在你就可以按上面两步完成安装，5 分钟后让两个生态的数据自由流通！

【免费下载链接】npy-matlabExperimental code to read/write NumPy .NPY files in MATLAB项目地址: https://gitcode.com/gh_mirrors/np/npy-matlab