10.113. Read NIfTI File (Version 1)

Group (Subgroup)

IO (Read)

Description

This Filter reads a NIfTI-1 volume (single-file format, .nii or .nii.gz) into an Image Geometry plus a Cell Data attribute matrix that holds the voxel values.

The filter transparently handles both uncompressed (.nii) and gzipped (.nii.gz) files via zlib, and detects / corrects for file byte order by comparing sizeof_hdr against the expected value of 348.

NIfTI-1 allows a variable-length extension block between the 348-byte header and the voxel data. The filter honors vox_offset (the byte offset in the file where the voxel data begins) and seeks past the extension block before reading voxels — any custom extension metadata (DICOM attributes, AFNI XML, etc.) is skipped, not preserved.

Supported voxel datatypes

NIfTI code	C type	simplnx DataType	Component count
NIFTI_TYPE_UINT8 (2)	uint8	uint8	1
NIFTI_TYPE_INT8 (256)	int8	int8	1
NIFTI_TYPE_UINT16 (512)	uint16	uint16	1
NIFTI_TYPE_INT16 (4)	int16	int16	1
NIFTI_TYPE_UINT32 (768)	uint32	uint32	1
NIFTI_TYPE_INT32 (8)	int32	int32	1
NIFTI_TYPE_UINT64 (1280)	uint64	uint64	1
NIFTI_TYPE_INT64 (1024)	int64	int64	1
NIFTI_TYPE_FLOAT32 (16)	float32	float32	1
NIFTI_TYPE_FLOAT64 (64)	float64	float64	1
NIFTI_TYPE_RGB24 (128)	3 × uint8	uint8	3
NIFTI_TYPE_RGBA32 (2304)	4 × uint8	uint8	4

Complex and 128-bit float types are not currently supported.

Orientation

NIfTI stores up to two affine transforms that map voxel indices to physical space: the sform (“standard” transform, a general affine matrix) and the qform (“quaternion” transform, a rigid rotation plus translation). When Use Stored Affine Transform is enabled (the default), the filter uses the NIfTI sform transform (if sform_code > 0) or qform transform (if qform_code > 0) to set the Image Geometry origin and spacing. If neither is set, the filter falls back to pixdim[1..3] (the per-axis voxel size stored in the header) for spacing and a zero origin.

The spacing units are whatever the source file recorded (most commonly millimeters for medical NIfTI data) and are not converted by this filter. Treat the resulting Image Geometry spacing as being in the file’s native physical units.

simplnx Image Geometries are axis-aligned; if the stored transform contains a non-trivial rotation, only the spacing (column magnitudes) and origin are extracted and a warning is emitted. The voxel data itself is loaded in its native storage order.

Data scaling

NIfTI can store a linear intensity rescaling defined by two header fields: scl_slope (the multiplicative slope) and scl_inter (the additive intercept). When Apply Scaling Transform is enabled and the header specifies a non-trivial scaling (scl_slope != 0 and (scl_slope != 1 or scl_inter != 0)), the filter computes y = scl_slope * x + scl_inter at read time and promotes the output array to float32. Per the NIfTI-1 specification, scaling is never applied to RGB24 or RGBA32 data and a warning is emitted if a scaling transform is present for those types.

Cropping on read

When the Cropping Options parameter is set to anything other than NoCropping, only the selected sub-volume is retained in the output DataArray. The rest of the file is still read (and, for .nii.gz, still decompressed) but is never stored, so peak memory is proportional to the cropped region, not the full source volume. See the Memory vs. wall-clock note below before assuming cropping speeds up I/O.

Two cropping modes are supported:

• Voxel Subvolume — pick an inclusive [start..end] voxel index range per axis. The range is zero-based and uses the source file’s voxel grid.

• Physical Subvolume — pick an inclusive physical coordinate range per axis. The filter builds a temporary axis-aligned ImageGeom from the source file’s origin and spacing (the same values the Orientation section would use) and converts the requested bounds to voxel indices via ImageGeom::getIndex(). Bounds that fall outside the volume produce a descriptive error rather than silently clamping.

Each axis can be toggled on or off independently via the Crop X / Y / Z flags. An axis whose flag is off is not cropped — its full extent from the source file is used, even if the physical or voxel bound values are populated.

How the cropped ImageGeom relates to the source

• Dimensions equal the cropped voxel count on each axis.

• Spacing is the same as the source file’s spacing (cropping never resamples).

