Various Methods for Reading Images in MATLAB

Table of Contents:(1) DPABI Package’s y_ReadAll Function(2) DPABI Package’s y_Read Function(3) SPM Package’s spm_vol + spm_read_vols Function

Briefly introduce the difference between NIfTI 3D and 4D files:

1. 3D Files: Contains only one three-dimensional image

Pixels in the x, y, and z directions
Example: Brain structure scan

Each 3D image is referred to as a “volume.”

2. 4D Files: Composed of multiple 3D images stacked together

The fourth dimension is time
Example: Each time point in fMRI is a 3D image

(1) DPABI Package’s y_ReadAll Function

DPABI package download link:https://rfmri.org/DPABIy_ReadAll is a MATLAB function used to read NIfTI images. It can handle a single file, a directory, or a list of multiple files, and outputs the results as a unified 4D matrix.

[Data, VoxelSize, FileList, Header] = y_ReadAll(InputName)

InputName: Supports various input formats:Single file:.nii, .nii.gz, or .img/.hdr files.Directory: The directory can contain either a 4D file or a set of 3D images.

File List (cell array): Each element is a path to a 3D image file or a single 4D file path. The function automatically determines whether the input is a single file, a directory, or a file list.

% Read a single compressed NIfTI filenii_path = 'S1.nii.gz';[Data, VoxelSize, FileList, Header] = y_ReadAll(nii_path);% Read all NIfTI files in a directorydir_path = '/data/sub01';[Data, VoxelSize, FileList, Header] = y_ReadAll(dir_path);% Read multiple file listfile_list = {'S1.nii.gz', 'S2.nii.gz', 'S3.nii.gz'};[Data, VoxelSize, FileList, Header] = y_ReadAll(file_list);

Output Parameters:

Data: 4D image matrix.
VoxelSize: Voxel size (x, y, z).
FileList: List of read files (cell array).
Header: A structure containing image information, with fields including:

fname: File name
dim: Dimensions of the volume in x, y, z
dt: Data type
mat: 4×4 affine matrix
pinfo: Scaling and offset information for each plane

(2) DPABI Package’sy_Read Functiony_Read Function is a more basic NIfTI file reading function than <code>y_ReadAll, mainly used to read a single file or a specified volume of a single 4D file.y_Read reads files through SPM’s NIfTI tools and can handle .nii, .nii.gz, .img/.hdr files.

 [Data, Header] = y_Read(FileName, VolumeIndex)

Input Parameters:

FileName: File path and name, supports the following formats:

.nii
.nii.gz
.img/.hdr

VolumeIndex (optional): Used to select which 3D image (volume) to read:

Can be an integer (1,2,3…) indicating which image to read
or 'all' (default), indicating to read all volumes

Output Parameters:

Data: Image data matrix

If only one volume is read → 3D matrix
If all volumes are read → 4D matrix

Header: Image header information (structure, consistent with SPM), fields include:

fnamee: File name
dim: Volume x, y, z dimensions
dt: Data type and byte order
mat: 4×4 affine matrix
pinfo: Scaling and offset information for each plane

Function Features:

Automatically handles compressed files: If it is a .nii.gz, it will decompress before reading, then delete the decompressed temporary file.
Flexible reading of volumes:

VolumeIndex = 1 → Read the first volume
VolumeIndex = 'all' → Read all volumes

Based on SPM’s nifti and spm_vol, ensuring compatibility and correct information.

Example:

% Read the entire 4D NIfTI file[Data, Header] = y_Read('S1.nii.gz');% Read only the 3rd volume[Data, Header] = y_Read('S1.nii.gz', 3);

(3) SPM Package’sspm_vol + spm_read_vols Function

spm_vol

Function: Reads the Header information of a NIfTI file (dimensions, affine matrix, data type, etc.), without reading image data.
Input: File name (string or cell array)
Output: Structure V, fields include:

fname: File name
dim: Volume dimensions [X Y Z]
mat: Affine matrix (voxel→mm)
dt: Data type
pinfo: Plane scaling and offset information

Example::

V = spm_vol('S1.nii');disp(V.dim);

spm_read_vols

Function: Reads image data based on spm_vol and returns a 3D or 4D matrix, with an option to set 0 values to NaN.
Input:

V: Structure returned by spm_vol
mask (optional):true/false, whether to convert 0 to NaN

Output:

Y: Image data matrix
XYZmm (optional): Spatial coordinates (mm) for each voxel

Example::

Y = spm_read_vols(V);      % Read imageY_masked = spm_read_vols(V,true); % 0 to NaN

Usage Process:

V = spm_vol('file.nii'); → Get Header
Y = spm_read_vols(V); → Read image data

In summary:spm_vol only looks at information, while spm_read_vols actually reads the data.