niftiwrite

Write volume to file using NIfTI format

Syntax

niftiwrite(V,filename)

niftiwrite(V,filename,info)

niftiwrite(V,filename,info,Name=Value)

Description

niftiwrite(V,filename) writes the volumetric image data V to a file by using the Neuroimaging Informatics Technology Initiative (NIfTI) format. By default, niftiwrite creates a combined NIfTI file that contains both metadata and volumetric data, using the NIfTI1 format. niftiwrite names the file filename, adding the .nii file extension. niftiwrite populates the metadata using appropriate default values and volume properties, such as size and data type.

niftiwrite(V,filename,info) also includes the file metadata from info. If the metadata does not match the image contents and size, then niftiwrite returns an error.

niftiwrite(V,filename,info,Name=Value) specifies additional options using one or more name-value arguments. For example, specify Version="NIfTI2" to write the data to a file in the NIfTI2 file format.

Examples

Write Median-Filtered Volume to NIfTI File

Read an image volume from a NIfTI file.

V = niftiread("brain.nii");

Filter the image in 3-D by using a 3-by-3 median filter.

V = medfilt3(V);

Write the filtered image to a NIfTI file, using default header values.

niftiwrite(V,"outbrain.nii");

Write Data to NIfTI File and Modify Header Structure

Read the metadata from a NIfTI file by using its .nii file name.

info = niftiinfo('brain.nii');

Read volumetric data from the file by using the file metadata.

V = niftiread(info);

Edit the Description metadata field of the file.

info.Description = 'Modified using MATLAB R2017b';

Write the volumetric data with the modified metadata to a new .nii file.

niftiwrite(V,'outbrain.nii',info);

Write Compressed NIfTI File

This example shows two approaches for writing volume data to compressed NIfTI files.

Read a volume from a NIfTI file.

V = niftiread("brain.nii");

Write the volume to a compressed NIfTI file by specifying a filename that includes the extension .nii.gz.

niftiwrite(V,"outbrain.nii.gz")

Alternatively, you can write a compressed file by specifying the Compressed name-value argument as true.

niftiwrite(V,"outbrain","Compressed",true)

Input Arguments

filename — Name of NIfTI file

character vector | string scalar

Name of the NIfTI file, specified as a string scalar or character vector. By default, niftiwrite creates a combined file that contains both metadata and image data with extension .nii.

• If you specify a filename with extension .nii.gz, or if you specify the Compressed name-value argument as true, then niftiwrite writes a compressed file with extension .nii.gz.

• If you specify the Combined name-value argument as false, then niftiwrite creates two files with the same name and different file extensions. One file contains the metadata associated with the volume and has the file extension .hdr. The other file contains image data and has the file extension .img.

Data Types: char | string

V — Volumetric data

numeric array

Volumetric data, specified as a numeric array.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical

info — File metadata

structure

File metadata, specified as a structure returned by the niftiinfo function.

Data Types: struct

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: niftiwrite(V,filename,Version="NIfTI2") writes the data to a file in the NIfTI2 file format.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: niftiwrite(V,filename,"Version","NIfTI2")

Combined — Type of NIfTI file to create

true (default) | false

Type of NIfTI file to create, specified as true or false. If the value is true, then niftiwrite creates a single file with the file extension .nii. If false, then niftiwrite creates two files with the same name but different file extensions: .hdr for the file containing metadata, and .img for the file containing the volumetric image data.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical

Compressed — Compress image data

false (default) | true

Compress image data, specified as true or false. If Compressed is true, then niftiwrite generates a compressed file, using gzip, with the file extension .nii.gz.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical

Endian — Endianness of the data

"little" (default) | "big"

Endianness of the data, specified as one of these values.

• "little" specifies little-endian format.

• "big" specifies big-endian format.

Data Types: char | string

Version — NIfTI data format

"NIfTI1" | "NIfTI2"

NIfTI data format, specified as one of these values.

• "NIfTI1" to write the file using the NIfTI1 format.

• "NIfTI2" to write the file using the NIfTI2 format.

• If Version is not specified, then the default value is determined by the maximum dimension of the input volumetric data.

  • If the maximum dimension of the input is less than or equal to 32767, then the default value is NIfTI1.

  • If the maximum dimension of the input is greater than 32767, then the default value is NIfTI2.

Data Types: char | string

References

[1] Cox, R. W., J. Ashburner, H. Breman, K. Fissell, C. Haselgrove, C. J. Holmes, J. L. Lancaster, D. E. Rex, S. M. Smith, J. B. Woodward, and S. C. Strother. "A (sort of) new image data format standard: NiFTI-1." 10th Annual Meeting of Organisation of Human Brain Mapping, Budapest, Hungary, June 2004.

Version History

Introduced in R2017b

R2024a: Write compressed file by specifying extension .nii.gz

You can write a compressed NIfTI file by specifying a filename with the extension .nii.gz, without needing to specify the Compressed name-value argument. For example, this code writes the volume data in V to a compressed file:

niftiwrite(V,"volume.nii.gz")

Before R2024a, you must specify the Compressed name-value argument as true to write a compressed file, even if the filename includes the extension .nii.gz.