• Origin is shifted so that the center of the first cropped voxel lands at its correct physical position, i.e. new_origin[i] = source_origin[i] + start_voxel[i] * spacing[i]. This is produced by running CropImageGeometryFilter::preflight on a temp geometry, so the behavior matches what you’d get from piping a standalone read + CropImageGeometry sequence.

Interaction with other options

• Scaling — if Apply Scaling Transform is on, y = slope*x + inter is applied only to the retained voxels. Voxels outside the crop region are discarded before scaling.

• RGB24 / RGBA32 — all per-voxel components are preserved. The crop operates on the voxel grid, not on individual color bytes.

• Orientation — cropping runs on the axis-aligned ImageGeom that was already constructed from the sform / qform / pixdim fallback chain; a stored rotation warning (if any) is emitted independently of cropping.

Memory vs. wall-clock

Cropping on read primarily saves memory, not I/O time, in this version:

• For .nii.gz the file is not seekable without linear decompression, so the full compressed stream is still read and decompressed even when the cropped region is small. Peak resident memory, however, is proportional to the cropped region, not the full uncompressed volume. This matters when the source file scaled up to float32 would not fit in RAM.

• For plain .nii this version also reads linearly (scan-line by scan-line, discarding out-of-range rows in place of a true seek-skip). A seek-skip optimization for uncompressed files may come later if real-world timings warrant it.

In short: use cropping to keep the output DataArray small, not to make large compressed files read faster.

Caveats

• Only the single-file NIfTI-1 format (magic n+1) is supported. The separate-file .hdr / .img pair (magic ni1) is not.

• Only 3D volumes (dim[0] == 3) are supported. 4D and higher files (fMRI time series, diffusion series, etc.) are rejected in this release.

• Any of dim[1], dim[2], dim[3] being <= 0 is rejected.

• Complex (complex64, complex128, complex256) and 128-bit float voxel datatypes are rejected.

• Extension blocks between the header and voxel data are skipped over (via vox_offset) but not preserved.

• Non-trivial rotations in sform / qform are flattened — the Image Geometry is axis-aligned in simplnx.

• Cropping saves memory, not wall-clock read time. A .nii.gz file must still be fully decompressed regardless of how small the cropped region is; plain .nii files are also read linearly in this version.

• Physical-subvolume crop bounds must map to voxels inside the source volume. Bounds outside the extent produce an error rather than silently clamping.

• start <= end is required on each cropped axis; reversed ranges are rejected at parameter-validation time.

Required Input Sources

None — this filter reads directly from a .nii or .nii.gz file on disk.

Input Parameter(s)

Parameter Name	Parameter Type	Parameter Notes	Description
Input NIfTI File	FileSystemPath		The NIfTI-1 file to read (.nii or .nii.gz)
Use Stored Affine Transform	Bool		If enabled and the file contains an sform/qform, use it to set the ImageGeom origin and spacing. Rotation components cannot be represented in an axis-aligned image geometry; a warning will be emitted if the transform has a non-trivial rotation.
Apply Scaling Transform	Bool		If enabled and the file defines a non-trivial scaling (scl_slope != 0 and (slope != 1 or inter != 0)), apply y = slope*x + inter at read time. The output array will be promoted to float32. Scaling is never applied to RGB24/RGBA32 data per the NIfTI-1 specification.

Cropping Options

Parameter Name	Parameter Type	Parameter Notes	Description
Cropping Options	CropGeometry		Optional cropping of the volume while it is being read. When cropping is enabled, only the selected sub-volume is streamed into memory; the rest of the file is discarded on read. Supports both voxel index and physical coordinate bounds.

Output Geometry

Parameter Name	Parameter Type	Parameter Notes	Description
Image Geometry	DataGroupCreation		Path to the created Image Geometry

Output Cell Attribute Matrix

Parameter Name	Parameter Type	Parameter Notes	Description
Cell Attribute Matrix Name	DataObjectName		Name of the attribute matrix holding the voxel data

Output Data Array

Parameter Name	Parameter Type	Parameter Notes	Description
Image Data Array Name	DataObjectName		Name of the array that will hold the voxel values

Reference

• NIfTI-1 Data Format (official NIMH reference)

• nifti1.h header (NITRC)

License & Copyright

Please see the description file distributed with this plugin.

DREAM3D Mailing Lists

If you need help, need to file a bug report or want to request a new feature, please head over to the DREAM3DNX-Issues GitHub site where the community of DREAM3D-NX users can help answer your questions.