read_vol: Load a single 3D image volume from a file

In neuroim2: Data Structures for Brain Imaging Data

Load a single 3D image volume from a file

Description

Reads exactly one 3D volume from a neuroimaging file and returns it as a DenseNeuroVol. Accepts both 3D files (where only index = 1 is valid) and 4D files (where index selects a single sub-volume along the 4th dimension).

Usage

read_vol(file_name, index = 1)

Arguments

file_name	Path to a single image file (NIfTI .nii or .nii.gz). A character vector of length > 1 is not supported — use read_vec if you need to read multiple files, or call read_vol in a loop.
index	Integer giving the index of the sub-volume to load. Must be 1 for a 3D file. For a 4D file, must satisfy 1 <= index <= dim(file)[4].

Value

A DenseNeuroVol (always 3D, always dense). The associated NeuroSpace has three spatial dimensions even when the source file is 4D.

See Also

read_vec for loading 4D data as a NeuroVec, read_image for automatic dimensionality-based dispatch, and read_hyper_vec for 5D data.

Examples

# Read the first volume from a 4D file
fname <- system.file("extdata", "global_mask_v4.nii", package="neuroim2")
x <- read_vol(fname)
print(dim(x))    # 3D
space(x)

# Read the 3rd sub-volume from the same 4D file
x3 <- read_vol(fname, index = 3)

neuroim2 documentation built on April 16, 2026, 5:07 p.m.